Version 1.9. This version is no longer supported. For information about how to upgrade to version 1.10, seeUpgrading Anthos on bare metalin the 1.10 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 clusters. The cluster certificate
authority (CA) manages these certificates and keys. When you run thebmctl update credentials certificate-authorities rotatecommand,
Google Distributed Cloud performs following actions:
Creates and uploads new cluster certificate authorities (CAs) for the
cluster CA, the etcd CA, and the front-proxy CA to the user cluster
namespace in the admin cluster.
The admin cluster controllers replace the user cluster certificate
authorities with the newly generated ones.
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 cluster's certificate authority, plan according to the
following conditions and impacts:
Ensure admin and user clusters are at version 1.9.0 or higher before
starting the CA rotation.
CA rotation is incremental, allowing system components to communicate during
the rotation.
The CA 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.
Cluster management operations aren't allowed during CA rotation.
CA rotation duration depends on the size of your cluster. For example, CA
rotation may take close to two hours to complete for a cluster with one
control plane and 50 worker nodes.
Limitations
The certificate authority rotation capability has the
following limitations:
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, 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:
CLUSTER_NAME: the name of the cluster for which you
want to rotate CAs.
ADMIN_KUBECONFIG: the path to the admin cluster
kubeconfig file. For self-managing clusters, this file is the cluster's
kubeconfig file.
Thebmctlcommand exits after the CA is rotated successfully and a new
kubeconfig file is generated. The standard path for the kubeconfig file isbmctl-workspace/CLUSTER_NAME/CLUSTER_NAME-kubeconfig.
Troubleshoot a cluster CA rotation
Thebmctl update credentialscommand displays the progress of the 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\u003eGoogle Distributed Cloud uses certificate authorities (CAs) to secure cluster communication, and these CAs should be periodically rotated to maintain security and address potential breaches.\u003c/p\u003e\n"],["\u003cp\u003eInitiating CA rotation involves creating and uploading new CAs, replacing existing ones, and distributing new certificates and key pairs to user cluster components, leading to restarts of system processes.\u003c/p\u003e\n"],["\u003cp\u003eCA rotation is an incremental process, requires clusters to be at version 1.9.0 or higher, cannot be paused or rolled back, and can take up to two hours for large clusters.\u003c/p\u003e\n"],["\u003cp\u003eThe \u003ccode\u003ebmctl update credentials certificate-authorities rotate\u003c/code\u003e command starts the rotation, and progress can be tracked through the command output and an associated log file located in a timestamped directory.\u003c/p\u003e\n"],["\u003cp\u003eCA rotation is currently a preview feature, subject to change and does not update manually issued certificates, which must be done separately after the process completes.\u003c/p\u003e\n"]]],[],null,["# Rotate certificate authorities\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 clusters. The cluster certificate\nauthority (CA) manages these certificates and keys. When you run the\n`bmctl update credentials certificate-authorities rotate` command,\nGoogle Distributed Cloud performs following actions:\n\n- Creates and uploads new cluster certificate authorities (CAs) for the\n cluster CA, the etcd CA, and the front-proxy CA to the user cluster\n namespace in the admin cluster.\n\n- The admin cluster controllers replace the user cluster certificate\n authorities with the newly generated ones.\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 cluster's certificate authority, plan according to the\nfollowing conditions and impacts:\n\n- Ensure admin and user clusters are at version 1.9.0 or higher before\n starting the CA rotation.\n\n- CA rotation is incremental, allowing system components to communicate during\n the rotation.\n\n- The CA rotation process restarts the API server, control plane processes,\n 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- Cluster management operations aren't allowed during CA rotation.\n\n- CA rotation duration depends on the size of your cluster. For example, CA\n rotation may take close to two hours to complete for a cluster with one\n control plane and 50 worker nodes.\n\nLimitations\n-----------\n\nThe certificate authority rotation capability has the\nfollowing limitations:\n\n- CA rotation doesn't update certificates issued manually by an administrator,\n even if the cluster CA signs the certificates. Update and redistribute any\n manually issued certificates after user cluster CA rotation is complete.\n\n- Once started, 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 certificate-authorities rotate --cluster \u003cvar translate=\"no\"\u003eCLUSTER_NAME\u003c/var\u003e \\\n --kubeconfig \u003cvar translate=\"no\"\u003eADMIN_KUBECONFIG\u003c/var\u003e\n\nReplace the following:\n\n- \u003cvar translate=\"no\"\u003eCLUSTER_NAME\u003c/var\u003e: the name of the cluster for which you want to rotate CAs.\n- \u003cvar translate=\"no\"\u003eADMIN_KUBECONFIG\u003c/var\u003e: the path to the admin cluster kubeconfig file. For self-managing clusters, this file is the cluster's kubeconfig file.\n\nThe `bmctl` command exits after the 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\"\u003eCLUSTER_NAME\u003c/var\u003e`/`\u003cvar translate=\"no\"\u003eCLUSTER_NAME\u003c/var\u003e`-kubeconfig`.\n\nTroubleshoot a cluster CA rotation\n----------------------------------\n\nThe `bmctl update credentials` command displays the progress of the CA rotation.\nThe associated `update-credentials.log` file is saved to the following\ntimestamped directory:\n\n`bmctl-workspace/`\u003cvar translate=\"no\"\u003eCLUSTER_NAME\u003c/var\u003e`/log/update-credentials-`\u003cvar translate=\"no\"\u003eTIMESTAMP\u003c/var\u003e"]]
