Protect resources by using 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.

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

Learn more About disk encryption.

Before you begin

  • Understand disks, images, persistent disk snapshots, and virtual machine (VM) instances.

  • Decide whether you are going to run Compute Engine and Cloud KMS in the same Google Cloud project, or in different projects. For information about Google Cloud project IDs and project numbers, see Identifying projects.

  • For the Google Cloud project that runs Cloud KMS, do the following:

    1. Enable the Cloud KMS API.

      Enable the API

  • + If you want to create a new Hyperdisk Balanced volume in Confidential mode, ensure your use case is supported by reviewing the relevant Limitations and supported regions.
  • If you haven't already, then set up authentication. Authentication is the process by which your identity is verified for access to Google Cloud services and APIs. To run code or samples from a local development environment, you can authenticate to Compute Engine by selecting one of the following options:

    Select the tab for how you plan to use the samples on this page:

    Console

    When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.

    gcloud

    1. Install the Google Cloud CLI, then initialize it by running the following command: 

      gcloud init
    2. Set a default region and zone.

    REST

    To use the REST API samples on this page in a local development environment, you use the credentials you provide to the gcloud CLI.

      Install the Google Cloud CLI, then initialize it by running the following command: 

      gcloud init

    For more information, see Authenticate for using REST in the Google Cloud authentication documentation.

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 the Cloud KMS CryptoKey Encrypter/Decrypter (roles/cloudkms.cryptoKeyEncrypterDecrypter) IAM role on your project. For more information about granting roles, see Manage access to projects, folders, and organizations.

Your administrator might also be able to give the Compute Engine Service Agent the required permissions through custom roles or other predefined 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-binding KMS_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 your Google Cloud project that runs Cloud KMS (even if this is the same project running Compute Engine)
  • PROJECT_NUMBER: the project number (not Google Cloud project ID) of your Google Cloud project that runs the Compute Engine resources

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

  • You can't encrypt existing resources with CMEKs. You can only encrypt disks, images, and snapshots with CMEKs when you create them.

  • When you create a disk from a CMEK-encrypted instant snapshot, you must specify the key used to encrypt the source disk. You don't have to specify the key when working with other CMEK-encrypted resources such as disk clones and standard snapshots.

  • You can't use your own keys with Local SSD disks because the keys are managed by Google Cloud infrastructure and deleted when the VM is terminated.

  • Regional resources (disks) can only be encrypted by a key in one of the following Cloud KMS locations:

    • A key in the same region as the disk
    • A multi-regional key in the same geographical location as the disk
    • A key in the global location.

    For example, a disk in zone us-west1-a can be encrypted by a key in the global location, the us-west1 region, or the us multi-region.

    Global resources (such as images and snapshots) can be encrypted by keys in any location. For more information, see Types of locations for Cloud KMS.

  • Encryption of a disk, snapshot, or image with a key is permanent. You can't remove the encryption from the resource, change the type of encryption, or change the key that is used. The only way to remove encryption or change encryption keys is to create a copy of the resource while specifying a new encryption option. For example, to change a disk's from using Google-generated keys to CMEKs, follow these steps:

    1. Create a snapshot of the disk.
    2. Create a new disk from the snapshot. When you create the new disk, select the encryption type that you want.

    For more information, see Change a disk's type.

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

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

    Go to Disks

  2. Click Create disk and enter the properties for the new disk.
  3. Under Encryption, select Customer-managed key.
  4. In the drop-down menu, select the Cloud KMS key that you want to use to encrypt this disk.
  5. 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.

Console

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

    Go to Disks

  2. Click Create disk and enter the properties for the new disk.
  3. In the Disk settings section, choose Hyperdisk Balanced for the disk type.
  4. Optional. Change the default disk Size, Provisioned IOPS, and Provisioned Throughput settings for the disk.
  5. In the Encryption section, select Cloud KMS key.
  6. In the list of keys, select the Cloud HSM key that you want to use to encrypt this disk.
  7. In the Confidential Computing section, select Enable Confidential Computing services.
  8. 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 CMEK

To help protect a snapshot that you create from a disk encrypted with CMEK, you must 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 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.

Snapshots from disks encrypted with CMEK are incremental.

Console

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

    Go to Snapshots

  2. Click Create snapshot.
  3. 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

    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.
    • SNAPSHOT_TYPE: The snapshot type, either STANDARD or ARCHIVE. If a snapshot type is not specified, a STANDARD snapshot is created.

    • STORAGE_LOCATION: Optional: 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.

REST

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, 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"
    ],
}

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

Encrypt an imported image with CMEK

You can encrypt a new image when you import a custom image to Compute Engine. Before you can import an image, you must create and compress a disk image file and upload that compressed file to Cloud Storage.

Console

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

    Go to Images

  2. Click Create image.
  3. For Source disk, select the disk you want to create an image of.
  4. For Encryption, select Customer-managed key.
  5. In the drop-down menu, select the Cloud KMS key that you want to use to encrypt this image.
  6. 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 Persistent Disk from a snapshot encrypted with CMEK

To create a new standalone Persistent Disk from an encrypted snapshot, do the following:

Console

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

    Go to Disks

  2. Click Create disk and enter the properties for the new disk.
  3. For Source type, select the snapshot or image you want to use.

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

  5. Continue with the Persistent Disk creation process.

gcloud

Use the gcloud compute disks create command to create a new standalone Persistent Disk from an encrypted snapshot.

gcloud compute disks create DISK_NAME \
    --source-snapshot SNAPSHOT_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

  • 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

  • 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 key, don't include the --kms-key flag.

REST

Construct a POST request to the compute.disks.insert method to create a new standalone Persistent Disk from an encrypted snapshot. 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"
  }
}

Replace the following:

  • PROJECT_ID: the project to create the new disk in
  • ZONE: the zone to create the new disk in
  • DISK_NAME: the name of the new disk
  • 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 key.

Attaching a boot disk encrypted with CMEK to a new VM

Console

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

    Go to Create an instance

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

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

Remove your Cloud KMS encryption key from a Persistent Disk

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

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

After you create the new Persistent 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.

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 uses a new Cloud KMS key version. Rotating keys is a best practice to comply with standardized security practices. To rotate your keys, do the following:

  1. Rotate your Cloud KMS key.
  2. Create a snapshot of the encrypted disk.
  3. Use the new snapshot to create a new disk with 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 for encryption. Any snapshots that you create from that disk use the latest primary key version.

When you rotate a key, data that was encrypted with previous key versions is not automatically re-encrypted. For more information, see Re-encrypting data. Rotating a key does not automatically disable or destroy an existing key version.

Disable or delete a CMEK

If you no longer need a CMEK or want to prevent its use, delete or disable 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:

  • 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 enabled VM 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 from the disk.
  • You can't use images or snapshots that are encrypted with revoked keys to create disks.

If you disable the key, you can reverse the preceding effects by enabling the key. 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 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:

  1. Begin creating a VM that includes a disk that is protected by a Cloud KMS key.
  2. Open the Networking, disks, security, management, sole-tenancy menu.
  3. Expand the Management section.
  4. 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.

  1. Begin creating a new instance template that includes a disk that is protected by a Cloud KMS key.
  2. Open the Networking, disks, security, management, sole-tenancy menu.
  3. Expand the Management section.
  4. 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.