Workspace

View as Markdown

Workspace object

workspace_idint64: A unique integer ID for the workspace

workspace_namestring: The human-readable name of the workspace.
Constraints: [ 1 .. 100 ] characters

aws_regionstring: AWS
The AWS region of the workspace data plane (for example, us-west-2).

creation_timeint64: Time in epoch milliseconds when the workspace was created.

deployment_namestring: AWS
The deployment name defines part of the subdomain for the workspace. The workspace URL for web application and REST APIs is <deployment-name>.cloud.databricks.com.
Constraints: <= 64 characters

workspace_statusstring: The status of a workspace
Values: NOT_PROVISIONED, PROVISIONING, RUNNING, FAILED, BANNED, CANCELLING

account_idstring: <Databricks> account ID.

credentials_idstring: ID of the workspace's credential configuration object.

storage_configuration_idstring: ID of the workspace's storage configuration object.

workspace_status_messagestring: Message describing the current workspace status.

network_idstring: If this workspace is BYO VPC, then the network_id will be populated. If this workspace is not BYO VPC, then the network_id will be empty.

gcp_managed_network_configobject

GCP

The network config for GCP workspace with <Databricks> managed network.

Show child attributesHide child attributes

subnet_cidrstring: The IP range which will be used to allocate GKE cluster nodes from. Note: Pods, services and master IP range must be mutually exclusive.

gke_cluster_pod_ip_rangestring: The IP range that will be used to allocate GKE cluster Pods from.

gke_cluster_service_ip_rangestring: The IP range that will be used to allocate GKE cluster Services from.

pricing_tierstring: Values: UNKNOWN, COMMUNITY_EDITION, STANDARD, PREMIUM, ENTERPRISE, DEDICATED

private_access_settings_idstring

ID of the workspace's private access settings object. Only used for PrivateLink. You must specify this ID if you are using AWS PrivateLink for either front-end (user-to-workspace connection), back-end (data plane to control plane connection), or both connection types.

Before configuring PrivateLink, read the <Databricks> article about PrivateLink.",

managed_services_customer_managed_key_idstring: ID of the key configuration for encrypting managed services.

storage_customer_managed_key_idstring: ID of the key configuration for encrypting workspace storage.

locationstring: The Google Cloud region of the workspace data plane in your Google account (for example, us-east4).

cloudstring: The cloud name. This field can have values like azure, gcp.

networkobject

The network configuration for the workspace.

DEPRECATED. Use network_id instead.

GCP

The network configuration for the workspace.

DEPRECATED. Use network_id, and gke_config instead.

Show child attributesHide child attributes

gcp_managed_network_configobject

The mutually exclusive network deployment modes. The option decides which network mode the workspace will use. The network config for GCP workspace with <Databricks> managed network. This object is input-only and will not be provided when listing workspaces.

Show child attributesHide child attributes

subnet_cidrstring: The IP range which will be used to allocate GKE cluster nodes from. Note: Pods, services and master IP range must be mutually exclusive.

gke_cluster_pod_ip_rangestring: The IP range that will be used to allocate GKE cluster Pods from.

gke_cluster_service_ip_rangestring: The IP range that will be used to allocate GKE cluster Services from.

network_idstring: The ID of the network object, if the workspace is a BYOVPC workspace. This should apply to workspaces on all clouds in internal services. In accounts-rest-api, user will use workspace.network_id for input and output instead. Currently (2021-06-19) the network ID is only used by GCP.

gcp_common_network_configobject

The shared network config for GCP workspace. This object has common network configurations that are network attributions of a workspace. This object is input-only.

Show child attributesHide child attributes

gke_connectivity_typestring: The type of network connectivity of the GKE cluster.
Values: PRIVATE_NODE_PUBLIC_MASTER, PUBLIC_NODE_PUBLIC_MASTER

gke_cluster_master_ip_rangestring: The IP range that will be used to allocate GKE cluster master resources from. This field must not be set if gke_cluster_type=PUBLIC_NODE_PUBLIC_MASTER.

azure_workspace_infoobject

