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

This page explains how to manage certificates manually with kubeadm.

Before you begin
Renew certificates with the certificates API
Set up a signer
Certificate requests with kubeadm
Cert usage
CA selection

Before you begin

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.

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

Renew certificates with the certificates API

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

Kubeadm can renew certificates with the kubeadm alpha certs renew commands; you should run these commands on control-plane nodes only.

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.

As an alternative, Kubernetes provides its own API for managing certificates. With kubeadm, you can use this API by running kubeadm alpha certs renew --use-api.

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.

You pass these arguments in any of the following ways:

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:

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

You can also upload a config file using kubeadm config upload from-files

Approve requests

If you set up an external signer such as 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 &

[1] 2890
[certs] certificate request "kubeadm-cert-kube-apiserver-ld526" created

kubectl certificate approve kubeadm-cert-kube-apiserver-ld526
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.

Certificate requests with kubeadm

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.

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, you can run kubeadm init --external-ca.

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

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)

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

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

CA selection

Kubeadm sets up three CAs by default. Make sure to sign the CSRs with a corresponding CA.

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.