Learn Kubernetes Basics

Get Started

Ready to get your hands dirty? Build a simple Kubernetes cluster that runs "Hello World" for Node.js.

Documentation

Learn how to use Kubernetes with conceptual, tutorial, and reference documentation. You can even help contribute to the docs!

Blog

Read the latest news for Kubernetes and the containers space in general, and get technical how-tos hot off the presses.

Interested in hacking on the core Kubernetes code base?

View On GitHub

Explore the community

Tasks

Kubernetes v1.15 documentation is no longer actively maintained. The version you are currently viewing is a static snapshot. For up-to-date documentation, see the latest version.

Edit This Page

Certificate Management with kubeadm

FEATURE STATE: Kubernetes v1.15 stable

This feature is stable, meaning:

The version name is vX where X is an integer.
Stable versions of features will appear in released software for many subsequent versions.

Client certificates generated by kubeadm expire after 1 year. This page explains how to manage certificate renewals with kubeadm.

Before you begin
Check certificate expiration
Automatic certificate renewal
Manual certificate renewal
Renew certificates with the Kubernetes certificates API
Renew certificates with external CA

Before you begin

Be familiar with PKI certificates and requirements in Kubernetes.

You should be familiar with PKI certificates and requirements in Kubernetes.

Check certificate expiration

check-expiration can be used to check certificate expiration.

kubeadm alpha certs check-expiration

The output is similar to this:

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

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.

Note: kubelet.conf is not included in the list above because kubeadm configures kubelet for automatic certificate renewal.

Automatic certificate renewal

kubeadm renews all the certificates during control plane upgrade.

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.

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.

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.

kubeadm alpha certs renew provides the following options:

The Kubernetes certificates normally reach their expiration date after one year.

--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.

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, or you can use the build-in signer. The built-in signer is part of kube-controller-manager. To activate the build-in signer, you pass the --cluster-signing-cert-file and --cluster-signing-key-file arguments.

The built-in signer is part of kube-controller-manager.

To activate the build-in signer, you must pass the --cluster-signing-cert-file and --cluster-signing-key-file flags.

If you’re creating a new cluster, you can use a kubeadm configuration file:

  apiVersion: kubeadm.k8s.io/v1beta2
  kind: ClusterConfiguration
  controllerManager:
    extraArgs:
      cluster-signing-cert-file: /etc/kubernetes/pki/ca.crt
      cluster-signing-key-file: /etc/kubernetes/pki/ca.key

Create certificate signing requests (CSR)

You can create the certificate signing requests for the Kubernetes certificates API with kubeadm alpha certs renew --use-api.

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 command. The following kubeadm command outputs the name of the certificate to approve, then blocks and waits for approval to occur:

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 command. e.g.

kubectl certificate approve kubeadm-cert-kube-apiserver-ld526

The output is similar to this:

certificatesigningrequest.certificates.k8s.io/kubeadm-cert-kube-apiserver-ld526 approved

You can view a list of pending certificates with kubectl get csr.

Renew certificates with external CA

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.

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).

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.

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.

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 when issuing a certificate.

In openssl this is done with the openssl ca command.
In cfssl you specify usages in the config file

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).

Feedback

Was this page helpful?

Thanks for the feedback. If you have a specific, answerable question about how to use Kubernetes, ask it on Stack Overflow. Open an issue in the GitHub repo if you want to report a problem or suggest an improvement.