Show child attributesHide child attributes

resource_groupstring: Azure Resource Group name

subscription_idstring: Azure Subscription ID

gke_configobject

GCP

The configurations of the GKE cluster used by the GCP workspace.

Show child attributesHide child attributes

connectivity_typestring: The type of network connectivity of the GKE cluster.
Values: PRIVATE_NODE_PUBLIC_MASTER, PUBLIC_NODE_PUBLIC_MASTER

master_ip_rangestring: The IP range that will be used to allocate GKE cluster master resources from. This field must not be set if gke_cluster_type=PUBLIC_NODE_PUBLIC_MASTER.

cloud_resource_containerobject

Show child attributesHide child attributes

gcpobject

GCP

The GCP cloud entities in which GCP workspaces are.

Show child attributesHide child attributes

project_idstring: GCP
The GCP project ID where the dataplane resources will be located in.

custom_tagsobject: The custom tags key-value pairing that is attached to this workspace. The key-value pair is a string of utf-8 characters. The value can be an empty string, with maximum length of 255 characters. The key can be of maximum length of 127 characters, and cannot be empty.

network_connectivity_config_idstring: The object ID of network connectivity config.

storage_modestring: The storage mode of the workspace.
Values: CUSTOMER_HOSTED, DEFAULT_STORAGE

compute_modestring: The compute mode of the workspace.
Values: HYBRID, SERVERLESS

View as Markdown

The Workspace object

{
  "workspace_id": 0,
  "workspace_name": "string",
  "aws_region": "string",
  "creation_time": 0,
  "deployment_name": "string",
  "workspace_status": "string",
  "account_id": "string",
  "credentials_id": "string",
  "storage_configuration_id": "string",
  "workspace_status_message": "string",
  "network_id": "string",
  "gcp_managed_network_config": {
    "subnet_cidr": "string",
    "gke_cluster_pod_ip_range": "string",
    "gke_cluster_service_ip_range": "string"
  },
  "pricing_tier": "string",
  "private_access_settings_id": "string",
  "managed_services_customer_managed_key_id": "string",
  "storage_customer_managed_key_id": "string",
  "location": "string",
  "cloud": "string",
  "network": {
    "gcp_managed_network_config": {},
    "network_id": "string",
    "gcp_common_network_config": {}
  },
  "azure_workspace_info": {
    "resource_group": "string",
    "subscription_id": "string"
  },
  "gke_config": {
    "connectivity_type": "string",
    "master_ip_range": "string"
  },
  "cloud_resource_container": {
    "gcp": {}
  },
  "custom_tags": {},
  "network_connectivity_config_id": "string",
  "storage_mode": "string",
  "compute_mode": "string"
}

Get GA

GET /api/2.0/accounts/{account_id}/workspaces/{workspace_id}

Gets information including status for a <Databricks> workspace, specified by ID. In the response, the workspace_status field indicates the current status. After initial workspace creation (which is asynchronous), make repeated GET requests with the workspace ID and check its status. The workspace becomes available when the status changes to RUNNING. For information about how to create a new workspace with this API including error handling, see Create a new workspace using the Account API.

API scopes: provisioning

Parameters

workspace_idint64path

account_idstringpath

Response

Returns the Workspace object.

View as Markdown

Response

{
  "workspace_id": 0,
  "workspace_name": "string",
  "aws_region": "string",
  "creation_time": 0,
  "deployment_name": "string",
  "workspace_status": "string",
  "account_id": "string",
  "credentials_id": "string",
  "storage_configuration_id": "string",
  "workspace_status_message": "string",
  "network_id": "string",
  "gcp_managed_network_config": {
    "subnet_cidr": "string",
    "gke_cluster_pod_ip_range": "string",
    "gke_cluster_service_ip_range": "string"
  },
  "pricing_tier": "string",
  "private_access_settings_id": "string",
  "managed_services_customer_managed_key_id": "string",
  "storage_customer_managed_key_id": "string",
  "location": "string",
  "cloud": "string",
  "network": {
    "gcp_managed_network_config": {},
    "network_id": "string",
    "gcp_common_network_config": {}
  },
  "azure_workspace_info": {
    "resource_group": "string",
    "subscription_id": "string"
  },
  "gke_config": {
    "connectivity_type": "string",
    "master_ip_range": "string"
  },
  "cloud_resource_container": {
    "gcp": {}
  },
  "custom_tags": {},
  "network_connectivity_config_id": "string",
  "storage_mode": "string",
  "compute_mode": "string"
}

