Protect resources by using Cloud KMS keys

This document provides information about how to use manually-createdCloud Key Management Service Cloud KMS keys to encrypt disks andother storage-related resources. Keys managed in Cloud KMS are known ascustomer-managed encryption keys (CMEKs).

You can use CMEKs to encryptCompute Engine resources, such asdisks,machine images,instant snapshots andstandard snapshots.

To learn more about using customer-supplied encryption keys (CSEKs) to encryptdisks and other storage resources, seeEncrypting disks with customer-supplied encryption keys.

Learn moreAbout disk encryption.

Before you begin

Required roles

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 Compute Engine Service Agent theCloud KMS CryptoKey Encrypter/Decrypter (roles/cloudkms.cryptoKeyEncrypterDecrypter) IAM role on your project.Important: You must grant this role to the Compute Engine Service Agent,not to your user account. Failure to grant the role to the correct principal might result in permission errors. For more information about granting roles, seeManage access to projects, folders, and organizations.

Your administrator might also be able to give the Compute Engine Service Agent the required permissions throughcustom roles or otherpredefined roles.

The Compute Engine Service Agent has the following form:

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

You can use the Google Cloud CLI to assign the role:

gcloud projects add-iam-policy-bindingKMS_PROJECT_ID \    --member serviceAccount:service-PROJECT_NUMBER@compute-system.iam.gserviceaccount.com \    --role roles/cloudkms.cryptoKeyEncrypterDecrypter

Replace the following:

  • KMS_PROJECT_ID: the ID of yourGoogle Cloud project that runs Cloud KMS (even if this is thesame project running Compute Engine)
  • PROJECT_NUMBER: the project number(not Google Cloud project ID) of your Google Cloud project that runsthe Compute Engine resources

Encryption specifications

The Cloud KMS keys used to help protect your data in Compute Engineare AES-256 keys. These keys are key encryption keys, and they encrypt the dataencryption 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 specificationsrelated to the default encryption in Google Cloud, seeDefault encryption at restin the Security documentation.

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

Limitations

Manual or automated key creation

You can either create Cloud KMS keys manually or useCloud KMS Autokey.Autokey simplifies creating and managing Cloud KMS keys by automatingprovisioning and assignment. With Autokey, you don't need to provision keyrings, keys, and service accounts ahead of time. Instead, they are generated ondemand as part of Compute Engine resource creation. For moreinformation, see theAutokey overview.

Manually create key ring and key

For the Google Cloud project that runs Cloud KMS, create a key ringand a key as described inCreating 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 diskcreation.

Console

  1. In the Google Cloud console, go to theDisks page.

    Go to Disks

  2. ClickCreate disk and enter the properties for the new disk.
  3. UnderEncryption, selectCustomer-managed key.
  4. In the drop-down menu, select the Cloud KMS key that you wantto use to encrypt this disk.
  5. To create the disk, clickCreate.

gcloud

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

gcloud compute disks createDISK_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 theCloud KMS key
  • REGION: the region where the key is located
  • KEY_RING: the name of the key ring that includesthe key
  • KEY: the name of the key used to encrypt the disk
Note: If you're creating a regional Persistent Disk, you must assign thedisk replicas to two different zones by specifying the--replica-zonesflag.

REST

Construct aPOST request to theinstances.insert method.To encrypt a disk, use thediskEncryptionKey property with thekmsKeyName property. For example, you can encrypt a new disk duringVM 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 theGoogle Cloud project running Compute Engine
  • ZONE: the zone to create the VM in
  • MACHINE_TYPE: the machine type, for examplec3-standard-4
  • KMS_PROJECT_ID: the project that owns theCloud KMS key
  • REGION: the region where the disk is located
  • KEY_RING: the name of the key ring thatincludes the key
  • KEY: the name of the key used toencrypt the disk
  • SOURCE_IMAGE: the image to use when creating theVM, for example,projects/debian-cloud/global/images/debian-11-bullseye-v20231115

Similarly, you can use thedisks.insert methodto create a new standalone Persistent Disk and encrypt it with yourCloud 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 theGoogle Cloud project running Compute Engine
  • ZONE: the zone to create the disk in
  • SOURCE_IMAGE: the image to use when creating thedisk, 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 theCloud KMS key
  • REGION: the region where the disk is located
  • KEY_RING: the name of the key ring thatincludes the key
  • KEY: the name of the key used toencrypt the disk
  • DISK_TYPE: thetype of disk to create

Create a Hyperdisk Balanced disk in Confidential mode

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

