Protect resources with Cloud KMS keys

This document provides information about how to use manually-created Cloud Key Management Service Cloud KMS keys to encrypt disks and other storage-related resources. Keys managed in Cloud KMS are known as customer-managed encryption keys (CMEKs). You can use CMEKs to encrypt Compute Engine resources, such as disks, machine images, instant snapshots, and standard snapshots.

Before you begin

Required roles and permissions

To ensure that the Compute Engine Service Agent has the necessary permissions to protect resources by using Cloud KMS keys, ask your administrator to grant the Cloud KMS CryptoKey Encrypter/Decrypter (roles/cloudkms.cryptoKeyEncrypterDecrypter) IAM role to the Compute Engine Service Agent on your project.

This predefined role contains the permissions required to protect resources by using Cloud KMS keys. To see the exact permissions that are required, expand the Required permissions section:

Your administrator might also be able to give the Compute Engine Service Agent these permissions with custom roles or other predefined roles.

Encryption specifications

The Cloud KMS keys used to help protect your data in Compute Engine are AES-256 keys. These keys are key encryption keys, and they encrypt the data encryption keys that encrypt your data, not the data itself.

The data on the disks is encrypted using Google-owned and Google-managed encryption keys. For specifications related to the default encryption in Google Cloud, see Default encryption at rest in the Security documentation.

With Confidential mode for Hyperdisk Balanced and Cloud HSM, the data encryption key (DEK) has additional security properties with hardware-backed enclaves.

Limitations

Manual or automated key creation

You can either create Cloud KMS keys manually or use Cloud KMS Autokey. Autokey simplifies creating and managing Cloud KMS keys by automating provisioning and assignment. With Autokey, you don't need to provision key rings, keys, and service accounts ahead of time. Instead, they are generated on demand as part of Compute Engine resource creation. For more information, see the Autokey overview.

Manually create key ring and key

For the Google Cloud project that runs Cloud KMS, create a key ring and a key as described in Creating key rings and keys.

Encrypt a new Persistent Disk with CMEK

You can encrypt a new Persistent Disk by supplying a key during VM or disk creation.

Console

In the Google Cloud console, go to the Disks page.
Go to Disks
Click Create disk and enter the properties for the new disk.
Under Encryption, select Customer-managed key.
In the drop-down menu, select the Cloud KMS key that you want to use to encrypt this disk.
To create the disk, click Create.

gcloud

Create an encrypted disk by using the gcloud compute disks create command, and specify the key using the --kms-key flag.

gcloud compute disks create DISK_NAME \
  --kms-key projects/KMS_PROJECT_ID/locations/REGION/keyRings/KEY_RING/cryptoKeys/KEY

Replace the following:

DISK_NAME: the name of the new disk
KMS_PROJECT_ID: the project that owns the Cloud KMS key
REGION: the region where the key is located
KEY_RING: the name of the key ring that includes the key
KEY: the name of the key used to encrypt the disk

REST

Construct a POST request to the instances.insert method. To encrypt a disk, use the diskEncryptionKey property with the kmsKeyName property. For example, you can encrypt a new disk during VM creation with your Cloud KMS key by using the following:

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances

{
"machineType": "zones/ZONE/machineTypes/MACHINE_TYPE",
"disks": [
 {
  "type": "PERSISTENT",
  "diskEncryptionKey": {
    "kmsKeyName": "projects/KMS_PROJECT_ID/locations/REGION/keyRings/KEY_RING/cryptoKeys/KEY"
  },
  "initializeParams": {
   "sourceImage": "SOURCE_IMAGE"
  },
  "boot": true
 }
],
...
}

Replace the following:

PROJECT_ID: the ID of the Google Cloud project running Compute Engine
ZONE: the zone to create the VM in
MACHINE_TYPE: the machine type, for example c3-standard-4
KMS_PROJECT_ID: the project that owns the Cloud KMS key
REGION: the region where the disk is located
KEY_RING: the name of the key ring that includes the key
KEY: the name of the key used to encrypt the disk
SOURCE_IMAGE: the image to use when creating the VM, for example, projects/debian-cloud/global/images/debian-11-bullseye-v20231115

Similarly, you can use the disks.insert method to create a new standalone Persistent Disk and encrypt it with your Cloud KMS key:

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/disks?sourceImage=SOURCE_IMAGE
{
 "name": "DISK_NAME",
 "diskEncryptionKey": {
   "kmsKeyName": "projects/KMS_PROJECT_ID/locations/REGION/keyRings/KEY_RING/cryptoKeys/KEY"
  },
 "type": "projects/PROJECT_ID/zones/ZONE/diskTypes/DISK_TYPE"
}