Create GA

POST /api/2.0/accounts/{account_id}/workspaces

Creates a new workspace using a credential configuration and a storage configuration, an optional network configuration (if using a customer-managed VPC), an optional managed services key configuration (if using customer-managed keys for managed services), and an optional storage key configuration (if using customer-managed keys for storage). The key configurations used for managed services and storage encryption can be the same or different.

Important: This operation is asynchronous. A response with HTTP status code 200 means the request has been accepted and is in progress, but does not mean that the workspace deployed successfully and is running. The initial workspace status is typically PROVISIONING. Use the workspace ID (workspace_id) field in the response to identify the new workspace and make repeated GET requests with the workspace ID and check its status. The workspace becomes available when the status changes to RUNNING.

You can share one customer-managed VPC with multiple workspaces in a single account. It is not required to create a new VPC for each workspace. However, you cannot reuse subnets or Security Groups between workspaces. If you plan to share one VPC with multiple workspaces, make sure you size your VPC and subnets accordingly. Because a Databricks Account API network configuration encapsulates this information, you cannot reuse a Databricks Account API network configuration across workspaces.

For information about how to create a new workspace with this API including error handling, see Create a new workspace using the Account API.

Important: Customer-managed VPCs, PrivateLink, and customer-managed keys are supported on a limited set of deployment and subscription types. If you have questions about availability, contact your <Databricks> representative.

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.

API scopes: provisioning

CloudsAWSGCP

Parameters

account_idstringpath

Request body

workspace_namestring: The human-readable name of the workspace.
Constraints: [ 1 .. 100 ] characters

deployment_namestring: The deployment name defines part of the subdomain for the workspace. The workspace URL for the web application and REST APIs is <workspace-deployment-name>.cloud.databricks.com. For example, if the deployment name is abcsales, your workspace URL will be https://abcsales.cloud.databricks.com. Hyphens are allowed. This property supports only the set of characters that are allowed in a subdomain. To set this value, you must have a deployment name prefix. Contact your <Databricks> account team to add an account deployment name prefix to your account. Workspace deployment names follow the account prefix and a hyphen. For example, if your account's deployment prefix is acme and the workspace deployment name is workspace-1, the JSON response for the deployment_name field becomes acme-workspace-1. The workspace URL would be acme-workspace-1.cloud.databricks.com. You can also set the deployment_name to the reserved keyword EMPTY if you want the deployment name to only include the deployment prefix. For example, if your account's deployment prefix is acme and the workspace deployment name is EMPTY, the deployment_name becomes acme only and the workspace URL is acme.cloud.databricks.com. This value must be unique across all non-deleted deployments across all AWS regions. If a new workspace omits this property, the server generates a unique deployment name for you with the pattern dbc-xxxxxxxx-xxxx.
Example: workspace_1
Constraints: <= 64 characters

aws_regionstring: AWS
The AWS region of the workspace data plane (for example, us-west-2).

locationstring: The Google Cloud region of the workspace data plane in your Google account (for example, us-east4).

cloudstring: DEPRECATED: This field is being ignored by the server and will be removed in the future. The cloud name. This field always has the value gcp.

pricing_tierstring: Values: UNKNOWN, COMMUNITY_EDITION, STANDARD, PREMIUM, ENTERPRISE, DEDICATED

cloud_resource_containerobject

Show child attributesHide child attributes

gcpobjectRequired

GCP

The GCP cloud entities in which GCP workspaces are.

Show child attributesHide child attributes

project_idstring: GCP
The GCP project ID where the dataplane resources will be located in.

credentials_idstring: ID of the workspace's credential configuration object.

