Edit

Create node pools for a cluster in Azure Kubernetes Service (AKS)

This article shows you how to create one or more node pools in an AKS cluster.

Note

This feature enables more control over creating and managing multiple node pools and requires separate commands for create/update/delete (CRUD) operations. Previously, cluster operations through az aks create or az aks update used the managedCluster API and were the only options to change your control plane and a single node pool. This feature exposes a separate operation set for agent pools through the agentPool API and requires use of the az aks nodepool command set to execute operations on an individual node pool.

Important

Starting on November 30, 2025, Azure Kubernetes Service (AKS) no longer supports or provides security updates for Azure Linux 2.0. The Azure Linux 2.0 node image is frozen at the 202512.06.0 release. Beginning on March 31, 2026, node images will be removed, and you'll be unable to scale your node pools. Migrate to a supported Azure Linux version by upgrading your node pools to a supported Kubernetes version or migrating to osSku AzureLinux3. For more information, see the Retirement GitHub issue and the Azure Updates retirement announcement. To stay informed on announcements and updates, follow the AKS release notes.

Prerequisites

  • You need Azure CLI version 2.87.0 or later installed and configured. Run az --version to find the version. If you need to install or upgrade, see Install Azure CLI.
  • To deploy an ARM template, you need write access on the resources you're deploying and access to all operations on the Microsoft.Resources/deployments resource type. For example, to deploy a virtual machine (VM), you need Microsoft.Compute/virtualMachines/write and Microsoft.Resources/deployments/* permissions. For a list of roles and permissions, see Azure built-in roles.
  • Review the following requirements for each parameter:
    • osType: The operating system type. The default is Linux.
    • osSKU: Specifies the OS SKU used by the agent pool.
    • count: Number of agents (VMs) to host docker containers. Allowed values must be in the range of 0 to 1000 (inclusive) for user pools and in the range of 1 to 1000 (inclusive) for system pools. The default value is 1.
  • After you deploy the cluster using an ARM template, you can use Azure CLI or Azure PowerShell to connect to the cluster and deploy the sample application.

Limitations

The following limitations apply when you create AKS clusters that support multiple node pools:

  • You can delete the system node pool if you have another system node pool to take its place in the AKS cluster. Otherwise, you can't delete the system node pool.
  • System pools must contain at least two nodes, and user node pools may contain zero or more nodes.
  • If you create a cluster with a single node pool, the OS type must be Linux. The OS SKU can be any Linux variation such as Ubuntu, AzureContainerLinux, or AzureLinux. You can't create a cluster with a single Windows node pool. If you want to run Windows containers, you must add a Windows node pool to the cluster after creating it with a Linux system node pool.
  • The AKS cluster must use the Standard SKU load balancer to use multiple node pools. This feature isn't supported with Basic SKU load balancers.
  • The AKS cluster must use Virtual Machine Scale Sets for the nodes.
  • The name of a node pool can only contain lowercase alphanumeric characters and must begin with a lowercase letter.
    • For Linux node pools, the length must be between 1-12 characters.
    • For Windows node pools, the length must be between 1-6 characters.
  • All node pools must reside in the same virtual network (VNet).
  • You can't change the VM size of a node pool after you create it.
  • When you create multiple node pools at cluster creation time, the Kubernetes versions for the node pools must match the version set for the control plane. You can make updates after provisioning the cluster using per node pool operations.

Important

If you're using Azure Container Linux (ACL) on AKS, make sure you review the following considerations and limitations:

Create specialized node pools

To learn how to create specialized node pools, see the following articles:

Set environment variables

Set the following environment variables in your shell to simplify the commands in this article. You can change the values to your preferred names.

export RESOURCE_GROUP_NAME="my-aks-rg"
export LOCATION="eastus"
export CLUSTER_NAME="my-aks-cluster"
export NODE_POOL_NAME="mynodepool"

Create a resource group

Create an Azure resource group using the az group create command.

az group create --name $RESOURCE_GROUP_NAME --location $LOCATION

Create an AKS cluster with a single node pool using the Azure CLI

If you want only one node pool in your AKS cluster, you can schedule application pods on system node pools. If you run a single system node pool for your AKS cluster in a production environment, we recommend you use at least three nodes for the node pool. If one node goes down, the redundancy is compromised. You can mitigate this risk by having more system node pool nodes.

  1. Create a cluster with a single Ubuntu node pool using the az aks create command. This step specifies two nodes in the single node pool.

    az aks create \
    --resource-group $RESOURCE_GROUP_NAME \
    --name $CLUSTER_NAME \
    --vm-set-type VirtualMachineScaleSets \
    --node-count 2 \
    --os-sku Ubuntu \
    --location $LOCATION \
    --load-balancer-sku standard \
    --generate-ssh-keys

    It takes a few minutes to create the cluster.

  2. When the cluster is ready, get the cluster credentials using the az aks get-credentials command.

    az aks get-credentials --resource-group $RESOURCE_GROUP_NAME --name $CLUSTER_NAME

