Skip to content

Commit 009fcef

Browse files
xrstfxrstf
committed
update documentation
On-behalf-of: @SAP [email protected]
1 parent 20aaaa3 commit 009fcef

File tree

4 files changed

+78
-53
lines changed

4 files changed

+78
-53
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

+18
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
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.

Diff for: ‎docs/getting-started.md

+58-51
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,62 +59,23 @@ $ 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:
@@ -127,6 +88,52 @@ Two `kcp-api-syncagent` Pods should start in the `kcp-system` namespace. If they
12788
identify the reason from container logs. A possible issue is that the provided kubeconfig does not
12889
have permissions against the target kcp workspace.
12990

91+
### RBAC
92+
93+
The Sync Agent usually requires additional RBAC on the service cluster to function properly. The
94+
Helm chart will automatically allow it to read CRDs, namespaces and Secrets, but depending on how
95+
you configure your PublishedResources, additional permissions need to be created.
96+
97+
For example, if the Sync Agent is meant to create `Certificate` objects (defined by cert-manager),
98+
you would need to grant it permissions on those:
99+
100+
```yaml
101+
apiVersion: rbac.authorization.k8s.io/v1
102+
kind: ClusterRole
103+
metadata:
104+
name: 'api-syncagent:unique-test'
105+
rules:
106+
- apiGroups:
107+
- cert-manager.io
108+
resources:
109+
- certificates
110+
verbs:
111+
- get
112+
- list
113+
- watch
114+
- create
115+
- update
116+
117+
---
118+
apiVersion: rbac.authorization.k8s.io/v1
119+
kind: ClusterRoleBinding
120+
metadata:
121+
name: 'api-syncagent:unique-test'
122+
roleRef:
123+
apiGroup: rbac.authorization.k8s.io
124+
kind: ClusterRole
125+
name: 'api-syncagent:unique-test'
126+
subjects:
127+
- kind: ServiceAccount
128+
name: 'kcp-api-syncagent'
129+
namespace: kcp-system
130+
```
131+
132+
**NB:** Even though the PublishedResources might only create/update Certificates in a single namespace,
133+
due to the inner workings of the Agent they will still be watched (cached) cluster-wide. So you can
134+
tighten permissions on `create`/`update` operations to certain namespaces, but `watch` permissions
135+
need to be granted cluster-wide.
136+
130137
## Publish Resources
131138

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

0 commit comments

Comments
 (0)