Rotate KSA signing keys

A Kubernetes service account (KSA) provides an identity for processes that run in a Pod.

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.

Limitations

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_CLUSTER_KUBECONIFG \
    [--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_CLUSTER_KUBECONIFG

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]}