|
| 1 | +--- |
| 2 | +description: > |
| 3 | + Shows how `Kubeconfig` objects can be used to provide credentials to kcp. |
| 4 | +--- |
| 5 | + |
| 6 | +# Kubeconfigs |
| 7 | + |
| 8 | +Besides provisioning kcp itself, the kcp-operator can also provide [kubeconfigs](https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/) to access kcp. Each kubeconfig will internally be backed by a dedicated client certificate. |
| 9 | + |
| 10 | +## Basics |
| 11 | + |
| 12 | +A minimal `Kubeconfig` object typically looks like this: |
| 13 | + |
| 14 | +```yaml |
| 15 | +apiVersion: operator.kcp.io/v1alpha1 |
| 16 | +kind: Kubeconfig |
| 17 | +metadata: |
| 18 | + name: susan |
| 19 | + namespace: my-kcp |
| 20 | +spec: |
| 21 | + # Required: the username inside Kubernetes; |
| 22 | + # this will be the client certificate's common name. |
| 23 | + username: susan |
| 24 | + |
| 25 | + # required: groups to attach to the user; |
| 26 | + # this will be the organizations in the client cert. |
| 27 | + groups: |
| 28 | + - system:kcp:admin |
| 29 | + |
| 30 | + # Required: in what Secret the generated kubeconfig should be stored. |
| 31 | + secretRef: |
| 32 | + name: susan-kubeconfig |
| 33 | + |
| 34 | + # Required: a Kubeconfig must target either a FrontProxy, Shard or RootShard. |
| 35 | + target: |
| 36 | + frontProxyRef: |
| 37 | + name: my-front-proxy |
| 38 | + |
| 39 | + # Required: how long the certificate should be valid for; |
| 40 | + # the operator will automatically renew the certificate, after which the |
| 41 | + # Secret will be renewed and have to be re-downloaded. |
| 42 | + validity: 8766h |
| 43 | +``` |
| 44 | +
|
| 45 | +`Kubeconfig` objects must exist in the same namespace as the kcp installation they are meant for. |
| 46 | + |
| 47 | +Once the `Kubeconfig` has been created, you can observe its status to wait for it to be ready. After that, retrieve the Secret mentioned in the `secretRef` to find the finished kubeconfig, ready to use. |
| 48 | + |
| 49 | +!!! warning |
| 50 | + Deleting a `Kubeconfig` will also delete the underlying Secret from the hosting cluster, however this will not invalidate the existing certificate that is embedded in the kubeconfig. This means anyone with a copy of the kubeconfig can keep using it until the certificate expires. |
| 51 | + |
| 52 | + To disarm an old kubeconfig, make sure to revoke any permissions granted through RBAC for the user and/or their groups. |
| 53 | + |
| 54 | +!!! note |
| 55 | + 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. |
| 56 | + |
| 57 | +## Authorization |
| 58 | + |
| 59 | +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. |
| 60 | + |
| 61 | +The administrator has to either rely on externally-managed RBAC rules to provide permissions, or use the kcp-operator to provision such RBAC in a workspace. |
| 62 | + |
| 63 | +To make the kcp-operator manage RBAC, use `spec.authorization` inside a `Kubeconfig`: |
| 64 | + |
| 65 | +```yaml |
| 66 | +apiVersion: operator.kcp.io/v1alpha1 |
| 67 | +kind: Kubeconfig |
| 68 | +metadata: |
| 69 | + name: susan |
| 70 | + namespace: my-kcp |
| 71 | +spec: |
| 72 | + #...snip... |
| 73 | +
|
| 74 | + authorization: |
| 75 | + clusterRoleBindings: |
| 76 | + # This can be a workspace path (root:something) or a cluster name (ID). |
| 77 | + cluster: root:initech:teamgibbons |
| 78 | + clusterRoles: |
| 79 | + - cluster-admin |
| 80 | +``` |
| 81 | + |
| 82 | +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. |
| 83 | + |
| 84 | +When deleting a `Kubeconfig` with authorization settings, the kcp-operator will first unprovision (delete) the `ClusterRoleBindings` before the `Kubeconfig` can be deleted. |
0 commit comments