Add or remove a subnet delegation

Subnet delegation gives explicit permissions to the service to create service-specific resources in the subnet using a unique identifier when deploying the service. This article describes how to add or remove a delegated subnet for an Azure service.

Prerequisites

Portal

• An Azure account with an active subscription. Create an account for free.

• If you didn't create the subnet you would like to delegate to an Azure service, you need the following permission: Microsoft.Network/virtualNetworks/subnets/write. The built-in Network Contributor role also contains the necessary permissions.

PowerShell

• An Azure account with an active subscription. Create an account for free.

• If you didn't create the subnet you would like to delegate to an Azure service, you need the following permission: Microsoft.Network/virtualNetworks/subnets/write. The built-in Network Contributor role also contains the necessary permissions.

• Azure PowerShell installed locally or Azure Cloud Shell.

• Sign in to Azure PowerShell and ensure you've selected the subscription with which you want to use this feature. For more information, see Sign in with Azure PowerShell.

• Ensure your Az.Network module is 4.3.0 or later. To verify the installed module, use the command Get-InstalledModule -Name "Az.Network". If the module requires an update, use the command Update-Module -Name Az.Network if necessary.

If you choose to install and use PowerShell locally, this article requires the Azure PowerShell module version 5.4.1 or later. Run Get-Module -ListAvailable Az to find the installed version. If you need to upgrade, see Install Azure PowerShell module. If you're running PowerShell locally, you also need to run Connect-AzAccount to create a connection with Azure.

Azure CLI

• An Azure account with an active subscription. Create an account for free.

• If you didn't create the subnet you would like to delegate to an Azure service, you need the following permission: Microsoft.Network/virtualNetworks/subnets/write. The built-in Network Contributor role also contains the necessary permissions.

• Use the Bash environment in Azure Cloud Shell. For more information, see Quickstart for Bash in Azure Cloud Shell.

  

• If you prefer to run CLI reference commands locally, install the Azure CLI. If you're running on Windows or macOS, consider running Azure CLI in a Docker container. For more information, see How to run the Azure CLI in a Docker container.

  • If you're using a local installation, sign in to the Azure CLI by using the az login command. To finish the authentication process, follow the steps displayed in your terminal. For other sign-in options, see Sign in with the Azure CLI.

  • When you're prompted, install the Azure CLI extension on first use. For more information about extensions, see Use extensions with the Azure CLI.

  • Run az version to find the version and dependent libraries that are installed. To upgrade to the latest version, run az upgrade.

• This how-to article requires version 2.31.0 or later of the Azure CLI. If using Azure Cloud Shell, the latest version is already installed.

Create the virtual network

In this section, you create a virtual network and the subnet that you delegate to an Azure service.

Portal

The following procedure creates a virtual network with a resource subnet.

1. In the portal, search for and select Virtual networks.

2. On the Virtual networks page, select + Create.

3. On the Basics tab of Create virtual network, enter or select the following information:

   Setting	Value
   Project details
   Subscription	Select your subscription.
   Resource group	Select Create new. Enter test-rg in Name. Select OK.
   Instance details
   Name	Enter vnet-1.
   Region	Select East US 2.

   

4. Select Next to proceed to the Security tab.

5. Select Next to proceed to the IP Addresses tab.

6. In the address space box in Subnets, select the default subnet.

7. In Edit subnet, enter or select the following information:

   Setting	Value
   Subnet purpose	Leave the default Default.
   Name	Enter subnet-1.

8. Leave the rest of the settings as their defaults. Select Save.

   

9. Select Save.

10. Select Review + create at the bottom of the screen, and when validation passes, select Create.

PowerShell

Create a resource group

Create a resource group with New-AzResourceGroup. An Azure resource group is a logical container into which Azure resources are deployed and managed.

The following example creates a resource group named test-rg in the eastus2 location:

$rg = @{
    Name = 'test-rg'
    Location = 'eastus2'
}  
New-AzResourceGroup @rg

Create virtual network

Create a virtual network named vnet-1 with a subnet named subnet-1 using New-AzVirtualNetworkSubnetConfig in the test-rg using New-AzVirtualNetwork.

The IP address space for the virtual network is 10.0.0.0/16. The subnet within the virtual network is 10.0.0.0/24.

$sub = @{
    Name = 'subnet-1'
    AddressPrefix = '10.0.0.0/24'
}
$subnet = New-AzVirtualNetworkSubnetConfig @sub

$net = @{
    Name = 'vnet-1'
    ResourceGroupName = 'test-rg'
    Location = 'eastus2'
    AddressPrefix = '10.0.0.0/16'
    Subnet = $subnet
}
New-AzVirtualNetwork @net

Azure CLI

Create a resource group

Create a resource group with az group create. An Azure resource group is a logical container into which Azure resources are deployed and managed.

The following example creates a resource group named test-rg in the eastu2 location:

az group create \
    --name test-rg \
    --location eastus2

Create a virtual network

Create a virtual network named vnet-1 with a subnet named subnet-1 in the test-rg using az network vnet create.

az network vnet create \
    --resource-group test-rg \
    --location eastus2 \
    --name vnet-1 \
    --address-prefix 10.0.0.0/16 \
    --subnet-name subnet-1 \
    --subnet-prefix 10.0.0.0/24

Delegate a subnet to an Azure service

In this section, you delegate the subnet that you created in the preceding section to an Azure service.

Portal

1. Sign-in to the Azure portal.

2. In the search box at the top of the portal, enter Virtual network. Select Virtual networks in the search results.

3. Select vnet-1.

4. Select Subnets in Settings.

5. Select subnet-1.

