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.

Portal

Sign in to Azure

Sign in to the Azure portal at https://portal.azure.com.

Create the virtual network

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

  1. On the upper-left side of the screen, select Create a resource > Networking > Virtual network.

  2. In Create virtual network, enter or select this information:

    Setting Value
    Name Enter MyVirtualNetwork.
    Address space Enter 10.0.0.0/16.
    Subscription Select your subscription.
    Resource group Select Create new, enter myResourceGroup, then select OK.
    Location Select EastUS.
    Subnet - Name Enter mySubnet.
    Subnet - Address range Enter 10.0.0.0/24.
  3. Leave the rest as default, and then select Create.

Permissions

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.

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.

  1. In the portal's search bar, enter myVirtualNetwork. When myVirtualNetwork appears in the search results, select it.
  2. In the search results, select myVirtualNetwork.
  3. Select Subnets, under SETTINGS, and then select mySubnet.
  4. On the mySubnet page, for the Subnet delegation list, select from the services listed under Delegate subnet to a service (for example, Microsoft.DBforPostgreSQL/serversv2).

Remove subnet delegation from an Azure service

  1. In the portal's search bar, enter myVirtualNetwork. When myVirtualNetwork appears in the search results, select it.
  2. In the search results, select myVirtualNetwork.
  3. Select Subnets, under SETTINGS, and then select mySubnet.
  4. In mySubnet page, for the Subnet delegation list, select None from the services listed under Delegate subnet to a service.

Azure CLI

Use Azure Cloud Shell

Azure hosts Azure Cloud Shell, an interactive shell environment that you can use through your browser. You can use either Bash or PowerShell with Cloud Shell to work with Azure services. You can use the Cloud Shell preinstalled commands to run the code in this article without having to install anything on your local environment.

To start Azure Cloud Shell:

Option Example/Link
Select Try It in the upper-right corner of a code block. Selecting Try It doesn't automatically copy the code to Cloud Shell. Example of Try It for Azure Cloud Shell
Go to https://shell.azure.com, or select the Launch Cloud Shell button to open Cloud Shell in your browser. Launch Cloud Shell in a new window
Select the Cloud Shell button on the top-right menu bar in the Azure portal. Cloud Shell button in the Azure portal

To run the code in this article in Azure Cloud Shell:

  1. Start Cloud Shell.

  2. Select the Copy button on a code block to copy the code.

  3. Paste the code into the Cloud Shell session by selecting Ctrl+Shift+V on Windows and Linux or by selecting Cmd+Shift+V on macOS.

  4. Select Enter to run the code.

If you decide to install and use Azure CLI locally instead, this article requires you to use Azure CLI version 2.0.28 or later. To find your installed version, run az --version. See Install Azure CLI for install or upgrade info.

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 myResourceGroup in the eastus location:


  az group create \
    --name myResourceGroup \
    --location eastus

Create a virtual network

Create a virtual network named myVnet with a subnet named mySubnet in the myResourceGroup using az network vnet create.

  az network vnet create \
    --resource-group myResourceGroup \
    --location eastus \
    --name myVnet \
    --address-prefix 10.0.0.0/16 \
    --subnet-name mySubnet \
    --subnet-prefix 10.0.0.0/24

Permissions

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.

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.

Use az network vnet subnet update to update the subnet named mySubnet with a delegation to an Azure service. In this example Microsoft.DBforPostgreSQL/serversv2 is used for the example delegation:

  az network vnet subnet update \
  --resource-group myResourceGroup \
  --name mySubnet
  --vnet-name myVnet
  --delegations Microsoft.DBforPostgreSQL/serversv2

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

  az network vnet show \
  --resource-group myResourceGroup \
  --name mySubnet \
  --vnet-name myVnet
  --query delegations
