update docs

On-behalf-of: @SAP [email protected]

Author: xrstf

docs/content/getting-started.md

@@ -12,8 +12,8 @@ All that is necessary to run the Sync Agent is a running Kubernetes cluster (for
 ## APIExport Setup
 
 Before installing the Sync Agent it is necessary to create an `APIExport` on kcp. The `APIExport` should
-be empty, because it is updated later by the Sync Agent, but it defines the new API group we're
-introducing. An example file could look like this:
+be empty, because it is updated later by the Sync Agent. The export's name is only important for
+binding to it, the resources in it can use other API groups. An example file could look like this:
 
 ```yaml
 apiVersion: apis.kcp.io/v1alpha1
@@ -23,9 +23,10 @@ metadata:
 spec: {}
 ```
 
-Create a file with a similar content (you most likely want to change the name, as that is the API
-group under which your published resources will be made available) and create it in a kcp workspace
-of your choice:
+The `APIExport` above might look like it is defining all resources for the `test.example.com` API
+group, but in reality it might contain resource schemas like `v1.crontabs.initech.com`.
+
+Create a file with a similar content and create it in a kcp workspace of your choice:
 
 ```sh
 # use the kcp kubeconfig
@@ -65,17 +66,40 @@ $ kubectl create --filename apibinding.yaml
 apibinding/test.example.com created
 ```
 
+### Creating an Endpoint Slice
+
+Beginning with kcp 0.28, `APIExports` do not contain the list of URLs the Sync Agent would need to
+connect to. Instead, kcp will create an `APIExportEndpointSlice` of the same name in the same
+workspace as the `APIExport` it belongs to. Just as before, without any existing `APIBindings`, this
+endpoint slice will not contain any URLs, so the step in the section above still applies in kcp 0.28+.
+
+In older kcp versions, no endpoint slice is automatically created by kcp, but admins are free to
+create their own.
+
+The Sync Agent can work with either `APIExports` or `APIExportEndpointSlices`. Depending on your
+situation and needs, start it with `--apiexport-ref` or `--apiexportendpointslice-ref`. When a
+reference to an endpoint slice is configured, the agent will automatically determine the `APIExport`
+the slice belongs to (and it will of course continue to manage the `APIResourceSchemas` in that
+`APIExport`).
+
+!!! note
+    The endpoint slices can live in workspaces other than the one where the `APIExport` exists. Make
+    sure that the kcp-kubeconfig provided to the Sync Agent always points to the workspace that has
+    the configured element (i.e. if using `--apiexportendpointslice-ref`, the kubeconfig must point
+    to the workspace where the endpoint slice exists, even if the APIExport is somewhere else).
+
 ## Sync Agent Installation
 
 The Sync Agent can be installed into any namespace, but in our example we are going with `kcp-system`.
 It doesn't necessarily have to live in the same Kubernetes cluster where it is synchronizing data
 to, but that is the common setup. Ultimately the Sync Agent synchronizes data between two kube
 endpoints.
 
-Now that the `APIExport` is created, switch to the Kubernetes cluster from which you wish to
-[publish resources](./publish-resources/index.md). You will need to ensure that a kubeconfig with access to
-the kcp workspace that the `APIExport` has been created in is stored as a `Secret` on this cluster.
-Make sure that the kubeconfig points to the right workspace (not necessarily the `root` workspace).
+Now that the `APIExport` (and optionally the `APIExportEndpointSlice`) are created, switch to the
+Kubernetes cluster from which you wish to [publish resources](./publish-resources/index.md). You will
+need to ensure that a kubeconfig with access to the kcp workspace that the referenced object (export
+or endpoint slice) has been created in is stored as a `Secret` on this cluster. Make sure that the
+kubeconfig points to the right workspace (not necessarily the `root` workspace).
 
 This can be done via a command like this:
 
@@ -88,13 +112,21 @@ $ kubectl create secret generic kcp-kubeconfig \
 ### Helm Chart Setup
 
 The Sync Agent is shipped as a Helm chart and to install it, the next step is preparing a `values.yaml`
-file for the Sync Agent Helm chart. We need to pass the target `APIExport`, a name for the Sync Agent
-itself and a reference to the kubeconfig secret we just created.
+file for the Sync Agent Helm chart. We need to pass the target `APIExport` or the target
+`APIExportEndpointSlice`, a name for the Sync Agent itself and a reference to the kubeconfig secret
+we just created.
 
 ```yaml
-# Required: the name of the APIExport in kcp that this Sync Agent is supposed to serve.
+# Either of the following two are required, and both fields are mutually exclusive:
+
+# the name of the APIExport in kcp that this Sync Agent is supposed to serve.
 apiExportName: test.example.com
 
+# -- or --
+
+# the name of the APIExportEndpointSlice in kcp that this Sync Agent is supposed to serve.
+# apiExportEndpointSliceName: test.example.com
+
 # Required: This Agent's public name, used to signal ownership over locally synced objects.
 # This value must be a valid Kubernetes label value, see
 # https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#syntax-and-character-set
@@ -119,9 +151,11 @@ helm install kcp-api-syncagent kcp/api-syncagent \
   --namespace kcp-system
 ```
 
-Two `kcp-api-syncagent` Pods should start in the `kcp-system` namespace. If they crash you will need to
-identify the reason from container logs. A possible issue is that the provided kubeconfig does not
-have permissions against the target kcp workspace.
+Two `kcp-api-syncagent` Pods should start in the `kcp-system` namespace. If they crash you will need
+to identify the reason from container logs. A possible issue is that the provided kubeconfig does not
+have permissions against the target kcp workspace (note that if you have an `APIExportEndpointSlice`
+in a different workspace than the `APIExport`, you will need to grant the Sync Agent permissions in
+both workspaces).
 
 ### Service Cluster RBAC
 
@@ -177,9 +211,11 @@ the RBAC rules that grant the Agent access.
 
 The Sync Agent needs to
 
-* access the workspace of its `APIExport`,
-* get the `LogicalCluster`,
+* access the workspace of its `APIExport` or `APIExportEndpointSlice`,
+* get the `LogicalCluster` (if export and endpoint slice are in different workspaces, then the agent
+  will need permission to fetch the logicalcluster in both of them),
 * manage its `APIExport`,
+* watch the `APIExportEndpointSlice` if configured,
 * manage `APIResourceSchemas`,
 * create `events` for `APIExports` and
 * access the virtual workspace for its `APIExport`.
@@ -201,6 +237,17 @@ rules:
       - cluster
     verbs:
       - get
+  # watch the APIExportEndpointSlice (optional, could also be in a different workspace)
+  - apiGroups:
+      - apis.kcp.io
+    resources:
+      - apiexportendpointslices
+    resourceNames:
+      - test.example.com
+    verbs:
+      - get
+      - list
+      - watch
   # manage its APIExport
   - apiGroups:
       - apis.kcp.io
@@ -271,6 +318,64 @@ subjects:
     name: api-syncagent-mango
 ```
 
+If you indeed have different workspaces for the export and endpoint slice, apply the RBAC above as
+mentioned in the workspace with the `APIExport`, and additionally apply the RBAC below in the
+workspace where the `APIExportEndpointSlice` exists:
+
+```yaml
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRole
+metadata:
+  name: api-syncagent-mango
+rules:
+  # get the LogicalCluster
+  - apiGroups:
+      - core.kcp.io
+    resources:
+      - logicalclusters
+    resourceNames:
+      - cluster
+    verbs:
+      - get
+  # watch the APIExportEndpointSlice
+  - apiGroups:
+      - apis.kcp.io
+    resources:
+      - apiexportendpointslices
+    resourceNames:
+      - test.example.com
+    verbs:
+      - get
+      - list
+      - watch
+
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRoleBinding
+metadata:
+  name: api-syncagent-mango:system
+roleRef:
+  apiGroup: rbac.authorization.k8s.io
+  kind: ClusterRole
+  name: api-syncagent-mango
+subjects:
+  - kind: User
+    name: api-syncagent-mango
+
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRoleBinding
+metadata:
+  name: api-syncagent-mango:access
+roleRef:
+  apiGroup: rbac.authorization.k8s.io
+  kind: ClusterRole
+  name: system:kcp:workspace:access
+subjects:
+  - kind: User
+    name: api-syncagent-mango
+```
+
 ## Publish Resources
 
 Once the Sync Agent Pods are up and running, you should be able to follow the
@@ -279,8 +384,8 @@ Once the Sync Agent Pods are up and running, you should be able to follow the
 ## Consume Service
 
 Once resources have been published through the Sync Agent, they can be consumed on the kcp side (i.e.
-objects on kcp will be synced back and forth with the service cluster). Follow the
-guide to [consuming services](consuming-services.md).
+objects on kcp will be synced back and forth with the service cluster). Follow the guide to
+[consuming services](consuming-services.md).
 
 [kind]: https://github.com/kubernetes-sigs/kind
 [kcp]: https://kcp.io

docs/content/publish-resources/index.md

@@ -2,8 +2,8 @@
 
 The guide describes the process of making a resource (usually defined by a CustomResourceDefinition)
 of one Kubernetes cluster (the "service cluster" or "local cluster") available for use in kcp. This
-involves setting up an `APIExport` and then installing the Sync Agent and defining
-`PublishedResources` in the local cluster.
+involves setting up an `APIExport`, potentially an `APIExportEndpointSlice` and then installing the
+Sync Agent and defining `PublishedResources` in the local cluster.
 
 All of the documentation and API types are worded and named from the perspective of a service owner,
 the person(s) who own a service and want to make it available to consumers in kcp.
@@ -23,7 +23,7 @@ versions and even change API group, versions and names in transit (for example p
 the service cluster as v1beta1 within kcp). This process of changing the identity of a CRD is called
 "projection" in the agent.
 
-All published resources together form the APIExport. When a service is enabled in a workspace
+All published resources together form the `APIExport`. When a service is enabled in a workspace
 (i.e. it is bound to it), users can manage objects for the projected resources described by the
 published resources. These objects will be synced from the workspace onto the service cluster,
 where they are meant to be processed in whatever way the service owners desire. Any possible