From 19e9d312ea609491661c4618cc65256ded7b6e9b Mon Sep 17 00:00:00 2001 From: Fabrizio Pandini Date: Thu, 6 Jun 2019 07:20:10 +0200 Subject: [PATCH] kubeadm-1.15-certs-renewal (#14716) --- .../kubeadm/kubeadm-certs.md | 168 +++++++++++++----- 1 file changed, 119 insertions(+), 49 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 5afdcffa15..55aa0902d0 100644 --- a/content/en/docs/tasks/administer-cluster/kubeadm/kubeadm-certs.md +++ b/content/en/docs/tasks/administer-cluster/kubeadm/kubeadm-certs.md @@ -7,46 +7,112 @@ content_template: templates/task {{% capture overview %}} -This page explains how to manage certificates manually with kubeadm. +{{< feature-state for_k8s_version="v1.15" state="stable" >}} + +Client certificates generated by [kubeadm](/docs/reference/setup-tools/kubeadm/kubeadm/) expire after 1 year. This page explains how to manage certificate renewals with kubeadm. {{% /capture %}} {{% capture prerequisites %}} -These are advanced topics for users who need to integrate their organization's certificate infrastructure into a kubeadm-built cluster. If kubeadm with the default configuration satisfies your needs, you should let kubeadm manage certificates instead. +Be familiar with [PKI certificates and requirements in Kubernetes](/docs/setup/certificates/). -You should be familiar with [PKI certificates and requirements in Kubernetes](/docs/setup/certificates/). +Have a working Kubernetes cluster installed using kubeadm with your certificates stored in `/etc/kubernetes/pki` folder; in case you are using a different location, the following can be adapted accordingly. {{% /capture %}} {{% capture steps %}} -## Renew certificates with the certificates API +## Check certificate expiration -The Kubernetes certificates normally reach their expiration date after one year. +`check-expiration` can be used to check certificate expiration. -Kubeadm can renew certificates with the `kubeadm alpha certs renew` commands; you should run these commands on control-plane nodes only. +``` +kubeadm alpha certs check-expiration +``` -Typically this is done by loading on-disk CA certificates and keys and using them to issue new certificates. -This approach works well if your certificate tree is self-contained. However, if your certificates are externally -managed, you might need a different approach. +The output is similar to this: -As an alternative, Kubernetes provides its own [API for managing certificates][manage-tls]. -With kubeadm, you can use this API by running `kubeadm alpha certs renew --use-api`. +``` +CERTIFICATE EXPIRES RESIDUAL TIME EXTERNALLY MANAGED +admin.conf May 15, 2020 13:03 UTC 364d false +apiserver May 15, 2020 13:00 UTC 364d false +apiserver-etcd-client May 15, 2020 13:00 UTC 364d false +apiserver-kubelet-client May 15, 2020 13:00 UTC 364d false +controller-manager.conf May 15, 2020 13:03 UTC 364d false +etcd-healthcheck-client May 15, 2020 13:00 UTC 364d false +etcd-peer May 15, 2020 13:00 UTC 364d false +etcd-server May 15, 2020 13:00 UTC 364d false +front-proxy-client May 15, 2020 13:00 UTC 364d false +scheduler.conf May 15, 2020 13:03 UTC 364d false +``` -## Set up a signer +The command shows expiration/residual time for the client certificates in the `/etc/kubernetes/pki` folder and for the client certificate embedded in the KUBECONFIG files used 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 for automatic certificate renewal. +{{< /note >}} + +## Automatic certificate renewal + +`kubeadm` renews all the certificates during control plane [upgrade](/docs/tasks/administer-cluster/kubeadm/kubeadm-upgrade-1-15/). + +This feature is designed for addressing the simplest use cases; +if you don't have specific requirements on certificate renewal and perform Kubernetes version 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`. + + +## Manual certificate renewal + +You can renew your certificates manually at any time with the `kubeadm alpha certs renew` command. + +This command performs the renewal using CA (or front-proxy-CA) certificate and key stored in `/etc/kubernetes/pki`. + +{{< warning >}} +If you are running an HA cluster, this command needs to be executed on all the control-plane nodes. +{{< /warning >}} + +{{< note >}} +`alpha 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 alpha certs renew` provides the following options: + +- `--use-api` allows you to use the Kubernetes certificates API for signing certificates (instead of the local CA/front-proxy-CA); see next paragraphs for more information. + +- `--csr-only` can be used to renew certificats with an external CA by generating certificate signing requests (without actually renewing certificates in place); see next paragraph for more information. + +- It's also possible to renew a single certificate instead of all. + +## Renew certificates with the Kubernetes certificates API + +This section provide more details about how to execute manual certificate renewal using the Kubernetes certificates API. + +{{< caution >}} +These are advanced topics for users who need to integrate their organization's certificate infrastructure into a kubeadm-built cluster. If the default kubeadm configuration satisfies your needs, you should let kubeadm manage certificates instead. +{{< /caution >}} + +### Set up a signer The Kubernetes Certificate Authority does not work out of the box. You can configure an external signer such as [cert-manager][cert-manager-issuer], or you can use the build-in signer. + The built-in signer is part of [`kube-controller-manager`][kcm]. -To activate the build-in signer, you pass the `--cluster-signing-cert-file` and `--cluster-signing-key-file` arguments. -You pass these arguments in any of the following ways: +To activate the build-in signer, you must pass the `--cluster-signing-cert-file` and `--cluster-signing-key-file` flags. -* Edit `/etc/kubernetes/manifests/kube-controller-manager.yaml` to add the arguments to the command. - Remember that your changes could be overwritten when you upgrade. - -* If you're creating a new cluster, you can use a kubeadm [configuration file][config]: +If you're creating a new cluster, you can use a kubeadm [configuration file][config]: ```yaml apiVersion: kubeadm.k8s.io/v1beta1 @@ -57,73 +123,77 @@ You pass these arguments in any of the following ways: cluster-signing-key-file: /etc/kubernetes/pki/ca.key ``` -* You can also upload a config file using [`kubeadm config upload from-files`][config-upload] - [cert-manager-issuer]: https://cert-manager.readthedocs.io/en/latest/tutorials/ca/creating-ca-issuer.html [kcm]: /docs/reference/command-line-tools-reference/kube-controller-manager/ -[config]: https://godoc.org/k8s.io/kubernetes/cmd/kubeadm/app/apis/kubeadm/v1beta1 -[config-upload]: /docs/reference/setup-tools/kubeadm/kubeadm-config/#cmd-config-from-file +[config]: https://godoc.org/k8s.io/kubernetes/cmd/kubeadm/app/apis/kubeadm/v1beta2 -### Approve requests +### Create certificate signing requests (CSR) -If you set up an external signer such as [cert-manager][cert-manager], certificate signing requests (CSRs) are automatically approved. -Otherwise, you must manually approve certificates with the [`kubectl certificate`][certs] command. -The following kubeadm command outputs the name of the certificate to approve, then blocks and waits for approval to occur: +You can create the certificate signing requests for the Kubernetes certificates API with `kubeadm alpha certs renew --use-api`. + +The command outputs the name of the certificate to approve, then blocks and waits for approval to occur. e.g.: ```shell sudo kubeadm alpha certs renew apiserver --use-api & ``` +The output is similar to this: ``` [1] 2890 [certs] certificate request "kubeadm-cert-kube-apiserver-ld526" created ``` + +### Approve certificate signing requests (CSR) + +If you set up an external signer, certificate signing requests (CSRs) are automatically approved. + +Otherwise, you must manually approve certificates with the [`kubectl certificate`][certs] command. e.g. + ```shell kubectl certificate approve kubeadm-cert-kube-apiserver-ld526 +``` +The output is similar to this: +```shell certificatesigningrequest.certificates.k8s.io/kubeadm-cert-kube-apiserver-ld526 approved -[1]+ Done sudo kubeadm alpha certs renew apiserver --use-api ``` You can view a list of pending certificates with `kubectl get csr`. -[manage-tls]: /docs/tasks/tls/managing-tls-in-a-cluster/ -[cert-manager]: https://github.com/jetstack/cert-manager -[certs]: /docs/reference/generated/kubectl/kubectl-commands#certificate +## Renew certificates with external CA -## Certificate requests with kubeadm +This section provide more details about how to execute manual certificate renewal using an external CA. -To better integrate with external CAs, kubeadm can also produce certificate signing requests (CSRs). -A CSR represents a request to a CA for a signed certificate for a client. -In kubeadm terms, any certificate that would normally be signed by an on-disk CA can be produced as a CSR instead. A CA, however, cannot be produced as a CSR. +{{< caution >}} +These are advanced topics for users who need to integrate their organization's certificate infrastructure into a kubeadm-built cluster. If the default kubeadm configuration satisfies your needs, you should let kubeadm manage certificates instead. +{{< /caution >}} -You can create an individual CSR with `kubeadm init phase certs apiserver --csr-only`. -The `--csr-only` flag can be applied only to individual phases. After [all certificates are in place][certs], you can run `kubeadm init --external-ca`. +### Create certificate signing requests (CSR) -You can pass in a directory with `--csr-dir` to output the CSRs to the specified location. -If `--csr-dir` is not specified, the default certificate directory (`/etc/kubernetes/pki`) is used. -Both the CSR and the accompanying private key are given in the output. After a certificate is signed, the certificate and the private key must be copied to the PKI directory (by default `/etc/kubernetes/pki`). +To better integrate with external CAs, kubeadm can produce certificate signing requests (CSRs). + +A CSR represents a request to a CA for a signed certificate for a client. + +You can create certificate signing requests with `kubeadm alpha certs renew --csr-only`. + +Both the CSR and the accompanying private key are given in the output; you can pass in a directory with `--csr-dir` to output the CSRs to the specified location. ### Renew certificates -Certificates can be renewed with `kubeadm alpha certs renew --csr-only`. -As with `kubeadm init`, an output directory can be specified with the `--csr-dir` flag. -To use the new certificates, copy the signed certificate and private key into the PKI directory (by default `/etc/kubernetes/pki`) +A CSR contains a certificate's name, domain(s), and IPs, but it does not specify usages. -## Cert usage - -A CSR contains a certificate's name, domains, and IPs, but it does not specify usages. It is the responsibility of the CA to specify [the correct cert usages][cert-table] when issuing a certificate. - + * In `openssl` this is done with the [`openssl ca` command][openssl-ca]. * In `cfssl` you specify [usages in the config file][cfssl-usages] -## CA selection - -Kubeadm sets up [three CAs][cert-cas] by default. Make sure to sign the CSRs with a corresponding CA. +After a certificate is signed using your preferred method, the certificate and the private key must be copied to the PKI directory (by default `/etc/kubernetes/pki`). [openssl-ca]: https://superuser.com/questions/738612/openssl-ca-keyusage-extension [cfssl-usages]: https://github.com/cloudflare/cfssl/blob/master/doc/cmd/cfssl.txt#L170 [certs]: /docs/setup/certificates [cert-cas]: /docs/setup/certificates/#single-root-ca [cert-table]: /docs/setup/certificates/#all-certificates +[manage-tls]: /docs/tasks/tls/managing-tls-in-a-cluster/ +[cert-manager]: https://github.com/jetstack/cert-manager +[certs]: /docs/reference/generated/kubectl/kubectl-commands#certificate {{% /capture %}}