To refresh the credentials that Pods use to authenticate, you can rotate the key pair that Google Distributed Cloud uses to sign the Kubernetes service account (KSA) tokens it issues to Pods in a user cluster. The rotation replaces the private and public keys, reissues tokens signed by the new private key, and gives Google Cloud the new public key for Workload Identity authentication. Key rotation isn't supported on advanced clusters.
About KSA signing keys
A KSA provides an identity for processes that run in a Pod. KSAs are different from Google Cloud service accounts, which applications use to make authorized calls to Google Cloud APIs.
Google Distributed Cloud uses a private key to sign the KSA tokens that it issues to Pods, and 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 key pair, registers the cluster to a fleet, and provides the public key to Google Cloud.
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.
Limitations
- If you created the cluster with
enableAdvancedClusterset totrue(which is required for setting up topology domains), key rotation isn't supported.
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.
To start a key rotation:
gkectl update credentials ksa-signing-key rotate \
--config USER_CLUSTER_CONFIG \
--kubeconfig ADMIN_KUBECONFIG_FILE \
[--skip-prompt]
Replace the following:
USER_CLUSTER_CONFIG: The path of the user cluster configuration file
ADMIN_KUBECONFIG_FILE: The path of the admin cluster kubeconfig file
Include --skip-prompt if you do not want to be prompted.
View the status of a key rotation
To view the status of a key rotation:
gkectl update credentials ksa-signing-key status \
--config USER_CLUSTER_CONFIG \
--kubeconfig ADMIN_KUBECONFIG_FILE
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 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]}