Customer Managed Key

View as Markdown

CustomerManagedKey object

customer_managed_key_idstring: ID of the encryption key configuration object.

creation_timeint64: Time in epoch milliseconds when the customer key was created.

account_idstring: The <Databricks> account ID that holds the customer-managed key.

aws_key_infoobject

Show child attributesHide child attributes

key_arnstring: The AWS KMS key's Amazon Resource Name (ARN).
Example: arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321

key_aliasstring: The AWS KMS key alias.
Example: alias/projectKey1

key_regionstring: The AWS KMS key region.
Example: us-east-1

reuse_key_for_cluster_volumesboolean: This field applies only if the use_cases property includes STORAGE. If this is set to true or omitted, the key is also used to encrypt cluster EBS volumes. If you do not want to use this key for encrypting EBS volumes, set to false.
Example: true

gcp_key_infoobject

Show child attributesHide child attributes

kms_key_idstring: Globally unique kms key resource id of the form projects/testProjectId/locations/us-east4/keyRings/gcpCmkKeyRing/cryptoKeys/cmk-eastus4

gcp_service_accountobject

Globally unique service account email that has access to the KMS key. The service account exists within the Databricks CP project.

Show child attributesHide child attributes

service_account_emailstring

use_casesarray of string: The cases that the key can be used for.
Values: MANAGED_SERVICES, STORAGE

View as Markdown

The CustomerManagedKey object

{
  "customer_managed_key_id": "string",
  "creation_time": 0,
  "account_id": "string",
  "aws_key_info": {
    "key_arn": "arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321",
    "key_alias": "alias/projectKey1",
    "key_region": "us-east-1",
    "reuse_key_for_cluster_volumes": true
  },
  "gcp_key_info": {
    "kms_key_id": "string",
    "gcp_service_account": {}
  },
  "use_cases": [
    "string"
  ]
}

Get GA

GET /api/2.0/accounts/{account_id}/customer-managed-keys/{customer_managed_key_id}

Gets a customer-managed key configuration object for an account, specified by ID. This operation uploads a reference to a customer-managed key to <Databricks>. If assigned as a workspace's customer-managed key for managed services, <Databricks> uses the key to encrypt the workspaces notebooks and secrets in the control plane, in addition to Databricks SQL queries and query history. If it is specified as a workspace's customer-managed key for storage, the key encrypts the workspace's root S3 bucket (which contains the workspace's root DBFS and system data) and, optionally, cluster EBS volume data.

Important: Customer-managed keys are supported only for some deployment types, subscription types, and AWS regions.

This operation is available only if your account is on the E2 version of the platform.",

API scopes: provisioning

CloudsAWSGCP

Parameters

customer_managed_key_idstringpath: <Databricks> encryption key configuration ID.

account_idstringpath

Response

Returns the CustomerManagedKey object.

View as Markdown

Response

{
  "customer_managed_key_id": "string",
  "creation_time": 0,
  "account_id": "string",
  "aws_key_info": {
    "key_arn": "arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321",
    "key_alias": "alias/projectKey1",
    "key_region": "us-east-1",
    "reuse_key_for_cluster_volumes": true
  },
  "gcp_key_info": {
    "kms_key_id": "string",
    "gcp_service_account": {}
  },
  "use_cases": [
    "string"
  ]
}

Create GA

POST /api/2.0/accounts/{account_id}/customer-managed-keys

Creates a customer-managed key configuration object for an account, specified by ID. This operation uploads a reference to a customer-managed key to <Databricks>. If the key is assigned as a workspace's customer-managed key for managed services, <Databricks> uses the key to encrypt the workspaces notebooks and secrets in the control plane, in addition to Databricks SQL queries and query history. If it is specified as a workspace's customer-managed key for workspace storage, the key encrypts the workspace's root S3 bucket (which contains the workspace's root DBFS and system data) and, optionally, cluster EBS volume data.

Important: Customer-managed keys are supported only for some deployment types, subscription types, and AWS regions that currently support creation of <Databricks> workspaces.

This operation is available only if your account is on the E2 version of the platform or on a select custom plan that allows multiple workspaces per account.

GCP only: To create a customer-managed key on GCP, you must include the X-Databricks-GCP-SA-Access-Token HTTP header in your request. This header must contain a Google Cloud OAuth access token with the cloud-platform scope. The Google identity associated with the token must also have the setIamPermissions and getIamPermissions IAM permissions on the key resource. For details on obtaining this token, see Authenticate with Google ID tokens.

API scopes: provisioning

CloudsAWSGCP

Parameters

account_idstringpath

Request body

aws_key_infoobjectRequired

Show child attributesHide child attributes

key_arnstring: The AWS KMS key's Amazon Resource Name (ARN).
Example: arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321

key_aliasstring: The AWS KMS key alias.
Example: alias/projectKey1

key_regionstring: The AWS KMS key region.
Example: us-east-1

reuse_key_for_cluster_volumesboolean: This field applies only if the use_cases property includes STORAGE. If this is set to true or omitted, the key is also used to encrypt cluster EBS volumes. If you do not want to use this key for encrypting EBS volumes, set to false.
Example: true

gcp_key_infoobjectRequired

Show child attributesHide child attributes

kms_key_idstring: Globally unique kms key resource id of the form projects/testProjectId/locations/us-east4/keyRings/gcpCmkKeyRing/cryptoKeys/cmk-eastus4

gcp_service_accountobject

Globally unique service account email that has access to the KMS key. The service account exists within the Databricks CP project.

Show child attributesHide child attributes

service_account_emailstring

use_casesarray of string: The cases that the key can be used for.
Values: MANAGED_SERVICES, STORAGE

Response

Returns the CustomerManagedKey object.

View as Markdown

Request

{
  "aws_key_info": {
    "key_arn": "arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321",
    "key_alias": "alias/projectKey1",
    "key_region": "us-east-1",
    "reuse_key_for_cluster_volumes": true
  },
  "gcp_key_info": {
    "kms_key_id": "string",
    "gcp_service_account": {}
  },
  "use_cases": [
    "string"
  ]
}

Response

{
  "customer_managed_key_id": "string",
  "creation_time": 0,
  "account_id": "string",
  "aws_key_info": {
    "key_arn": "arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321",
    "key_alias": "alias/projectKey1",
    "key_region": "us-east-1",
    "reuse_key_for_cluster_volumes": true
  },
  "gcp_key_info": {
    "kms_key_id": "string",
    "gcp_service_account": {}
  },
  "use_cases": [
    "string"
  ]
}

Delete GA

DELETE /api/2.0/accounts/{account_id}/customer-managed-keys/{customer_managed_key_id}

Deletes a customer-managed key configuration object for an account. You cannot delete a configuration that is associated with a running workspace.

API scopes: provisioning

CloudsAWSGCP

Parameters

customer_managed_key_idstringpath: <Databricks> encryption key configuration ID.

account_idstringpath

Response

Returns the CustomerManagedKey object.

View as Markdown

Response

{
  "customer_managed_key_id": "string",
  "creation_time": 0,
  "account_id": "string",
  "aws_key_info": {
    "key_arn": "arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321",
    "key_alias": "alias/projectKey1",
    "key_region": "us-east-1",
    "reuse_key_for_cluster_volumes": true
  },
  "gcp_key_info": {
    "kms_key_id": "string",
    "gcp_service_account": {}
  },
  "use_cases": [
    "string"
  ]
}