Console

  1. In the Google Cloud console, go to theDisks page.

    Go to Disks

  2. ClickCreate disk and enter the properties for the new disk.
  3. In theDisk settings section, chooseHyperdisk Balanced for the disk type.
  4. Optional. Change the default diskSize,Provisioned IOPS, andProvisioned Throughput settings for the disk.
  5. In theEncryption section, selectCloud KMS key.
  6. In the list of keys, select the Cloud HSM key that you wantto use to encrypt this disk.
  7. In theConfidential Computing section, selectEnable Confidential Computing services.
  8. To create the disk, clickCreate.

gcloud

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

gcloud compute disks createDISK_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 theCloud HSM key
  • REGION: the region where the key is located
  • KEY_RING: the name of the key ring that includesthe key
  • KEY: the name of the key used to encrypt the disk

REST

Construct aPOST request to theinstances.insert method.To encrypt a disk with Confidential mode for Hyperdisk Balanced, use thediskEncryptionKey property with thekmsKeyName property and set theenableConfidentialCompute flag. For example,you can encrypt a new disk during VM creation with your Cloud HSM key byusing 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, forexample,hyperdisk-balanced
  • PROJECT_ID: the ID of the Google Cloud projectrunning Compute Engine
  • ZONE: the zone to create the VM in
  • MACHINE_TYPE: the machine type, for examplen2d-standard-4
  • KMS_PROJECT_ID: the project that owns theCloud HSM key
  • REGION: the region where the disk is located
  • KEY_RING: the name of the key ring that includesthe key
  • KEY: the name of the key used to encrypt the disk
  • SOURCE_IMAGE: the image that supportsConfidential VM to use when creating the VM, for example,projects/debian-cloud/global/images/debian-11-bullseye-v20231115

Similarly, you can use thedisks.insert methodto 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 theGoogle Cloud project running Compute Engine
  • ZONE: the zone to create the disk in
  • SOURCE_IMAGE: the image that supports Confidential VM when creating thedisk, 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 theCloud HSM key
  • REGION: the region where the disk is located
  • KEY_RING: the name of the key ring thatincludes the key
  • KEY: the name of the key used toencrypt the disk
  • DISK_TYPE: the type of disk to create, forexample,hyperdisk-balanced.

Create a snapshot from a disk encrypted with CMEK

To help protect a snapshot that you create from a disk encrypted with CMEK, youmust use 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 CMEKas well. Also, you can't convert CMEK-encrypted disks or snapshots to useGoogle Cloud default encryption unless youcreate a completely new disk image and a new persistent disk.

Snapshots from disks encrypted with CMEK areincremental.

Caution: If you try to create a snapshot from a diskand the snapshot creation process fails, you won't be able to delete the originaldisk until you capture a clean snapshot. This failsafehelps to prevent the accidental deletion of source data in the event of anunsuccessful backup.

Console

  1. In the Google Cloud console, go to theSnapshots page.

    Go to Snapshots

  2. ClickCreate snapshot.
  3. UnderSource disk, choose the source disk for the snapshot. Thesnapshot is automatically encrypted with the same key used by thesource disk.

gcloud

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

You can create your snapshot in the storage location policydefined by yoursnapshot settings orusing an alternative storage location of your choice. For more information, seeChoose your snapshot storage location.

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

    gcloud compute snapshots createSNAPSHOT_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 createSNAPSHOT_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 createSNAPSHOT_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, eitherSTANDARD orARCHIVE. If a snapshot type is not specified, aSTANDARD snapshot is created.

  • STORAGE_LOCATION: Optional: For globally scoped snapshots, theCloud Storage multi-region or theCloud 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. TheSTORAGE_LOCATION is automatically set to theSNAPSHOT_SCOPE_REGION.

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

REST

You can create your snapshot in the storage location policydefined by yoursnapshot settings orusing an alternative storage location of your choice. For more information, seeChoose your snapshot storage location.

  • To create a snapshot in the predefined or customized default location configured in your snapshot settings, make aPOST request to thesnapshots.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 aPOST request to thesnapshots.insert method and include thestorageLocations 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 aPOST request to thesnapshots.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, eitherSTANDARD orARCHIVE. If a snapshot type is not specified, aSTANDARD snapshot is created.

  • STORAGE_LOCATION: Optional: For globally scoped snapshots, theCloud Storage multi-region or theCloud Storage region where you want to store your snapshot. You can specify only one storage location.

    Use thestorageLocations 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 thestorageLocations parameter. TheSTORAGE_LOCATION is automatically set to theSNAPSHOT_SCOPE_REGION.

