Use customer-managed encryption keys

By default, Cloud Scheduler encrypts customer content at rest. Cloud Scheduler 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 Cloud Scheduler. 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 lifecycles. 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 Cloud Scheduler resources is similar to using Google default encryption. For more information about your encryption options, see Customer-managed encryption keys (CMEK).

What is protected with CMEK

You can specify a Cloud KMS key per Google Cloud project and per supported Cloud Scheduler region. This key is used to protect the following data in that project and region:

  • Jobs with an HTTP or HTTPS endpoint target: the HTTP request body and customer headers.
  • Jobs with a Pub/Sub topic target: the Pub/Sub message payload and attributes.

Before you begin

Before using CMEK in Cloud Scheduler, complete the following prerequisite steps.

  1. Set up your environment.

  2. Update gcloud components.

    gcloud components update

  3. Sign in using your account.

    gcloud auth login

  4. Enable the Cloud KMS API for the project that stores your encryption keys:

    gcloud services enable cloudkms.googleapis.com \
        --project=KMS_PROJECT_ID

    Replace KMS_PROJECT_ID with the ID of the project that stores your Cloud KMS keys. This can be the same project as your Cloud Scheduler jobs or a separate project.

  5. Cloud KMS produces Cloud Audit Logs when keys are enabled, disabled, or used by Cloud Scheduler resources to encrypt and decrypt data.

    Make sure that logging is enabled for the Cloud KMS API in your project and that you have decided which logging-specific permissions and roles apply to your use case. For more information, see Cloud KMS audit logging.

Required roles

To get the permissions that you need to configure CMEK for Cloud Scheduler, ask your administrator to grant you the following IAM roles:

  • Grant the service agent access to the key: Cloud KMS Admin (roles/cloudkms.admin) on the key, key ring, or project that contains the Cloud KMS key
  • Enable or disable CMEK: Cloud Scheduler Admin (roles/cloudscheduler.admin) on the Cloud Scheduler project
  • View the CMEK configuration or operation status:

For more information about granting roles, see Manage access to projects, folders, and organizations.

These predefined roles contain the permissions required to configure CMEK for Cloud Scheduler. To see the exact permissions that are required, expand the Required permissions section:

Required permissions

The following permissions are required to configure CMEK for Cloud Scheduler:

  • Grant the service agent access to the key: cloudkms.cryptoKeys.setIamPolicy on the key, key ring, or project that contains the Cloud KMS key
  • Enable or disable CMEK: cloudscheduler.cmekConfig.update on the Cloud Scheduler project
  • View the CMEK configuration or operation status:
    • cloudscheduler.cmekConfig.get on the Cloud Scheduler project
    • cloudscheduler.operations.get on the Cloud Scheduler project

You might also be able to get these permissions with custom roles or other predefined roles.

Create a Cloud KMS key ring and key

You can create a new key ring or use an existing one. Within the key ring, you can add a new key or use an existing key. We recommend using different keys for distinct applications, services, or environments.

  1. Create a key ring.

  2. Create a key. The key must use the symmetric encryption algorithm.

Grant the Cloud Scheduler service agent access to the key

You must grant the Cloud Scheduler service agent the Cloud KMS CryptoKey Encrypter/Decrypter Identity and Access Management (IAM) role so that it can access the Cloud KMS key. If you recently enabled the Cloud Scheduler API in a project and haven't created any jobs yet, you might first need to create the service agent by running gcloud beta services identity create --service=cloudscheduler.googleapis.com --project=PROJECT_ID.

gcloud kms keys add-iam-policy-binding KEY_NAME \
    --keyring=KEY_RING \
    --location=LOCATION \
    --project=KMS_PROJECT_ID \
    --member=serviceAccount:service-PROJECT_NUMBER@gcp-sa-cloudscheduler.iam.gserviceaccount.com \
    --role=roles/cloudkms.cryptoKeyEncrypterDecrypter

Replace the following:

  • KEY_NAME: the name of the key—for example, my-key.
  • KEY_RING: the name of the key ring—for example, my-keyring.
  • LOCATION: the location of the key—for example, us-central1.
  • KMS_PROJECT_ID: the ID of the project where the Cloud KMS key is located.
  • PROJECT_NUMBER: the project number of your Cloud Scheduler Google Cloud project. You can find your project number on the Welcome page of the Google Cloud console or by running the following command:

    export PROJECT=$(gcloud info --format='value(config.project)')
    gcloud projects describe ${PROJECT} --format="value(projectNumber)"

As long as the service agent has the roles/cloudkms.cryptoKeyEncrypterDecrypter role, a job in your project can encrypt and decrypt its data using the CMEK key. If you revoke this role, or if you disable or destroy the CMEK key, then that data can't be accessed. In this document, see Remove Cloud KMS.

