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`](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/apis/service/kms/kms-api-overview.md.txt#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](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/platform/pa-user/kms/kms.md.txt#root_key_types) for more
information about root keys.

Refer to the [KMS API overview](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/apis/kms-api-overview) for details
on the KMS API and the [Key Management Service KRM API](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/apis/kms-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 IAM Org Admin to request the
**KMS Rotation Job Admin** (`kms-rotationjob-admin`) role.

### Prepare your environment

- [Download](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/resources/gdcloud-download.md.txt) and
  [install](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/resources/gdcloud-install.md.txt) the gdcloud CLI,
  if you haven't already done so.

- [Install the kubectl CLI](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/get-started/kubectl.md.txt).

- [Generate a kubeconfig file](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/resources/gdcloud-auth.md.txt#get-kubeconfig)
  to configure `kubectl` access.

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

   ```bash
   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:

   ```bash
   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:

   ```yaml
   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:

   ```bash
   kubectl apply -f FILENAME.yaml
   ```

   Replace <var translate="no">FILENAME</var> 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:

   ```bash
   kubectl get rotationjobs ROTATION_NAME
   ```

   Replace <var translate="no">ROTATION_NAME</var> with the name of the rotation job.

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