Why a new workspace
A workspace deployed in the Databricks-managed VNet can't simply be converted to VNet injection — in most cases you deploy a new workspace with the target network and migrate content. Check the current docs: some network changes are possible in place for already-injected workspaces, but moving from managed VNet to your VNet generally isn't.
If the workspace already uses Unity Catalog, the migration is much easier: data and permissions live in the metastore and stay put.
1. Network design
| Component | Design |
|---|---|
| Host + container subnets | Delegated to Microsoft.Databricks/workspaces, sized for peak nodes (/22+ for busy workspaces) |
| Secure cluster connectivity | On (no public IPs on nodes) |
| Egress | NAT gateway or Azure Firewall with required Databricks destinations |
| Back-end Private Link | databricks_ui_api private endpoint in the workspace VNet |
| Front-end Private Link | Endpoint in the hub/transit VNet for users; plus browser_authentication endpoint per region |
| Public access | Disabled once front-end Private Link works (or restricted with IP access lists) |
| DNS | privatelink.azuredatabricks.net zone linked to the right VNets; on-prem forwarding |
2. Deploy with IaC
resource "azurerm_databricks_workspace" "prod" {
name = "dbw-prod-weu"
resource_group_name = azurerm_resource_group.dbx.name
location = "westeurope"
sku = "premium"
public_network_access_enabled = false
network_security_group_rules_required = "NoAzureDatabricksRules"
custom_parameters {
no_public_ip = true
virtual_network_id = azurerm_virtual_network.dbx.id
public_subnet_name = "snet-dbx-host"
private_subnet_name = "snet-dbx-container"
public_subnet_network_security_group_association_id = azurerm_subnet_network_security_group_association.host.id
private_subnet_network_security_group_association_id = azurerm_subnet_network_security_group_association.container.id
}
}
NoAzureDatabricksRules is used with back-end Private Link; check the allowed values for your design.
3. Attach to Unity Catalog
Assign the existing metastore to the new workspace; bind catalogs as needed. Tables, volumes and grants are immediately available — no data copy.
4. Migrate workspace content
| Content | How |
|---|---|
| Notebooks, files, repos | Git folders (re-clone), or databricks workspace export-dir / import-dir |
| Jobs | Databricks Asset Bundles redeployed to the new workspace (best), or export/import job JSON |
| Cluster policies, pools, SQL warehouses | IaC (Terraform provider) |
| Secrets | Re-create scopes; Key Vault-backed scopes point to the same vaults |
| Permissions | Groups are account-level; re-apply workspace object ACLs via IaC |
| HMS tables (if any) | Migrate to UC first — otherwise they don't travel |
databricks workspace export-dir /Shared/prod ./export --profile OLD
databricks workspace import-dir ./export /Shared/prod --profile NEW
5. Switch
- Run jobs in the new workspace in parallel (writing to test tables) or in a short freeze window.
- Pause schedules in the old workspace, enable them in the new.
- Update ADF linked services, BI connections and user bookmarks (new workspace URL).
- Disable the old workspace's jobs; delete it after the rollback window.
Tip
Test front-end Private Link from every user network (office, VPN, VDI) before disabling public access. DNS is where most go-lives break.
Checklist
- Network, DNS and egress designed and approved
- Workspace deployed by IaC with SCC and Private Link
- Metastore assigned; catalogs bound
- Content, jobs, policies, secrets migrated
- Users and integrations switched; public access disabled