From 75a33b2650ae419dff079b99b6acf87d173b6e44 Mon Sep 17 00:00:00 2001 From: "Lubomir I. Ivanov" Date: Wed, 2 Feb 2022 21:41:40 +0200 Subject: [PATCH] kubeadm: add missing guide for "kubeconfig user" The command "kubeadm kubeconfig user" is missing some examples and more details on why it is needed. - Add a new section "Generating kubeconfig files for additional users" under the kubeadm-certs page. - Link to this section from the kubeadm-kubeconfig reference page. - Link to this section from the create-cluster-kubeadm page. --- .../setup-tools/kubeadm/kubeadm-kubeconfig.md | 3 + .../tools/kubeadm/create-cluster-kubeadm.md | 7 ++- .../kubeadm/kubeadm-certs.md | 57 ++++++++++++++++++- 3 files changed, 61 insertions(+), 6 deletions(-) diff --git a/content/en/docs/reference/setup-tools/kubeadm/kubeadm-kubeconfig.md b/content/en/docs/reference/setup-tools/kubeadm/kubeadm-kubeconfig.md index f912285f7d..a5684ecceb 100644 --- a/content/en/docs/reference/setup-tools/kubeadm/kubeadm-kubeconfig.md +++ b/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" >}} diff --git a/content/en/docs/setup/production-environment/tools/kubeadm/create-cluster-kubeadm.md b/content/en/docs/setup/production-environment/tools/kubeadm/create-cluster-kubeadm.md index 9d7b717594..e8b0a6d1a7 100644 --- a/content/en/docs/setup/production-environment/tools/kubeadm/create-cluster-kubeadm.md +++ b/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 >}} diff --git a/content/en/docs/tasks/administer-cluster/kubeadm/kubeadm-certs.md b/content/en/docs/tasks/administer-cluster/kubeadm/kubeadm-certs.md index 094b7a767a..789723777e 100644 --- a/content/en/docs/tasks/administer-cluster/kubeadm/kubeadm-certs.md +++ b/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 +```