Create a workspace using the account console

This article describes how to create and manage workspaces using the account console. Alternatively, you can create a workspace using the Account API or Terraform.

Before you begin

  • Be sure that you understand all configuration settings before you create a new workspace. You cannot modify a workspace configuration after you create the workspace.

  • You must have some required Google permissions on your account, which can be a Google Account or a service account. See Required permissions.

  • Be sure you have enough Google Cloud resource quotas needed for the workspace. Request a quota increase if you need to.

  • Do not modify or customize the Google Kubernetes Engine (GKE) cluster that is launched by Databricks for your workspace. If you have a need to customize the cluster, please contact your Databricks account team to ascertain the safety and long term maintainability of such a change.

Create a workspace

To create a workspace:

  1. Choose a network type for your new workspace:

  2. As a Databricks account admin, log in to the account console and click the Workspaces icon.

  3. Click Create Workspace.

  4. In the Workspace Name field, enter a human-readable name for this workspace. Only alphanumeric characters, underscores, and hyphens are allowed, and the name must be 3-30 characters long.

  5. In the Region field, select a region for your workspace’s network and clusters. For the list of supported regions, see Databricks clouds and regions.

  6. In the Google cloud project ID field, enter your Google Cloud project ID. To learn how to get your project ID, see Requirements.

    If you plan to use a customer-managed VPC for this workspace:

    • If it is a standalone VPC, set this to the project ID for your VPC.

    • If it is a Shared VPC, set this to the project ID for this workspace’s resources.

  7. Network setup. This step varies based on the workspace’s network type. For a customer-managed VPC, click the Customer-managed VPC tab.

    • Optionally specify custom subnet sizes. If you leave these fields blank, Databricks uses defaults.

      Important

      Configure the GKE subnets used by your Databricks workspace accurately. You cannot change them after your workspace is deployed. If the address ranges for your Databricks subnets are too small, then the workspace exhausts its IP space, which in turn causes your Databricks jobs to fail. To determine the address range sizes that you need, Databricks provides a subnet calculator as a Microsoft Excel spreadsheet.

      Click Advanced configurations to specify custom IP ranges in CIDR format. The IP ranges for these fields must not overlap. All IP addresses must be entirely within the following ranges: 10.0.0.0/8, 100.64.0.0/10, 172.16.0.0/12, 192.168.0.0/16, and 240.0.0.0/4.

      The sizes of these IP ranges affect the maximum number of nodes for the workspace.

      • In the Subnet CIDR field, type the IP range in CIDR format to use for the subnet. Nodes of the GKE cluster come from this IP range. This is also the IP range of the subnet where the GKE cluster lives. Range must be no bigger than /9 and no smaller than /29.

      • In the Pod address range field, type the IP range in CIDR format to use as the secondary IP range for GKE pods. Range must be no bigger than /9 and no smaller than /21.

      • In the Service address range field, type the IP range in CIDR format to use as the secondary IP range for GKE services. Range must be no bigger than /16 and no smaller than /27.

    • Specify a network configuration that represents your VPC and its subnets:

      • Network Mode: Set this to Customer-managed network.

      • Network configuration: Select your network configuration’s name.

  8. (Optional) Configure details about private GKE clusters.

    • By default, Databricks creates a private GKE cluster instead of a public GKE cluster. A private cluster’s GKE nodes have no public IP that is routable in the public internet. This option requires that Databricks create an additional Google Cloud cloud NAT. For a private cluster, you can optionally set a custom value for the IP range for GKE master resources. Click Advanced configurations then set the IP range for GKE master resources field. All IP addresses must be entirely within the following ranges: 10.0.0.0/8, 100.64.0.0/10, 172.16.0.0/12, 192.168.0.0/16, and 240.0.0.0/4. The range must have the size /28.

    • To instead use a public GKE cluster, click Advanced configurations and deselect Enable private cluster.

  9. (Optional) You can secure a workspace with private connectivity and mitigate data exfiltration risks by enabling Google Private Service Connect (PSC) on the workspace. To configure this, click Advanced configurations and choose a private access settings object. Before adding PSC configuration, Databricks strongly recommends reading the article Enable Private Service Connect for your workspace for requirements and context.

  10. (Optional) You can add customer-managed keys for two different use cases:

    • Managed services data in the Databricks control plane (notebooks, secrets, and Databricks SQL query data).

    • Workspace storage (the two workspace GCS buckets, as well as GCE Persistent Disk volumes of a cluster or SQL warehouse).

    To configure this during workspace creation, you can use the two pickers to select an already-created encryption key configuration for each use case. You can choose the same configuration if it supports both use cases. For detailed instructions using the account console, see Configure customer-managed keys for encryption.

    Alternatively, you can also create a key configuration in this workspace creation flow by clicking a picker for a use case and click Add new encryption key configuration.

  11. Click Save.

  12. If this is the first time that you have created a workspace, a Google popup window asks you to select your Google account. Complete the following instructions.

    Important

    If you do not see the Google account popup:

    • If the page does not change, you may have a popup blocker in your web browser. Look for a notification about blocking a popup window. Configure your popup blocker to allow popup windows from domain accounts.gcp.databricks.com.

    • If you do not see the Google dialog but your browser now shows a list of workspaces, continue to the next step.

    1. In the Google dialog, select the Google account with which you signed into the account console.

    2. On the next screen, reply to the consent request that asks you for additional scopes. Click Allow.

      The consent screen is shown the first time you attempt to create a workspace. For successive new workspaces, Google does not show the consent screen. If you use Google account tools to revoke the consent granted to Databricks, Google displays the consent screen again.

  13. Confirm that your workspace was created successfully. Next to your workspace in the list of workspaces, click Open. To view workspace status and test the workspace, see View workspace status.

  14. Secure the workspace’s GCS buckets. See Secure the workspace’s GCS buckets in your project.

    When you create a workspace, Databricks on Google Cloud creates two Google Cloud Storage (GCS) buckets in your Google Cloud project. Databricks strongly recommends that you secure these GCS buckets so that they are not accessible from outside Databricks on Google Cloud.