Replace the following:

PROJECT_ID: the ID of the Google Cloud project running Compute Engine
ZONE: the zone to create the disk in
SOURCE_IMAGE: the image to use when creating the disk, for example, projects/debian-cloud/global/images/debian-11-bullseye-v20231115
DISK_NAME: a name for the new disk
KMS_PROJECT_ID: the project that owns the Cloud KMS key
REGION: the region where the disk is located
KEY_RING: the name of the key ring that includes the key
KEY: the name of the key used to encrypt the disk
DISK_TYPE: the type of disk to create

Create a Hyperdisk Balanced disk in Confidential mode

You can create a new Hyperdisk Balanced disk in Confidential mode with the Google Cloud console, Google Cloud CLI, or REST. To create a disk that isn't in confidential mode, follow the steps in Create a Persistent Disk from a snapshot encrypted with CMEK.

Console

In the Google Cloud console, go to the Disks page.
Go to Disks
Click Create disk and enter the properties for the new disk.
In the Disk settings section, choose Hyperdisk Balanced for the disk type.
Optional. Change the default disk Size, Provisioned IOPS, and Provisioned Throughput settings for the disk.
In the Encryption section, select Cloud KMS key.
In the list of keys, select the Cloud HSM key that you want to use to encrypt this disk.
In the Confidential Computing section, select Enable Confidential Computing services.
To create the disk, click Create.

gcloud

Encrypt a new disk with Confidential mode for Hyperdisk Balanced by using the gcloud compute disks create command. Enable Confidential mode with the --confidential-compute flag and specify the key using the --kms-key flag.

gcloud compute disks create DISK_NAME \
  --type=hyperdisk-balanced \
  --kms-key projects/KMS_PROJECT_ID/locations/REGION/keyRings/KEY_RING/cryptoKeys/KEY \
  --confidential-compute

Replace the following:

DISK_NAME: the name of the new disk
KMS_PROJECT_ID: the project that owns the Cloud HSM key
REGION: the region where the key is located
KEY_RING: the name of the key ring that includes the key
KEY: the name of the key used to encrypt the disk

REST

Construct a POST request to the instances.insert method. To encrypt a disk with Confidential mode for Hyperdisk Balanced, use the diskEncryptionKey property with the kmsKeyName property and set the enableConfidentialCompute flag. For example, you can encrypt a new disk during VM creation with your Cloud HSM key by using the following:

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances

{
"machineType": "zones/ZONE/machineTypes/MACHINE_TYPE",
"disks": [
 {
  "type": "DISK_TYPE",
  "diskEncryptionKey": {
    "kmsKeyName": "projects/KMS_PROJECT_ID/locations/REGION/keyRings/KEY_RING/cryptoKeys/KEY"
  },
  "initializeParams": {
   "sourceImage": "SOURCE_IMAGE",
   "enableConfidentialCompute": true
  },
  "boot": true
 }
],
"networkInterfaces": [
  {
   "network": "global/networks/default"
  }
]
}

Replace the following:

DISK_TYPE: the type of disk to create, for example, hyperdisk-balanced
PROJECT_ID: the ID of the Google Cloud project running Compute Engine
ZONE: the zone to create the VM in
MACHINE_TYPE: the machine type, for example n2d-standard-4
KMS_PROJECT_ID: the project that owns the Cloud HSM key
REGION: the region where the disk is located
KEY_RING: the name of the key ring that includes the key
KEY: the name of the key used to encrypt the disk
SOURCE_IMAGE: the image that supports Confidential VM to use when creating the VM, for example, projects/debian-cloud/global/images/debian-11-bullseye-v20231115

Similarly, you can use the disks.insert method to create a new Confidential mode for Hyperdisk Balanced:

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/disks?sourceImage=SOURCE_IMAGE
{
 "name": "DISK_NAME",
 "diskEncryptionKey": {
   "kmsKeyName": "projects/KMS_PROJECT_ID/locations/REGION/keyRings/KEY_RING/cryptoKeys/KEY"
  },
 "type": "projects/PROJECT_ID/zones/ZONE/diskTypes/DISK_TYPE",
 "enableConfidentialCompute": true
}

Replace the following:

PROJECT_ID: the ID of the Google Cloud project running Compute Engine
ZONE: the zone to create the disk in
SOURCE_IMAGE: the image that supports Confidential VM when creating the disk, for example, projects/debian-cloud/global/images/debian-11-bullseye-v20231115
DISK_NAME: a name for the new disk
KMS_PROJECT_ID: the project that owns the Cloud HSM key
REGION: the region where the disk is located
KEY_RING: the name of the key ring that includes the key
KEY: the name of the key used to encrypt the disk
DISK_TYPE: the type of disk to create, for example, hyperdisk-balanced.

