Customer-managed encryption keys

Customer-managed encryption keys

Vertex AI Workbench user-managed notebooks is deprecated. On January 30, 2025, support for user-managed notebooks will end and the ability to create user-managed notebooks instances will be removed. Existing instances will continue to function but patches, updates, and upgrades won't be available. To continue using Vertex AI Workbench, we recommend that you migrate your user-managed notebooks instances to Vertex AI Workbench instances.

By default, Vertex AI Workbench encrypts customer content at rest. Vertex AI Workbench handles encryption for you without any additional actions on your part. This option is called Google default encryption.

If you want to control your encryption keys, then you can use customer-managed encryption keys (CMEKs) in Cloud KMS with CMEK-integrated services including Vertex AI Workbench. Using Cloud KMS keys gives you control over their protection level, location, rotation schedule, usage and access permissions, and cryptographic boundaries. Using Cloud KMS also lets you view audit logs and control key life cycles. Instead of Google owning and managing the symmetric key encryption keys (KEKs) that protect your data, you control and manage these keys in Cloud KMS.

After you set up your resources with CMEKs, the experience of accessing your Vertex AI Workbench resources is similar to using Google default encryption. For more information about your encryption options, see Customer-managed encryption keys (CMEK).

This page describes some specific benefits and limitations of using CMEK with user-managed notebooks and shows how to configure a new user-managed notebooks instance to use CMEK.

Benefits of CMEK

In general, CMEK is most useful if you need full control over the keys used to encrypt your data. With CMEK, you can manage your keys within Cloud Key Management Service. For example, you can rotate or disable a key or you can set up a rotation schedule by using the Cloud KMS API.

When you run a user-managed notebooks instance, your instance runs on a virtual machine (VM) managed by Vertex AI Workbench. When you enable CMEK for a user-managed notebooks instance, Vertex AI Workbench uses the key that you designate, rather than a key managed by Google, to encrypt data on the boot disks of the VM.

The CMEK key doesn't encrypt metadata, like the instance's name and region, associated with your user-managed notebooks instance. Metadata associated with user-managed notebooks instances is always encrypted using Google's default encryption mechanism.

Limitations of CMEK

To decrease latency and to prevent cases where resources depend on services that are spread across multiple failure domains, Google recommends that you protect regional user-managed notebooks instances with keys in the same location.

• You can encrypt regional user-managed notebooks instances by using keys in the same location or in the global location. For example, you can encrypt data in a disk in zone us-west1-a by using a key in us-west1 or global.
• You can encrypt global instances by using keys in any location.
• Configuring CMEK for user-managed notebooks doesn't automatically configure CMEK for other Google Cloud products that you use. To use CMEK to encrypt data in other Google Cloud products, you must complete additional configuration.

Configure CMEK for your user-managed notebooks instance

The following sections describe how to create a key ring and key in Cloud Key Management Service, grant the service account encrypter and decrypter permissions for your key, and create a user-managed notebooks instance that uses CMEK.

Before you begin

We recommend using a setup that supports a separation of duties. To configure CMEK for user-managed notebooks, you can use two separate Google Cloud projects:

• A Cloud KMS project: a project for managing your encryption key
• A user-managed notebooks project: a project for accessing user-managed notebooks instances and interacting with any other Google Cloud products that you need for your use case

Alternatively, you can use a single Google Cloud project. To do so, use the same project for all of the following tasks.

Set up the Cloud KMS project

1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Go to project selector

3. Make sure that billing is enabled for your Google Cloud project.

4. Enable the Cloud KMS API.

   Enable the API

5. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Go to project selector

6. Make sure that billing is enabled for your Google Cloud project.

7. Enable the Cloud KMS API.

   Enable the API

Set up the user-managed notebooks project

1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Go to project selector

3. Make sure that billing is enabled for your Google Cloud project.

4. Enable the Notebooks API.

   Enable the API

5. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Go to project selector

6. Make sure that billing is enabled for your Google Cloud project.

7. Enable the Notebooks API.

   Enable the API

Set up the Google Cloud CLI

The gcloud CLI is required for some steps on this page and optional for others.

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

gcloud init

Note: You can run the gcloud CLI in the Google Cloud console without installing the Google Cloud CLI. To run the gcloud CLI in the Google Cloud console, use Cloud Shell.

Create a key ring and key

When you create a key ring and key, keep the following requirements in mind:

• When you choose your key ring's location, use either global or the location where your user-managed notebooks instance will be.

• Make sure to create your key ring and key in your Cloud KMS project.

To create a key ring and a key, see Create symmetric encryption keys.

Grant user-managed notebooks permissions

To use CMEK for your user-managed notebooks instance, you must grant your user-managed notebooks instance permission to encrypt and decrypt data using your key.

Determine the service account to use

User-managed notebooks use a service account to run your user-managed notebooks instance. This service account is either the default Compute Engine service account or a service account that you specify when you create the instance.

