This feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of theService Specific Terms. Pre-GA features are available "as is" and might have limited support. For more information, see thelaunch stage descriptions.

This page shows you how to rotate the etcd and control plane boot diskencryption keys that you configured for GKE control plane authority.This page is intended for cluster administrators and Security engineers.

Before you read this page, familiarize yourself with the followingGKE control plane authority concepts:

• Key and credential management.
• Rotation of customer-managed credentials.

Plan key rotations

This page shows you how to rotate the following credential components in yourcontrol plane:

• The encryption key for etcd and the control plane boot disks.
• The encryption key for the etcd internal backup that Google Cloud usesfor disaster recovery.

You can also rotate the customer-managed certificate authorities (CAs) andservice account signing keys that you configure withGKE control plane authority. For more information, seeRotate customer-managed control plane CAs and signing keys.

Keys in Cloud Key Management Service (Cloud KMS) don't expire. If your organization hasa security requirement for key rotation, manually rotate the keys. To minimizedisruptions to running workloads, don't configure automatic key rotation forthese keys.

When you rotate the encryption keys for your control plane boot disks and etcd,GKE creates a new disk that's encrypted using the new key. Forregional clusters, this operation has no downtime because of the replicatedcontrol plane. For zonal clusters, the control plane becomes unavailable untilthe new disk is available.

Before you begin

Before you start, make sure that you have performed the following tasks:

• Enable the Google Kubernetes Engine API.
Enable Google Kubernetes Engine API
• If you want to use the Google Cloud CLI for this task,install and theninitialize the gcloud CLI. If you previously installed the gcloud CLI, get the latest version by running thegcloud components update command. Earlier gcloud CLI versions might not support running the commands in this document.Note: For existing gcloud CLI installations, make sure to set thecompute/regionproperty. If you use primarily zonal clusters, set thecompute/zone instead. By setting a default location, you can avoid errors in the gcloud CLI like the following:One of [--zone, --region] must be supplied: Please specify location. You might need to specify the location in certain commands if the location of your cluster differs from the default that you set.

• Have an existing cluster that usescontrol plane boot disk and etcd encryption

• Identify the project IDs of the following Google Cloud projects:

  • Key project: the project that contains your Cloud KMSresources.
  • Cluster project: the project that contains your GKEcluster.

• To do the validation tasks on this page, verify that theDATA_READ DataAccess audit log is enabled for the Cloud Key Management Service (KMS) API. For moreinformation, seeEnable Data Access audit logs.

Required roles and permissions

To get the permissions that you need to rotate your customer-managed CAs and keys, ask your administrator to grant you the following IAM roles:

• Manage keys or key versions:Cloud KMS Admin (roles/cloudkms.admin) on your key project
• Configure clusters to use new keys:Kubernetes Engine Cluster Admin (roles/container.clusterAdmin) on your cluster project

For more information about granting roles, seeManage access to projects, folders, and organizations.

You might also be able to get the required permissions throughcustom roles or otherpredefined roles.

Limitations

You can update your clusters to newversions of existing keys, but you can'tupdate your clusters to use entirely new keys for these encryption operations.

Grant IAM roles to the GKE service agent

To rotate your encryption keys for boot disks and etcd, grant theKubernetes Engine KMS Crypto Key User(roles/container.cloudKmsKeyUser) role on the encryption keys in your keyproject to the GKE service agent in your cluster project:

gcloudkmskeysadd-iam-policy-bindingKCP_DISK_KEY_NAME\--keyring=KEYRING_NAME\--location=LOCATION\--member="serviceAccount:service-CLUSTER_PROJECT_NUMBER@container-engine-robot.iam.gserviceaccount.com"\--role=roles/container.cloudKmsKeyUser\--project=KEY_PROJECT_ID

Replace the following:

• KCP_DISK_KEY_NAME: the name of the encryption keyfor your control plane boot disks and etcd disks.
• KEYRING_NAME: the name of the key ring thatholds the key.
• LOCATION: the Google Cloud location ofthe key ring. This must be the same as your cluster location. For a listof regions, filter for "Region" in theCloud KMS locations table.
• CLUSTER_PROJECT_NUMBER: the numerical projectnumber of the cluster project.
• KEY_PROJECT_ID: the project ID of yourkey project.

Rotate the key for etcd and control plane boot disks

1. Create a new primary key version for the boot disk and etcd encryption key:

   gcloudkmskeysversionscreate\--key=KCP_DISK_KEY_NAME\--keyring=KEYRING_NAME\--location=LOCATION\--project=KEY_PROJECT_ID\--primary

   It might take up to 10 minutes for the changes to propagate in the project.

2. Find the current patch version of the cluster control plane:

   gcloudcontainerclustersdescribeCLUSTER_NAME\--location=LOCATION\--format='value(currentMasterVersion)'

   Replace the following:

   • CLUSTER_NAME: the name of your GKEcluster.
   • LOCATION: the location of the GKEcluster control plane, such asus-central1.

3. Upgrade the cluster control plane to the same version that it alreadyuses.

   Caution: In zonal clusters, the control plane becomes unavailable until theupgrade operation completes. In Autopilot clusters and regionalStandard clusters, the control plane remains available.

   gcloudcontainerclustersupgradeCLUSTER_NAME\--master\--location=LOCATION\--cluster-version=CONTROL_PLANE_VERSION\--project=CLUSTER_PROJECT_ID

   Replace the following:

   • CONTROL_PLANE_VERSION: the version of the clustercontrol plane from the output of the previous step.
   • CLUSTER_PROJECT_ID: the project ID of yourcluster project.

After the control plane upgrade operation completes, the cluster uses the newkey version to encrypt your control plane boot disks and any etcd disks.

Rotate the etcd internal backup encryption key

This section shows you how to rotate the encryption key for the etcd internalbackup, which Google Cloud uses for disaster recovery purposes. You canconfigure automatic rotation for this key, but we recommend that you performmanual rotation instead. After you rotate the key, the cluster uses the newkey version to encrypt new etcd internal backups.

etcd internal backups use the primary key version and occur at the followingintervals:

• Every 30 minutes for zonal clusters.
• Every 10 minutes for Autopilot clusters and regionalStandard clusters.

After you rotate the key, don't immediately disable or destroy the previous keyversion. Wait until enough time has passed for GKE to create newetcd internal backups that use the new key version.

• Create a new primary key version for the etcd internal backup encryptionkey:

  gcloudkmskeysversionscreate\--key=ETCD_BACKUP_KEY_NAME\--keyring=KEYRING_NAME\--location=LOCATION\--project=KEY_PROJECT_ID\--primary

  Replace the following:

  • ETCD_BACKUP_KEY_NAME: the name of the etcdinternal backup encryption key.
  • KEYRING_NAME: the name of the key ring thatholds the key.
  • LOCATION: the Google Cloud location ofthe key ring. This must be the same as your cluster location. For a listof regions, filter for "Region" in theCloud KMS locations table.
  • KEY_PROJECT_ID: the project ID of yourkey project.

What's next

• Rotate customer-managed control plane CAs and keys
• Verify identity issuance and usage