Rotate user cluster certificate authority

Version 1.8 (unsupported)

• Version 1.28 (latest)
• Version 1.16
• Version 1.15
• Earlier versions (unsupported)

Preview

This feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

GKE on Bare Metal uses certificates and private keys to authenticate and encrypt connections between system components in user clusters. The cluster certificate authority (CA) manages these certificates and keys. When you run the bmctl update credentials --cluster-ca command, GKE on Bare Metal performs following actions:

• Creates and uploads a new cluster certificate authority to the user cluster namespace in the admin cluster.

• The admin cluster controllers replace the user cluster certificate authority with the newly generated certificate authority.

• The admin cluster controllers distribute the new public CA certificates and leaf certificate key pairs to user cluster system components.

To maintain secure cluster communication, rotate your user cluster CA periodically and whenever there is a possible security breach.

Before you begin

Before you rotate your user cluster certificate authority, plan according to the following conditions and impacts::

• Ensure admin and user clusters are at version 1.8.2 or higher before starting the user cluster CA rotation.

• User cluster CA rotation is incremental, allowing system components to communicate during the rotation.

• The user cluster rotation process restarts the API server, control plane processes, and pods in the user cluster.

• Expect workloads to restart and be rescheduled during CA rotation.

• For non-high-availability cluster configurations, expect brief periods of control plane downtime during CA rotation.

• User cluster management operations aren't allowed during CA rotation.

• User cluster CA rotation duration depends on the size of your cluster. For example, user cluster CA rotation may take close to two hours to complete for a user cluster with one control plane and 50 worker nodes.

Limitations

While in preview, the user cluster certificate authority rotation capability has the following limitations:

• Cluster CA rotation is supported for user clusters only.

• User cluster CA rotation is limited to the cluster CA only. User cluster CA rotation does not rotate the etcd CA or the front-proxy CA for your user cluster.

• User cluster CA rotation doesn't update certificates issued manually by an administrator, even if the cluster CA signs the certificates. Update and redistribute any manually issued certificates after user cluster CA rotation is complete.

• Once started, user cluster CA rotation can't be paused or rolled back.

• Cluster CA rotation is a preview feature and its interfaces and operation are subject to change.

Start a cluster CA rotation

Use the following command to start the CA rotation process:

bmctl update credentials --cluster-ca --cluster-name USER_CLUSTER_NAME \
    --kubeconfig ADMIN_KUBECONFIG

Replace the following:

• USER_CLUSTER_NAME: the name of the user cluster.
• ADMIN_KUBECONFIG: the path to the admin cluster kubeconfig file.

The bmctl command exits after the cluster CA is rotated successfully and a new kubeconfig file is generated. The standard path for the kubeconfig file is bmctl-workspace/USER_CLUSTER_NAME/USER_CLUSTER_NAME-kubeconfig.

Troubleshooting a cluster CA rotation

The bmctl update credentials command displays the progress of the cluster CA rotation. The associated update-credentials.log file is saved to the following timestamped directory:

bmctl-workspace/USER_CLUSTER_NAME/log/update-credentials-TIMESTAMP