Manual Rotation of CA Certificates

    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 or you can use one of these Kubernetes playgrounds:

    • Killercoda

    • For more information about authentication in Kubernetes, see Authenticating.

    • For more information about best practices for CA certificates, see .

    Rotate the CA certificates manually

    Caution:

    Make sure to back up your certificate directory along with configuration files and any other necessary files.

    This approach assumes operation of the Kubernetes control plane in a HA configuration with multiple API servers. Graceful termination of the API server is also assumed so clients can cleanly disconnect from one API server and reconnect to another.

    Configurations with a single API server will experience unavailability while the API server is being restarted.

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

    2. Update the --root-ca-file flag for the to include both old and new CA, then restart the kube-controller-manager.

      Any ServiceAccount created after this point will get Secrets that include both old and new CAs.

      Note:

      The files specified by the kube-controller-manager flags --client-ca-file and --cluster-signing-cert-file cannot be CA bundles. If these flags and --root-ca-file point to the same ca.crt file which is now a bundle (includes both old and new CA) you will face an error. To workaround this problem you can copy the new CA to a separate file and make the flags --client-ca-file and --cluster-signing-cert-file point to the copy. Once ca.crt is no longer a bundle you can restore the problem flags to point to ca.crt and delete the copy.

      for kubeadm tracks an bug with the kube-controller-manager being unable to accept a CA bundle.

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

    4. Append the both old and new CA to the file against --client-ca-file and --kubelet-certificate-authority flag in the kube-apiserver configuration.

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

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

    7. Update the --root-ca-file flag for the to include both old and new CA, then restart the cloud-controller-manager.

      Note: If your cluster does not have a cloud-controller-manager, you can skip this step.

    8. Follow the steps below 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 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. Since the Pods in your cluster trust both old and new CAs, there will be a momentarily disconnection after which pods’ Kubernetes clients reconnect to the new API server. The new API server uses a certificate signed by the new CA.

        • Make sure control plane components logs no TLS errors.

        Note: To generate certificates and private keys for your cluster using the openssl command line tool, see . You can also use cfssl.

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

      Note: To limit the number of concurrent disruptions that your application experiences, see .

    9. If your cluster is using bootstrap tokens to join nodes, update the ConfigMap cluster-info in the kube-public namespace with new CA.

    10. Verify the cluster functionality.

      1. Check the logs from control plane components, along with the kubelet and the kube-proxy. Ensure those components are not reporting any TLS errors; see looking at the logs for more details.

      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 Secret, so that no Pods are relying on the old cluster CA.

      2. On each node, restart the kubelet by removing the old CA from file against the clientCAFile flag and from the kubelet kubeconfig file. You should carry this out as a rolling update.

        If your cluster lets you make this change, you can also roll it out by replacing nodes rather than reconfiguring them.