Create a snapshot from a disk encrypted with a CMEK

To create a snapshot from a disk that is encrypted with CMEK, you must create the snapshot with the same encryption key that you used to encrypt the disk.

You can't create a snapshot that uses a CMEK unless the source disk uses CMEK as well. Also, you can't convert CMEK-encrypted disks or snapshots to use Google Cloud default encryption unless you create a completely new disk image and a new persistent disk.

Console

In the Google Cloud console, go to the Snapshots page.
Go to Snapshots
Click Create snapshot.
Under Source disk, choose the source disk for the snapshot. The snapshot is automatically encrypted with the same key used by the source disk.

gcloud

For customer-managed encryption, the Cloud KMS key that was used to encrypt the disk is also used to encrypt the snapshot.

You can create your snapshot in the storage location policy defined by your snapshot settings or using an alternative storage location of your choice. For more information, see Choose your snapshot storage location.

To create a snapshot in the predefined or customized default location configured in your snapshot settings, use the gcloud compute snapshots create command.

gcloud compute snapshots create SNAPSHOT_NAME \
    --source-disk-zone=SOURCE_ZONE \
    --source-disk=SOURCE_DISK_NAME \
    --snapshot-type=SNAPSHOT_TYPE

Alternatively, to override the snapshot settings and create a snapshot in a custom storage location, include the --storage-location flag to indicate where to store your snapshot.

gcloud compute snapshots create SNAPSHOT_NAME \
    --source-disk-zone=SOURCE_ZONE \
    --source-disk=SOURCE_DISK_NAME \
    --snapshot-type=SNAPSHOT_TYPE \
    --storage-location=STORAGE_LOCATION

(Preview) To create a regionally scoped snapshot in an allowed region, include the --region flag to indicate where to create your snapshot.

  gcloud beta compute snapshots create SNAPSHOT_NAME \
      --region=SNAPSHOT_SCOPE_REGION
      --source-disk=SOURCE_DISK_NAME \
      --source-disk-zone=SOURCE_ZONE \
      --snapshot-type=SNAPSHOT_TYPE \
      --kms-key=projects/KMS_PROJECT_ID/locations/KEY_REGION/keyRings/KEY_RING/cryptoKeys/SNAPSHOT_KEY

Replace the following:

SNAPSHOT_NAME: A name for the snapshot.
SOURCE_ZONE: The zone of the source disk.
SOURCE_DISK_NAME: The name of the disk volume from which you want to create a snapshot.
KMS_PROJECT_ID: The project that contains the encryption key that is stored in Cloud Key Management Service.
KEY_REGION: The region where the Cloud KMS key is located.
KEY_RING: The name of the key ring that contains the Cloud KMS key.
SNAPSHOT_KEY: The name of the Cloud KMS key that you used to encrypt the source disk.
SNAPSHOT_TYPE: The snapshot type, either STANDARD or ARCHIVE. If a snapshot type is not specified, a STANDARD snapshot is created.
STORAGE_LOCATION: Optional: For globally scoped snapshots, the Cloud Storage multi-region or the Cloud Storage region where you want to store your snapshot. You can specify only one storage location.

Use the --storage-location parameter only when you want to override the predefined or customized default storage location configured in your snapshot settings.
SNAPSHOT_SCOPE_REGION: Optional: For regionally scoped snapshots, the region that the snapshot is scoped to. If you include this parameter, you can't use the --storage-location parameter. The STORAGE_LOCATION is automatically set to the SNAPSHOT_SCOPE_REGION.

Note: Google recommends using the gcloud compute snapshots create command instead of the gcloud compute disks snapshot command because it supports more features, such as creating snapshots in a project different from the source disk project.

REST

To create a snapshot in the predefined or customized default location configured in your snapshot settings, make a POST request to the snapshots.insert method:

POST https://compute.googleapis.com/compute/v1/projects/DESTINATION_PROJECT_ID/global/snapshots
{
    "name": "SNAPSHOT_NAME",
    "sourceDisk": "projects/SOURCE_PROJECT_ID/zones/SOURCE_ZONE/disks/SOURCE_DISK_NAME",
    "snapshotEncryptionKey":  {
     "kmsKeyName": "projects/KMS_PROJECT_ID/locations/KEY_REGION/keyRings/KEY_RING/cryptoKeys/SNAPSHOT_KEY"
    },
    "snapshotType": "SNAPSHOT_TYPE"
}

