Protect resources by using Cloud KMS keys

---

This document provides information about how to use keys managed by the Cloud Key Management Service Cloud KMS to encrypt disks and other storage-related resources. Keys managed by the 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

  2. Create a key ring and a key as described in Creating key rings and keys.
• If you haven't already, 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 as follows.
  

  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

     Note: If you installed the gcloud CLI previously, make sure you have the latest version by running gcloud components update.
  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

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.

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:

[e-mail]

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

gcloud projects add-iam-policy-binding KMS_PROJECT_ID \
    --member serviceAccount:[e-mail] \
    --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-generated keys. For specifications related to the default encryption in Google Cloud, see Default encryption at rest in the Security documentation.

Limitations

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

• You can't use your own keys with Local SSD because Local SSD disks don't persist beyond the life of a VM. Local SSD disks are protected with Google default encryption.

• Regional resources (disks) can be encrypted by keys in the same location or in the global location. For example, a disk in zone us-west1-a can be encrypted by a key in us-west1 or global. Global resources (images, snapshots) can be encrypted by keys in any location.

• Encrypting a disk, snapshot, or image with a key is permanent. You cannot remove the encryption from the resource or change the key that is used. The only way to remove encryption or change keys is to create a copy of the resource while specifying a new encryption option.

Note: It is recommended that you help to protect regional resources with keys in the same location. This approach helps to decrease latency and prevent cases where resources depend on services spread across multiple failure domains.

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

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

Replace the following:

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

Note: If you're creating a regional Persistent Disk, you must assign the disk replicas to two different zones by specifying the --replica-zones flag.

REST

Encrypt a disk using 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/e2-standard-2",
"disks": [
 {
  "type": "PERSISTENT",
  "diskEncryptionKey": {
    "kmsKeyName": "projects/KMS_PROJECT_ID/locations/REGION/keyRings/KEY_RING/cryptoKeys/KEY"
  },
  "initializeParams": {
   "sourceImage": "projects/debian-cloud/global/images/debian-8-jessie-v20160301"
  },
  "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
• 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

Similarly, you can also use the API 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=https%3A%2F%2Fwww.googleapis.com%2Fcompute%2Fprojects%2Fdebian-cloud%2Fglobal%2Fimages%2Fdebian-8-jessie-v20160301

{
 "name": "new-encrypted-disk-key",
 "diskEncryptionKey": {
   "kmsKeyName": "projects/KMS_PROJECT_ID/locations/REGION/keyRings/KEY_RING/cryptoKeys/KEY"
  },
 "type": "zones/ZONE/diskTypes/pd-standard"
}

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.

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

gcloud compute disks snapshot encrypted-disk --zone ZONE

Replace ZONE with the zone to create the snapshot in.

REST

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/disks/example-disk/createSnapshot

{
 "snapshotEncryptionKey":  {
   "kmsKeyName": "projects/KMS_PROJECT_ID/locations/REGION/keyRings/KEY_RING/cryptoKeys/SNAPSHOT_KEY"
 },
 "name": "snapshot-encrypted-disk"
}

Replace SNAPSHOT_KEY with the name of the key that you used to encrypt the source disk.

You cannot create a snapshot that uses a CMEK unless the source disk uses CMEK as well. Also, you cannot convert encrypted disks or encrypted snapshots to use Compute Engine default encryption unless you create a completely new disk image and a new persistent disk.

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

gcloud compute images create [...] \
  --kms-key projects/KMS_PROJECT_ID/locations/REGION/keyRings/KEY_RING/cryptoKeys/KEY

REST

To encrypt an imported image, 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": "new-encrypted-image",
 "sourceType": "RAW",
 "imageEncryptionKey": {
   "kmsKeyName": "projects/KMS_PROJECT_ID/locations/REGION/keyRings/KEY_RING/cryptoKeys/IMAGE_KEY"
   }
}

Replace IMAGE_KEY with the name of the key that you want to use to encrypt the image.

Create a Persistent Disk from a snapshot encrypted with CMEK

To create a new standalone Persistent Disk using 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. Continue with the Persistent Disk creation process.

gcloud

gcloud compute disks create [...] --source-snapshot example-snapshot \
  --kms-key projects/KMS_PROJECT_ID/locations/REGION/keyRings/KEY_RING/cryptoKeys/KEY

To use an image instead of a snapshot, replace --source-snapshot example-snapshot with --image example-image.

REST

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

{
  "name": "disk-from-encrypted-snapshot",
  "sourceSnapshot": "global/snapshots/encrypted-snapshot"
}

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

gcloud compute instances create example-instance \
  --disk name=encrypted-disk,boot=yes

REST

"disks": [
  {
    "deviceName": "encrypted-disk",
    "source": "projects/PROJECT_ID/zones/ZONE/disks/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 Compute Engine default encryption instead. By default, Compute Engine encrypts all data at rest.

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

After you create the new Persistent Disk, it uses Compute Engine 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 Persistent 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 Persistent Disk with the key rotated in the preceding step.

When you create the new Persistent Disk, it uses the new key version for encryption. Any snapshots that you create from that disk also use the same 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.

Impact of disabling or deleting CMEKs

Disabling or deleting an encryption key has the following effects on the following resources that the key helps to protect:

• VMs with attached disks cannot boot. If you enabled VM shutdown on key revocation, then VMs with attached disks that the key helps to protect shut down.
• Disks cannot be attached to VMs, nor can snapshots be created for them.
• Snapshots cannot be used to create a disk.
• Images cannot be used to create a disk.

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.

Note: There is a delay of up to an hour between when you disable or delete the key, during which it is still usable for encrypting and decrypting data. You may disable the Compute Engine Service Agent used to encrypt and decrypt keys in order to apply the effects of disabling or deleting a key more quickly.

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 Persistent 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 set the field --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 field "keyRevocationActionType": "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 gcloud CLI or REST.

Console

To configure VMs that are created from an instance template to shutdown when a Cloud KMS key is revoked, do the following:

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 set the field --key-revocation-action-type=stop.

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

REST

Create an instance template by using the instanceTemplates.insert method. In the instance template API, 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-9"
      }
    }
  ],
  "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.