Update workspace network configuration

2025-10-27

Important

This page provides step-by-step instructions for updating the virtual network (VNet) configuration of an existing an Azure Databricks workspace. This allows you to migrate a workspace from an Azure Databricks-managed VNet to your own VNet, a process known as VNet injection, or to modify the VNet configuration of an existing VNet-injected workspace.

Why migrate your workspace to a VNet injection deployment

Migrating your workspace to a VNet injection deployment provides critical network customization and security capabilities:

Full network control: Define custom routing, firewall rules, and connectivity to on-premises networks using services like Azure ExpressRoute.
Enhanced security: Implement advanced security features like network security groups (NSGs) and restrict outbound traffic according to your organization's policies.
Flexible IP addressing: Control the VNet and subnet IP address ranges to avoid conflicts within your corporate network.

Before you begin

Verify workspace must not be configured with Azure Load Balancer. If this applies to your workspace, contact your account team for assistance.
To prevent disruption, terminate all running clusters and jobs in the workspace. You can restart them after the update is complete.

Migrate from a managed VNet to VNet injection

Follow these steps to convert a workspace deployed in a an Azure Databricks-managed VNet into a VNet-injected workspace within your own VNet.

This implementation method uses an ARM template with a NAT gateway. For instructions to use the Azure Portal UI instead, see Upgrade Managed Workspace to VNet Injected Workspace.

Step 1: Create a network security group (NSG)

In the Azure portal, search for and select Deploy a custom template.
Click Build your own template in the editor.

Paste the following ARM template into the editor and click Save.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "location": {
      "type": "string",
      "defaultValue": "[resourceGroup().location]",
      "metadata": { "description": "Location for all resources." }
    },
    "NSGName": {
      "type": "string",
      "defaultValue": "databricks-nsg-01",
      "metadata": { "description": "The name for the Network Security Group." }
    }
  },
  "resources": [
    {
      "apiVersion": "2020-05-01",
      "type": "Microsoft.Network/networkSecurityGroups",
      "name": "[parameters('NSGName')]",
      "location": "[parameters('location')]"
    }
  ],
  "outputs": {
    "existingNSGId": {
      "type": "string",
      "value": "[resourceId('Microsoft.Network/networkSecurityGroups', parameters('NSGName'))]"
    }
  }
}

On the Basics tab, configure the following parameters:
- Subscription: Select the subscription containing your workspace.
- Resource group: Select the same resource group as your workspace, not the managed resource group.
- Location: Ensure this matches your workspace's region.
Click Review + create, and then Create. Make a note of the existingNSGId from the deployment outputs.

Step 2: Create a new VNet

Go back to Deploy a custom template.
In the template search box, find the Azure Quickstart template databricks-vnet-for-vnet-injection-with-nat-gateway.
Click Select template.
On the Basics tab, configure the following parameters:
- Subscription: Select the subscription containing your workspace.
- Resource group: Select the same resource group as your workspace.
- NSG ID: Paste the resource ID of the NSG you created in Step 1.
- VNet Name: Provide a unique name for your new VNet.
- VNet CIDR, Private Subnet CIDR, Public Subnet CIDR: Define the address ranges. Ensure they are large enough for your workspace needs.
Click Review + create, and then Create.

Note

Ensure the VNet Name is unique within the resource group. If the name already exists, the template will attempt to modify the existing VNet instead of creating a new one.

Step 3: Update the workspace

In the Azure portal, go to your Azure Databricks workspace.
In the left sidebar, under Automation, click Export template.
Wait until the template finishes loading, then click Deploy.
On the custom deployment page, click Edit template.

In the editor, make the following changes:

Set the apiVersion to 2025-08-01-preview.
Remove the following parameters from the properties section if they exist:
- vnetAddressPrefix
- natGatewayName
- publicIpName

Add the following parameters to resources.properties.parameters, replacing the placeholder values with your new VNet and subnet names from Step 2.

{
  "customPrivateSubnetName": {
    "value": "your-private-subnet-name"
  },
  "customPublicSubnetName": {
    "value": "your-public-subnet-name"
  },
  "customVirtualNetworkId": {
    "value": "/subscriptions/<your-subscription-id>/resourceGroups/<your-resource-group>/providers/Microsoft.Network/virtualNetworks/<your-vnet-name>"
  }
}

Click Save.

Move a VNet-injected workspace to a new VNet

Follow each step in Migrate from a managed VNet to VNet injection to move an existing VNet-injected workspace to a new VNet.

Note

If your workspace uses a back-end Private Link connection, it is tied to the old VNet. After migrating to the new VNet, the old Private Link connection breaks. You must manually delete the old private endpoint and its corresponding Private DNS zone before creating a new Private Link connection for the new VNet.

Replace existing subnets in a VNet-injected workspace

Use the following steps to replace the existing subnet with a new subnet in a VNet-injected workspace.

Step 1: Create a new subnet

In the Azure portal, go to your workspace page and click the VNet link.
In the VNet page, click Subnets in the left sidebar.
Click + Subnet to create a new subnet.
Update the Name and IPv4 fields based on your needs.
Click Add to create the subnet.

Step 2: Update the workspace

Follow the instructions in Step 3: Update the workspace to edit the workspace template.
Change the apiVersion to 2025-08-01-preview.
Update one or both of the following fields with your new subnet names:
- customPrivateSubnetName
- customPublicSubnetName
Ensure all other fields remain unchanged.
Click Save to apply the changes.

Test validation

After completing any workspace network configuration update, use the following test matrix to confirm your workspace operates as expected:

Test	Steps
New clusters work as expected	Create a new cluster and run a job
Existing clusters work as expected	Run a job with a cluster that was created before the update