If the service account is the default Compute Engine service account, complete the following to find the service account's email address:

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

   Go to IAM

2. Find the principal with the name Compute Engine default service account.

   Make note of the email address for this service account, and use it in the following steps to grant it permission to encrypt and decrypt data using your key.

Grant the service account permission

Grant permission by using the Google Cloud console or by using the Google Cloud CLI.

Console

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

   Go to Key management

2. Select your Cloud KMS project.

3. Click the name of the key ring that you created in Create a key ring and key. The Key ring details page opens.

4. Select the checkbox for the key that you created in Create a key ring and key. If an info panel labeled with the name of your key isn't already open, click Show info panel.

5. In the info panel, click  Add member. The Add members to "KEY_NAME" dialog opens. In this dialog, do the following:

   1. In the New members field, enter the service account email address for your instance.

   2. In the Select a role list, click Cloud KMS and then select the Cloud KMS CryptoKey Encrypter/Decrypter role.

   3. Click Save.

gcloud

Run the following command:

gcloud kms keys add-iam-policy-binding KEY_NAME \
    --keyring=KEY_RING_NAME \
    --location=REGION \
    --project=KMS_PROJECT_ID \
    --member=serviceAccount:SERVICE_ACCOUNT \
    --role=roles/cloudkms.cryptoKeyEncrypterDecrypter

Replace the following:

• KEY_NAME: the name of the key that you created in Create a key ring and key
• KEY_RING_NAME: the key ring that you created in Create a key ring and key
• REGION: the region where you created your key ring
• KMS_PROJECT_ID: the ID of your Cloud KMS project
• SERVICE_ACCOUNT: the service account email address for your instance

Create a user-managed notebooks instance with CMEK

After you have granted your user-managed notebooks instance permission to encrypt and decrypt data using your key, you can create a user-managed notebooks instance that encrypts data using this key.

The following examples show how to encrypt and decrypt data using your key by using the Google Cloud console or gcloud CLI.

Console

To create a user-managed notebooks instance with a customer-managed encryption key, use the following steps:

1. In the Google Cloud console, go to the User-managed notebooks page. Or go to notebook.new (https://notebook.new) and skip the next step.

   Go to User-managed notebooks

2. Click  New notebook, and then select Customize.

3. On the Create a user-managed notebook page, in the Details section, provide the following information for your new instance:

   • Name: a name for your new instance
   • Region: the region that your key and key ring are in
   • Zone: a zone within the region that you selected

4. Select the Disks section.

5. To use customer-managed encryption keys, under Encryption, select Customer-managed encryption key (CMEK).

6. Click Select a customer-managed key.

   • If the customer-managed key that you want to use is in the list, select it.

   • If the customer-managed key that you want to use isn't in the list, enter the resource ID for your customer-managed key. The resource ID for your customer-managed key looks like this:

     projects/NOTEBOOKS_PROJECT_NUMBER/locations/global/keyRings/KEY_RING_NAME/cryptoKeys/KEY_NAME
     

     Replace the following:

     • NOTEBOOKS_PROJECT_NUMBER: the ID of your user-managed notebooks project
     • KEY_RING_NAME: the key ring that you created in Create a key ring and key
     • KEY_NAME: the name of the key that you created in Create a key ring and key

7. Complete the rest of the instance creation dialog, and then click Create.

8. Vertex AI Workbench creates a user-managed notebooks instance based on your specified properties and automatically starts the instance. When the instance is ready to use, Vertex AI Workbench activates an Open JupyterLab link.

gcloud

To use the gcloud CLI to create a user-managed notebooks instance with a customer-managed encryption key, run the following command. This example assumes that you want to create a user-managed notebooks instance with an n1-standard-1 machine type and a 100 GB standard persistent boot disk.

gcloud notebooks instances create notebook-vm-cmek \
    --location=REGION \
    --vm-image-family=IMAGE_FAMILY \
    --vm-image-project=deeplearning-platform-release \
    --machine-type="n1-standard-1" \
    --boot-disk-type="PD_STANDARD" \
    --boot-disk-size=100 \
    --kms-key=KEY_NAME \
    --kms-project=KMS_PROJECT_ID \
    --kms-location=REGION \
    --kms-keyring=KEY_RING_NAME \
    --disk-encryption=CMEK \
    --metadata='proxy-mode=project_editors'

Replace the following:

• REGION: the region where you created your key ring and where you plan to create your user-managed notebooks instance
• IMAGE_FAMILY: the image family that you want to use to create your user-managed notebooks instance
• KEY_NAME: the name of the key that you created in Create a key ring and key
• KMS_PROJECT_ID: the ID of your Cloud KMS project
• KEY_RING_NAME: the key ring that you created in Create a key ring and key

What's next

• Learn more about CMEK on Google Cloud
• Learn how to use CMEK with other Google Cloud products