Note: Google recommends using thesnapshots.insert method instead of thedisks.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

You can encrypt a new image when youimport a custom image toCompute Engine. Before you can import an image, you mustcreate and compress a disk image fileandupload that compressed file to Cloud Storage.

Console

  1. In the Google Cloud console, go to theImages page.

    Go to Images

  2. ClickCreate image.
  3. ForSource disk, select the disk you want to create an image of.
  4. ForEncryption, selectCustomer-managed key.
  5. In the drop-down menu, select the Cloud KMS key that you wantto use to encrypt this image.
  6. Continue with the image creation process.

gcloud

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

gcloud compute images createIMAGE_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 snapshotof
  • KMS_PROJECT_ID: the project that contains theCloud KMS key
  • REGION: the region the Cloud KMS key islocated in
  • KEY_RING: the key ring that contains theCloud KMS key
  • KEY: the name of the key to use to encrypt the new disk

REST

To encrypt an imported image, construct aPOST request to theimages.insert method.Specify the URI to the compressed file, addtheimageEncryptionKey property to the image creation request, and specifythe key to encrypt the image in thekmsKeyName 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 imagein
  • IMAGE_NAME: the name of the image you're creating
  • KMS_PROJECT_ID: the project that contains theCloud KMS key
  • REGION: the region the Cloud KMS key islocated in
  • KEY_RING: the key ring that contains theCloud KMS key
  • KEY: the name of the key that you used toencrypt the source disk

Create a disk from a snapshot encrypted with CMEK

To create a new disk from an encrypted snapshot, do thefollowing:

Console

  1. In the Google Cloud console, go to theDisks page.

    Go to Disks

  2. ClickCreate disk and enter the properties for the new disk.
  3. ForSource type, select the snapshot or image you want to use.

  4. Optional: If you want to specify a new encryption key, forEncryption, specify the type of encryption key to use, and thenprovide the encryption key information.

    If you want to remove the customer managed or customersupplied encryption key, forEncryption, use the default valueGoogle-managed encryption key.

  5. Continue with the disk creation process.

gcloud

  • To create a new disk from a globally scopedencrypted snapshot, use thegcloud compute disks create command.

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

  • (Preview) To create a newdisk from a regionally scoped encrypted snapshot, usethegcloud compute disks create commandand specify the source snapshot region.

    gcloud compute disks createDISK_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-snapshotSNAPSHOT_NAME with--imageIMAGE_NAME.

  • KMS_PROJECT_ID: Optional: the project that containsthe Cloud KMS key

  • REGION: Optional: the region the Cloud KMSkey is located in

  • SOURCE_REGION: The region that the source snapshotis scoped to

  • ZONE: The zone where the new disk will reside

  • KEY_RING: Optional: the key ring that contains theCloud KMS key

  • KEY: Optional: the name of the Cloud KMS keyto 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 scopedencrypted snapshot, construct aPOST request to thecompute.disks.insert method.Use thesourceSnapshot 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 newdisk from a regionally scopedencrypted snapshot, construct aPOST request to thecompute.disks.insert method.Use thesourceSnapshot 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 snapshotis scoped to
  • DISK_NAME: The name of the new disk
  • DISK_TYPE: The full or partial URL for thetype of the disk, for example,PROJECT_ID/zones/ZONE/diskTypes/pd-ssd
  • SNAPSHOT_PROJECT_ID: The project that contains thesnapshot

  • SNAPSHOT_NAME: The name of the encrypted snapshot

    To use an image instead of a snapshot, replacesourceSnapshot withsourceImage.

  • KMS_PROJECT_ID: Optional: the project that containsthe Cloud KMS key

  • REGION: Optional: the region the Cloud KMSkey is located in

  • KEY_RING: Optional: the key ring that contains theCloud KMS key

  • KEY: Optional: the name of the Cloud KMS keyto use to encrypt the new disk

    If you includediskEncryptionKey, then the disk is encrypted withthe specified Cloud KMS key. If you don't includediskEncryptionKey, 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

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

    Go to Create an instance

  2. Specify the VM details, and in theBoot disk section, clickChange. Then, do the following:

    1. ClickExisting disks.
    2. In theDisk list, select an existing disk to attach to the VM.
    3. ClickSelect.

  3. Continue with the VM creation process.

gcloud

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