Alternatively, to override the snapshot settings and create a snapshot in a custom storage location, make a POST request to the snapshots.insert method and include the storageLocations property in your request:

POST https://compute.googleapis.com/compute/v1/projects/DESTINATION_PROJECT_ID/global/snapshots
{
    "name": "SNAPSHOT_NAME",
    "sourceDisk": "projects/SOURCE_PROJECT_ID/zones/SOURCE_ZONE/disks/SOURCE_DISK_NAME",
    "snapshotEncryptionKey":  {
     "kmsKeyName": "projects/KMS_PROJECT_ID/locations/KEY_REGION/keyRings/KEY_RING/cryptoKeys/SNAPSHOT_KEY"
    },
    "snapshotType": "SNAPSHOT_TYPE",
    "storageLocations": [
        "STORAGE_LOCATION"
    ],
}

(Preview) To create a regionally scoped snapshot in an allowed region, make a POST request to the snapshots.insert method and define the creation region:

POST https://compute.googleapis.com/compute/beta/projects/DESTINATION_PROJECT_ID/regions/SNAPSHOT_SCOPE_REGION/snapshots
{
  "name": "SNAPSHOT_NAME",
  "sourceDisk": "projects/SOURCE_PROJECT_ID/regions/SOURCE_REGION/disks/SOURCE_DISK_NAME",
  "snapshotType": "SNAPSHOT_TYPE",
  "snapshotEncryptionKey": {
    "kmsKeyName":"projects/KMS_PROJECT_ID/locations/KEY_REGION/keyRings/KEY_RING/cryptoKeys/SNAPSHOT_KEY",
  },
}

Replace the following:

DESTINATION_PROJECT_ID: The ID of project in which you want to create the snapshot.
SNAPSHOT_NAME: A name for the snapshot.
SOURCE_PROJECT_ID: The ID of the source disk project.
SOURCE_ZONE: The zone of the source disk.
SOURCE_DISK_NAME: The name of the disk from which you want to create a snapshot.
KMS_PROJECT_ID: The project that contains the encryption key that is stored in Cloud Key Management Service.
KEY_REGION: The region where the Cloud KMS key is located.
KEY_RING: The name of the key ring that contains the Cloud KMS key.
SNAPSHOT_KEY: The name of the Cloud KMS key that you used to encrypt the source disk.
SNAPSHOT_TYPE: The snapshot type, either STANDARD or ARCHIVE. If a snapshot type is not specified, a STANDARD snapshot is created.
STORAGE_LOCATION: Optional: For globally scoped snapshots, the Cloud Storage multi-region or the Cloud Storage region where you want to store your snapshot. You can specify only one storage location.

Use the storageLocations parameter only when you want to override the predefined or customized default storage location configured in your snapshot settings.
SNAPSHOT_SCOPE_REGION: Optional: For regionally scoped snapshots, the region that the snapshot is scoped to. If you include this parameter, you can't use the storageLocations parameter. The STORAGE_LOCATION is automatically set to the SNAPSHOT_SCOPE_REGION.

Note: Google recommends using the snapshots.insert method instead of the disks.createSnapshot method because it supports more features, such as creating snapshots in a project different from the source disk project.

Encrypt an imported image with CMEK

Console

In the Google Cloud console, go to the Images page.
Go to Images
Click Create image.
For Source disk, select the disk you want to create an image of.
For Encryption, select Customer-managed key.
In the drop-down menu, select the Cloud KMS key that you want to use to encrypt this image.
Continue with the image creation process.

gcloud

To import and encrypt an image, use the gcloud compute images create command. For customer-managed encryption, specify the Cloud KMS key for the image.

gcloud compute images create IMAGE_NAME \
    --source-disk=SOURCE_DISK  \
    --kms-key projects/KMS_PROJECT_ID/locations/REGION/keyRings/KEY_RING/cryptoKeys/KEY

Replace the following:

IMAGE_NAME: the name of the image you're creating
SOURCE_DISK: the name of the disk to create a snapshot of
KMS_PROJECT_ID: the project that contains the Cloud KMS key
REGION: the region the Cloud KMS key is located in
KEY_RING: the key ring that contains the Cloud KMS key
KEY: the name of the key to use to encrypt the new disk

REST

To encrypt an imported image, construct a POST request to the images.insert method. Specify the URI to the compressed file, add the imageEncryptionKey property to the image creation request, and specify the key to encrypt the image in the kmsKeyName property.

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/global/images