Enable CMEK for a Cloud Scheduler region

Specify the Cloud KMS key to use for data encryption in a Cloud Scheduler region by using the gcloud scheduler cmek-config update command:

gcloud scheduler cmek-config update \
    --location=LOCATION \
    --kms-key-name=KEY_NAME \
    --kms-keyring=KEY_RING \
    --kms-project=KMS_PROJECT_ID

Replace the following:

  • LOCATION: a supported Cloud Scheduler region.
  • KEY_NAME: the name of the key—for example, my-key.
  • KEY_RING: the name of the key ring—for example, my-keyring.
  • KMS_PROJECT_ID: the ID of the project where the Cloud KMS key you want to use is located.

Note the following:

  • Enabling, changing, or disabling a CMEK key in Cloud Scheduler runs asynchronously and returns a long-running operation (projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID). You can check whether the update has finished by running the gcloud scheduler operations describe command.
  • Cloud Scheduler encrypts new and updated jobs in the protected project and region with the enabled key. Existing jobs previously encrypted with an earlier key are re-encrypted with the new key.
  • Existing unprotected jobs are encrypted.
  • Rotating a key in Cloud KMS doesn't automatically re-encrypt existing jobs or switch new jobs in the region to the new primary key version. For more information, see CMEK key rotation.
  • If you disable CMEK for a region, existing jobs are encrypted using Google default encryption, and subsequent jobs are created without CMEK encryption. In this document, see Disable CMEK for a Cloud Scheduler region.

Verify the Cloud KMS configuration

Verify that CMEK is enabled by retrieving the CMEK configuration for a Cloud Scheduler region by using the gcloud scheduler cmek-config describe command:

gcloud scheduler cmek-config describe \
    --location=LOCATION

The output is similar to the following:

kmsKeyName: projects/KMS_PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY_NAME
name: projects/PROJECT_ID/locations/LOCATION/cmekConfig

The kmsKeyName value is the resource ID of the Cloud KMS key used to secure the jobs in the region.

Disable CMEK for a Cloud Scheduler region

You can disable CMEK for a Cloud Scheduler region so that any jobs created in that region are created without CMEK encryption.

gcloud scheduler cmek-config update \
    --location=LOCATION \
    --clear-kms-key

This disables CMEK for the specific region and any subsequent jobs are created without CMEK encryption. Existing jobs are encrypted using Google default encryption.

Remove Cloud KMS

If you want to revoke data access to your jobs, you can remove Cloud KMS in one of the following ways:

  • Disable or destroy the appropriate key version of your customer-managed encryption key. You can check whether a key version is in use. Disabling a CMEK key version suspends access to all data protected by that key version until the key is re-enabled. Destroying a key version permanently blocks access and can cause unrecoverable data loss. Both affect only the jobs that are associated with the specific key version.

    You can't view the resources protected by the disabled or destroyed key version. Any active job executions fail with a corresponding error message.

  • Revoke the roles/cloudkms.cryptoKeyEncrypterDecrypter IAM role from the Cloud Scheduler service agent. This affects all jobs in the specific Google Cloud project and region that support encryption using CMEK. You can't create new CMEK-integrated jobs, or view or list CMEK-encrypted jobs (though you can still delete them). Any active job executions fail with a corresponding error message.

Although none of these operations guarantees instantaneous access revocation, IAM changes generally take effect faster. For more information, see Cloud KMS resource consistency and Access change propagation.

About CMEK organization policy constraints

Cloud Scheduler supports the following organization policy constraints, which can help you enforce CMEK usage across an organization:

  • constraints/gcp.restrictNonCmekServices: use this constraint to require that CMEKs be used to protect all new Cloud Scheduler resources in an organization, folder, or project.

    If active, this organization policy prevents creating or updating resources unless you first enable a Cloud KMS key. You also can't disable CMEK for a Cloud Scheduler region.

  • constraints/gcp.restrictCmekCryptoKeyProjects: use this constraint to ensure that your CMEK-protected Cloud Scheduler resources use a key from an approved project.

    For example, you can specify a rule similar to the following: "For all Cloud Scheduler resources in projects/my-company-data-project, the Cloud KMS key used in this project must come from projects/my-company-central-keys OR projects/team-specific-keys."

Note the following:

  • After applying a CMEK organization policy, you can still access existing jobs that use Google default encryption; however, you can't update them unless you first configure an acceptable Cloud KMS key for the Cloud Scheduler region.

  • Jobs that target an App Engine application aren't subject to the CMEK organization policies. For example, if you set the constraints/gcp.restrictNonCmekServices constraint, you can still create or update a job that targets an App Engine application.

For more about configuring organization policies, see CMEK organization policies.

Troubleshooting

