<button class="button button-with-icon cloud-select-dropdown__button button-primary" aria-haspopup="true">Version 1.13 </button>

- [Latest version](https://docs.cloud.google.com/anthos/clusters/docs/on-prem/latest/how-to/rotate-ksa-signing-key)
- [Version 1.16](https://docs.cloud.google.com/anthos/clusters/docs/on-prem/1.16/how-to/rotate-ksa-signing-key.md.txt)
- [Earlier versions (unsupported)](https://docs.cloud.google.com/anthos/clusters/docs/on-prem/latest/version-history#expandable-1)

<br />

Google Distributed Cloud uses a private cryptographic key to sign the
Kubernetes service account 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](https://docs.cloud.google.com/anthos/fleet-management/docs/use-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](https://docs.cloud.google.com/anthos/fleet-management/docs)
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](https://cloud.google.com/blog/products/containers-kubernetes/kubernetes-bound-service-account-tokens)
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](https://kubernetes.io/docs/concepts/storage/projected-volumes/#serviceaccounttoken).
Legacy tokens never expire and are held in Kubernetes
[Secrets](https://kubernetes.io/docs/concepts/configuration/secret/).
We recommend bound tokens because they are more secure.

Both bound tokens and legacy tokens are refreshed during a key rotation.

> [!IMPORTANT]
> **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.

## 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:

- <var translate="no">USER_CLUSTER_CONFIG</var>: The path of the user cluster configuration
  file

- <var translate="no">ADMIN_KUBECONFIG_FILE</var>: 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]}
```