{
 "rawDisk": {
  "source": "http://storage.googleapis.com/example-image/example-image.tar.gz"
  },
 "name": "IMAGE_NAME",
 "sourceType": "RAW",
 "imageEncryptionKey": {
   "kmsKeyName": "projects/KMS_PROJECT_ID/locations/REGION/keyRings/KEY_RING/cryptoKeys/KEY"
   }
}

Replace the following:

PROJECT_ID: the project to create the encrypted image in
IMAGE_NAME: the name of the image you're creating
KMS_PROJECT_ID: the project that contains the Cloud KMS key
REGION: the region the Cloud KMS key is located in
KEY_RING: the key ring that contains the Cloud KMS key
KEY: the name of the key that you used to encrypt the source disk

Create a disk from a snapshot encrypted with CMEK

Console

In the Google Cloud console, go to the Disks page.
Go to Disks
Click Create disk and enter the properties for the new disk.
For Source type, select the snapshot or image you want to use.
Optional: If you want to specify a new encryption key, for Encryption, specify the type of encryption key to use, and then provide the encryption key information.

If you want to remove the customer managed or customer supplied encryption key, for Encryption, use the default value Google-managed encryption key.
Continue with the disk creation process.

gcloud

To create a new disk from a globally scoped encrypted snapshot, use the gcloud compute disks create command.

gcloud compute disks create DISK_NAME \
  --zone=ZONE \
  --source-snapshot=SNAPSHOT_NAME \
  --kms-key=projects/KMS_PROJECT_ID/locations/REGION/keyRings/KEY_RING/cryptoKeys/KEY

(Preview) To create a new disk from a regionally scoped encrypted snapshot, use the gcloud compute disks create command and specify the source snapshot region.

gcloud compute disks create DISK_NAME \
  --zone=ZONE \
  --source-snapshot=SNAPSHOT_NAME \
  --source-snapshot-region=SOURCE_REGION \
  --kms-key=projects/KMS_PROJECT_ID/locations/REGION/keyRings/KEY_RING/cryptoKeys/KEY

Replace the following:

DISK_NAME: the name of the new disk
SNAPSHOT_NAME: the name of the encrypted snapshot

To use an image instead of a snapshot, replace --source-snapshot SNAPSHOT_NAME with --image IMAGE_NAME.
KMS_PROJECT_ID: Optional: the project that contains the Cloud KMS key
REGION: Optional: the region the Cloud KMS key is located in
SOURCE_REGION: The region that the source snapshot is scoped to
ZONE: The zone where the new disk will reside
KEY_RING: Optional: the key ring that contains the Cloud KMS key
KEY: Optional: the name of the Cloud KMS key to use to encrypt the new disk

To encrypt the new disk, you can do one of the following:
- To specify a new customer managed encryption key, use the --kms-key flag.
- To use the default Google-owned and Google-managed encryption key, don't include the --kms-key flag.

REST

To create a new disk from a globally scoped encrypted snapshot, construct a POST request to the compute.disks.insert method. Use the sourceSnapshot property to specify the snapshot.

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/disks

{
  "name": "DISK_NAME",
  "sourceSnapshot": "projects/SNAPSHOT_PROJECT_ID/global/snapshots/SNAPSHOT_NAME",
  "diskEncryptionKey": {
    "kmsKeyName": "projects/KMS_PROJECT_ID/locations/REGION/keyRings/KEY_RING/cryptoKeys/KEY"
  }
}

(Preview) To create a new disk from a regionally scoped encrypted snapshot, construct a POST request to the compute.disks.insert method. Use the sourceSnapshot property to specify the snapshot.

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/disks

{
  "name": "DISK_NAME",
  "sourceSnapshot": "projects/SNAPSHOT_PROJECT_ID/regions/SOURCE_REGION/snapshots/SNAPSHOT_NAME",
  "type": "projects/PROJECT_ID/zones/ZONE/diskTypes/DISK_TYPE",
  "zone": "projects/PROJECT_ID/zones/ZONE"
  "diskEncryptionKey": {
    "kmsKeyName": "projects/KMS_PROJECT_ID/locations/REGION/keyRings/KEY_RING/cryptoKeys/KEY"
  }
}

Replace the following:

PROJECT_ID: The project to create the new disk in
ZONE: The zone to create the new disk in
SOURCE_REGION: The region that the source snapshot is scoped to
DISK_NAME: The name of the new disk
DISK_TYPE: The full or partial URL for the type of the disk, for example, PROJECT_ID/zones/ZONE/diskTypes/pd-ssd
SNAPSHOT_PROJECT_ID: The project that contains the snapshot
SNAPSHOT_NAME: The name of the encrypted snapshot

