Rotate Kubernetes Cluster Certificates

Page last updated:

This topic describes how to rotate certificates for Kubernetes clusters created by Tanzu Kubernetes Grid Integrated Edition (TKGI).

Overview of TKGI-Provisioned Kubernetes Cluster Certificates

When TKGI provisions a Kubernetes cluster, the system generates certificate authority (CA) certificates and leaf certificates that have values and expiration dates unique to that cluster.

You can use the TKGI CLI to list and rotate TLS certificates for a Kubernetes cluster provisioned by Tanzu Kubernetes Grid Integrated Edition.


The following table summarizes the TKGI-provisioned Kubernetes cluster certificates and how to rotate them.

Certificates When Used How to Rotate
kubo_master_ca_2021, kubo_ca_2018, etcd_ca_2018, and their leaf certificates All clusters. See Rotate Kubernetes Cluster Certificates below.
tls_nsx_t and tls_nsx_lb NSX-T only. These certificates must be registered with NSX Manager. See Rotate NSX-T Certificates for Kubernetes Clusters.


To rotate the certificates used by the TKGI control plane, see Rotating TKGI Control Plane Certificates.

Kubernetes Cluster Certificates

A TKGI-provisioned Kubernetes cluster includes the following CA certificates and their leaf certificates:

  • kubo_master_ca_2021

    • tls-kubernetes-2018
    • tls-ncp-2018 (with NSX-T)
    • tls-nsx-kube-proxy-2018 (with NSX-T)
  • kubo_ca_2018:

    • tls-kubelet-2018
    • tls-metrics-server-2018
    • tls-kubelet-client-2018
    • tls-kube-controller-manager-2018
  • etcd_ca_2018:

    • tls-etcd-2018-2
    • tls-etcdctl-2018-2
    • tls-etcdctl-root-2018-2
    • tls-etcdctl-flanneld-2018-2
  • NSX certificates

    • tls-nsx-lb
    • tls-nsx-t

TKGI CLI Support for Certificate Rotation

You can use the TKGI CLI to list and rotate the TLS certificates created for a Kubernetes cluster.

Usage:

tkgi rotate-certs | rotate-certificates <ClusterName> [flags]

Flags:

      --all               Rotate all certs, not implemented yet, will be available in future releases.
  -h, --help              help for rotate-certs
      --json              Return the PKS-API output as json
      --non-interactive   Don't ask for user input
      --only-nsx          Rotate the tls-nsx-lb and tls-nsx-t certificates.
      --wait              Wait for the operation to finish

TLS Certificate Rotation Use Cases

The TKGI CLI supports the following TLS certificate rotation scenarios:

List TLS Certificates

To list the TLS certificates used by TKGI-provisioned Kubernetes cluster, run the following command:

tkgi certificates <ClusterName> -d <number of days>

For example:

tkgi certificates tkgi-cluster-01 -d 10000

The sample output lists all TLS certificates that TKGI uses for the specified cluster.

NAME                                                                                            Type  Days Left  Valid until
/p-bosh/service-instance_62e2a43a-dc2a-47a8-a361-3911589e60aa/tls-nsx-lb                        Leaf  1803       2025-12-14T06:47:46Z
/p-bosh/service-instance_62e2a43a-dc2a-47a8-a361-3911589e60aa/tls-nsx-kube-proxy-2018           Leaf  1439       2024-12-15T06:47:41Z
/p-bosh/service-instance_62e2a43a-dc2a-47a8-a361-3911589e60aa/tls-ncp-2018                      Leaf  1439       2024-12-15T06:47:41Z
/p-bosh/service-instance_62e2a43a-dc2a-47a8-a361-3911589e60aa/tls-nsx-t                         Leaf  708        2022-12-15T06:47:40Z
/p-bosh/service-instance_62e2a43a-dc2a-47a8-a361-3911589e60aa/tls-kube-controller-manager-2018  Leaf  1439       2024-12-15T06:47:40Z
/p-bosh/service-instance_62e2a43a-dc2a-47a8-a361-3911589e60aa/tls-metrics-server-2018           Leaf  1439       2024-12-15T06:47:39Z
/p-bosh/service-instance_62e2a43a-dc2a-47a8-a361-3911589e60aa/tls-etcdctl-flanneld-2018-2       Leaf  1439       2024-12-15T06:47:39Z
/p-bosh/service-instance_62e2a43a-dc2a-47a8-a361-3911589e60aa/tls-etcdctl-root-2018-2           Leaf  1439       2024-12-15T06:47:38Z
/p-bosh/service-instance_62e2a43a-dc2a-47a8-a361-3911589e60aa/tls-etcdctl-2018-2                Leaf  1439       2024-12-15T06:47:37Z
/p-bosh/service-instance_62e2a43a-dc2a-47a8-a361-3911589e60aa/tls-etcd-2018-2                   Leaf  1439       2024-12-15T06:47:36Z
/p-bosh/service-instance_62e2a43a-dc2a-47a8-a361-3911589e60aa/tls-kubelet-client-2018           Leaf  1439       2024-12-15T06:47:36Z
/p-bosh/service-instance_62e2a43a-dc2a-47a8-a361-3911589e60aa/tls-kubelet-2018                  Leaf  1439       2024-12-15T06:47:35Z
/p-bosh/service-instance_62e2a43a-dc2a-47a8-a361-3911589e60aa/etcd_ca_2018                      Root  1439       2024-12-15T06:47:35Z
/p-bosh/service-instance_62e2a43a-dc2a-47a8-a361-3911589e60aa/tls-kubernetes-2018               Leaf  1439       2024-12-15T06:47:34Z
/p-bosh/service-instance_62e2a43a-dc2a-47a8-a361-3911589e60aa/kubo_ca_2018                      Root  1439       2024-12-15T06:47:34Z

Rotate All Cluster Certificates

To rotate all cluster certificates:

tkgi rotate-certificates <cluster name> --all

This command rotates all certificates except a custom CA kubo_master_ca_2021 (if implemented).

Rotate All Cluster Certificates Except NSX-T

To rotate all cluster certificates except the NSX-T certificates:

tkgi rotate-certificates <cluster name> --skip-nsx --all

This command rotates all certificates except tls-nsx-t and tls-nsx-lb.

Rotate NSX-T Certificates Only

To rotate only NSX certificates:

tkgi rotate-certificates <cluster name> --only-nsx

This command only rotates the NSX-T certificates tls-nsx-t and tls-nsx-lb.

For example:

tkgi rotate-certs <ClusterName> --only-nsx

You are about to rotate nsx related certificates for cluster <ClusterName>. This operation requires bosh deployment, and will take a significant time. Are you sure you want to continue? (y/n):

For more information, see Rotate NSX-T Certificates for Kubernetes Clusters.

Rotate Custom CA

If you have implemented a custom CA for the kubo_master_ca_2021, rotation is handled by the update-cluster CLI command.

For example:

tkgi update-cluster <cluster name> --config-file <path to the config file>

For complete usage, see Use a Custom CA for Kubernetes Clusters.


Please send any feedback you have to pks-feedback@pivotal.io.