# Encrypt a TPU VM boot disk with a customer-managed
encryption key (CMEK) with Compute Engine

By default, Cloud TPU encrypts customer content at
rest. Cloud TPU handles encryption for you without any
additional actions on your part. This option is called *Google default encryption*.

If you want to control your encryption keys, then you can use customer-managed encryption keys
(CMEKs) in [Cloud KMS](https://docs.cloud.google.com/kms/docs.md.txt) with CMEK-integrated services including
Cloud TPU. Using Cloud KMS keys gives you control over their protection
level, location, rotation schedule, usage and access permissions, and cryptographic boundaries.
Using Cloud KMS also lets
you view audit logs and control key lifecycles.

Instead of Google owning and managing the symmetric
[key encryption keys (KEKs)](https://docs.cloud.google.com/kms/docs/envelope-encryption.md.txt#key_encryption_keys) that protect your data, you control and
manage these keys in Cloud KMS.

After you set up your resources with CMEKs, the experience of accessing your
Cloud TPU resources is similar to using Google default encryption.
For more information about your encryption
options, see [Customer-managed encryption keys (CMEK)](https://docs.cloud.google.com/kms/docs/cmek.md.txt).

To use a CMEK, [create a key ring](https://docs.cloud.google.com/kms/docs/create-key-ring.md.txt#kms-create-key-ring-gcloud).
Create your key ring in the same location where you create
your TPU VM or slice. For example, a TPU VM in the `us-central1-a` zone can
only use a key in the `us-central1` region.

Next, [create a key](https://docs.cloud.google.com/kms/docs/create-key.md.txt) in your key ring. After creating a
CMEK, lets the Compute Engine service account access your
key.

## Grant permission to use the key

Grant the [Cloud KMS CryptoKey Encrypter/Decrypter](https://docs.cloud.google.com/kms/docs/reference/permissions-and-roles.md.txt#cloudkms.cryptoKeyEncrypterDecrypter)
(`roles/cloudkms.cryptoKeyEncrypterDecrypter`) IAM role on the
Cloud KMS key to the [Compute Engine service agent](https://docs.cloud.google.com/iam/docs/service-agents.md.txt#compute-engine-service-agent)
in your Google Cloud project. Granting this role lets the Compute Engine
service access and use your encryption key.

To grant the `roles/cloudkms.cryptoKeyEncrypterDecrypter` role to the
Compute Engine service agent, select one of the following options:

### gcloud

Run the following command:

```bash
gcloud kms keys add-iam-policy-binding KEY_NAME \
    --location LOCATION \
    --keyring RING_NAME \
    --member serviceAccount:service-PROJECT_NUMBER@compute-system.iam.gserviceaccount.com \
    --role roles/cloudkms.cryptoKeyEncrypterDecrypter \
    --project KEY_PROJECT_ID
```

Replace the following:

- <var translate="no">KEY_NAME</var>: The name of your key.
- <var translate="no">LOCATION</var>: The location where you created your key ring.
- <var translate="no">RING_NAME</var>: The name of your key ring.
- <var translate="no">PROJECT_NUMBER</var>: Your Google Cloud project number.
- <var translate="no">KEY_PROJECT_ID</var>: Your key project ID.

### Console

1. In the Google Cloud console, go to the **Key management** page.

   [Go to Key management](https://console.cloud.google.com/security/kms)
2. Click the key ring name that contains the key.

3. Click the key name that you want to modify.

4. Click **Permissions**.

5. Click **Grant Access** .
   The **Grant Access** pane opens.

6. In the **New principals** field, enter the Compute Engine service agent name:

       service-PROJECT_NUMBER@compute-system.iam.gserviceaccount.com

   Replace <var translate="no">PROJECT_NUMBER</var> with your Google Cloud project number.
7. In the **Select a role** menu, select **Cloud KMS CryptoKey
   Encrypter/Decrypter**.

8. Click **Save**.

## Create a TPU VM with a CMEK

You can specify a CMEK when creating a TPU VM or an instance template for a
managed instance group (MIG) by using the `--boot-disk-kms-key` flag.

### Create a single TPU VM instance with a CMEK

To specify a CMEK when creating a single TPU VM, use the `--boot-disk-kms-key`
flag in the `gcloud compute instances create` command:

```bash
  gcloud compute instances create TPU_NAME \
    --machine-type=MACHINE_TYPE \
    --image-family=IMAGE_FAMILY \
    --image-project=IMAGE_PROJECT \
    --zone=ZONE \
    --maintenance-policy=TERMINATE \
    --boot-disk-kms-key=projects/KEY_PROJECT_ID/locations/REGION/keyRings/RING_NAME/cryptoKeys/KEY_NAME
```

Replace the following placeholders:

- <var translate="no">TPU_NAME</var>: A name for your TPU VM.
- <var translate="no">MACHINE_TYPE</var>: The [machine type](https://docs.cloud.google.com/compute/docs/tpus/tpu-machines.md.txt#tpu_machine_types) for the TPU VM, for example, `ct6e-standard-8t`.
- <var translate="no">IMAGE_FAMILY</var>: The [OS image family](https://docs.cloud.google.com/compute/docs/images.md.txt#image_families) for the TPU VM. If you want to install a specific OS version, use the `--image` flag. For more information about OS images, see [OS images](https://docs.cloud.google.com/compute/docs/images.md.txt).
- <var translate="no">IMAGE_PROJECT</var>: The project that contains the OS image. For TPU images, this is `ubuntu-os-accelerator-images`.
- <var translate="no">ZONE</var>: The [zone](https://docs.cloud.google.com/tpu/docs/regions-zones.md.txt) for the TPU VM, for example, `us-central1-b`.
- <var translate="no">KEY_PROJECT_ID</var>: The project that contains the encryption key.
- <var translate="no">REGION</var>: The region where you created your key ring.
- <var translate="no">RING_NAME</var>: The name of your key ring.
- <var translate="no">KEY_NAME</var>: The name of your key.

> [!NOTE]
> **Note:** This example creates a TPU VM instance using the on-demand provisioning model. For information about using other provisioning models, see [Plan your TPU resources](https://docs.cloud.google.com/tpu/docs/plan-tpus.md.txt).

### Create a MIG with a single-host slice with a CMEK

To use a CMEK with a MIG, specify the key when you create the instance template.

1. Create an instance template using the `--boot-disk-kms-key` flag:

   ```bash
   gcloud compute instance-templates create INSTANCE_TEMPLATE_NAME \
       --machine-type=MACHINE_TYPE \
       --maintenance-policy=TERMINATE \
       --image-family=IMAGE_FAMILY \
       --image-project=IMAGE_PROJECT \
       --boot-disk-kms-key=projects/KEY_PROJECT_ID/locations/REGION/keyRings/RING_NAME/cryptoKeys/KEY_NAME
   ```

   Replace the following placeholders:
   - <var translate="no">INSTANCE_TEMPLATE_NAME</var>: A name for your instance template.
   - <var translate="no">MACHINE_TYPE</var>: The [machine type](https://docs.cloud.google.com/compute/docs/tpus/tpu-machines.md.txt#tpu_machine_types) for the TPU VM, for example, `ct6e-standard-8t`.
   - <var translate="no">IMAGE_FAMILY</var>: The [OS image family](https://docs.cloud.google.com/compute/docs/images.md.txt#image_families) for the TPU VM. If you want to install a specific OS version, use the `--image` flag. For more information about OS images, see [OS images](https://docs.cloud.google.com/compute/docs/images.md.txt).
   - <var translate="no">IMAGE_PROJECT</var>: The project that contains the OS image. For TPU images, this is `ubuntu-os-accelerator-images`.
   - <var translate="no">KEY_PROJECT_ID</var>: The project that contains the encryption key.
   - <var translate="no">REGION</var>: The region where you created your key ring.
   - <var translate="no">RING_NAME</var>: The name of your key ring.
   - <var translate="no">KEY_NAME</var>: The name of your key.

   > [!NOTE]
   > **Note:** This example creates an instance template using the on-demand provisioning model. For information about using other provisioning models, see [Plan your TPU resources](https://docs.cloud.google.com/tpu/docs/plan-tpus.md.txt).

2. Create a MIG using the template:

   ```bash
   gcloud compute instance-groups managed create MIG_NAME \
       --size=MIG_SIZE \
       --template=INSTANCE_TEMPLATE_NAME \
       --zone=ZONE \
       --size=MIG_SIZE
   ```

   Replace the following placeholders:
   - <var translate="no">MIG_NAME</var>: A name for your MIG.
   - <var translate="no">MIG_SIZE</var>: The number of TPU VMs in the MIG.
   - <var translate="no">INSTANCE_TEMPLATE_NAME</var>: The name of the instance template to use.
   - <var translate="no">ZONE</var>: The [zone](https://docs.cloud.google.com/tpu/docs/regions-zones.md.txt) for the TPU VM, for example, `us-central1-b`.
   - <var translate="no">MIG_SIZE</var>: The number of TPU VMs in the MIG. For a single-host TPU VM, set the size to 1.

### Create a MIG with a multi-host slice with a CMEK

When you create a multi-host slice MIG, specify the encryption key in the
instance template.

1. Create the instance template.

   ```bash
   gcloud compute instance-templates create INSTANCE_TEMPLATE_NAME
       --machine-type=MACHINE_TYPE \
       --maintenance-policy=TERMINATE \
       --image-family=IMAGE_FAMILY \
       --image-project=IMAGE_PROJECT \
       --boot-disk-kms-key=projects/KEY_PROJECT_ID/locations/REGION/keyRings/RING_NAME/cryptoKeys/KEY_NAME
   ```

   Replace the following placeholders:
   - <var translate="no">INSTANCE_TEMPLATE_NAME</var>: A name for your instance template.
   - <var translate="no">MACHINE_TYPE</var>: The [machine type](https://docs.cloud.google.com/compute/docs/tpus/tpu-machines.md.txt#tpu_machine_types) for the TPU VM, for example, `ct6e-standard-8t`.
   - <var translate="no">IMAGE_FAMILY</var>: The [OS image family](https://docs.cloud.google.com/compute/docs/images.md.txt#image_families) for the TPU VM. If you want to install a specific OS version, use the `--image` flag. For more information about OS images, see [OS images](https://docs.cloud.google.com/compute/docs/images.md.txt).
   - <var translate="no">IMAGE_PROJECT</var>: The project that contains the OS image. For TPU images, this is `ubuntu-os-accelerator-images`.
   - <var translate="no">KEY_PROJECT_ID</var>: The project that contains the encryption key.
   - <var translate="no">REGION</var>: The region where you created your key ring.
   - <var translate="no">RING_NAME</var>: The name of your key ring.
   - <var translate="no">KEY_NAME</var>: The name of your key.

   > [!NOTE]
   > **Note:** This example creates an instance template using the on-demand provisioning model. For information about using other provisioning models, see [Plan your TPU resources](https://docs.cloud.google.com/tpu/docs/plan-tpus.md.txt).

2. Create a workload policy.

   The following command creates a workload policy:

   ```bash
   gcloud compute resource-policies create workload WORKLOAD_POLICY_NAME \
   --type=high-throughput \
   --accelerator-topology=TOPOLOGY
   ```

   Replace the following placeholders:
   - <var translate="no">WORKLOAD_POLICY_NAME</var>: The name of your workload policy.
   - <var translate="no">TOPOLOGY</var>: The topology of the TPU VMs, for example, `4x4x8`.
3. Create the MIG.

   ```bash
   gcloud compute instance-groups managed create MIG_NAME \
       --size=MIG_SIZE \
       --target-size-policy-mode=bulk \
       --template=INSTANCE_TEMPLATE_NAME \
       --zone=ZONE \
       --default-action-on-vm-failure=do-nothing \
       --workload-policy=WORKLOAD_POLICY_NAME
   ```

   Replace the following placeholders:
   - <var translate="no">MIG_NAME</var>: The name of your MIG.
   - <var translate="no">MIG_SIZE</var>: The number of VMs in the MIG. This value is validated against the topology specified in the workload policy.
   - <var translate="no">INSTANCE_TEMPLATE_NAME</var>: The name of your instance template.
   - <var translate="no">ZONE</var>: The [zone](https://docs.cloud.google.com/tpu/docs/regions-zones.md.txt) for your MIG.
   - <var translate="no">WORKLOAD_POLICY_NAME</var>: The name of your workload policy.

For information about creating TPU VMs with CMEKs by using GKE,
see [Use customer-managed encryption keys](https://docs.cloud.google.com/kubernetes-engine/docs/how-to/using-cmek.md.txt)
in the GKE documentation.

## Deleted or revoked CMEKs

If a CMEK is revoked or deleted, any TPU VM that uses a boot disk encrypted
with the deleted or revoked CMEK does not automatically shut down. The TPU VM
still accesses data on the encrypted boot disk until you shut down or restart the VM.
This lets you recover your data if you restore access to a
revoked or deleted key. If you re-enable a key, you can start or repair your TPU
VM, and the boot disk successfully decrypts and loads.