To use an image instead of a snapshot, replace sourceSnapshot with sourceImage.
KMS_PROJECT_ID: Optional: the project that contains the Cloud KMS key
REGION: Optional: the region the Cloud KMS key is located in
KEY_RING: Optional: the key ring that contains the Cloud KMS key
KEY: Optional: the name of the Cloud KMS key to use to encrypt the new disk

If you include diskEncryptionKey, then the disk is encrypted with the specified Cloud KMS key. If you don't include diskEncryptionKey, then the disk is encrypted using a Google-owned and Google-managed encryption key.

Attaching a boot disk encrypted with CMEK to a new VM

Console

In the Google Cloud console, go to the Create an instance page.

Go to Create an instance
Specify the VM details, and in the Boot disk section, click Change. Then, do the following:
1. Click Existing disks.
2. In the Disk list, select an existing disk to attach to the VM.
3. Click Select.
Continue with the VM creation process.

gcloud

To attach an encrypted disk when you create a new VM, use the gcloud compute instances create command. Use the --disk flag to specify the encrypted boot disk, as shown in the following example:

gcloud compute instances create VM_NAME \
  ...
  --disk name=DISK_NAME,boot=yes

Replace the following:

VM_NAME: the name of the VM you are creating
DISK_NAME: the name of the encrypted disk

REST

Construct a POST request to the compute.instances.insert method. Use the disks property to specify the encrypted boot disk, as shown in the following example:

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances
{
  ...
  "disks": [
    {
      "deviceName": "DISK_ALIAS",
      "source": "projects/PROJECT_ID/zones/ZONE/disks/DISK_NAME"
    }
  ]
}

Replace the following:

PROJECT_ID: the project to create the new VM in
ZONE: the zone to create the new VM in
DISK_ALIAS: a unique device name to use as the disk alias in the /dev/disk/by-id/google-* directory of VM that runs a Linux operating system. This name can be used to reference the disk for operations such as mounting or resizing from within the instance. If you don't specify a device name, the VM chooses a default device name to apply to this disk, in the form persistent-disk-x, where x is a number assigned by Compute Engine. This field is only applicable for Persistent Disk volumes.
DISK_NAME: the name of the encrypted disk

Rotate the CMEK for a disk or snapshot

To reduce the potential consequences of your key being compromised, we recommend that you rotate Cloud KMS encryption keys on a regular schedule using one of the following methods.

gcloud

To rotate the Cloud KMS key that's used to encrypt a disk, an archive snapshot, or a standard snapshot to a new key version, use the gcloud compute disks update-kms-key command or gcloud compute snapshots update-kms-key command.

To rotate the key version encrypting a disk:

gcloud compute disks update-kms-key DISK_NAME \
--zone ZONE

To rotate the key version encrypting a standard snapshot:
```
gcloud compute snapshots update-kms-key SNAPSHOT_NAME
```

Replace the following:

DISK_NAME: the name of the encrypted disk
ZONE: the zone where the encrypted disk is located
SNAPSHOT_NAME: the name of the encrypted snapshot

REST

To rotate the Cloud KMS key that's used to encrypt a disk, archive snapshot, or standard snapshot to a new key version, construct a PATCH request to the compute.disks.updateKmsKey method or compute.snapshots.updateKmsKey method.

To rotate the key version encrypting a zonal disk:

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/disks/DISK_NAME/updateKmsKey

To rotate the key version encrypting a regional disk:

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION/disks/DISK_NAME/updateKmsKey

To rotate the key version encrypting a globally scoped standard snapshot:

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/global/snapshots/SNAPSHOT_NAME/updateKmsKey

(Preview) To rotate the key version encrypting a regionally scoped standard snapshot:

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION/snapshots/SNAPSHOT_NAME/updateKmsKey

Replace the following:

PROJECT_ID: the project where the encrypted disk or snapshot is located
ZONE: the zone where the encrypted disk is located
REGION: the region where the regional disk or regionally scoped snapshot is located
DISK_NAME: the name of the encrypted disk
SNAPSHOT_NAME: the name of the encrypted snapshot
REGION: the region where the regional disk or regionally scoped snapshot is located

The response will include a name item with an operation value that represents the key rotation:

  "name": "operation-YYYYYYYYYYYYY-YYYYYYYYYYYYY-YYYYYYYY-YYYYYYYY"

You can then poll the status for the operation to determine if your API call was successful by making a GET request:

  GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/operations/OPERATION_NAME

Replace the following:

PROJECT_ID: the project where the encrypted disk or snapshot is located
ZONE: the zone where the encrypted disk is located
OPERATION_NAME: the name of the CMEK rotation operation, in the format operation-YYYYYYYYYYYYY-YYYYYYYYYYYYY-YYYYYYYY-YYYYYYYY

