Create and manage workspaces using the account console

A workspace is a Databricks deployment in a cloud service account. It provides a unified environment for working with Databricks assets for a specified set of users.

This article describes how to create and manage workspaces using the account console for accounts on the E2 version of the platform. To learn how to create and manage workspaces using the Account API, see Create a new workspace using the Account API.

Note

If your account is not on the E2 version of the platform, see Access the account console (legacy). All new Databricks accounts and most existing accounts are now E2. If you are unsure which account type you have, contact your Databricks representative.

Be sure that you understand all configuration settings before you create a new workspace. There are limits to the modifications you can make to a workspace configuration:

  • You can update the configuration of a workspace that fails to deploy, but only a subset of the fields.
  • You can update a running workspace, but only to change the credential configuration or the network configuration. You can change the network configuration only if the workspace already uses a Customer-managed VPC.

Important

The account console does not support creating a workspace that uses customer-managed keys for managed services (Public Preview) or AWS PrivateLink (Public Preview). To use these two features, create your workspace using the Account API instead of the account console.

Create a workspace

To create a workspace:

  1. Go to the account console and click the Workspaces icon.

    This is the account console default view.

  2. Click Create Workspace.

  3. In the Workspace Name field, enter a human-readable name for this workspace. It can contain spaces.

  4. In the Workspace URL field, enter a deployment name (optional). This field may be hidden for some customers.

    The deployment name defines part of the subdomain for the workspace. The workspace URL for access to the Databricks 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. This value must be unique across all workspaces across all AWS regions, not including deleted workspaces. If you leave this field blank, the server generates a unique deployment name for you with the pattern dbc-xxxxxxxx-xxxx.

    Some Databricks accounts have a deployment name prefix that interacts with this feature. Contact your Databricks representative to set a deployment name prefix for your account. If your account has a deployment name prefix, the final workspace deployment name includes the account prefix followed by a hyphen. For example, if your account’s deployment prefix is acme and you enter the deployment name as workspace-1, the new workspace’s deployment name becomes acme-workspace-1. The final workspace URL is acme-workspace-1.cloud.databricks.com.

    The deployment name must adhere to the Databricks acceptable use policy.

  5. In the Pricing Tier field, select the pricing tier (plan) that you want to associate with this workspace. Depending on your account, there may be only one choice. For detailed information about pricing tiers, see Databricks AWS pricing.

  6. In the Region field, select an AWS region for your workspace’s network and clusters.

  7. In the Credentials field, select or add a credential configuration, which references a cross-account IAM role in your AWS account to delegate limited access to Databricks.

    You must set up the AWS cross-account IAM role in your account so that Databricks can perform certain tasks in your account, such as creating new Databricks Runtime clusters.

    If you have already created credential configurations, they appear in the picker, and you can select one.

    If you want to create a new credential configuration, select + Add a new credential configuration to open the Add Credential Configuration dialog and follow these instructions:

    1. Create a cross-account IAM role
    2. Create a credential configuration
  8. In the Storage field, select or add a storage configuration, which contains the name of an AWS S3 bucket that stores certain workspace objects, such as libraries, logs, and notebook version history.

    If you have already created storage configurations, they appear in the picker, and you can select one.

    If you want to create a new storage configuration, select + Add a new storage configuration to open the Add Storage Configuration dialog and follow the instructions in Manage storage configurations using the account console (E2).

  9. (Optional) If you want to use your own VPC (a feature known as customer-managed VPC), use the Advanced Settings > Network Configuration field to select or configure a network configuration.

    By default, Databricks creates a VPC for each workspace it creates in your AWS account. If you choose, you can use a customer-managed VPC and configure it according to your organization’s enterprise cloud standards while still conforming to Databricks requirements.

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

    The maximum number of addresses has been reached.
    

    If you have already created network configurations, select one from the Network Configuration picker. If you want to create a new network configuration, select + Add a new network configuration and follow the instructions in Manage network configurations using the account console (E2).

    Note

    If you want to use a customer-managed VPC, the IAM role referenced in the workspace’s credential configuration must use a role policy that supports customer-managed VPCs. The instructions in Create a cross-account IAM role explain which role policy to use.

  10. Click Create.

  11. Confirm that your workspace was created successfully. See View workspace status and test the new workspace.

View workspace status and test the new workspace

You are automatically added as a workspace admin to any workspace that you create. After you create a workspace (or update a failed workspace configuration), you can view it on the Workspaces page and follow a link from that page to access the workspace.

  1. View the workspace creation Status column for your new workspace:
    • Provisioning: In progress. Wait a few minutes and refresh the page.
    • Running: Successful workspace deployment. Continue to the next step in this procedure.
    • Failed: Failed deployment. However, you can update the failed workspace configuration and re-attempt workspace creation with the new configuration. See Update a workspace.
    • Banned: Contact your Databricks representative.
    • Cancelling: In the process of cancellation.
  2. When your new workspace is Running, test your workspace:
    1. From the Actions menu in the Workspace row, select Visit Workspace.
    2. Log in with your account owner or account administrator email address and password.