storage_configuration_idstring: ID of the workspace's storage configuration object.

network_idstring: The ID of the workspace's network configuration object. To use AWS PrivateLink, this field is required.

gcp_managed_network_configobject

GCP

The network config for GCP workspace with <Databricks> managed network.

Show child attributesHide child attributes

subnet_cidrstring: The IP range which will be used to allocate GKE cluster nodes from. Note: Pods, services and master IP range must be mutually exclusive.

gke_cluster_pod_ip_rangestring: The IP range that will be used to allocate GKE cluster Pods from.

gke_cluster_service_ip_rangestring: The IP range that will be used to allocate GKE cluster Services from.

gke_configobject

GCP

The configurations of the GKE cluster used by the GCP workspace.

Show child attributesHide child attributes

connectivity_typestring: The type of network connectivity of the GKE cluster.
Values: PRIVATE_NODE_PUBLIC_MASTER, PUBLIC_NODE_PUBLIC_MASTER

master_ip_rangestring: The IP range that will be used to allocate GKE cluster master resources from. This field must not be set if gke_cluster_type=PUBLIC_NODE_PUBLIC_MASTER.

private_access_settings_idstring: ID of the workspace's private access settings object. Only used for PrivateLink. You must specify this ID if you are using AWS PrivateLink for either front-end (user-to-workspace connection), back-end (data plane to control plane connection), or both connection types. Before configuring PrivateLink, read the <Databricks> article about PrivateLink.",

managed_services_customer_managed_key_idstring: The ID of the workspace's managed services encryption key configuration object. This is used to help protect and control access to the workspace's notebooks, secrets, Databricks SQL queries, and query history. The provided key configuration object property use_cases must contain MANAGED_SERVICES.
Example: 849b3d6b-e68e-468d-b3e5-deb08b03c56d

storage_customer_managed_key_idstring: The ID of the workspace's storage encryption key configuration object. This is used to encrypt the workspace's root S3 bucket (root DBFS and system data) and, optionally, cluster EBS volumes. The provided key configuration object property use_cases must contain STORAGE.
Example: 849b3d6b-e68e-468d-b3e5-deb08b03c56d

custom_tagsobject: The custom tags key-value pairing that is attached to this workspace. The key-value pair is a string of utf-8 characters. The value can be an empty string, with maximum length of 255 characters. The key can be of maximum length of 127 characters, and cannot be empty.

compute_modestring: If the compute mode is SERVERLESS, a serverless workspace is created that comes pre-configured with serverless compute and default storage, providing a fully-managed, enterprise-ready SaaS experience. This means you don't need to provide any resources managed by you, such as credentials, storage, or network. If the compute mode is HYBRID (which is the default option), a classic workspace is created that uses customer-managed resources.
Values: HYBRID, SERVERLESS
Example: SERVERLESS

network_connectivity_config_idstring: The object ID of network connectivity config. Once assigned, the workspace serverless compute resources use the same set of stable IP CIDR blocks and optional private link to access your resources.
Example: 0560fb5c-0ec3-4018-bd88-9820331d9eab

Response

Returns the Workspace object.

View as Markdown

Request

{
  "workspace_name": "string",
  "deployment_name": "workspace_1",
  "aws_region": "string",
  "location": "string",
  "cloud": "string",
  "pricing_tier": "string",
  "cloud_resource_container": {
    "gcp": {}
  },
  "credentials_id": "string",
  "storage_configuration_id": "string",
  "network_id": "string",
  "gcp_managed_network_config": {
    "subnet_cidr": "string",
    "gke_cluster_pod_ip_range": "string",
    "gke_cluster_service_ip_range": "string"
  },
  "gke_config": {
    "connectivity_type": "string",
    "master_ip_range": "string"
  },
  "private_access_settings_id": "string",
  "managed_services_customer_managed_key_id": "849b3d6b-e68e-468d-b3e5-deb08b03c56d",
  "storage_customer_managed_key_id": "849b3d6b-e68e-468d-b3e5-deb08b03c56d",
  "custom_tags": {},
  "compute_mode": "SERVERLESS",
  "network_connectivity_config_id": "0560fb5c-0ec3-4018-bd88-9820331d9eab"
}

