Update a running Databricks workspace

Account admins can change a running workspace's credential configuration, network configuration, customer-managed keys, and AWS PrivateLink settings after deployment. Only a subset of fields is updatable. Workspaces in the FAILED state cannot be updated at all and must be recreated.

Use either the account console or the Account API to update a workspace object. Workspace updates run asynchronously: when you submit an update, the workspace status changes to PROVISIONING and returns to RUNNING after all updates are complete.

Failed workspaces cannot be updated

important

You cannot update a workspace that is in the FAILED state. Both the account console and the Account API reject the update and return the following message:

Console

Updating a failed workspace is no longer supported. Please create a new workspace or reach out to Databricks.

To recover from a failed deployment, delete the failed workspace and create a new one with a corrected configuration. See Create a classic workspace or Create a workspace using the Account API. For help diagnosing why the deployment failed, see Troubleshoot Databricks workspace creation. If the error messages are unclear, contact your Databricks account team.

Before you recreate the workspace, click the failed workspace on the Workspaces page and read Workspace Status Message to find the cause. If the message points to a specific configuration object, open that object for more detail. For example, if the error mentions the network, go to Cloud resources > Network configurations. Open the failed network configuration to see errors such as invalid subnet IDs or bad address ranges. Delete any failed configuration object and create a new one to use for the replacement workspace.

Common causes:

• For credential configurations, confirm that your cross-account identity and access management (IAM) policy includes the required permissions. See Create a credential configuration for the policy to use for your deployment type. Which policy you need depends on whether you use the Databricks-managed virtual private cloud (VPC) or provide your own VPC.
• For network configurations, confirm that your VPC, subnets, and security groups comply with the customer-managed VPC requirements.

note

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

What you can update

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 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 Configure classic private connectivity to Databricks.
  • 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 credentials and network configurations.

1. Log in to the account console as an account admin.

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

3. Click Configure, then select Update Workspace.

4. Edit the available fields for a running workspace. For the list of available fields, see the list at the beginning of this section.

5. Click Update.

6. Wait for the workspace update to take effect. When you submit an update, the workspace status changes to PROVISIONING. The update response returns the workspace in PROVISIONING state with pre-update field values.

   important

   • Wait for the workspace status to return to RUNNING before reading updated field values. Do not rely on field values while the workspace is in PROVISIONING state.
   • If the update fails, the system rolls back the workspace to its previous configuration and returns it to RUNNING state.
   • If both the update and rollback fail, the workspace status changes to FAILED. You cannot update the workspace again to recover it. See Failed workspaces cannot be updated.
   • You cannot use or create compute resources while the workspace is updating, and for another 20 minutes after the status returns to RUNNING. If you create or use compute before this time interval elapses, the compute launch might fail or 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.