You might encounter errors when using Cloud KMS with Cloud Scheduler. The following table describes different issues and how to resolve them.

Issue Description
Permission cloudkms.cryptoKeyVersions.useToEncrypt is denied

Either the provided Cloud KMS key does not exist or the permission is not properly configured.

Solution:

Key version is not enabled

The provided Cloud KMS key version has been disabled.

Solution: Re-enable the Cloud KMS key version.

Key ring region does not match the resource to be protected

The provided Cloud KMS key ring region is different from the protected Cloud Scheduler region.

Solution: Use a Cloud KMS key ring from the same region as the Cloud Scheduler region. The key ring can be in a different project. For more information, see Cloud KMS locations and Cloud Scheduler locations.

Project is not compatible with CMEK in Cloud Scheduler

Enabling CMEK fails with a FAILED_PRECONDITION error with the message: Your project is currently not compatible with CMEK in Cloud Scheduler. This error occurs when existing Cloud Scheduler jobs in your project haven't been migrated to support CMEK. For example, missing service agent permissions or legacy jobs with invalid Pub/Sub topic names can prevent migration.

Solution:

  1. Review and fix any permission or job configuration issues in your project:
    • Verify that the Cloud Scheduler service agent has the Cloud Scheduler Service Agent (roles/cloudscheduler.serviceAgent) role on the project. This role includes the pubsub.topics.publish permission for Pub/Sub topics in the project. For instructions, see Grant the Cloud Scheduler Service Agent role.
    • If roles/cloudscheduler.serviceAgent isn't granted on the project or is restricted, verify that the service agent has the Pub/Sub Publisher (roles/pubsub.publisher) role on each target topic.
    • Check for legacy Pub/Sub target jobs with invalid topic names and update or delete them. Topic names must use the projects/PROJECT_ID/topics/TOPIC_ID format in the same project as the job. For topic naming rules, see Guidelines to name a topic, subscription, schema, or snapshot.
  2. After resolving any permission or job configuration issues, open a support request in the Google Cloud console to complete the migration so you can enable CMEK for your project. Fixing permissions or job configurations alone doesn't clear the error until the migration completes.

Audit logging

Cloud KMS produces audit logs when keys are enabled, disabled, or used by Cloud Scheduler resources to encrypt and decrypt messages. For more information, see Cloud KMS audit logging.

Cloud EKM errors

To resolve issues that you might encounter when using externally managed keys through Cloud External Key Manager (Cloud EKM), see the Cloud EKM error reference.

Unavailable key status

If for some reason Cloud KMS is unavailable, Cloud Scheduler might be unable to retrieve the status of your key from Cloud KMS.

If Cloud KMS is unavailable when a job is scheduled to run, Cloud Scheduler can't decrypt the job data or invoke the job's target. For transient Cloud KMS errors (such as UNAVAILABLE, RESOURCE_EXHAUSTED, or an unreachable Cloud EKM key), Cloud Scheduler retries decryption internally with exponential backoff and logs CmekRetryFailure entries in Cloud Logging under cloudscheduler.googleapis.com/cmek. For non-retryable errors, such as a permission error or a disabled or destroyed key, decryption fails immediately without invoking the target.

Cloud KMS quotas

When you use CMEK in Cloud Scheduler, your projects can consume Cloud KMS cryptographic requests quotas. For example, Cloud Scheduler can consume these quotas when running jobs, handling job management requests, or updating the CMEK configuration. Cloud Scheduler reuses a cached intermediary key for up to five minutes per project and region, so frequent job runs don't each consume quota. Encryption and decryption operations using CMEK keys affect Cloud KMS quotas only if you use hardware (Cloud HSM) or external (Cloud EKM) keys. For more information, see Cloud KMS quotas.

Pricing

This integration doesn't incur additional costs beyond the Cloud KMS key operations, which are billed to your Google Cloud project.

Underlying delivery resources that use your key through key grants can perform additional Cloud KMS operations. To help estimate Cloud KMS usage for direct Cloud Scheduler operations, expect the following cryptographic operation rates per project and region:

  • Job executions: Cloud Scheduler reuses a cached intermediary key for up to five minutes per project and region. Projects with fewer than one job execution every five minutes perform approximately one Cloud KMS decrypt operation per execution. Projects with more frequent executions perform approximately one decrypt operation every five minutes across the region.
  • Job management operations: Requests to create, update, get, list, pause, or resume jobs with protected data use a separate cached intermediary key for up to five minutes per project and region.
  • CMEK configuration updates: Enabling or changing a CMEK key with cmek-config performs additional Cloud KMS key operations to validate the key and re-encrypt existing protected jobs in the region. Disabling CMEK decrypts existing protected jobs back to Google default encryption.

For pricing information, see Cloud KMS pricing.