Use customer-managed encryption keys (CMEK)

This page describes how to use Customer Managed Encryption Keys (CMEK) on Google Kubernetes Engine (GKE). If you need to control management of your keys, you can use Cloud Key Management Service and CMEK to protect attached Persistent Disks and custom boot disks in your GKE cluster.

Overview

By default, Google Cloud encrypts customer content at rest, and GKE manages encryption for you without any action on your part.

If you want to control and manage encryption key rotation yourself, you can use CMEK. These keys encrypt the data encryption keys that encrypt your data. For more information, see Key management.

You can also encrypt secrets in your cluster using keys that you manage. For details, see Application-layer secrets encryption.

In GKE, CMEK can protect data of two types of storage disks: node boot disks and attached disks.

Node boot disks
Node boot disks are part of your cluster's node pools. You can create a CMEK-encrypted node boot disk when you create clusters and node pools.
Attached disks
Attached disks are PersistentVolumes used by Pods for durable storage. CMEK-encrypted attached persistent disks are available in GKE as a dynamically provisioned PersistentVolume.

To learn more about storage disks, see Storage options. Control plane disks, used for GKE control planes, cannot be protected with CMEK.

Before you begin

  1. To do the exercises in this topic, you need two Google Cloud projects:

    • Key project: This is where you create an encryption key.

    • Cluster project: This is where you create a cluster that enables CMEK.

  2. In your key project, ensure that you have enabled the Cloud KMS API.

    Enable Cloud KMS API

  3. In your key project, the user who creates the key ring and key needs the following IAM permissions:

    • cloudkms.keyRings.getIamPolicy
    • cloudkms.keyRings.setIamPolicy

    These permissions are granted to the predefined roles/cloudkms.admin Identity and Access Management role. You can learn more about granting permissions to manage keys in the Cloud KMS documentation.

  4. In your cluster project, ensure that you have enabled the Cloud KMS API.

    Enable Cloud KMS API

  5. Ensure that you have installed the gcloud CLI.

  6. Update gcloud to the latest version:

    gcloud components update

Create a Cloud KMS key

Before you can protect your node boot disk or attached disk with a CMEK, you need a Cloud KMS key ring and key.

Your key ring and key have the following requirements:

  • Your key should use symmetric encryption.

  • You need to grant the GKE service account permissions to use the key.

  • Your key ring must have a location that matches the location of your GKE cluster:

    • A zonal cluster should use a key ring from a superset location. For example, a cluster in the us-central1-a zone can only use a key in the us-central1 region.

    • A regional cluster should use a key ring from the same location. For example, a cluster in the asia-northeast1 region should be protected with a key ring from the asia-northeast1 region.

    • The Cloud KMS global region is not supported for use with GKE.

For instructions on how to create a key ring and key, see Creating symmetric keys.

Grant permission to use the key

You must grant the Cloud KMS CryptoKey Encrypter/Decrypter (roles/cloudkms.cryptoKeyEncrypterDecrypter) IAM role on the Cloud KMS key to the Compute Engine service agent in your cluster project. Granting this role allows GKE Persistent Disks to access and use your encryption key.

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

gcloud

Run the following command:

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

Replace the following:

  • KEY_NAME: the name of your key.
  • LOCATION: the region where you created your key ring.
  • RING_NAME: the name of your key ring.
  • PROJECT_NUMBER: your cluster's project number.
  • KEY_PROJECT_ID: your key project ID.

Console

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

    Go to Key management

  2. Click the name of the key ring that contains the key.

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

  4. Click the Permissions tab.

  5. Click Grant access. The Grant access to key pane opens.

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

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

    Replace PROJECT_NUMBER with your cluster's project number.

  7. In the Select a role menu, select Cloud KMS CryptoKey Encrypter/Decrypter.

  8. Click Save.

Use CMEK-protected node boot disks

In this section, you create a new cluster or node pool with a CMEK protected boot disk.

You cannot enable customer-managed encryption for node boot disks on an existing cluster, as you cannot change the boot disk type of an existing cluster or node pool. However, you can create a new node pool for your cluster with customer- managed encryption enabled, and delete the previous node pool.

You also cannot disable customer-managed encryption for node boot disks on an existing cluster or an existing node pool. However, you can create a new node pool for your cluster with customer-managed encryption disabled, and delete the previous node pool.

Create a cluster with a CMEK-protected node boot disk

You can create a cluster with a CMEK-protected node boot disk using the gcloud CLI or the Google Cloud console.

For Standard clusters, only a standard persistent disk (pd-standard) or an SSD persistent disk (pd-ssd) can be encrypted with a CMEK key.

gcloud

To create a cluster whose boot disk is encrypted with a CMEK key, specify a value for the --boot-disk-kms-key parameter in your cluster creation command.

Create a Standard cluster

To create a Standard cluster whose boot disk is encrypted with a CMEK key, use the following command:

gcloud container clusters create CLUSTER_NAME \
    --cluster-version=latest \
    --location CONTROL_PLANE_LOCATION \
    --boot-disk-kms-key projects/KEY_PROJECT_ID/locations/LOCATION/keyRings/RING_NAME/cryptoKeys/KEY_NAME \
    --project CLUSTER_PROJECT_ID \
    --disk-type DISK_TYPE

Create an Autopilot cluster

To create an Autopilot cluster whose boot disk is encrypted with a CMEK key, use the following command:

gcloud container clusters create-auto CLUSTER_NAME \
    --cluster-version=latest \
    --location CONTROL_PLANE_LOCATION \
    --boot-disk-kms-key projects/KEY_PROJECT_ID/locations/LOCATION/keyRings/RING_NAME/cryptoKeys/KEY_NAME \
    --project CLUSTER_PROJECT_ID

Replace the following:

  • CLUSTER_NAME: the name for your new cluster.
  • CONTROL_PLANE_LOCATION: the Compute Engine