From 2b2973562ad3b29330cc5616473e13e3936142e3 Mon Sep 17 00:00:00 2001 From: Tim Bannister Date: Fri, 27 Sep 2024 10:03:39 +0100 Subject: [PATCH 1/2] Revise callouts for kubeadm cert page Use fewer note and warning blocks, to keep the important messages focused. --- .../kubeadm/kubeadm-certs.md | 96 +++++++++---------- 1 file changed, 48 insertions(+), 48 deletions(-) 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 87853ef728c25..b5de9f5fde75d 100644 --- a/content/en/docs/tasks/administer-cluster/kubeadm/kubeadm-certs.md +++ b/content/en/docs/tasks/administer-cluster/kubeadm/kubeadm-certs.md @@ -19,6 +19,11 @@ to kubeadm certificate management. You should be familiar with [PKI certificates and requirements in Kubernetes](/docs/setup/best-practices/certificates/). +This guide covers the usage of the `openssl` command (used for manual certificate signing, +if you choose that approach), but you can use your preferred tools. + +Some of the steps here use `sudo` for administrator access. You can use any equivalent tool. + ## Using custom certificates {#custom-certificates} @@ -53,6 +58,9 @@ There are various ways to prepare the component credentials when using external [PKI certificates and requirements](/docs/setup/best-practices/certificates/) includes information on how to prepare all the required by kubeadm component credentials manually. +This guide covers the usage of the `openssl` command (used for manual certificate signing, +if you choose that approach), but you can use your preferred tools. + ### Preparation of credentials by signing CSRs generated by kubeadm kubeadm can [generate CSR files](#signing-csr) that you can sign manually with tools like @@ -87,7 +95,11 @@ Once the credentials are prepared on all nodes, call `kubeadm init` and `kubeadm join the cluster. kubeadm will use the existing kubeconfig and certificate files under `/etc/kubernetes/` and its `pki` sub directory. -## Check certificate expiration +## Certificate expiry and management {#check-certificate-expiration} + +{{< note >}} +`kubeadm` cannot manage certificates signed by an external CA. +{{< /note >}} You can use the `check-expiration` subcommand to check when certificates expire: @@ -123,20 +135,15 @@ by kubeadm (`admin.conf`, `controller-manager.conf` and `scheduler.conf`). Additionally, kubeadm informs the user if the certificate is externally managed; in this case, the user should take care of managing certificate renewal manually/using other tools. -{{< warning >}} -`kubeadm` cannot manage certificates signed by an external CA. -{{< /warning >}} - -{{< note >}} -`kubelet.conf` is not included in the list above because kubeadm configures kubelet +The `kubelet.conf` configuration file is not included in the list above because kubeadm +configures kubelet for [automatic certificate renewal](/docs/tasks/tls/certificate-rotation/) with rotatable certificates under `/var/lib/kubelet/pki`. To repair an expired kubelet client certificate see [Kubelet client certificate rotation fails](/docs/setup/production-environment/tools/kubeadm/troubleshooting-kubeadm/#kubelet-client-cert). -{{< /note >}} -{{< warning >}} -On nodes created with `kubeadm init`, prior to kubeadm version 1.17, there is a +{{< note >}} +On nodes created with `kubeadm init` from versions prior to kubeadm version 1.17, there is a [bug](https://github.com/kubernetes/kubeadm/issues/1753) where you manually have to modify the contents of `kubelet.conf`. After `kubeadm init` finishes, you should update `kubelet.conf` to point to the rotated kubelet client certificates, by replacing `client-certificate-data` and @@ -146,7 +153,7 @@ point to the rotated kubelet client certificates, by replacing `client-certifica client-certificate: /var/lib/kubelet/pki/kubelet-client-current.pem client-key: /var/lib/kubelet/pki/kubelet-client-current.pem ``` -{{< /warning >}} +{{< /note >}} ## Automatic certificate renewal @@ -166,18 +173,20 @@ If you have more complex requirements for certificate renewal, you can opt out f behavior by passing `--certificate-renewal=false` to `kubeadm upgrade apply` or to `kubeadm upgrade node`. -{{< warning >}} -Prior to kubeadm version 1.17 there is a [bug](https://github.com/kubernetes/kubeadm/issues/1818) -where the default value for `--certificate-renewal` is `false` for the `kubeadm upgrade node` -command. In that case, you should explicitly set `--certificate-renewal=true`. -{{< /warning >}} - ## Manual certificate renewal -You can renew your certificates manually at any time with the `kubeadm certs renew` command, with the appropriate command line options. +You can renew your certificates manually at any time with the `kubeadm certs renew` command, +with the appropriate command line options. If you are running cluster with a replicated control +plane, this command needs to be executed on all the control-plane nodes. This command performs the renewal using CA (or front-proxy-CA) certificate and key stored in `/etc/kubernetes/pki`. +`kubeadm certs renew` uses the existing certificates as the authoritative source for attributes +(Common Name, Organization, subject alternative name) and does not rely on the `kubeadm-config` +ConfigMap. +Even so, the Kubernetes project recommends keeping the served certificate and the associated +values in that ConfigMap synchronized, to avoid any risk of confusion. + 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 @@ -188,33 +197,25 @@ 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 the Pod and the certificate renewal for the component can complete. -{{< warning >}} -If you are running an HA cluster, this command needs to be executed on all the control-plane nodes. -{{< /warning >}} - -{{< note >}} -`certs renew` uses the existing certificates as the authoritative source for attributes (Common -Name, Organization, SAN, etc.) instead of the `kubeadm-config` ConfigMap. It is strongly recommended -to keep them both in sync. -{{< /note >}} - -`kubeadm certs renew` can renew any specific certificate or, with the subcommand `all`, it can renew all of them, as shown below: +`kubeadm certs renew` can renew any specific certificate or, with the subcommand `all`, it can renew all of them: ```shell +# If you are running cluster with a replicated control plane, this command +# needs to be executed on all the control-plane nodes. kubeadm certs renew all ``` -{{< note >}} +### Copying the administrator certificate (optional) {#admin-certificate-copy} + Clusters built with kubeadm often copy the `admin.conf` certificate into `$HOME/.kube/config`, as instructed in [Creating a cluster with kubeadm](/docs/setup/production-environment/tools/kubeadm/create-cluster-kubeadm/). On such a system, to update the contents of `$HOME/.kube/config` -after renewing the `admin.conf`, you must run the following commands: +after renewing the `admin.conf`, you could run the following commands: ```shell sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config sudo chown $(id -u):$(id -g) $HOME/.kube/config ``` -{{< /note >}} ## Renew certificates with the Kubernetes certificates API @@ -430,16 +431,13 @@ as extra SANs and custom IP addresses must be stored in the same configuration file and used for all relevant kubeadm commands by passing it as `--config`. {{< note >}} -This guide will cover the usage of the `openssl` command for singing the CSRs, -but you can use your preferred tools. -{{< /note >}} +This guide uses the default Kubernetes directory `/etc/kubernetes`, which requires +a super user. If you are following this guide and are using directories that you can +write to (typically, this means running `kubeadm` with `--cert-dir` and `--kubeconfig-dir`) +then you can omit the `sudo` command). -{{< note >}} -This guide will use the default Kubernetes directory `/etc/kubernetes`, which requires -a super user. If you are following this guide with permissive directories -(by passing `--cert-dir` and `--kubeconfig-dir`) you can omit the `sudo` command). -But note that the resulted files must be copied to the `/etc/kubernetes` tree, -so that `kubeadm init` or `kubeadm join` will find them. +You must then copy the files that you produced over to within the `/etc/kubernetes` +directory so that `kubeadm init` or `kubeadm join` will find them. {{< /note >}} ### Preparing CA and service account files @@ -460,8 +458,9 @@ private keys) that kubeadm needs for a control plane node. {{< note >}} If you are using an external CA, you must generate the same files out of band and manually -copy them to the primary control plane node in `/etc/kubernetes`. Once all CSRs -are signed, you can delete the root CA key (`ca.key`) as noted in the +copy them to the primary control plane node in `/etc/kubernetes`. + +Once all CSRs are signed, you can delete the root CA key (`ca.key`) as noted in the [External CA mode](#external-ca-mode) section. {{< /note >}} @@ -500,9 +499,10 @@ That is because the active kube-controller-manager will be responsible for signing new kubelet client certificates. {{< note >}} -Processing the `kubelet.conf.csr` on the primary control plane node -(`kubeadm init`) is required, because that is considered the node that -bootstraps the cluster and a pre-populated `kubelet.conf` is needed. +You must process the `kubelet.conf.csr` file on the primary control plane node +(the host where you originally ran `kubeadm init`). This is because `kubeadm` +considers that as the node that bootstraps the cluster, and a pre-populated +`kubelet.conf` is needed. {{< /note >}} #### Control plane nodes @@ -539,8 +539,8 @@ the steps for worker nodes entirely. {{< note >}} If you are using external CA and already have CA serial number files (`.srl`) for -`openssl` you can copy such files to a kubeadm node where CSRs will be processed. -`.srl` files to copy are `/etc/kubernetes/pki/ca.srl`, +`openssl`, you can copy such files to a kubeadm node where CSRs will be processed. +The `.srl` files to copy are `/etc/kubernetes/pki/ca.srl`, `/etc/kubernetes/pki/front-proxy-ca.srl` and `/etc/kubernetes/pki/etcd/ca.srl`. The files can be then moved to a new node where CSR files will be processed. From e3c1c5b8b8b09da4a34434d86a129bbc34a77c1a Mon Sep 17 00:00:00 2001 From: Tim Bannister Date: Fri, 27 Sep 2024 10:28:41 +0100 Subject: [PATCH 2/2] Redo advice about cluster upgrades Use one consistent phrase about the advice around upgrading a cluster. --- .../en/docs/tasks/administer-cluster/cluster-upgrade.md | 4 ++++ .../tasks/administer-cluster/kubeadm/kubeadm-certs.md | 9 +++++---- .../tasks/administer-cluster/kubeadm/kubeadm-upgrade.md | 4 ++++ 3 files changed, 13 insertions(+), 4 deletions(-) diff --git a/content/en/docs/tasks/administer-cluster/cluster-upgrade.md b/content/en/docs/tasks/administer-cluster/cluster-upgrade.md index e58572589787a..7e552eab58b66 100644 --- a/content/en/docs/tasks/administer-cluster/cluster-upgrade.md +++ b/content/en/docs/tasks/administer-cluster/cluster-upgrade.md @@ -8,6 +8,10 @@ weight: 350 This page provides an overview of the steps you should follow to upgrade a Kubernetes cluster. +The Kubernetes project recommends upgrading to the latest patch releases promptly, and +to ensure that you are running a supported minor release of Kubernetes. +Following this recommendation helps you to to stay secure. + The way that you upgrade a cluster depends on how you initially deployed it and on any subsequent changes. 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 b5de9f5fde75d..ab362ef8fbdcc 100644 --- a/content/en/docs/tasks/administer-cluster/kubeadm/kubeadm-certs.md +++ b/content/en/docs/tasks/administer-cluster/kubeadm/kubeadm-certs.md @@ -14,6 +14,11 @@ Client certificates generated by [kubeadm](/docs/reference/setup-tools/kubeadm/) This page explains how to manage certificate renewals with kubeadm. It also covers other tasks related to kubeadm certificate management. +The Kubernetes project recommends upgrading to the latest patch releases promptly, and +to ensure that you are running a supported minor release of Kubernetes. +Following this recommendation helps you to to stay secure. + + ## {{% heading "prerequisites" %}} @@ -165,10 +170,6 @@ if you don't have specific requirements on certificate renewal and perform Kuber upgrades regularly (less than 1 year in between each upgrade), kubeadm will take care of keeping your cluster up to date and reasonably secure. -{{< note >}} -It is a best practice to upgrade your cluster frequently in order to stay secure. -{{< /note >}} - If you have more complex requirements for certificate renewal, you can opt out from the default behavior by passing `--certificate-renewal=false` to `kubeadm upgrade apply` or to `kubeadm upgrade node`. diff --git a/content/en/docs/tasks/administer-cluster/kubeadm/kubeadm-upgrade.md b/content/en/docs/tasks/administer-cluster/kubeadm/kubeadm-upgrade.md index 30c07cc690e41..4da8581355584 100644 --- a/content/en/docs/tasks/administer-cluster/kubeadm/kubeadm-upgrade.md +++ b/content/en/docs/tasks/administer-cluster/kubeadm/kubeadm-upgrade.md @@ -21,6 +21,10 @@ please refer to following pages instead: - [Upgrading a kubeadm cluster from {{< skew currentVersionAddMinor -4 >}} to {{< skew currentVersionAddMinor -3 >}}](https://v{{< skew currentVersionAddMinor -3 "-" >}}.docs.kubernetes.io/docs/tasks/administer-cluster/kubeadm/kubeadm-upgrade/) - [Upgrading a kubeadm cluster from {{< skew currentVersionAddMinor -5 >}} to {{< skew currentVersionAddMinor -4 >}}](https://v{{< skew currentVersionAddMinor -4 "-" >}}.docs.kubernetes.io/docs/tasks/administer-cluster/kubeadm/kubeadm-upgrade/) +The Kubernetes project recommends upgrading to the latest patch releases promptly, and +to ensure that you are running a supported minor release of Kubernetes. +Following this recommendation helps you to to stay secure. + The upgrade workflow at high level is the following: 1. Upgrade a primary control plane node.