gcloud compute instances createVM_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 aPOST request to thecompute.instances.insert method.Use thedisks property to specify the encrypted boot disk, as shown in thefollowing 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 diskalias in the/dev/disk/by-id/google-* directory of VM that runs aLinux operating system. This name can be used to reference the disk foroperations such as mounting or resizing from within the instance. If you don'tspecify a device name, the VM chooses a default device name to apply tothis disk, in the formpersistent-disk-x, wherex is a numberassigned by Compute Engine. This field is only applicable forPersistent Disk volumes.
  • DISK_NAME: the name of the encrypted disk

Remove your Cloud KMS encryption key from a Persistent Disk

You can decrypt the contents of an encrypted disk and create a new disk thatuses Google Cloud default encryption instead. By default, Google Cloudencrypts all data at rest.

  1. Create a snapshot of the encrypted disk.
  2. Use the new encrypted snapshot tocreate a new persistent disk.

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

Rotate your Cloud KMS encryption key for a disk

Rotate the key that is used to encrypt the disk by creating a new disk that usesa new Cloud KMS key version. Rotating keys is abest practice tocomply with standardized security practices. To rotateyour keys, do the following:

  1. Rotate your Cloud KMS key.
  2. Create a snapshot of the encrypted disk.
  3. Use the new snapshot tocreate a new diskwith the key rotated in the preceding step.
  4. Replace the disk attached to your VM that uses the old encryption key.

When you create the new disk, it uses the new key version forencryption. Any snapshots that you create from that disk use the latest primarykey version.

When you rotate a key, data that was encrypted with previous key versions is notautomatically re-encrypted. For more information, seeRe-encrypting data. Rotating a key doesnot automaticallydisable ordestroy an existing key version.

Disable or delete a CMEK

If you no longer need a CMEK or want to prevent its use,deleteordisablethe key. Deleting, disabling, or removing IAM permissions on a key is alsoreferred to asrevoking the key.

Note: There is a delay of up to an hour between when you disable or deletethe key, during which it is still usable for encrypting and decrypting data. Youmay disable the Compute Engine Service Agent used to encrypt anddecrypt keys in order to apply the effects of disabling or deleting a key morequickly.Note: If a disk was attached to a VM when you revoked the disk's encryption key,the disk is still accessible from the VM until the VM shuts down. To triggerthe automatic shutdown of VMs that are attached to such disks,enable VM shutdown on key revocation.

Impact of key revocation on encrypted resources

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

  • You can't boot a VM if any of its attached disks have revoked keys.
  • If a disk that uses the key is attached to a running VM, and you enabledVM shutdown on key revocation for the VM,then Compute Engine shuts down the VM within 7 hours.
  • You can't attach a disk with a revoked key to a VM or create a snapshot fromthe disk.
  • You can't use images or snapshots that are encrypted with revoked keys tocreate disks.

If you disable the key, you can reverse the preceding effects by enabling thekey. If you delete 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 theCloud KMS key that is helping to protect a disk attached tothe VM. You can revoke a key bydisablingordeletingit. With this setting enabled, the VM shuts down within 7 hours of keyrevocation.

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

Console

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

  1. Begin creating a VM that includes a disk that is protected by aCloud KMS key.
  2. Open theNetworking, disks, security, management, sole-tenancy menu.
  3. Expand theManagement section.
  4. UnderCustomer Managed Encryption Key (CMEK) revocation policy,selectShut down.

gcloud

Use thegcloud compute instances createcommand to create a VM, andinclude--key-revocation-action-type=stop.

gcloud compute instances createVM_NAME \  --imageIMAGE \  --key-revocation-action-type=stop

REST

Use theinstances.insert methodto create a VM, and set the property"keyRevocationActionType" to"STOP". The following example creates theVM 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 aninstance templateto create VMs that shut down on key revocation by using theGoogle Cloud CLI or REST.

Console

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

  1. Begin creating a new instance template that includes a disk that isprotected by a Cloud KMS key.
  2. Open theNetworking, disks, security, management, sole-tenancy menu.
  3. Expand theManagement section.
  4. UnderCustomer Managed Encryption Key (CMEK) revocation policy,selectShutdown.

gcloud

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

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

REST

Construct a POST request to theinstanceTemplates.insert method.In the request body, you must explicitly define all of therequired configuration fields. If you want VMs created from this template toshut down on key revocation, specify"keyRevocationActionType":"STOP".For example, an instance template with the minimalrequired fields that will create VMs that shut down on key revocation lookslike 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 KMSrevocation,create andattach a Persistent Diskencrypted with a Cloud KMS key.

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-10-02 UTC.