Add a second node pool using the Azure CLI

The cluster created in the previous section has a single node pool. In this section, we add a second node pool to the cluster. This second node pool can have an OS type of Linux with an OS SKU of Ubuntu or AzureLinux, or an OS type of Windows.

Note

If you want to add a node pool that uses Ephemeral OS disks to your AKS cluster, you can set the --node-osdisk-type flag to Ephemeral when running the az aks nodepool add command.

With Ephemeral OS, you can deploy VMs and instance images up to the size of the VM cache. The default node OS disk configuration in AKS uses 128 GB, which means that you need a VM size that has a cache larger than 128 GB. The default Standard_DS2_v2 has a cache size of 86 GB, which isn't large enough. The Standard_DS3_v2 VM SKU has a cache size of 172 GB, which is large enough. You can also reduce the default size of the OS disk using --node-osdisk-size, but keep in mind the minimum size for AKS images is 30 GB.

If you want to create node pools with network-attached OS disks, you can set the --node-osdisk-type flag to Managed when running the az aks nodepool add command.

Add a Linux node pool

Create a new node pool using the az aks nodepool add command. The following example creates a Linux node pool with the Ubuntu OS SKU that runs three nodes. If you don't specify an OS SKU, AKS defaults to Ubuntu.

az aks nodepool add \
    --resource-group $RESOURCE_GROUP_NAME \
    --cluster-name $CLUSTER_NAME \
    --name $NODE_POOL_NAME \
    --node-vm-size Standard_DS2_v2 \
    --os-type Linux \
    --os-sku Ubuntu \
    --node-count 3

It takes a few minutes to create the node pool.

Add a Windows Server node pool

Create the Windows Server 2025 node pool

Create a new node pool using the az aks nodepool add command. The following example creates a Windows node pool with the Windows2025 OS SKU that runs three nodes.

For more information about Windows OS, see Windows best practices.

az aks nodepool add \
    --resource-group $RESOURCE_GROUP_NAME \
    --cluster-name $CLUSTER_NAME \
    --name $NODE_POOL_NAME \
    --node-vm-size Standard_DS2_v2 \
    --os-type Windows \
    --os-sku Windows2025 \
    --node-count 3

Check the status of your node pools

Check the status of your node pools using the az aks nodepool list command and specify your resource group and cluster name.

az aks nodepool list --resource-group $RESOURCE_GROUP_NAME --cluster-name $CLUSTER_NAME

Create an AKS cluster with a single node pool using an ARM template

If you want only one node pool in your AKS cluster, you can schedule application pods on system node pools. If you run a single system node pool for your AKS cluster in a production environment, we recommend you use at least three nodes for the node pool. If one node goes down, the redundancy is compromised. You can mitigate this risk by having more system node pool nodes.

Create a Microsoft.ContainerService/managedClusters resource

Create a Microsoft.ContainerService/managedClusters resource by adding this JSON to your template.

  • Create a single Ubuntu node pool in your AKS cluster by making the following modifications to your ARM template:

      "properties": {
    "agentPoolProfiles": [
    {
        "count": "1",
        "osSKU": "ubuntu",
        "osType": "linux"
     } 
     ],
}

Add a second node pool using an ARM template

The cluster created in the previous section has a single node pool. In this section, we add a second node pool to the cluster. This second node pool can have an OS type of Linux with an OS SKU of Ubuntu or AzureLinux, or an OS type of Windows.

Add Linux node pools

  • Create multiple Ubuntu node pools in your AKS cluster by making the following modifications to your ARM template:

      "properties": {
    "agentPoolProfiles": [
    {
        "count": "3",
        "osSKU": "ubuntu",
        "osType": "linux"
     } 
     ],
}

Add Windows Server node pools

Create the Windows Server 2025 node pools

  • Create multiple Windows node pools in your AKS cluster by making the following modifications to your ARM template:

      "properties": {
    "agentPoolProfiles": [
    {
        "count": "3",
        "osSKU": "windows2025",
        "osType": "windows"
     } 
     ],
}

Deploy your ARM template

Set taints, labels, or tags for a node pool

When creating a node pool, you can add taints, labels, or tags to it. When you add a taint, label, or tag, all nodes within that node pool also get that taint, label, or tag. We recommend applying these properties to an entire node pool instead of individual nodes. This way, you can easily manage the properties of all nodes in the node pool by updating the node pool properties instead of updating each node individually.

For specific instructions on how to set taints, labels, or tags for a node pool, use the following resources:

Next steps

In this article, you learned how to create an AKS cluster with a single node pool and add additional node pools to your cluster. To learn more about how to manage your node pools, see the following articles:

  • Last updated on