Response

{
  "workspace_id": 0,
  "workspace_name": "string",
  "aws_region": "string",
  "creation_time": 0,
  "deployment_name": "string",
  "workspace_status": "string",
  "account_id": "string",
  "credentials_id": "string",
  "storage_configuration_id": "string",
  "workspace_status_message": "string",
  "network_id": "string",
  "gcp_managed_network_config": {
    "subnet_cidr": "string",
    "gke_cluster_pod_ip_range": "string",
    "gke_cluster_service_ip_range": "string"
  },
  "pricing_tier": "string",
  "private_access_settings_id": "string",
  "managed_services_customer_managed_key_id": "string",
  "storage_customer_managed_key_id": "string",
  "location": "string",
  "cloud": "string",
  "network": {
    "gcp_managed_network_config": {},
    "network_id": "string",
    "gcp_common_network_config": {}
  },
  "gke_config": {
    "connectivity_type": "string",
    "master_ip_range": "string"
  },
  "cloud_resource_container": {
    "gcp": {}
  },
  "custom_tags": {},
  "network_connectivity_config_id": "string",
  "storage_mode": "string",
  "compute_mode": "string"
}

Update GA

PATCH /api/2.0/accounts/{customer_facing_workspace.account_id}/workspaces/{customer_facing_workspace.workspace_id}

Updates a workspace.

API scopes: provisioning

CloudsAWSAzure

AWS

Updates the configuration of a running workspace.

Updatable fields include:

credentials_id: The credential configuration ID.
network_id: The network configuration ID. You can only update this field if the workspace already uses a customer-managed VPC.
managed_services_customer_managed_key_id: The key configuration ID for managed services.
storage_customer_managed_key_id: The key configuration ID for workspace storage. You cannot replace an existing key configuration for workspace storage. This field is only updatable for workspaces without a key configuration for workspace storage.
private_access_settings_id: The private access settings ID. Can add or upgrade PrivateLink support, but you cannot downgrade a workspace that already has PrivateLink support.
custom_tags: The custom tags. If you update the workspace with empty custom tags, no update is applied.
network_connectivity_config_id: The network connectivity configuration ID. Once attached to a workspace, this can be switched but not removed.

Important: To update a running workspace, you must first stop all running compute resources in the workspace's VPC in the classic data plane, including all-purpose compute, job compute, pools with running compute, and classic SQL warehouses.

This operation is asynchronous. After calling PATCH, poll the workspace with GET requests and check the workspace status. The update is successful when the status changes from PROVISIONING to RUNNING. Wait up to 20 minutes after the workspace is running before creating or using compute.

If you update only the managed services key configuration, you do not need to stop DBFS API calls. For storage customer-managed key configurations, stop all DBFS API calls for 20 minutes while changes take effect.

Azure

Updates a workspace configuration. This API allows you to assign the workspace to a network connectivity configuration object. Upon assignment, the network configuration will propagated to the serverless compute plane of your Azure <Databricks> workspace. It will be applied after you create or restart your serverless SQL warehouses. See configure serverless secure connectivity.

Parameters

customer_facing_workspaceobjectpath

Show child attributesHide child attributes

workspace_idint64: A unique integer ID for the workspace

workspace_namestring: The human-readable name of the workspace.
Constraints: [ 1 .. 100 ] characters

aws_regionstring: AWS
The AWS region of the workspace data plane (for example, us-west-2).

creation_timeint64: Time in epoch milliseconds when the workspace was created.

deployment_namestring: AWS
The deployment name defines part of the subdomain for the workspace. The workspace URL for web application and REST APIs is <deployment-name>.cloud.databricks.com.
Constraints: <= 64 characters

workspace_statusstring: The status of a workspace
Values: NOT_PROVISIONED, PROVISIONING, RUNNING, FAILED, BANNED, CANCELLING

account_idstring: <Databricks> account ID.

credentials_idstring: ID of the workspace's credential configuration object.

