Edit

Share via

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 30 November 2025, AKS will no longer support or provide security updates for Azure Linux 2.0. Starting on 31 March 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 Retirement: Azure Linux 2.0 node pools on AKS.

Prerequisites

  • You need Azure CLI version 2.2.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 one node. User node pools can 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 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.

  • 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.

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 a new node pool using the az aks nodepool add command. The following example creates a Windows node pool with the Windows2022 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 Windows2022 \
    --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

Delete a node pool

If you no longer need a node pool, you can delete it and remove the underlying VM nodes.

Caution

When you delete a node pool, AKS doesn't perform cordon and drain, and there are no recovery options for data loss that may occur when you delete a node pool. If pods can't be scheduled on other node pools, those applications become unavailable. Make sure you don't delete a node pool when in-use applications don't have data backups or the ability to run on other node pools in your cluster. To minimize the disruption of rescheduling pods currently running on the node pool you want to delete, perform a cordon and drain on all nodes in the node pool before deleting.

  • Delete a node pool using the az aks nodepool delete command and specify the node pool name.

    az aks nodepool delete --resource-group $RESOURCE_GROUP_NAME --cluster-name $CLUSTER_NAME --name $NODE_POOL_NAME --no-wait

    It takes a few minutes to delete the nodes and the node pool.

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 multiple Windows node pools in your AKS cluster by making the following modifications to your ARM template:

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

Deploy your ARM template

Next steps

In this article, you learned how to create node pools in an AKS cluster using the Azure CLI.