Skip to content

add docs for targeting kubeconfings #249

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
SimonTheLeg wants to merge 1 commit into
base: main
Choose a base branch
from
Open

add docs for targeting kubeconfings #249

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 27 additions & 3 deletions docs/content/architecture/kubeconfig.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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:<name>`. 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.
Expand All @@ -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).
Loading