storage_configuration_idstring: ID of the workspace's storage configuration object.

workspace_status_messagestring: Message describing the current workspace status.

network_idstringRequired: If this workspace is BYO VPC, then the network_id will be populated. If this workspace is not BYO VPC, then the network_id will be empty.

pricing_tierstring: Values: UNKNOWN, COMMUNITY_EDITION, STANDARD, PREMIUM, ENTERPRISE, DEDICATED

private_access_settings_idstring

Before configuring PrivateLink, read the <Databricks> article about PrivateLink.",

managed_services_customer_managed_key_idstring: ID of the key configuration for encrypting managed services.

storage_customer_managed_key_idstring: ID of the key configuration for encrypting workspace storage.

azure_workspace_infoobject

Show child attributesHide child attributes

resource_groupstring: Azure Resource Group name

subscription_idstring: Azure Subscription ID

custom_tagsobject: The custom tags key-value pairing that is attached to this workspace. The key-value pair is a string of utf-8 characters. The value can be an empty string, with maximum length of 255 characters. The key can be of maximum length of 127 characters, and cannot be empty.

network_connectivity_config_idstring: The object ID of network connectivity config.

storage_modestring: The storage mode of the workspace.
Values: CUSTOMER_HOSTED, DEFAULT_STORAGE

compute_modestring: The compute mode of the workspace.
Values: HYBRID, SERVERLESS

Response

Returns the Workspace object.

View as Markdown

Response

{
  "workspace_id": 0,
  "workspace_name": "string",
  "aws_region": "string",
  "creation_time": 0,
  "deployment_name": "string",
  "workspace_status": "string",
  "account_id": "string",
  "credentials_id": "string",
  "storage_configuration_id": "string",
  "workspace_status_message": "string",
  "network_id": "string",
  "pricing_tier": "string",
  "private_access_settings_id": "string",
  "managed_services_customer_managed_key_id": "string",
  "storage_customer_managed_key_id": "string",
  "azure_workspace_info": {
    "resource_group": "string",
    "subscription_id": "string"
  },
  "custom_tags": {},
  "network_connectivity_config_id": "string",
  "storage_mode": "string",
  "compute_mode": "string"
}

Delete GA

DELETE /api/2.0/accounts/{account_id}/workspaces/{workspace_id}

Deletes a <Databricks> workspace, both specified by ID.

API scopes: provisioning

CloudsAWSGCP

Parameters

workspace_idint64path

account_idstringpath

Response

Returns the Workspace object.

View as Markdown

Response

{
  "workspace_id": 0,
  "workspace_name": "string",
  "aws_region": "string",
  "creation_time": 0,
  "deployment_name": "string",
  "workspace_status": "string",
  "account_id": "string",
  "credentials_id": "string",
  "storage_configuration_id": "string",
  "workspace_status_message": "string",
  "network_id": "string",
  "gcp_managed_network_config": {
    "subnet_cidr": "string",
    "gke_cluster_pod_ip_range": "string",
    "gke_cluster_service_ip_range": "string"
  },
  "pricing_tier": "string",
  "private_access_settings_id": "string",
  "managed_services_customer_managed_key_id": "string",
  "storage_customer_managed_key_id": "string",
  "location": "string",
  "cloud": "string",
  "network": {
    "gcp_managed_network_config": {},
    "network_id": "string",
    "gcp_common_network_config": {}
  },
  "gke_config": {
    "connectivity_type": "string",
    "master_ip_range": "string"
  },
  "cloud_resource_container": {
    "gcp": {}
  },
  "custom_tags": {},
  "network_connectivity_config_id": "string",
  "storage_mode": "string",
  "compute_mode": "string"
}

Workspace object​

Get GA​

Parameters​

Response​

Create GA​

Parameters​

Request body​

Response​

Update GA​

Parameters​

Response​

Delete GA​

Parameters​

Response​

Workspace object

Get GA

Parameters

Response

Create GA

Parameters

Request body

Response

Update GA

Parameters

Response

Delete GA

Parameters

Response