From 66891f74d36f5e2a241a1dacdb7dc1209bea777a Mon Sep 17 00:00:00 2001 From: Simon Bein Date: Wed, 24 Jun 2026 11:05:28 +0200 Subject: [PATCH] add docs for targeting kubeconfings On-behalf-of: SAP Signed-off-by: Simon Bein --- docs/content/architecture/kubeconfig.md | 30 ++++++++++++++++++++++--- 1 file changed, 27 insertions(+), 3 deletions(-) diff --git a/docs/content/architecture/kubeconfig.md b/docs/content/architecture/kubeconfig.md index 74f541c7..10eca2d5 100644 --- a/docs/content/architecture/kubeconfig.md +++ b/docs/content/architecture/kubeconfig.md @@ -36,6 +36,11 @@ spec: frontProxyRef: name: my-front-proxy + # Optional: specifies the workspace path this kubeconfig targets. + # Used in the generated kubeconfig server URL and as the default RBAC + # provisioning target. Defaults to "root" if unset. + targetWorkspace: root:orga:teamb + # Required: how long the certificate should be valid for; # the operator will automatically renew the certificate, after which the # Secret will be renewed and have to be re-downloaded. @@ -54,6 +59,22 @@ Once the `Kubeconfig` has been created, you can observe its status to wait for i !!! note The `Kubeconfig`'s name is embedded into the certificate in form of a group (organization) named `kubeconfig:`. This is to allow a unique mapping from RBAC rules to `Kubeconfig` objects for the authorization (see further down). Take note that this means the `Kubeconfig`' name is leaked to whoever gets the kubeconfig. +## Target Workspace + +By default, the generated kubeconfig's server URL points to the `root` workspace. To target a different workspace, set `spec.targetWorkspace`: + +```yaml +spec: + targetWorkspace: root:orga:teamb +``` + +This affects two things: + +1. **Server URL**: The generated kubeconfig will contain a server URL pointing to the specified workspace (e.g. `https://.../clusters/root:orga:teamb`). +2. **RBAC target**: When authorization is configured (see below), the RBAC rules will be provisioned in this workspace by default. + +The field accepts kcp workspace paths like `root`, `root:org`, or `root:org:team`. + ## Authorization Without any further configuration than shown in the basics section above, the created identity (username + groups) will not get any permissions in kcp. So while the kubeconfig is valid and allows proper authentication, pretty much no actions will be permitted yet. @@ -71,14 +92,17 @@ metadata: spec: #...snip... + targetWorkspace: root:orga:teamb + authorization: clusterRoleBindings: - # This can be a workspace path (root:something) or a cluster name (ID). - cluster: root:initech:teamgibbons clusterRoles: - cluster-admin ``` -This configuration would bind the group `kubeconfig:susan` to the ClusterRole `cluster-admin` inside the given workspace. Note that this is specifically not bound to the user (common name), so that two `Kubeconfig` objects that both have the same `spec.name` to not have colliding RBAC. +This configuration would bind the group `kubeconfig:susan` to the ClusterRole `cluster-admin` inside the workspace specified in `spec.targetWorkspace`. Note that this is specifically not bound to the user (common name), so that two `Kubeconfig` objects that both have the same `spec.name` to not have colliding RBAC. When deleting a `Kubeconfig` with authorization settings, the kcp-operator will first unprovision (delete) the `ClusterRoleBindings` before the `Kubeconfig` can be deleted. + +!!! note "Deprecated: `authorization.clusterRoleBindings.cluster`" + Previously, the target workspace for RBAC was specified via `spec.authorization.clusterRoleBindings.cluster`. This field is now deprecated in favor of `spec.targetWorkspace`. The two fields cannot be set together. Existing resources using the deprecated field will continue to work for RBAC provisioning, but note that the deprecated field does **not** influence the kubeconfig server URL (which always defaults to `root` unless `spec.targetWorkspace` is set).