You are viewing documentation for Kubernetes version: v1.23

Kubernetes v1.23 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.

Manual Rotation of CA Certificates

This page shows how to manually rotate the certificate authority (CA) certificates.

Before you begin

You need to have a Kubernetes cluster, and the kubectl command-line tool must be configured to communicate with your cluster. It is recommended to run this tutorial on a cluster with at least two nodes that are not acting as control plane hosts. If you do not already have a cluster, you can create one by using minikube or you can use one of these Kubernetes playgrounds:

Your Kubernetes server must be at or later than version v1.13. To check the version, enter kubectl version.

  • For more information about authentication in Kubernetes, see Authenticating.
  • For more information about best practices for CA certificates, see Single root CA.

Rotate the CA certificates manually

  1. Distribute the new CA certificates and private keys (ex: ca.crt, ca.key, front-proxy-ca.crt, and front-proxy-ca.key) to all your control plane nodes in the Kubernetes certificates directory.

  2. Update kube-controller-manager's --root-ca-file to include both old and new CA. Then restart the component.

    Any service account created after this point will get secrets that include both old and new CAs.

  3. Update all service account tokens to include both old and new CA certificates.

    If any pods are started before new CA is used by API servers, they will get this update and trust both old and new CAs.

    base64_encoded_ca="$(base64 -w0 <path to file containing both old and new CAs>)"
    for namespace in $(kubectl get ns --no-headers | awk '{print $1}'); do
        for token in $(kubectl get secrets --namespace "$namespace" --field-selector -o name); do
            kubectl get $token --namespace "$namespace" -o yaml | \
              /bin/sed "s/\(ca.crt:\).*/\1 ${base64_encoded_ca}/" | \
              kubectl apply -f -
  4. Restart all pods using in-cluster configs (ex: kube-proxy, coredns, etc) so they can use the updated certificate authority data from ServiceAccount secrets.

    • Make sure coredns, kube-proxy and other pods using in-cluster configs are working as expected.
  5. Append the both old and new CA to the file against --client-ca-file and --kubelet-certificate-authority flag in the kube-apiserver configuration.

  6. Append the both old and new CA to the file against --client-ca-file flag in the kube-scheduler configuration.

  7. Update certificates for user accounts by replacing the content of client-certificate-data and client-key-data respectively.

    For information about creating certificates for individual user accounts, see Configure certificates for user accounts.

    Additionally, update the certificate-authority-data section in the kubeconfig files, respectively with Base64-encoded old and new certificate authority data

  8. Follow below steps in a rolling fashion.

    1. Restart any other aggregated api servers or webhook handlers to trust the new CA certificates.

    2. Restart the kubelet by update the file against clientCAFile in kubelet configuration and certificate-authority-data in kubelet.conf to use both the old and new CA on all nodes.

      If your kubelet is not using client certificate rotation update client-certificate-data and client-key-data in kubelet.conf on all nodes along with the kubelet client certificate file usually found in /var/lib/kubelet/pki.

    3. Restart API servers with the certificates (apiserver.crt, apiserver-kubelet-client.crt and front-proxy-client.crt) signed by new CA. You can use the existing private keys or new private keys. If you changed the private keys then update these in the Kubernetes certificates directory as well.

      Since the pod trusts both old and new CAs, there will be a momentarily disconnection after which the pod's kube client will reconnect to the new API server that uses the certificate signed by the new CA.

      • Restart Scheduler to use the new CAs.

      • Make sure control plane components logs no TLS errors.

    4. Annotate any Daemonsets and Deployments to trigger pod replacement in a safer rolling fashion.


      for namespace in $(kubectl get namespace -o jsonpath='{.items[*]}'); do
          for name in $(kubectl get deployments -n $namespace -o jsonpath='{.items[*]}'); do
              kubectl patch deployment -n ${namespace} ${name} -p '{"spec":{"template":{"metadata":{"annotations":{"ca-rotation": "1"}}}}}';
          for name in $(kubectl get daemonset -n $namespace -o jsonpath='{.items[*]}'); do
              kubectl patch daemonset -n ${namespace} ${name} -p '{"spec":{"template":{"metadata":{"annotations":{"ca-rotation": "1"}}}}}';
  9. If your cluster is using bootstrap tokens to join nodes, update the ConfigMap cluster-info in the kube-public namespace with new CA.

    base64_encoded_ca="$(base64 -w0 /etc/kubernetes/pki/ca.crt)"
    kubectl get cm/cluster-info --namespace kube-public -o yaml | \
        /bin/sed "s/\(certificate-authority-data:\).*/\1 ${base64_encoded_ca}/" | \
        kubectl apply -f -
  10. Verify the cluster functionality.

    1. Validate the logs from control plane components, along with the kubelet and the kube-proxy are not throwing any tls errors, see looking at the logs.

    2. Validate logs from any aggregated api servers and pods using in-cluster config.

  11. Once the cluster functionality is successfully verified:

    1. Update all service account tokens to include new CA certificate only.

      • All pods using an in-cluster kubeconfig will eventually need to be restarted to pick up the new SA secret for the old CA to be completely untrusted.
    2. Restart the control plane components by removing the old CA from the kubeconfig files and the files against --client-ca-file, --root-ca-file flags resp.

    3. Restart kubelet by removing the old CA from file against the clientCAFile flag and kubelet kubeconfig file.

Last modified April 29, 2022 at 6:34 PM PST: [en] modify the link about debug-application (0e0f62c478)