Applies toAzure Databricks across Microsoft Entra tenants; Databricks on AWS/GCP across Databricks accounts; Unity Catalog workspaces
1. Why it's a rebuild, not a move
- An Azure Databricks workspace belongs to the Databricks account of its Entra tenant. It can't be re-parented to another tenant, and moving the Azure subscription to another tenant is not a supported path for Databricks workspaces.
- Unity Catalog metastores, identities, storage credentials (managed identities / access connectors) and service principals are all tenant- or account-scoped.
So a tenant-to-tenant migration means: build new workspaces in the target, then migrate content, data and identities. The same applies on AWS when moving between Databricks accounts.
2. Typical drivers
| Driver | Implication |
|---|---|
| Acquisition: integrate into the parent's tenant | Adopt the parent's landing zone, identity and UC standards |
| Divestiture: carve out to a new company | Copy only the divested scope; strict data separation |
| Tenant consolidation | Merge several workspaces into fewer; rename catalogs consistently |
3. Inventory of what moves
| Asset | Approach | Post in this series |
|---|---|---|
| Users, groups, service principals | Re-provision from the target Entra ID (SCIM); map old → new | Identity migration |
| Notebooks, files, Git folders | Export/import or re-clone from Git | Workspace objects |
| Jobs, pipelines (DLT), dashboards, queries, alerts | Terraform exporter / Asset Bundles | Workspace objects |
| Cluster policies, pools, SQL warehouses | IaC | Workspace objects |
| Unity Catalog: catalogs, schemas, grants, volumes, external locations | Recreate with IaC in the new metastore | UC migration |
| Table data | Storage copy, Delta Sharing + CTAS, or deep clone | Data migration |
| Secrets | Recreate from the source vault in the target Key Vault | Cutover runbook |
| ML models / experiments | UC model copy; MLflow export-import | Workspace objects |
| Job run history, query history, audit logs | Not migrated — archive if needed | Cutover runbook |
4. Target design first
Don't recreate the old mess. Before moving anything, decide in the target:
- Workspace layout (per environment / per domain), network (VNet injection, Private Link), region.
- Catalog naming (
<env>_<domain>), storage per catalog, ownership by groups. - CI/CD: Git + Asset Bundles + Terraform as the only way to deploy.
See the deployment best-practice checklist in this series.
5. Phases
- Assess (2–4 weeks): inventory, dependency map, sizing of data to copy.
- Build the target platform (landing zone, workspaces, UC, identity, CI/CD).
- Migrate in waves by domain or team: identities → code and jobs → data → validation.
- Parallel run: target jobs run on copied data; compare outputs.
- Cutover per wave: stop source jobs, final data sync, start target jobs, repoint consumers.
- Decommission the source after sign-off.
6. Key risks
| Risk | Mitigation |
|---|---|
Hard-coded paths (dbfs:/mnt/..., abfss://old-account...) | Scan code; replace with UC tables/volumes |
| Old UPNs and group names in code, grants and job owners | Mapping table; run-as service principals |
| Data copy time and egress cost | Measure early; copy incrementally |
| Downstream consumers (Power BI, APIs) pointing at old hosts | Consumer inventory; DNS/config switch plan |
| Hive metastore tables in the source | Upgrade to UC first (UCX) or migrate as UC directly |
Tip
Treat this as the chance to finish Unity Catalog adoption. Migrating Hive metastore tables and DBFS mounts into a fresh UC design in the target is far easier than fixing them later.