Skip to content

Certificate renewal and rotation in RKE2 and K3s clusters

Article Number: 000022026

Environment

A Rancher-provisioned or standalone RKE2 or K3s cluster

Procedure

This article provides a comprehensive guide on the certificate rotation process for RKE2 and K3s clusters. It covers both standalone deployments and downstream clusters managed by Rancher.

Rotating certificates is a critical maintenance task. RKE2 and K3s utilize client and server certificates to establish trust and secure communication between the cluster components. If certificates expire, authentication between components (such as the kubelet and the Kubernetes API Server) will fail, leading to cluster instability or total service outages.

Per the RKE2 and K3s certification documentation: the client and server certificates are valid for 365 days from their date of issuance. Any certificates that are expired or within 120 days of expiring are automatically renewed every time RKE2 or K3s starts. This renewal reuses the existing keys, and extends the lifetime of the existing certificates. If you want to generate new certificates and keys, instead of extending the validity of the existing certificates, rotate certificates as documented below.

N.B. Prior to the May 2025 releases (RKE2: v1.33.1+rke2r1, v1.32.5+rke2r1, v1.31.9+rke2r1, v1.30.13+rke2r1; K3s: v1.33.1+k3s1, v1.32.5+k3s1, v1.31.9+k3s1, v1.30.13+k3s1), alerts and renewal were triggered at 90 days, instead of 120 days.

Monitoring Certificate Expiration

Manually checking expiration

Node certificates and their expiration date can be checked using the rke2 certificate check --output table and k3s certificate check --output table commands, per the RKE2 and K3s documentation.

N.B.  Prior to the May 2025 releases (as listed above), the kube-scheduler and kube-controller-manager certificates, for Rancher-provisioned clusters, were not included in the output of the certificate check command. In older versions these two certificates can be checked manually with openssl x509 -enddate -noout -in /var/lib/rancher/rke2/server/tls/kube-scheduler/kube-scheduler.crt and openssl x509 -enddate -noout -in /var/lib/rancher/rke2/server/tls/kube-controller-manager/kube-controller-manager.crt or  openssl x509 -enddate -noout -in /var/lib/rancher/k3s/server/tls/kube-scheduler/kube-scheduler.crt and openssl x509 -enddate -noout -in /var/lib/rancher/k3s/server/tls/kube-controller-manager/kube-controller-manager.crt

Automated monitoring

When a certificate is within 120 days of expiring a Kubernetes Warning Event with reason: CertificateExpirationWarning is created, with a relation to the Node using the certificate. These Events can be used as the basis for automated monitoring of certificate expiration.

An alternative approach would be to use the x509-certificate-exporter to track expiration dates and set up proactive alerts using Prometheus and Alertmanager, such as in rancher-monitoring.

Renewal Process

To renew certificates that are expired or within 120 days of expiring, reusing the existing keys, simply restart the RKE2 or K3s supervisor process, i.e. systemctl restart rke2-server, systemctl restart rke2-agent, systemctl restart k3s, or systemctl restart k3s-agent

N.B. Prior to the May 2025 releases (as listed above), the kube-scheduler and kube-controller-manager certificates, for Rancher-provisioned clusters, were not managed by the RKE2 or K3s supervisor process. As a result restarting the supervisor process will not renew these certificates. To rotate these certificates in older K3s and RKE2 versions, perform a rotation using the Rancher UI, as documented below, or remove the certificate and key files manually before restarting the supervisor, i.e.: rm /var/lib/rancher/rke2/server/tls/kube-controller-manager/kube-controller-manager.{crt,key} /var/lib/rancher/rke2/server/tls/kube-scheduler/kube-scheduler.{crt,key} or rm /var/lib/rancher/k3s/server/tls/kube-controller-manager/kube-controller-manager.{crt,key} /var/lib/rancher/k3s/server/tls/kube-scheduler/kube-scheduler.{crt,key}

Rotation Process

RKE2 and K3s certificates can be rotated - generating new certificates and keys, versus extending the validity of existing certificates - using the following processes for standalone and Rancher-provisioned clusters.

Standalone clusters

To rotate the certificates in a standalone cluster, follow the steps for the certificate rotate subcommand in the RKE2 or K3s documentation.

  1. Stop the RKE2 or K3s supervisor process: systemctl stop rke2-server, systemctl stop rke2-agent, systemctl stop k3s, or systemctl stop k3s-agent
  2. Rotate the certificates: rke2 certificate rotate or k3s certificate rotate
  3. Start the RKE2 or K3s supervisor process: systemctl start rke2-server, systemctl start rke2-agent, systemctl start k3s, or systemctl start k3s-agent

Per the RKE2 and K3s documentation, it is also possible to specify individual services for which to rotate certificates, using the --service argument.

Rancher-provisioned clusters

To rotate the certificates of a Rancher-provisioned RKE2 or K3s cluster, follow the steps from the Rancher documentation:

  1. In the upper left corner, click ☰ > Cluster Management.
  2. On the Clusters page, go to the cluster you want to rotate certificates for and click ⋮ > Rotate Certificates.
  3. Choose to Rotate all Service certificates (recommended) or select an individual service.
  4. Click Save. Rancher will orchestrate the rotation across the nodes automatically.

Rotating CA Certificates - Standalone clusters only

By default, RKE2 and K3s generate self-signed CA certificates during startup of the first server node. These CA certificates are valid for 10 years and do not renew automatically.

For standalone clusters, the CA certificate can be rotated, per the RKE2 and K3s documentation. If the cluster was started with the default self-signed CA certificates, CA rotation will be disruptive. If the new CA certificates are not cross-signed by the old CA certificates, or the root CA is replaced when using custom CA certificates, all nodes will also need to be reconfigured to use the new secure cluster token, and pods will need to be restarted.