Rotate a root key

This document describes how to rotate a root key. If your root key becomes compromised, or if you choose to periodically rotate root keys to enhance security, you can rotate your keys to a new root key using the RotationJob resource.

Rotating a root key creates a new root key, which becomes the primary key and wraps all non-root keys. You can't delete a root key; rotation is the only way to replace it. See Root key types for more information about root keys.

Refer to the KMS API overview for details on the KMS API and the Key Management Service KRM API to view the full API definition.

Before you begin

Before continuing, ensure you have the following:

  • The kubectl command configured to access the Management API server. To do this, get a kubeconfig file using the gdcloud command-line interface (CLI).

  • The KMS Rotation Job Admin role. To get the permissions that you need to rotate keys, ask your Organization IAM Admin to grant you the KMS Rotation Job Admin (kms-rotationjob-admin) role.

Rotate a root key

To create a new root key and rotate your keys, complete the following steps:

  1. Create a YAML file, and add in the RotationJob resource and the following contents:

    apiVersion: "kms.gdc.goog/v1"
kind: RotationJob
metadata:
  name: ROTATION_NAME
spec:
  rootKeyResourceName: ROOT_KEY_RESOURCE_NAME

    Replace ROTATION_NAME with a name for the rotation job — for example: rotate-job1.

    Replace ROOT_KEY_RESOURCE_NAME with the root key name specified in the form namespace/NAMESPACE/secrets/ROOT_KEY_NAME

    For example, namespaces/kms-system/secrets/ctm-root.

  2. Apply the contents of the YAML file to the KMS:

    kubectl apply -f FILENAME.yaml

    Replace FILENAME with the name of the YAML file.

    After running the command, the KMS creates a new root key and rotates every key with the new root key.

  3. To verify the root key rotation is complete, run the following:

    kubectl get rotationjobs ROTATION_NAME

    Replace ROTATION_NAME with the name of the rotation job.

    After running the command, you see the status of the rotation job as Completed if successful.

  4. Remove the Done annotation from the root key. Removing the annotation lets you rotate the key more than once. Your Infrastructure Operator (IO) must perform this step. Ask your IO to run the following:

    kubectl annotate secret kms-key-ROOT_KEY_NAME -n kms-system gdch.cluster.gke.io/rotation-status-