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 rotating a root key, you must have the necessary permissions and prepare your environment.

Request IAM roles

To rotate keys, contact your Organization IAM Admin to request the KMS Rotation Job Admin (kms-rotationjob-admin) role.

Prepare your environment

Rotate a root key

To rotate a root key, you first need to identify the resource name of the root key in use. You can find this information by examining any AEADKey resource within your project, as all these keys are protected by the same root key.

Create a new root key and rotate your keys:

  1. List the AEADKey resources in your project:

    kubectl get AEADKey -n PROJECT

    Replace PROJECT with the name of your project namespace.

    From the output, note the name of any AEADKey.

  2. Get the ROOT_KEY_RESOURCE_NAME from the AEADKey. The following command extracts and reformats the root key identifier needed for the RotationJob resource:

    kubectl describe aeadkey KEY_NAME -n PROJECT | grep "Root Key ID:" | awk '{print $4}' | awk -F/ '{print "namespaces/" $1 "/secrets/" $2}'

    Replace the following:

    • KEY_NAME: the name of any AEADKey in your project
    • PROJECT: the name of your project namespace

    The output might look similar to the following:

    namespaces/kms-system/secrets/kms-key-local-root

  3. 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 the following:

    • ROTATION_NAME: a name for the rotation job — for example: rotate-job1.
    • ROOT_KEY_RESOURCE_NAME: the output you obtained in the preceding step

  4. 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.

  5. 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.