Skip to content

Commit 9edf625

Browse files
kcp-ci-botkcp-ci-bot
authored
Merge pull request #14 from kcp-dev/update-docs
📖 update documentation
2 parents 20aaaa3 + 0398d04 commit 9edf625

File tree

4 files changed

+171
-54
lines changed

4 files changed

+171
-54
lines changed

Diff for: ‎docs/README.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Documentation
22

3-
kcp-api-syncagent is a Kubernetes agent responsible for integrating external Kubernetes clusters.
3+
The api-syncagent is a Kubernetes agent responsible for integrating external Kubernetes clusters.
44
It runs on a Kubernetes cluster, is configured with credentials to a kcp instance and will then
55
synchronize data out of kcp (i.e. out of kcp workspaces) onto the local cluster, and vice versa.
66

Diff for: ‎docs/consuming-services.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ A Service provided by a Sync Agent should not be confused with a Kubernetes Serv
1919
## Consuming a Service
2020

2121
To consume a service (or to make use of an `APIExport`) you have to create an `APIBinding` object
22-
in the kcp workspace where the servie should be used. This section assumes that you are familiar
22+
in the kcp workspace where the service should be used. This section assumes that you are familiar
2323
with kcp on the command line and have the kcp kubectl plugin installed.
2424

2525
First you need to get the kubeconfig for accessing your kcp workspaces. Once you have set your

Diff for: ‎docs/faq.md

+38
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
# Frequently Asked Questions
2+
3+
## Can I run multiple Sync Agents on the same service cluster?
4+
5+
Yes, absolutely, however you must configure them properly:
6+
7+
A given `PublishedResource` must only ever be processed by a single Sync Agent Pod. The Helm chart
8+
configures leader-election by default, so you can scale up to have Pods on stand-by if needed.
9+
10+
By default the Sync Agent will discover and process all `PublishedResources` in your cluster. Use
11+
the `--published-resource-selector` (`publishedResourceSelector` in the Helm values.yaml) to
12+
restrict an Agent to a subset of published resources.
13+
14+
## Can I synchronize multiple kcp setups onto the same service cluster?
15+
16+
Only if you have distinct API groups (and therefore also distinct `PublishedResources`) for them.
17+
You cannot currently publish the same API group onto multiple kcp setups. See issue #13 for more
18+
information.
19+
20+
## What happens when CRDs are updated?
21+
22+
At the moment, nothing. `APIResourceSchemas` in kcp are immutable and the Sync Agent currently does
23+
not attempt to update existing schemas in an `APIExport`. If you add a _new_ CRD that you want to
24+
publish, that's fine, it will be added to the `APIExport`. But changes to existing CRDs require
25+
manual work.
26+
27+
To trigger an update:
28+
29+
* remove the `APIResourceSchema` from the `latestResourceSchemas`,
30+
* delete the `APIResourceSchema` object in kcp,
31+
* restart the api-syncagent
32+
33+
## Does the Sync Agent handle permission claims?
34+
35+
Only those required for its own operation. If you configure a namespaced resource to sync, it will
36+
automatically add a claim for `namespaces` in kcp, plus it will add either `configmaps` or `secrets`
37+
if related resources are configured in a `PublishedResource`. But you cannot specify additional
38+
permissions claims.

Diff for: ‎docs/getting-started.md

+131-52
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
# Getting Started with the Sync Agent
22

33
All that is necessary to run the Sync Agent is a running Kubernetes cluster (for testing you can use
4-
[kind][kind]) [kcp][kcp] installation.
4+
[kind][kind]) and a [kcp][kcp] installation.
55

66
## Prerequisites
77

@@ -31,7 +31,7 @@ of your choice:
3131
# use the kcp kubeconfig
3232
$ export KUBECONFIG=/path/to/kcp.kubeconfig
3333

34-
# nativagate to the workspace wher the APIExport should exist
34+
# nativagate to the workspace where the APIExport should exist
3535
$ kubectl ws :workspace:you:want:to:create:it
3636

