Update a running or failed workspace

This article describes how to make workspace changes using the admin settings page. 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 also make workspace changes using the Account API. With the API, you can update a workspace object or other objects. See the Account API.

Update a failed workspace

You can update the configuration of a workspace that fails to deploy, but only a subset of the fields:

Change the credential configuration.
Change the storage configuration.
Change the network configuration. If a network configuration is already set, you can change it. For a failed workspace only, you can convert a workspace with a Databricks-managed VPC to instead use a customer-managed VPC. To do so, add a network configuration.

Important

If you change a workspace to use a customer-managed VPC, Databricks recommends also changing your credentials configuration to use an access policy specific to <Databricks> workspaces with customer-managed VPCs, since it’s a smaller set of required permissions.
Add customer-managed keys for managed services (certain types of control plane storage, such as notebook source and Databricks SQL queries).
Add customer-managed keys for workspace storage (root S3 bucket and optionally EBS volumes). You can add keys for workspace storage in this update only if the workspace does not already have a key configuration for workspace storage. If the workspace was ever in the running state, even if briefly before becoming a failed workspace, you cannot add a new key configuration ID for workspace storage.
Enable or update AWS PrivateLink configuration settings:
- Enable PrivateLink by updating the network configuration and adding a private access settings. If the workspace already has PrivateLink enabled, you can use the account console to update fields in the private access settings object or you can add a new private access settings object to a running workspace. Note that you can add (upgrade) front-end, back-end, or both types of connectivity, but you cannot remove (downgrade) any existing front-end or back-end PrivateLink support. To use the new network configuration, create a new network configuration with new settings, for example for a new VPC or different PrivateLink support settings, and then update the workspace. For other important details, see Enable AWS PrivateLink.
- Add or update a workspace’s registered VPC endpoints by creating a new network configuration object with registered VPC endpoints and then update the workspace’s network configuration.
- To update CIDR ranges on an existing VPC, see Updating CIDRs.

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.

Log in to the account console as an account admin.
On the Workspaces page, click the name of the failed workspace.
View the error message in Workspace Status Message.

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

One of the workspace’s individual configurations could have an error. For example, if the workspace error mentions a problem with the network, go to Cloud resources > 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 an IAM role for workspace deployment 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.
On the Workspaces page, click the workspace name, click Configure, then select Update Workspace.
Edit workspace configuration fields as needed. For example, select a different credential or storage configuration. You cannot change the workspace name or workspace URL. For the list of available fields for failed workspaces, see the list at the beginning of this section.
Click Update.
Check the status. See View workspace status.

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

Update a running workspace

You can update a running workspace, but only a subset of the fields:

Change the credential configuration.
Change the network configuration only if the workspace already uses a Configure a customer-managed VPC.
Enable Unity Catalog.
Add customer-managed keys for managed services or workspace storage. You can add keys for workspace storage in this update only if the workspace does not already have a key configuration for workspace storage.
Enable or update AWS PrivateLink configuration settings:
- Enable PrivateLink by updating the network configuration and adding a private access settings. If the workspace already has PrivateLink enabled, you can use the account console to update fields in the private access settings object or you can add a new private access settings object to a running workspace. Note that you can add (upgrade) front-end, back-end, or both types of connectivity, but you cannot remove (downgrade) any existing front-end or back-end PrivateLink support. To use the new configuration, create a new network configuration with new settings, for example for a new VPC or different PrivateLink support settings, and then update the workspace. For other important details, see Enable AWS PrivateLink.
- Add or update a workspace’s registered VPC endpoints by creating a new network configuration object with registered VPC endpoints and then update the workspace’s network configuration. You can also do this step using the Account API.
- To update CIDR ranges on an existing VPC, see Updating CIDRs.

Note

If you update a workspace with a Databricks-managed VPC, the update will delete and recreate the workspace’s VPC, subnets, and security groups.

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

Log in to the account console as an account admin.
On the Workspaces page, click the workspace name.
Click Configure, then select Update Workspace.
Edit the available fields for a running workspace. For the list of available fields for failed workspaces, see the list at the beginning of this section.
Click Update.
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 in the 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 Configure IP access lists for workspaces.
Enable audit logging: Databricks strongly recommends that you configure audit logging to monitor the activities performed and usage incurred by your Databricks users. See Configure audit log delivery for instructions.