Update a workspace

You can make limited modifications to workspaces that have already been created. Available updates depend on whether the workspace configuration is in a failed state or is already running:

  • You can update the configuration of a workspace that fails to deploy, but only a subset of the fields.
  • You can update a running workspace, but only to change the credential configuration or the network configuration. You can change the network configuration only if the workspace already uses a Customer-managed VPC.

Update a failed workspace

If the status for your new workspace is Failed, you can update the failed workspace configuration and try workspace creation again with the new configuration.

  1. On the Workspaces page, click the name of the failed workspace.

  2. View the error message in Workspace Status Message.

    This may tell you the cause of the problem. If the error mentions credential, storage, or network validation, depending on the issue you may need to go to additional pages to view the exact errors. Your next step depends on what is wrong. You may need to select a different configuration object than you originally used.

    One of your individual configurations may have problems. For example, if the workspace error mentions a problem with the network, go to Account Settings > Network configurations for more details. The details view of the failed network configuration includes error messages that identify problems such as invalid subnet IDs or bad address ranges.

    Note

    If you have a firewall or NAT instance (instead of a NAT gateway), network validation issues a warning.

    For any failed configuration, delete it and create a new one. See Delete a credential configuration, Delete a storage configuration, and Delete a network configuration.

    Common issues:

    • For credential configurations, confirm that your cross-account IAM policy includes the required permissions. See Create a cross-account IAM role for the policy to use for your deployment type. When deciding what role policy to use, decide whether you want to use the default Databricks-managed VPC or provide your own VPC. Follow instructions on that page for the role policy to use.
    • For network configurations, confirm that your VPC, subnets, and security groups comply with the customer-managed VPC requirements.
  3. On the Workspaces page, click the workspace name, click Configure, then select Update Workspace.

  4. Edit workspace configuration fields as needed. For example, select a different credential or storage configuration. You cannot change the workspace name or workspace URL.

  5. Click Update.

  6. Check the status. See View workspace status and test the new workspace.

    For additional guidance or error messages that are not clear, contact your Databricks representative.

Update a running workspace

For a running workspace, you can update only the credential and network configurations.

  1. On the Workspaces page, click the workspace name.

  2. Click Configure, then select Update Workspace.

  3. Edit the available fields for a running workspace:

    • Edit the credential configuration.
    • Expand Advanced configurations to edit the network configuration. You can change the network configuration only if the workspace already uses a Customer-managed VPC.
  4. Click Update.

  5. Wait for the workspace update to take effect.

    Important

    • For workspaces with a Databricks-managed VPC, the workspace status becomes PROVISIONING temporarily (typically under 20 minutes). If the workspace update is successful, the workspace status changes to RUNNING. You can check the workspace status in the list of workspaces inthe account console. However, you cannot use or create clusters for another 20 minutes after that status change. This results in a total of up to 40 minutes in which you cannot create clusters. If you create or use clusters before this time interval elapses, clusters do not launch successfully, fail, or could cause other unexpected behavior.
    • For workspaces with a customer-managed VPC, the workspace status stays at status RUNNING and the VPC change happens immediately. However, you cannot use or create clusters for another 20 minutes. If you create or use clusters before this time interval elapses, clusters do not launch successfully, fail, or could cause other unexpected behavior.

Optional post-deployment configurations

  • Enable IP access lists: Configure the IP addresses from which you want to allow users to connect to the web application, REST APIs, JDBC/ODBC endpoints, and DBConnect. You can specify allow lists and block lists as IP addresses or ranges. See IP access lists.
  • Enable audit logging: Databricks strongly recommends that you configure audit logging to monitor the activities performed and usage incurred by your Databricks users. You must contact your Databricks representative to enable audit logs for your new workspace. See Configure audit logging for instructions.

Log into a workspace

  1. Go to the account console and click the Workspaces icon.
  2. On the row with your workspace, click Actions, then Visit Workspace. Alternatively, click the workspace name, then click the link under the URL label.
  3. To log in as a workspace administrator, log in with your account owner or account administrator email address and password. If you configured single-sign on (SSO), click the Single Sign On tab, and then click the large blue Single Sign On button.

Delete a workspace

  1. Go to the account console and click the Workspaces icon.
  2. On the row with your workspace, click Actions, then Delete. Alternatively, click the workspace name, click the Configure button, and select Delete Workspace.
  3. In the confirmation dialog, type the workspace name and click Confirm Delete.