The response will include a progress value that represents the status of the key rotation. When progress is 100, the operation succeeded.

Rotating keys doesn't disable or delete previous key versions. For more information, see After you rotate keys.

Change the CMEK for a disk or snapshot

You can change the encryption of a disk, an archive snapshot, or a standard snapshot to a different CMEK (for example, during a project migration or to meet new compliance requirements) without downtime.

Changing the CMEK re-encrypts the resource's data encryption key (DEK) with the new key. This process doesn't change the DEK and doesn't impact performance on running workloads.

gcloud

To change the Cloud KMS key for a disk or standard snapshot, use the --kms-key flag with the gcloud compute disks update-kms-key command or gcloud compute snapshots update-kms-key command.

To change the key for a zonal disk:

gcloud compute disks update-kms-key DISK_NAME \
--kms-key=projects/KEY_PROJECT_ID/locations/global/keyRings/KEY_RING/cryptoKeys/NEW_KEY_NAME \
--zone=ZONE

To change the key for a regional disk:

gcloud compute disks update-kms-key DISK_NAME \
--kms-key=projects/KEY_PROJECT_ID/locations/global/keyRings/KEY_RING/cryptoKeys/NEW_KEY_NAME \
--region=REGION

To change the key for a global snapshot:

gcloud compute snapshots update-kms-key SNAPSHOT_NAME \
--kms-key=projects/KEY_PROJECT_ID/locations/global/keyRings/KEY_RING/cryptoKeys/NEW_KEY_NAME

To change the key for a regionally scoped snapshot:

gcloud beta compute snapshots update-kms-key SNAPSHOT_NAME \
--kms-key=projects/KEY_PROJECT_ID/locations/global/keyRings/KEY_RING/cryptoKeys/NEW_KEY_NAME \
--regions=REGION

Replace the following:

DISK_NAME: the name of the encrypted disk.
NEW_KMS_KEY: the full resource ID of the new CMEK.
ZONE: the zone where the disk is located.
REGION: the region where the disk or snapshot is located.
SNAPSHOT_NAME: the name of the encrypted snapshot.

REST

To change the key, send a POST request to the compute.disks.updateKmsKey method or compute.snapshots.updateKmsKey method and include the kmsKeyName in the request body.

To change the key for a zonal disk:

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/disks/DISK_NAME/updateKmsKey

{
"kmsKeyName": "projects/KEY_PROJECT_ID/locations/global/keyRings/KEY_RING/cryptoKeys/NEW_KEY_NAME"
}

To change the key for a regional disk:

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION/disks/DISK_NAME/updateKmsKey

{
"kmsKeyName": "projects/KEY_PROJECT_ID/locations/global/keyRings/KEY_RING/cryptoKeys/NEW_KEY_NAME"
}

To change the key for a global snapshot:

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/global/snapshots/SNAPSHOT_NAME/updateKmsKey

{
"kmsKeyName": "projects/KEY_PROJECT_ID/locations/global/keyRings/KEY_RING/cryptoKeys/NEW_KEY_NAME"
}

To change the key for a regionally scoped snapshot:

POST https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/regions/REGION/snapshots/SNAPSHOT_NAME/updateKmsKey

{
"kmsKeyName": "projects/KEY_PROJECT_ID/locations/global/keyRings/KEY_RING/cryptoKeys/NEW_KEY_NAME"
}

Replace the following:

PROJECT_ID: the project containing the disk or snapshot.
ZONE: the zone where the disk is located.
REGION: the region where the disk or snapshot is located.
DISK_NAME: the name of the disk.
NEW_KEY_NAME: the name of the new CMEK.
SNAPSHOT_NAME: the name of the encrypted snapshot.

Remove the CMEK from a disk

You can't remove a CMEK from a disk or change the encryption key's type. You can do one of the following:

To create a disk that uses Google-owned and managed key from a CMEK-encrypted disk, follow these steps:

After you create the new disk, it uses Google Cloud default encryption to help protect the disk contents. Any snapshots that you create from that disk must also use default encryption.

Remove the CMEK from a snapshot

You can't remove a CMEK from a snapshot or change the encryption key's type. You can change the snapshot to use a different CMEK, or create a copy of the snapshot and encrypt the copy with a Google-owned and managed key.

To create a snapshot that uses Google-owned and managed key from a CMEK-encrypted snapshot, follow these steps:

Disable or destroy a CMEK

If you no longer need a CMEK or want to prevent its use, disable or destroy the key. Deleting, disabling, or removing IAM permissions on a key is also referred to as revoking the key.