6. Enter or select the following information:

   Setting	Value
   SUBNET DELEGATION
   Delegate subnet to a service	Select the service that you want to delegate the subnet to. For example, Microsoft.Sql/managedInstances.

7. Select Save.

PowerShell

Use Add-AzDelegation to update the subnet named subnet-1 with a delegation named myDelegation to an Azure service. In this example Microsoft.Sql/managedInstances is used for the example delegation:

$net = @{
    Name = 'vnet-1'
    ResourceGroupName = 'test-rg'
}
$vnet = Get-AzVirtualNetwork @net

$sub = @{
    Name = 'subnet-1'
    VirtualNetwork = $vnet
}
$subnet = Get-AzVirtualNetworkSubnetConfig @sub

$del = @{
    Name = 'myDelegation'
    ServiceName = 'Microsoft.Sql/managedInstances'
    Subnet = $subnet
}
$subnet = Add-AzDelegation @del

Set-AzVirtualNetwork -VirtualNetwork $vnet

Use Get-AzDelegation to verify the delegation:

$sub = @{
    Name = 'vnet-1'
    ResourceGroupName = 'test-rg'
}  
$subnet = Get-AzVirtualNetwork @sub | Get-AzVirtualNetworkSubnetConfig -Name 'subnet-1'

$dg = @{
    Name ='myDelegation'
    Subnet = $subnet
}
Get-AzDelegation @dg

  ProvisioningState : Succeeded
  ServiceName       : Microsoft.Sql/managedInstances
  Actions           : {Microsoft.Network/virtualNetworks/subnets/join/action}
  Name              : myDelegation
  Etag              : W/"9cba4b0e-2ceb-444b-b553-454f8da07d8a"
  Id                : /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/test-rg/providers/Microsoft.Network/virtualNetworks/vnet-1/subnets/subnet-1/delegations/myDelegation

Azure CLI

Use az network virtual network subnet update to update the subnet named subnet-1 with a delegation to an Azure service. In this example Microsoft.Sql/managedInstances is used for the example delegation:

az network vnet subnet update \
    --resource-group test-rg \
    --name subnet-1 \
    --vnet-name vnet-1 \
    --delegations Microsoft.Sql/managedInstances

To verify the delegation was applied, use az network vnet subnet show. Verify the service is delegated to the subnet in the property serviceName:

az network vnet subnet show \
    --resource-group test-rg \
    --name subnet-1 \
    --vnet-name vnet-1 \
    --query delegations

[
  {
    "actions": [
      "Microsoft.Network/virtualNetworks/subnets/join/action",
      "Microsoft.Network/virtualNetworks/subnets/prepareNetworkPolicies/action",
      "Microsoft.Network/virtualNetworks/subnets/unprepareNetworkPolicies/action"
    ],
    "etag": "W/\"30184721-8945-4e4f-9cc3-aa16b26589ac\"",
    "id": "/subscriptions/bbbb1b1b-cc2c-dd3d-ee4e-ffffff5f5f5f/resourceGroups/test-rg/providers/Microsoft.Network/virtualNetworks/vnet-1/subnets/subnet-1/delegations/0",
    "name": "0",
    "provisioningState": "Succeeded",
    "resourceGroup": "test-rg",
    "serviceName": "Microsoft.Sql/managedInstances",
    "type": "Microsoft.Network/virtualNetworks/subnets/delegations"
  }
]

Remove subnet delegation from an Azure service

In this section, you remove a subnet delegation for an Azure service.

Portal

1. Sign-in to the Azure portal.

2. In the search box at the top of the portal, enter Virtual network. Select Virtual networks in the search results.

3. Select vnet-1.

4. Select Subnets in Settings.

5. Select subnet-1.

6. Enter or select the following information:

   Setting	Value
   SUBNET DELEGATION
   Delegate subnet to a service	Select None.

7. Select Save.

PowerShell

Use Remove-AzDelegation to remove the delegation from the subnet named subnet-1:

$net = @{
    Name = 'vnet-1'
    ResourceGroupName = 'test-rg'
}
$vnet = Get-AzVirtualNetwork @net

$sub = @{
    Name = 'subnet-1'
    VirtualNetwork = $vnet
}
$subnet = Get-AzVirtualNetworkSubnetConfig @sub

$del = @{
    Name = 'myDelegation'
    Subnet = $subnet
}
$subnet = Remove-AzDelegation @del

Set-AzVirtualNetwork -VirtualNetwork $vnet

Use Get-AzDelegation to verify the delegation was removed:

$sub = @{
    Name = 'vnet-1'
    ResourceGroupName = 'test-rg'
}  
$subnet = Get-AzVirtualNetwork @sub | Get-AzVirtualNetworkSubnetConfig -Name 'subnet-1'

$dg = @{
    Name ='myDelegation'
    Subnet = $subnet
}
Get-AzDelegation @dg  

Get-AzDelegation: Sequence contains no matching element

Azure CLI

Use az network vnet subnet update to remove the delegation from the subnet named subnet-1:

az network vnet subnet update \
    --resource-group test-rg \
    --name subnet-1 \
    --vnet-name vnet-1 \
    --remove delegations

To verify the delegation was removed, use az network vnet subnet show. Verify the service is removed from the subnet in the property serviceName:

az network vnet subnet show \
    --resource-group test-rg \
    --name subnet-1 \
    --vnet-name vnet-1 \
    --query delegations

Output from command is a null bracket:

[]

When you finish using the resources that you created, you can delete the resource group and all its resources.

1. In the Azure portal, search for and select Resource groups.

2. On the Resource groups page, select the test-rg resource group.

3. On the test-rg page, select Delete resource group.

4. Enter test-rg in Enter resource group name to confirm deletion, and then select Delete.

Next steps

• Learn how to manage subnets in Azure.