[
  {
    "actions": [
      "Microsoft.Network/virtualNetworks/subnets/join/action"
    ],
    "etag": "W/\"8a8bf16a-38cf-409f-9434-fe3b5ab9ae54\"",
    "id": "/subscriptions/3bf09329-ca61-4fee-88cb-7e30b9ee305b/resourceGroups/myResourceGroup/providers/Microsoft.Network/virtualNetworks/myVnet/subnets/mySubnet/delegations/0",
    "name": "0",
    "provisioningState": "Succeeded",
    "resourceGroup": "myResourceGroup",
    "serviceName": "Microsoft.DBforPostgreSQL/serversv2",
    "type": "Microsoft.Network/virtualNetworks/subnets/delegations"
  }
]

Remove subnet delegation from an Azure service

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

  az network vnet subnet update \
  --resource-group myResourceGroup
  --name mySubnet
  --vnet-name myVnet
  --remove delegations

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

  az network vnet show \
  --resource-group myResourceGroup \
  --name mySubnet \
  --vnet-name myVnet
  --query delegations

Output from command is a null bracket:

[]

Azure PowerShell

Note

This article has been updated to use the new Azure PowerShell Az module. You can still use the AzureRM module, which will continue to receive bug fixes until at least December 2020. To learn more about the new Az module and AzureRM compatibility, see Introducing the new Azure PowerShell Az module. For Az module installation instructions, see Install Azure PowerShell.

Connect to Azure

  Connect-AzAccount

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 myResourceGroup in the eastus location:

  New-AzResourceGroup -Name myResourceGroup -Location eastus

Create virtual network

Create a virtual network named myVnet with a subnet named mySubnet using New-AzVirtualNetworkSubnetConfig in the myResourceGroup 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.

  $subnet = New-AzVirtualNetworkSubnetConfig -Name mySubnet -AddressPrefix "10.0.0.0/24"

  New-AzVirtualNetwork -Name myVnet -ResourceGroupName myResourceGroup -Location eastus -AddressPrefix "10.0.0.0/16" -Subnet $subnet

Permissions

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.

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.

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

  $vnet = Get-AzVirtualNetwork -Name "myVNet" -ResourceGroupName "myResourceGroup"
  $subnet = Get-AzVirtualNetworkSubnetConfig -Name "mySubnet" -VirtualNetwork $vnet
  $subnet = Add-AzDelegation -Name "myDelegation" -ServiceName "Microsoft.DBforPostgreSQL/serversv2" -Subnet $subnet
  Set-AzVirtualNetwork -VirtualNetwork $vnet

Use Get-AzDelegation to verify the delegation:

  $subnet = Get-AzVirtualNetwork -Name "myVnet" -ResourceGroupName "myResourceGroup" | Get-AzVirtualNetworkSubnetConfig -Name "mySubnet"
  Get-AzDelegation -Name "myDelegation" -Subnet $subnet

  ProvisioningState : Succeeded
  ServiceName       : Microsoft.DBforPostgreSQL/serversv2
  Actions           : {Microsoft.Network/virtualNetworks/subnets/join/action}
  Name              : myDelegation
  Etag              : W/"9cba4b0e-2ceb-444b-b553-454f8da07d8a"
  Id                : /subscriptions/3bf09329-ca61-4fee-88cb-7e30b9ee305b/resourceGroups/myResourceGroup/providers/Microsoft.Network/virtualNetworks/myVnet/subnets/mySubnet/delegations/myDelegation

Remove subnet delegation from an Azure service

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

  $vnet = Get-AzVirtualNetwork -Name "myVnet" -ResourceGroupName "myResourceGroup"
  $subnet = Get-AzVirtualNetworkSubnetConfig -Name "mySubnet" -VirtualNetwork $vnet
  $subnet = Remove-AzDelegation -Name "myDelegation" -Subnet $subnet
  Set-AzVirtualNetwork -VirtualNetwork $vnet

Use Get-AzDelegation to verify the delegation was removed:

  $subnet = Get-AzVirtualNetwork -Name "myVnet" -ResourceGroupName "myResourceGroup" | Get-AzVirtualNetworkSubnetConfig -Name "mySubnet"
  Get-AzDelegation -Name "myDelegation" -Subnet $subnet

  Get-AzDelegation: Sequence contains no matching element

Next steps