Impact of key revocation on encrypted resources

When you revoke an encryption key, resources that the key protects are affected as follows:

If you disable the key, you can reverse the preceding effects by enabling the key. If you destroy the key, you cannot reverse the preceding effects.

Configure VM shutdown on Cloud KMS key revocation

You can configure your VM to shutdown automatically when you revoke the Cloud KMS key that is helping to protect a disk attached to the VM. You can revoke a key by disabling or deleting it. With this setting enabled, the VM shuts down within 7 hours of key revocation.

If you enable the key again, you can restart the VM with the attached disk that the key helps to protect. The VM does not automatically restart after you enable the key.

Console

To configure a VM to shutdown when a Cloud KMS key is revoked, do the following:

Begin creating a VM that includes a disk that is protected by a Cloud KMS key.
Open the Networking, disks, security, management, sole-tenancy menu.
Expand the Management section.
Under Customer Managed Encryption Key (CMEK) revocation policy, select Shut down.

gcloud

Use the gcloud compute instances create command to create a VM, and include --key-revocation-action-type=stop.

gcloud compute instances create VM_NAME \
  --image IMAGE \
  --key-revocation-action-type=stop

REST

Use the instances.insert method to create a VM, and set the property "keyRevocationActionType" to "STOP". The following example creates the VM from a public image.

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances

{
  "machineType": "zones/MACHINE_TYPE_ZONE/machineTypes/MACHINE_TYPE",
  "name": "VM_NAME",
  "disks": [
    {
      "initializeParams": {
        "sourceImage": "projects/IMAGE_PROJECT/global/images/IMAGE"
      },
      "boot": true
    }
  ],
  "keyRevocationActionType": "STOP"
}

Alternatively, you can configure an instance template to create VMs that shut down on key revocation by using the Google Cloud CLI or REST.

Console

You can use an instance template to create VMs that shutdown when a Cloud KMS key is revoked.

Begin creating a new instance template that includes a disk that is protected by a Cloud KMS key.
Open the Networking, disks, security, management, sole-tenancy menu.
Expand the Management section.
Under Customer Managed Encryption Key (CMEK) revocation policy, select Shutdown.

gcloud

Create an instance template by using the gcloud compute instance-templates create command, and include --key-revocation-action-type=stop.

gcloud compute instance-templates create INSTANCE_TEMPLATE_NAME \
  --key-revocation-action-type=stop

REST

Construct a POST request to the instanceTemplates.insert method. In the request body, you must explicitly define all of the required configuration fields. If you want VMs created from this template to shut down on key revocation, specify "keyRevocationActionType":"STOP". For example, an instance template with the minimal required fields that will create VMs that shut down on key revocation looks like the following:

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instanceTemplates

{
  "name": "example-template",
  "properties": {
  "machineType": "e2-standard-4",
  "networkInterfaces": [
    {
      "network": "global/networks/default",
      "accessConfigs": [
        {
          "name": "external-IP",
          "type": "ONE_TO_ONE_NAT"
        }
      ]
    }
  ],
  "disks":
  [
    {
      "type": "PERSISTENT",
      "boot": true,
      "mode": "READ_WRITE",
      "initializeParams":
      {
        "sourceImage": "projects/debian-cloud/global/images/family/debian-11"
      }
    }
  ],
  "keyRevocationActionType": "STOP"
  }
}

After you create a VM that is configured to shut down on Cloud KMS revocation, create and attach a Persistent Disk encrypted with a Cloud KMS key.

Protect resources with Cloud KMS keys Stay organized with collections Save and categorize content based on your preferences.

Before you begin

Console

gcloud

REST

Required roles and permissions

Required permissions

Encryption specifications

Limitations

Manual or automated key creation

Manually create key ring and key

Encrypt a new Persistent Disk with CMEK

Console

gcloud

REST

Create a Hyperdisk Balanced disk in Confidential mode

Console

gcloud

REST

Create a snapshot from a disk encrypted with a CMEK

Permissions required for this task

Console

gcloud

REST

Encrypt an imported image with CMEK

Console

gcloud

REST

Create a disk from a snapshot encrypted with CMEK

Console

gcloud

REST

Attaching a boot disk encrypted with CMEK to a new VM

Console

gcloud

REST

Rotate the CMEK for a disk or snapshot

gcloud

REST

Change the CMEK for a disk or snapshot

gcloud

REST

Remove the CMEK from a disk

Remove the CMEK from a snapshot

Disable or destroy a CMEK

Impact of key revocation on encrypted resources

Configure VM shutdown on Cloud KMS key revocation

Console

gcloud

REST

Console

gcloud

REST

What's next