Merge pull request #31604 from neolit123/1.24-add-example-for-kubeconfig-user

kubeadm: add missing guide for "kubeconfig user"

Author: k8s-ci-robot

content/en/docs/reference/setup-tools/kubeadm/kubeadm-kubeconfig.md

@@ -6,6 +6,9 @@ weight: 90
 
 `kubeadm kubeconfig` provides utilities for managing kubeconfig files.
 
+For examples on how to use `kubeadm kubeconfig user` see
+[Generating kubeconfig files for additional users](/docs/tasks/administer-cluster/kubeadm/kubeadm-certs#kubeconfig-additional-users).
+
 ## kubeadm kubeconfig {#cmd-kubeconfig}
 
 {{< tabs name="tab-kubeconfig" >}}

content/en/docs/setup/production-environment/tools/kubeadm/create-cluster-kubeadm.md

@@ -210,7 +210,8 @@ export KUBECONFIG=/etc/kubernetes/admin.conf
 Kubeadm signs the certificate in the `admin.conf` to have `Subject: O = system:masters, CN = kubernetes-admin`.
 `system:masters` is a break-glass, super user group that bypasses the authorization layer (e.g. RBAC).
 Do not share the `admin.conf` file with anyone and instead grant users custom permissions by generating
-them a kubeconfig file using the `kubeadm kubeconfig user` command.
+them a kubeconfig file using the `kubeadm kubeconfig user` command. For more details see
+[Generating kubeconfig files for additional users](/docs/tasks/administer-cluster/kubeadm/kubeadm-certs#kubeconfig-additional-users).
 {{< /warning >}}
 
 Make a record of the `kubeadm join` command that `kubeadm init` outputs. You
@@ -384,8 +385,8 @@ A few seconds later, you should notice this node in the output from `kubectl get
 nodes` when run on the control-plane node.
 
 {{< note >}}
-As the cluster nodes are usually initialized sequentially, the CoreDNS Pods are likely to all run 
-on the first control-plane node. To provide higher availability, please rebalance the CoreDNS Pods 
+As the cluster nodes are usually initialized sequentially, the CoreDNS Pods are likely to all run
+on the first control-plane node. To provide higher availability, please rebalance the CoreDNS Pods
 with `kubectl -n kube-system rollout restart deployment coredns` after at least one new node is joined.
 {{< /note >}}
 

content/en/docs/tasks/administer-cluster/kubeadm/kubeadm-certs.md

@@ -10,7 +10,9 @@ weight: 10
 
 {{< feature-state for_k8s_version="v1.15" state="stable" >}}
 
-Client certificates generated by [kubeadm](/docs/reference/setup-tools/kubeadm/) expire after 1 year. This page explains how to manage certificate renewals with kubeadm.
+Client certificates generated by [kubeadm](/docs/reference/setup-tools/kubeadm/) expire after 1 year.
+This page explains how to manage certificate renewals with kubeadm. It also covers other tasks related
+to kubeadm certificate management.
 
 ## {{% heading "prerequisites" %}}
 
@@ -126,13 +128,13 @@ command. In that case, you should explicitly set `--certificate-renewal=true`.
 
 You can renew your certificates manually at any time with the `kubeadm certs renew` command.
 
-This command performs the renewal using CA (or front-proxy-CA) certificate and key stored in `/etc/kubernetes/pki`. 
+This command performs the renewal using CA (or front-proxy-CA) certificate and key stored in `/etc/kubernetes/pki`.
 
 After running the command you should restart the control plane Pods. This is required since
 dynamic certificate reload is currently not supported for all components and certificates.
 [Static Pods](/docs/tasks/configure-pod-container/static-pod/) are managed by the local kubelet
 and not by the API Server, thus kubectl cannot be used to delete and restart them.
-To restart a static Pod you can temporarily remove its manifest file from `/etc/kubernetes/manifests/` 
+To restart a static Pod you can temporarily remove its manifest file from `/etc/kubernetes/manifests/`
 and wait for 20 seconds (see the `fileCheckFrequency` value in [KubeletConfiguration struct](/docs/reference/config-api/kubelet-config.v1beta1/).
 The kubelet will terminate the Pod if it's no longer in the manifest directory.
 You can then move the file back and after another `fileCheckFrequency` period, the kubelet will recreate
@@ -289,3 +291,52 @@ Such a controller is not a secure mechanism unless it not only verifies the Comm
 in the CSR but also verifies the requested IPs and domain names. This would prevent
 a malicious actor that has access to a kubelet client certificate to create
 CSRs requesting serving certificates for any IP or domain name.
+
+## Generating kubeconfig files for additional users {#kubeconfig-additional-users}
+
+During cluster creation, kubeadm signs the certificate in the `admin.conf` to have
+`Subject: O = system:masters, CN = kubernetes-admin`.
+[`system:masters`](/docs/reference/access-authn-authz/rbac/#user-facing-roles)
+is a break-glass, super user group that bypasses the authorization layer (e.g. RBAC).
+Sharing the `admin.conf` with additional users is **not recommended**!
+
+Instead, you can use the [`kubeadm kubeconfig user`](/docs/reference/setup-tools/kubeadm/kubeadm-kubeconfig)
+command to generate kubeconfig files for additional users.
+The command accepts a mixture of command line flags and
+[kubeadm configuration](/docs/reference/config-api/kubeadm-config.v1beta3/) options.
+The generated kubeconfig will be written to stdout and can be piped to a file
+using `kubeadm kubeconfig user ... > somefile.conf`.
+
+Example configuration file that can be used with `--config`:
+
+```yaml
+# example.yaml
+apiVersion: kubeadm.k8s.io/v1beta3
+kind: ClusterConfiguration
+# Will be used as the target "cluster" in the kubeconfig
+clusterName: "kubernetes"
+# Will be used as the "server" (IP or DNS name) of this cluster in the kubeconfig
+controlPlaneEndpoint: "some-dns-address:6443"
+# The cluster CA key and certificate will be loaded from this local directory
+certificatesDir: "/etc/kubernetes/pki"
+```
+
+Make sure that these settings match the desired target cluster settings.
+To see the settings of an existing cluster use:
+
+```shell
+kubectl get cm kubeadm-config -n kube-system -o=jsonpath="{.data.ClusterConfiguration}"
+```
+
+The following example will generate a kubeconfig file with credentials valid for 24 hours
+for a new user `johndoe` that is part of the `appdevs` group:
+
+```shell
+kubeadm kubeconfig user --config example.yaml --org appdevs --client-name johndoe --validity-period 24h
+```
+
+The following example will generate a kubeconfig file with administrator credentials valid for 1 week:
+
+```shell
+kubeadm kubeconfig user --config example.yaml --client-name admin --validity-period 168h
+```