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 for some changes:

    • You can update the credential configuration, the network configuration, enable Unity Catalog, and add customer-managed keys.

    • You can change the network configuration only if the workspace already uses a Customer-managed VPC.

    • Although it is supported to update an existing workspace to enable AWS PrivateLink, you cannot use the account console to update the private access settings field on a running workspace. Contact your Databricks representative to perform the workspace update step for you. Note that if you already have PrivateLink enabled, you can use the account console to update fields in the private access settings object, but you cannot add a new private access settings object to a running workspace to enable PrivateLink.

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. Log in to the account console as an account admin.

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

  3. 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 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.

  4. On the Workspaces page, click the workspace name, click Configure, then select Update Workspace.

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

  6. Click Update.

  7. 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. 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:

    • 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.

  5. Click Update.

  6. 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.