3737
# create it
@@ -59,74 +59,153 @@ $ kubectl create secret generic kcp-kubeconfig \
5959
--from-file "kubeconfig=admin.kubeconfig"
6060
```
6161

62+
### Helm Chart Setup
63+
6264
The Sync Agent is shipped as a Helm chart and to install it, the next step is preparing a `values.yaml`
6365
file for the Sync Agent Helm chart. We need to pass the target `APIExport`, a name for the Sync Agent
6466
itself and a reference to the kubeconfig secret we just created.
6567

6668
```yaml
67-
syncAgent:
68-
# Required: the name of the APIExport in kcp that this Sync Agent is supposed to serve.
69-
apiExportName: test.example.com
70-
71-
# Required: this Sync Agent's public name, will be shown in kcp, purely for informational purposes.
72-
agentName: unique-test
73-
74-
# Required: Name of the Kubernetes Secret that contains a "kubeconfig" key, with the kubeconfig
75-
# provided by kcp to access it.
76-
kcpKubeconfig: kcp-kubeconfig
77-
78-
# Create additional RBAC on the service cluster. These rules depend somewhat on the Sync Agent
79-
# configuration, but the following two rules are very common. If you configure the Sync Agent to
80-
# only work with cluster-scoped objects, you do not need to grant it permissions to create
81-
# namespaces, for example.
82-
rbac:
83-
createClusterRole: true
84-
rules:
85-
# in order to create APIResourceSchemas
86-
- apiGroups:
87-
- apiextensions.k8s.io
88-
resources:
89-
- customresourcedefinitions
90-
verbs:
91-
- get
92-
- list
93-
- watch
94-
# so copies of remote objects can be placed in their target namespaces
95-
- apiGroups:
96-
- ""
97-
resources:
98-
- namespaces
99-
verbs:
100-
- get
101-
- list
102-
- watch
103-
- create
104-
```
69+
# Required: the name of the APIExport in kcp that this Sync Agent is supposed to serve.
70+
apiExportName: test.example.com
10571

106-
In addition, it is important to create RBAC rules for the resources you want to publish. If you want
107-
to publish the `Certificate` resource as created by cert-manager, you will need to append the
108-
following ruleset:
72+
# Required: This Agent's public name, purely for informational purposes.
73+
# If not set, defaults to the Helm release name.
74+
agentName: unique-test
10975

110-
```yaml
111-
# so we can manage certificates
112-
- apiGroups:
113-
- cert-manager.io
114-
resources:
115-
- certificates
116-
verbs:
117-
- '*'
76+
# Required: Name of the Kubernetes Secret that contains a "kubeconfig" key,
77+
# with the kubeconfig provided by kcp to access it.
78+
kcpKubeconfig: kcp-kubeconfig
11879
```
11980
12081
Once this `values.yaml` file is prepared, install a recent development build of the Sync Agent:
12182

12283
```sh
123-
helm install kcp-api-syncagent oci://github.com/kcp-dev/helm-charts/api-syncagent --version 9.9.9-9fc9a430d95f95f4b2210f91ef67b3ec153b5cab -f values.yaml -n kcp-system
84+
helm repo add kcp https://kcp-dev.github.io/helm-charts
85+
helm repo update
86+
87+
helm install kcp-api-syncagent kcp/api-syncagent \
88+
--values values.yaml \
89+
--namespace kcp-system
12490
```
12591

12692
Two `kcp-api-syncagent` Pods should start in the `kcp-system` namespace. If they crash you will need to
12793
identify the reason from container logs. A possible issue is that the provided kubeconfig does not
12894
have permissions against the target kcp workspace.
12995

96+
### Service Cluster RBAC
97+
98+
The Sync Agent usually requires additional RBAC on the service cluster to function properly. The
99+
Helm chart will automatically allow it to read CRDs, namespaces and Secrets, but depending on how
100+
you configure your PublishedResources, additional permissions need to be created.
101+
102+
For example, if the Sync Agent is meant to create `Certificate` objects (defined by cert-manager),
103+
you would need to grant it permissions on those:
104+
105+
```yaml
106+
apiVersion: rbac.authorization.k8s.io/v1
107+
kind: ClusterRole
108+
metadata:
109+
name: 'api-syncagent:unique-test'
110+
rules:
111+
- apiGroups:
112+
- cert-manager.io
113+
resources:
114+
- certificates
115+
verbs:
116+
- get
117+
- list
118+
- watch
119+
- create
120+
- update
121+
122+
---
123+
apiVersion: rbac.authorization.k8s.io/v1
124+
kind: ClusterRoleBinding
125+
metadata:
126+
name: 'api-syncagent:unique-test'
127+
roleRef:
128+
apiGroup: rbac.authorization.k8s.io
129+
kind: ClusterRole
130+
name: 'api-syncagent:unique-test'
131+
subjects:
132+
- kind: ServiceAccount
133+
name: 'kcp-api-syncagent'
134+
namespace: kcp-system
135+
```
136+
137+
**NB:** Even though the PublishedResources might only create/update Certificates in a single namespace,
138+
due to the inner workings of the Agent they will still be watched (cached) cluster-wide. So you can
139+
tighten permissions on `create`/`update` operations to certain namespaces, but `watch` permissions
140+
need to be granted cluster-wide.
141+
142+
### kcp RBAC
143+
144+
The Helm chart is installed on the service cluster and so cannot provision the necessary RBAC for
145+
the Sync Agent within kcp. Usually whoever creates the `APIExport` is also responsible for creating
146+
the RBAC rules that grant the Agent access.
147+
148+
The Sync Agent needs to
149+
150+
* manage its `APIExport`,
151+
* manage `APIResourceSchemas` and
152+
* access the virtual workspace for its `APIExport`.
153+
154+
This can be achieved by applying RBAC like this _in the workspace where the `APIExport` resides_:
155+
156+
```yaml
157+
apiVersion: rbac.authorization.k8s.io/v1
158+
kind: ClusterRole
159+
metadata:
160+
name: api-syncagent-mango
161+
rules:
162+
# manage its APIExport
163+
- apiGroups:
164+
- apis.kcp.io
165+
resources:
166+
- apiexports
167+
resourceNames:
168+
- test.example.com
169+
verbs:
170+
- get
171+
- list
172+
- watch
173+
- patch
174+
- update
175+
# manage APIResourceSchemas
176+
- apiGroups:
177+
- apis.kcp.io
178+
resources:
179+
- apiresourceschemas
180+
verbs:
181+
- get
182+
- list
183+
- watch
184+
- create
185+
# access the virtual workspace
186+
- apiGroups:
187+
- apis.kcp.io
188+
resources:
189+
- apiexports/content
190+
resourceNames:
191+
- test.example.com
192+
verbs:
193+
- '*'
194+
195+
---
196+
apiVersion: rbac.authorization.k8s.io/v1
197+
kind: ClusterRoleBinding
198+
metadata:
199+
name: api-syncagent-columbo:mango-system
200+
roleRef:
201+
apiGroup: rbac.authorization.k8s.io
202+
kind: ClusterRole
203+
name: api-syncagent-mango
204+
subjects:
205+
- kind: User
206+
name: api-syncagent-mango
207+
```
208+
130209
## Publish Resources
131210

132211
Once the Sync Agent Pods are up and running, you should be able to follow the

0 commit comments

Comments
 (0)