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)](https://kubernetes.io/docs/reference/access-authn-authz/service-accounts-admin/)
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](https://docs.cloud.google.com/anthos/fleet-management/docs/use-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](https://docs.cloud.google.com/iam/docs/service-account-overview.md.txt), 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](https://docs.cloud.google.com/anthos/fleet-management/docs), 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](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.

## Limitations

- If you created the cluster with [`enableAdvancedCluster`](https://docs.cloud.google.com/kubernetes-engine/distributed-cloud/vmware/docs/how-to/user-cluster-configuration-file-latest.md.txt#enable-advanced-cluster-field) set to `true` (which is required for [setting up topology domains](https://docs.cloud.google.com/kubernetes-engine/distributed-cloud/vmware/docs/how-to/topology-domains-set-up.md.txt)), 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:

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