Kubernetes service accounts are different from the
Google Cloud service accounts
that applications use to make authorized calls to Google Cloud APIs.
Google Distributed Cloud uses a private cryptographic key to sign the
KSA tokens that it issues to Pods. It uses the corresponding public key to
validate the tokens when Pods send requests to the Kubernetes API server. When
a Pod uses
Workload Identity
to call Google Cloud APIs, Google Cloud uses the same public key to
authenticate the Pod's identity.
During user cluster creation, Google Distributed Cloud generates the private and
public keys. Also during cluster creation, Google Distributed Cloud
registers the cluster to a fleet
and provides the public key to Google Cloud.
At a later
time, you can rotate the private/public key pair. The rotation automatically
issues new tokens signed by the new private key. At the end of the rotation,
the cluster has a new private key, a new public key, and refreshed tokens. Also,
Google Cloud has the new public key.
Bound tokens and legacy tokens
A Pod can use either a
legacy token or a bound token
for authentication and authorization when it calls the Kubernetes API server.
Bound tokens have a limited lifetime and are distributed to Pods using
projected volumes.
Legacy tokens never expire and are held in Kubernetes
Secrets.
We recommend bound tokens because they are more secure.
Both bound tokens and legacy tokens are refreshed during a key rotation.
Start a key rotation
Before you start a key rotation, consider these points:
During a key rotation, you cannot start another key rotation, certificate
authority rotation, or cluster update.
Key rotation cannot be paused or rolled back. All old keys are deleted.
A key rotation deletes existing cluster nodes and creates new nodes.
If the key rotation has already completed, you will see a message similar to
this:
State of KSASigningKeyRotation with KSASigningKeyVersion 2 is -
status: True,
reason: KSASigningKeyRotationCompleted,
message:{"tokenVersion":2,"privateKeyVersion":2,"publicKeyVersions":[2]}
If the KSA Signing Key rotation rotation is still in progress, you will see a
message similar to this:
State of KSASigningKeyRotation with KSASigningKeyVersion 2 is -
status: False,
reason: KSASigningKeyRotationProcessedReason,
message:{"tokenVersion":2,"privateKeyVersion":2,"publicKeyVersions":[1,2]}
[[["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-09 UTC."],[[["\u003cp\u003eKubernetes service accounts (KSAs) provide identity for processes within a Pod, using a private cryptographic key to sign tokens for Pods, and a corresponding public key for validation.\u003c/p\u003e\n"],["\u003cp\u003eGoogle Distributed Cloud generates and manages a private/public key pair during cluster creation, registering the cluster to a fleet and providing the public key to Google Cloud for authentication, and the key pair can be rotated.\u003c/p\u003e\n"],["\u003cp\u003ePods can use either bound tokens (limited lifetime, more secure) or legacy tokens (never expire) for Kubernetes API server authentication, with bound tokens recommended for better security.\u003c/p\u003e\n"],["\u003cp\u003eKey rotation involves deleting existing cluster nodes and creating new ones, and once started, it cannot be paused or rolled back, with all old keys deleted at completion.\u003c/p\u003e\n"],["\u003cp\u003eYou can initiate a key rotation using the \u003ccode\u003egkectl update credentials ksa-signing-key rotate\u003c/code\u003e command and check its status using the \u003ccode\u003egkectl update credentials ksa-signing-key status\u003c/code\u003e command.\u003c/p\u003e\n"]]],[],null,["# Rotate KSA signing keys\n\n\u003cbr /\u003e\n\nA [Kubernetes service account (KSA)](https://kubernetes.io/docs/reference/access-authn-authz/service-accounts-admin/)\nprovides an identity for processes that run in a Pod.\n\nKubernetes service accounts are different from the\n[Google Cloud service accounts](/iam/docs/service-account-overview)\nthat applications use to make authorized calls to Google Cloud APIs.\n\nGoogle Distributed Cloud uses a private cryptographic key to sign the\nKSA tokens that it issues to Pods. It uses the corresponding public key to\nvalidate the tokens when Pods send requests to the Kubernetes API server. When\na Pod uses\n[Workload Identity](/anthos/fleet-management/docs/use-workload-identity)\nto call Google Cloud APIs, Google Cloud uses the same public key to\nauthenticate the Pod's identity.\n\nDuring user cluster creation, Google Distributed Cloud generates the private and\npublic keys. Also during cluster creation, Google Distributed Cloud\n[registers the cluster to a fleet](/anthos/fleet-management/docs)\nand provides the public key to Google Cloud.\n\nAt a later\ntime, you can rotate the private/public key pair. The rotation automatically\nissues new tokens signed by the new private key. At the end of the rotation,\nthe cluster has a new private key, a new public key, and refreshed tokens. Also,\nGoogle Cloud has the new public key.\n\nBound tokens and legacy tokens\n------------------------------\n\nA Pod can use either a\n[legacy token or a bound token](https://cloud.google.com/blog/products/containers-kubernetes/kubernetes-bound-service-account-tokens)\nfor authentication and authorization when it calls the Kubernetes API server.\nBound tokens have a limited lifetime and are distributed to Pods using\n[projected volumes](https://kubernetes.io/docs/concepts/storage/projected-volumes/#serviceaccounttoken).\nLegacy tokens never expire and are held in Kubernetes\n[Secrets](https://kubernetes.io/docs/concepts/configuration/secret/).\nWe recommend bound tokens because they are more secure.\n\nBoth bound tokens and legacy tokens are refreshed during a key rotation.\n| **Important:** If you are using third-party tokens, they are not automatically refreshed during a rotation. To generate new third-party tokens, you will need to restart the Pods using these tokens.\n\nStart a key rotation\n--------------------\n\nBefore you start a key rotation, consider these points:\n\n- During a key rotation, you cannot start another key rotation, certificate\n authority rotation, or cluster update.\n\n- Key rotation cannot be paused or rolled back. All old keys are deleted.\n\n- A key rotation deletes existing cluster nodes and creates new nodes.\n\nTo start a key rotation:\n\n```\ngkectl update credentials ksa-signing-key rotate \\\n --config USER_CLUSTER_CONFIG \\\n --kubeconfig ADMIN_CLUSTER_KUBECONIFG \\\n [--skip-prompt]\n```\n\nReplace the following:\n\n- \u003cvar translate=\"no\"\u003eUSER_CLUSTER_CONFIG\u003c/var\u003e: The path of the user cluster configuration\n file\n\n- \u003cvar translate=\"no\"\u003eADMIN_KUBECONFIG_FILE\u003c/var\u003e: The path of the admin cluster kubeconfig\n file\n\nInclude `--skip-prompt` if you do not want to be prompted.\n\nView the status of a key rotation\n---------------------------------\n\nTo view the status of a key rotation:\n\n```\ngkectl update credentials ksa-signing-key status \\\n --config USER_CLUSTER_CONFIG \\\n --kubeconfig ADMIN_CLUSTER_KUBECONIFG\n```\n\nIf the key rotation has already completed, you will see a message similar to\nthis:\n\n```\nState of KSASigningKeyRotation with KSASigningKeyVersion 2 is -\nstatus: True,\nreason: KSASigningKeyRotationCompleted,\nmessage:{\"tokenVersion\":2,\"privateKeyVersion\":2,\"publicKeyVersions\":[2]}\n```\n\nIf the KSA Signing Key rotation rotation is still in progress, you will see a\nmessage similar to this:\n\n```\nState of KSASigningKeyRotation with KSASigningKeyVersion 2 is -\nstatus: False,\nreason: KSASigningKeyRotationProcessedReason,\nmessage:{\"tokenVersion\":2,\"privateKeyVersion\":2,\"publicKeyVersions\":[1,2]}\n```"]]
