Skip to main content

Create a workspace using the Account API

This page explains how to use the Workspace APIs to deploy a new workspace in your Databricks account.

Required configuration objects​

To create a Databricks workspace, you must reference the following two configuration objects. You can use existing configurations in your account, or create new ones if needed.

  • Storage configuration: Defines and grants Databricks access to the root S3 bucket where workspace assets such as data, libraries, and logs are stored. See Create a storage configuration
  • Credential configuration: Grants Databricks permission to deploy resources in your AWS account. See Create a credential configuration.

Additional configuration objects​

If you would like to use any of the following features, you must reference specific configuration objects when you deploy your workspace:

Create workspace parameter reference​

Here is an example CLI command that creates a new workspace:

Bash
databricks account workspaces create --json '{
  "aws_region": "us-west-2",
  "workspace_name": "string",
  "deployment_name": "workspace-1",
  "pricing_tier": "PREMIUM",
  "storage_configuration_id": "b43a6064-04c1-4e1c-88b6-d91e5b136b13",
  "credentials_id": "ccc64f28-ebdc-4c89-add9-5dcb6d7727d8",
  "network_id": "fd0cc5bc-683c-47e9-b15e-144d7744a496",
  "private_access_settings_id": "3b3bbcb5-46bd-4b03-944e-97eb44ed7991",
  "managed_services_customer_managed_key_id": "849b3d6b-e68e-468d-b3e5-deb08b03c56d",
  "storage_customer_managed_key_id": "14138d0f-a575-4ae2-be71-ddfd0b602286",
  "custom_tags": {
    "property1": "string",
    "property2": "string"
  }
}'

Standard parameters​

  • aws_region: The AWS region of the workspace’s compute plane. See Databricks clouds and regions.
  • workspace_name: Human-readable name for your workspace. This is the workspace name users see in the Databricks UI.
  • deployment_name: (Recommended but optional) Unique deployment name for your workspace. For details, see the Workspace API reference.
  • custom_tags: Key-value pairs that act as metadata for organizing resources. Tags can help to manage, identify, organize, search, and filter resources, as well as monitor cost and attribute usage.
  • pricing_tier: The pricing tier of the workspace. PREMIUM, ENTERPRISE, or COMMUNITY_EDITION
  • storage_configuration_id: Your storage configuration ID, which represents your root S3 bucket. Use an existing configuration or create a new storage configuration.
  • credentials_id: Your credential configuration ID. Use an existing configuration or create a new credential configuration.

Advanced configurations​

Use the following optional parameters to configure networking and security features in your workspace:

  • network_id: The network configuration ID. Required when deploying the workspace in a customer-managed VPC. See Create network configurations for custom VPC deployment.
  • private_access_settings_id: The ID of the private access settings object used to enable AWS PrivateLink. See Manage private access settings. Required for PrivateLink access for all connection types (front-end, back-end, or both). Must be configured when you deploy the workspace.
  • managed_services_customer_managed_key_id: The key configuration ID for managed services, which is the customer_managed_key_id field from a key configuration object. Used to encrypt managed services such as notebook and secret data in the control plane. If you are encrypting both managed services and workspace storage, use the same ID in the storage_customer_managed_key_id field. Must be configured when you deploy the workspace. See Customer-managed keys for managed services.
  • storage_customer_managed_key_id: The key configuration ID for workspace storage, which is the customer_managed_key_id field from the key configuration object. If you are encrypting both managed services and workspace storage, use the same ID in the managed_services_customer_managed_key_id field. Used only to encrypt workspace storage. Must be configured when you deploy the workspace. See Customer-managed keys for workspace storage.

Create workspace response​

After you call the create workspace API, you will receive a response similar to the following:

JSON
{
  "account_id": "449e7a5c-69d3-4b8a-aaaf-5c9b713ebc65",
  "aws_region": "string",
  "creation_time": 0,
  "credentials_id": "c7814269-df58-4ca3-85e9-f6672ef43d77",
  "custom_tags": {
    "property1": "string",
    "property2": "string"
  },
  "deployment_name": "string",
  "managed_services_customer_managed_key_id": "faacdc79-6530-4583-a154-5d427a663e53",
  "network_id": "d6797cf4-42b9-4cad-8591-9dd91c3f0fc3",
  "pricing_tier": "PREMIUM",
  "private_access_settings_id": "3b3bbcb5-46bd-4b03-944e-97eb44ed7991",
  "storage_configuration_id": "04aae505-1b1e-4cb9-997d-e1c49282675d",
  "storage_customer_managed_key_id": "14138d0f-a575-4ae2-be71-ddfd0b602286",
  "workspace_id": 1614665312930232,
  "workspace_name": "string",
  "workspace_status": "PROVISIONING",
  "workspace_status_message": "Workspace resources are being set up."
}

If you receive an error when creating your workspace, see Troubleshoot workspace creation errors.

Confirm the new workspace​

To check workspace status, call the get workspace API.

Use the workspace_id value from the JSON response returned when you created the workspace.

In the response, possible workspace_status values are:

  • NOT_PROVISIONED:  Not yet provisioned.
  • PROVISIONING: Still provisioning. Wait a few minutes and repeat this API request.
  • RUNNING: Successful deployment and now running.
  • FAILED: Failed deployment.
  • BANNED: Banned.
  • CANCELLING: In process of cancellation.

Troubleshoot workspace creation errors​

The following sections provide solutions for common workspace creation errors.

The maximum number of addresses has been reached​

When Databricks creates a VPC on your behalf, you must have at least one unused Elastic IP. Otherwise, the VPC isn't created and the following error occurs:

Console
The maximum number of addresses has been reached.

Increase the number of Elastic IPs and try again.

General troubleshooting steps​

For all workspace creation errors, try the following troubleshooting steps in the order provided.

Validate network​

If the workspace creation or status check steps indicate a network-related error, call the get network configuration API to ensure that the network settings are correct.

In the response, view the warning_messages error_messages fields. If both arrays are empty, there are no warnings or errors.

Otherwise, review the warnings and error JSON objects carefully:

  • For warnings, the warning_type enumeration indicates that the problem was with either a subnet or security group. The warning_message provides additional details. Be aware that if you have a firewall or NAT instance (instead of a NAT gateway), the network validation always issues a warning.
  • For errors, the error_type enumeration indicates that the problem was with either credentials, VPC, subnet, security group, or network ACL. The error_message provides additional details.

Fix infrastructure issues​

Depending on the errors in the response to the get network configuration API API request, confirm that:

Update the failed workspace​

To update the failed workspace, call the Update workspace API.

note

You can use the same API to update a running (successfully deployed) workspace but you only can change the credential and network configurations.

You can pass these workspace configuration fields to change them: credentials_id, storage_configuration_id, network_id, managed_services_customer_managed_key_id, and storage_customer_managed_key_id.

If the workspace_status value returns PROVISIONING, keep checking for RUNNING state using the get workspace API.

If the workspace update fails, recreate the network and workspace​

If the update workspace API doesn't work, you must delete and recreate the network (if you provided your own VPC) and the failed workspace in the following order.

  1. Delete the workspace using the delete workspace API.

  2. If you provided your own VPC, delete the network configuration using the delete network configuration API.

  3. Recreate the network using the correct values for vpc_id, subnet_ids and security_group_ids.

  4. Recreate the workspace using the correct values for credentials_id, storage_configuration_id, network_id, managed_services_customer_managed_key_id, and storage_customer_managed_key_id.

    If you get the workspace_status value PROVISIONING, keep checking for RUNNING state using the get workspace API.

Last updated on