During workspace creation, Databricks enables some required Google APIs on the project, if they are not already enabled. See Enabling Google APIs on a workspace’s project.

Enabling Google APIs on a workspace’s project

During workspace creation, Databricks automatically enables the following required Google APIs on the Google Cloud project if they are not already enabled:

These APIs are not disabled automatically during workspace deletion.

Workspace creation limits

You can create at most 200 workspaces per week in the same Google Cloud project. If you exceed this limit, creating a workspace fails with the error message: “Creating custom cloud IAM role <your-role> in project <your-project> rejected.”

View workspace status

After you create a workspace, you can view its status on the Workspaces page.

  • Provisioning: In progress. Wait a few minutes and refresh the page.

  • Running: Successful workspace deployment.

  • Failed: Failed deployment.

  • Banned: Contact your Databricks account team.

  • Cancelling: In the process of cancellation.

If the status for your new workspace is Failed, click the workspace to view a detailed error message. If you do not understand the error, contact your Databricks account team.

You cannot update the configuration of a failed workspace. You must delete it and create a new workspace.

Log into a workspace

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

  2. On the row with your workspace, click Open.

  3. To log in as a workspace administrator, log in with your account owner or account administrator email address.

Secure the workspace’s GCS buckets in your project

When you create a workspace, Databricks on Google Cloud creates two Google Cloud Storage GCS buckets in your GCP project:

  • One GCS bucket stores system data that is generated as you use various Databricks features such as creating notebooks. This bucket includes notebook revisions, job run details, command results, and Spark logs.

  • Another GCS bucket store is your workspace’s root storage for the Databricks File System (DBFS). Your DBFS root bucket is not intended for storage of production customer data. Create other data sources and storage for production customer data in additional GCS buckets. You can optionally mount the additional GCS buckets as the Databricks File System (DBFS) mounts. See Connect to Google Cloud Storage.

Databricks strongly recommends that you secure these GCS buckets so that they are not accessible from outside Databricks on Google Cloud.

To secure these GCS buckets:

  1. In a browser, go to the GCP Cloud Console.

  2. Select the Google Cloud project that hosts your Databricks workspace.

  3. Go to that project’s Storage Service page.

  4. Look for the buckets for your new workspace. Their names are:

    • databricks-<workspace id>

    • databricks-<workspace id>-system

  5. For each bucket:

    1. Click on the bucket to view details.

    2. Click the Permissions tab.

    3. Review all the entries of the Members list and determine if access is expected for each member.

    4. Check the IAM Condition column. Some permissions, such as those named “Databricks service account for workspace”, have IAM Conditions that restrict them to certain buckets. The Google Cloud console UI does not evaluate the condition, so it may show roles that would not actually be able to access the bucket.

      Pay special attention to roles without any IAM Condition. Consider adding restrictions on these:

      • When adding Storage permissions at the project level or above, use IAM Conditions to exclude Databricks buckets or to only allow specific buckets.

      • Choose the minimal set of permissions needed. For example, if only read access is needed, specify Storage Viewer instead of Storage Admin.

        Warning

        Do not use Basic Roles because they are too broad.

    5. Enable Google Cloud Data Access audit logging. Databricks strongly recommends that you enable Data Access audit logging for the GCS buckets that Databricks creates. This enables faster investigation of any issues that may come up. Be aware that Data Access audit logging can increase GCP usage costs. For instructions, see Configuring Data Access audit logs.

If you have questions about securing these GCS buckets, contact your Databricks account team.

Next steps

Now that you have deployed a workspace, you can start building out your data strategy. Databricks recommends the following articles: