Version 1.8. This version is no longer supported. For information about how to upgrade to version 1.9, seeUpgrading Anthos on bare metalin the 1.9 documentation. For more information about supported and unsupported versions, see theVersion historypage in the latest documentation.
Google Distributed Cloud 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 thebmctl update credentials --cluster-cacommand, Google Distributed Cloud 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:
ADMIN_KUBECONFIG: the path to the admin cluster
kubeconfig file.
Thebmctlcommand exits after the cluster CA is rotated successfully and a new
kubeconfig file is generated. The standard path for the kubeconfig file isbmctl-workspace/USER_CLUSTER_NAME/USER_CLUSTER_NAME-kubeconfig.
Troubleshooting a cluster CA rotation
Thebmctl update credentialscommand displays the progress of the cluster CA
rotation. The associatedupdate-credentials.logfile is saved to the following
timestamped directory:
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-09-04 UTC."],[[["\u003cp\u003eThis document describes the process of rotating the cluster certificate authority (CA) in Google Distributed Cloud user clusters, a preview feature that is subject to change and has limitations.\u003c/p\u003e\n"],["\u003cp\u003eRotating the user cluster CA is necessary to maintain secure cluster communication and should be done periodically or after a potential security breach, and can be initiated with the \u003ccode\u003ebmctl update credentials --cluster-ca\u003c/code\u003e command.\u003c/p\u003e\n"],["\u003cp\u003eBefore starting, ensure both admin and user clusters are at version 1.8.2 or higher, note that the rotation will restart the API server, control plane processes, and pods in the user cluster, resulting in workload restarts and rescheduling.\u003c/p\u003e\n"],["\u003cp\u003eWhile in preview, cluster CA rotation is only for user clusters and only updates the cluster CA, not the etcd CA or the front-proxy CA; also, it cannot be paused or rolled back once started.\u003c/p\u003e\n"],["\u003cp\u003eThe progress of the cluster CA rotation can be tracked using the \u003ccode\u003ebmctl update credentials\u003c/code\u003e command, and the detailed log file is located in the \u003ccode\u003ebmctl-workspace/USER_CLUSTER_NAME/log/update-credentials-TIMESTAMP\u003c/code\u003e directory.\u003c/p\u003e\n"]]],[],null,["# Rotate user cluster certificate authority\n\n\u003cbr /\u003e\n\n|\n| **Preview**\n|\n|\n| This feature is subject to the \"Pre-GA Offerings Terms\" in the General Service Terms section\n| of the [Service Specific Terms](/terms/service-terms#1).\n|\n| Pre-GA features are available \"as is\" and might have limited support.\n|\n| For more information, see the\n| [launch stage descriptions](/products#product-launch-stages).\n\nGoogle Distributed Cloud uses certificates and private keys to authenticate and encrypt\nconnections between system components in user clusters. The cluster certificate\nauthority (CA) manages these certificates and keys. When you run the\n`bmctl update credentials --cluster-ca` command, Google Distributed Cloud performs\nfollowing actions:\n\n- Creates and uploads a new cluster certificate authority to the user cluster\n namespace in the admin cluster.\n\n- The admin cluster controllers replace the user cluster certificate authority\n with the newly generated certificate authority.\n\n- The admin cluster controllers distribute the new public CA certificates and\n leaf certificate key pairs to user cluster system components.\n\nTo maintain secure cluster communication, rotate your user cluster CA\nperiodically and whenever there is a possible security breach.\n\nBefore you begin\n----------------\n\nBefore you rotate your user cluster certificate authority, plan according to the\nfollowing conditions and impacts::\n\n- Ensure admin and user clusters are at version 1.8.2 or higher before\n starting the user cluster CA rotation.\n\n- User cluster CA rotation is incremental, allowing system components to\n communicate during the rotation.\n\n- The user cluster rotation process restarts the API server, control plane\n processes, and pods in the user cluster.\n\n- Expect workloads to restart and be rescheduled during CA rotation.\n\n- For non-high-availability cluster configurations, expect brief periods of\n control plane downtime during CA rotation.\n\n- User cluster management operations aren't allowed during CA rotation.\n\n- User cluster CA rotation duration depends on the size of your cluster.\n For example, user cluster CA rotation may take close to two hours to\n complete for a user cluster with one control plane and 50 worker nodes.\n\nLimitations\n-----------\n\nWhile in preview, the user cluster certificate authority rotation capability has\nthe following limitations:\n\n- Cluster CA rotation is supported for user clusters only.\n\n- User cluster CA rotation is limited to the cluster CA only. User cluster CA\n rotation does not rotate the etcd CA or the front-proxy CA for your user\n cluster.\n\n- User cluster CA rotation doesn't update certificates issued manually by an\n administrator, even if the cluster CA signs the certificates. Update and\n redistribute any manually issued certificates after user cluster CA rotation\n is complete.\n\n- Once started, user cluster CA rotation can't be paused or rolled back.\n\n- Cluster CA rotation is a preview feature and its interfaces and operation\n are subject to change.\n\nStart a cluster CA rotation\n---------------------------\n\nUse the following command to start the CA rotation process: \n\n bmctl update credentials --cluster-ca --cluster-name \u003cvar translate=\"no\"\u003eUSER_CLUSTER_NAME\u003c/var\u003e \\\n --kubeconfig \u003cvar translate=\"no\"\u003eADMIN_KUBECONFIG\u003c/var\u003e\n\nReplace the following:\n\n- \u003cvar translate=\"no\"\u003eUSER_CLUSTER_NAME\u003c/var\u003e: the name of the user cluster.\n- \u003cvar translate=\"no\"\u003eADMIN_KUBECONFIG\u003c/var\u003e: the path to the admin cluster kubeconfig file.\n\nThe `bmctl` command exits after the cluster CA is rotated successfully and a new\nkubeconfig file is generated. The standard path for the kubeconfig file is\n`bmctl-workspace/`\u003cvar translate=\"no\"\u003eUSER_CLUSTER_NAME\u003c/var\u003e`/`\u003cvar translate=\"no\"\u003eUSER_CLUSTER_NAME\u003c/var\u003e`-kubeconfig`.\n\nTroubleshooting a cluster CA rotation\n-------------------------------------\n\nThe `bmctl update credentials` command displays the progress of the cluster CA\nrotation. The associated `update-credentials.log` file is saved to the following\ntimestamped directory:\n\n`bmctl-workspace/`\u003cvar translate=\"no\"\u003eUSER_CLUSTER_NAME\u003c/var\u003e`/log/update-credentials-`\u003cvar translate=\"no\"\u003eTIMESTAMP\u003c/var\u003e"]]
