Create a node auto-provisioning (NAP) cluster in a custom virtual network in Azure Kubernetes Service (AKS)

This article shows you how to create a virtual network (VNet) and subnet, create a managed identity with permissions to access the VNet, and create an Azure Kubernetes Service (AKS) cluster in your custom VNet with node auto-provisioning (NAP) enabled.

Prerequisites

An Azure subscription. If you don't have one, you can create a Trial.
Azure CLI version 2.76.0 or later. To find the version, run az --version. For more information about installing or upgrading the Azure CLI, see Install Azure CLI.
Read the Overview of node auto-provisioning (NAP) in AKS article, which details how NAP works.
Read the Overview of networking configurations for node auto-provisioning (NAP) in Azure Kubernetes Service (AKS).

Limitations

When creating a NAP cluster in a custom virtual network (VNet), you must use a Standard Load Balancer. The Basic Load Balancer isn't supported.
To review other limitations and unsupported features for NAP, see the Overview of node auto-provisioning (NAP) in AKS article.

Create a virtual network and subnet

Important

When using a custom VNet with NAP keep the following information in mind:

You must create and delegate an API server subnet to Microsoft.ContainerService/managedClusters, which grants the AKS service permissions to inject the API server pods and internal load balancer into that subnet. You can't use the subnet for any other workloads, but you can use it for multiple AKS clusters located in the same VNet. The minimum supported API server subnet size is /28.
All traffic within the VNet is allowed by default. However, if you added network security group (NSG) rules to restrict traffic between different subnets, you need to ensure you configure the proper permissions. For more information, see the Network security group documentation.

Create a VNet using the az network vnet create command.

az network vnet create \
    --name $VNET_NAME \
    --resource-group $RG_NAME \
    --location $LOCATION \
    --address-prefixes 172.19.0.0/16

Create a subnet using the az network vnet subnet create command and delegate it to Microsoft.ContainerService/managedClusters.

az network vnet subnet create \
    --resource-group $RG_NAME \
    --vnet-name $VNET_NAME \
    --name $SUBNET_NAME \
    --delegations Microsoft.ContainerService/managedClusters \
    --address-prefixes 172.19.0.0/28

Create a managed identity and give it permissions to access the VNet

Create a managed identity using the az identity create command.

az identity create \
    --resource-group $RG_NAME \
    --name $IDENTITY_NAME \
    --location $LOCATION

Get the principal ID of the managed identity and set it to an environment variable using the [az identity show][az-identity-show] command.
```
IDENTITY_PRINCIPAL_ID=$(az identity show --resource-group $RG_NAME --name $IDENTITY_NAME --query principalId -o tsv)
```

Assign the Network Contributor role to the managed identity using the az role assignment create command.

az role assignment create \
    --scope "/subscriptions/$SUBSCRIPTION_ID/resourceGroups/$RG_NAME/providers/Microsoft.Network/virtualNetworks/$VNET_NAME" \
    --role "Network Contributor" \
    --assignee $IDENTITY_PRINCIPAL_ID

Create an AKS cluster with node auto-provisioning (NAP) in a custom VNet

Create an AKS cluster with NAP enabled in your custom VNet using the az aks create command. Make sure to set the --node-provisioning-mode flag to Auto to enable NAP.

The following command also sets the --network-plugin to azure, --network-plugin-mode to overlay, and --network-dataplane to cilium. For more information on networking configurations supported with NAP, see Configure networking for node auto-provisioning on AKS.

az aks create \
    --name $CLUSTER_NAME \
    --resource-group $RG_NAME \
    --location $LOCATION \
    --assign-identity "/subscriptions/$SUBSCRIPTION_ID/resourceGroups/$RG_NAME/providers/Microsoft.ManagedIdentity/userAssignedIdentities/$IDENTITY_NAME" \
    --network-dataplane cilium \
    --network-plugin azure \
    --network-plugin-mode overlay \
    --vnet-subnet-id "/subscriptions/$SUBSCRIPTION_ID/resourceGroups/$RG_NAME/providers/Microsoft.Network/virtualNetworks/$CUSTOM_VNET_NAME/subnets/$SUBNET_NAME" \
    --node-provisioning-mode Auto

After a few minutes, the command completes and returns JSON-formatted information about the cluster.

Configure kubectl to connect to your Kubernetes cluster using the az aks get-credentials command. This command downloads credentials and configures the Kubernetes CLI to use them.
```
az aks get-credentials \
    --resource-group $RG_NAME \
    --name $CLUSTER_NAME
```
Verify the connection to your cluster using the kubectl get command. This command returns a list of the cluster nodes.
```
kubectl get nodes
```

Next steps

For more information on node auto-provisioning in AKS, see the following articles:

Last updated on 2025-11-20