Skip to content

azurermKubernetesClusterNodePool

Manages a Node Pool within a Kubernetes Cluster

-> Note: Due to the fast-moving nature of AKS, we recommend using the latest version of the Azure Provider when using AKS - you can find the latest version of the Azure Provider here.

\~> NOTE: Multiple Node Pools are only supported when the Kubernetes Cluster is using Virtual Machine Scale Sets.

Example Usage

This example provisions a basic Kubernetes Node Pool. Other examples of the azurermKubernetesClusterNodePool resource can be found in the /examples/kubernetes directory within the GitHub Repository

/*Provider bindings are generated by running cdktf get.
See https://cdk.tf/provider-generation for more details.*/
import * as azurerm from "./.gen/providers/azurerm";
/*The following providers are missing schema information and might need manual adjustments to synthesize correctly: azurerm.
For a more precise conversion please use the --provider flag in convert.*/
const azurermResourceGroupExample = new azurerm.resourceGroup.ResourceGroup(
  this,
  "example",
  {
    location: "West Europe",
    name: "example-resources",
  }
);
const azurermKubernetesClusterExample =
  new azurerm.kubernetesCluster.KubernetesCluster(this, "example_1", {
    default_node_pool: [
      {
        name: "default",
        node_count: 1,
        vm_size: "Standard_D2_v2",
      },
    ],
    dns_prefix: "exampleaks1",
    location: azurermResourceGroupExample.location,
    name: "example-aks1",
    resource_group_name: azurermResourceGroupExample.name,
    service_principal: [
      {
        client_id: "00000000-0000-0000-0000-000000000000",
        client_secret: "00000000000000000000000000000000",
      },
    ],
  });
/*This allows the Terraform resource name to match the original name. You can remove the call if you don't need them to match.*/
azurermKubernetesClusterExample.overrideLogicalId("example");
const azurermKubernetesClusterNodePoolExample =
  new azurerm.kubernetesClusterNodePool.KubernetesClusterNodePool(
    this,
    "example_2",
    {
      kubernetes_cluster_id: azurermKubernetesClusterExample.id,
      name: "internal",
      node_count: 1,
      tags: {
        Environment: "Production",
      },
      vm_size: "Standard_DS2_v2",
    }
  );
/*This allows the Terraform resource name to match the original name. You can remove the call if you don't need them to match.*/
azurermKubernetesClusterNodePoolExample.overrideLogicalId("example");

Argument Reference

The following arguments are supported:

  • name - (Required) The name of the Node Pool which should be created within the Kubernetes Cluster. Changing this forces a new resource to be created.

\~> NOTE: A Windows Node Pool cannot have a name longer than 6 characters.

  • kubernetesClusterId - (Required) The ID of the Kubernetes Cluster where this Node Pool should exist. Changing this forces a new resource to be created.

\~> NOTE: The type of Default Node Pool for the Kubernetes Cluster must be virtualMachineScaleSets to attach multiple node pools.

  • vmSize - (Required) The SKU which should be used for the Virtual Machines used in this Node Pool. Changing this forces a new resource to be created.

  • capacityReservationGroupId - (Optional) Specifies the ID of the Capacity Reservation Group where this Node Pool should exist. Changing this forces a new resource to be created.

  • customCaTrustEnabled - (Optional) Specifies whether to trust a Custom CA.

-> Note: This requires that the Preview Feature microsoftContainerService/customCaTrustPreview is enabled and the Resource Provider is re-registered, see the documentation for more information.

  • enableAutoScaling - (Optional) Whether to enable auto-scaler.

  • enableHostEncryption - (Optional) Should the nodes in this Node Pool have host encryption enabled? Changing this forces a new resource to be created.

\~> NOTE: Additional fields must be configured depending on the value of this field - see below.

  • enableNodePublicIp - (Optional) Should each node have a Public IP Address? Changing this forces a new resource to be created.

  • evictionPolicy - (Optional) The Eviction Policy which should be used for Virtual Machines within the Virtual Machine Scale Set powering this Node Pool. Possible values are deallocate and delete. Changing this forces a new resource to be created.

\~> Note: An Eviction Policy can only be configured when priority is set to spot and will default to delete unless otherwise specified.

  • hostGroupId - (Optional) The fully qualified resource ID of the Dedicated Host Group to provision virtual machines from. Changing this forces a new resource to be created.

  • kubeletConfig - (Optional) A kubeletConfig block as defined below. Changing this forces a new resource to be created.

  • linuxOsConfig - (Optional) A linuxOsConfig block as defined below. Changing this forces a new resource to be created.

  • fipsEnabled - (Optional) Should the nodes in this Node Pool have Federal Information Processing Standard enabled? Changing this forces a new resource to be created.

\~> Note: FIPS support is in Public Preview - more information and details on how to opt into the Preview can be found in this article.

  • kubeletDiskType - (Optional) The type of disk used by kubelet. Possible values are os and temporary.

  • maxPods - (Optional) The maximum number of pods that can run on each agent. Changing this forces a new resource to be created.

  • messageOfTheDay - (Optional) A base64-encoded string which will be written to /etc/motd after decoding. This allows customization of the message of the day for Linux nodes. It cannot be specified for Windows nodes and must be a static string (i.e. will be printed raw and not executed as a script). Changing this forces a new resource to be created.

  • mode - (Optional) Should this Node Pool be used for System or User resources? Possible values are system and user. Defaults to user.

  • nodeNetworkProfile - (Optional) A nodeNetworkProfile block as documented below.

  • nodeLabels - (Optional) A map of Kubernetes labels which should be applied to nodes in this Node Pool.

  • nodePublicIpPrefixId - (Optional) Resource ID for the Public IP Addresses Prefix for the nodes in this Node Pool. enableNodePublicIp should be true. Changing this forces a new resource to be created.

  • nodeTaints - (Optional) A list of Kubernetes taints which should be applied to nodes in the agent pool (e.g key=value:noSchedule). Changing this forces a new resource to be created.

  • orchestratorVersion - (Optional) Version of Kubernetes used for the Agents. If not specified, the latest recommended version will be used at provisioning time (but won't auto-upgrade). AKS does not require an exact patch version to be specified, minor version aliases such as 122 are also supported. - The minor version's latest GA patch is automatically chosen in that case. More details can be found in the documentation.

-> Note: This version must be supported by the Kubernetes Cluster - as such the version of Kubernetes used on the Cluster/Control Plane may need to be upgraded first.

  • osDiskSizeGb - (Optional) The Agent Operating System disk size in GB. Changing this forces a new resource to be created.

  • osDiskType - (Optional) The type of disk which should be used for the Operating System. Possible values are ephemeral and managed. Defaults to managed. Changing this forces a new resource to be created.

  • podSubnetId - (Optional) The ID of the Subnet where the pods in the Node Pool should exist. Changing this forces a new resource to be created.

  • osSku - (Optional) Specifies the OS SKU used by the agent pool. Possible values include: ubuntu, cblMariner, mariner, windows2019, windows2022. If not specified, the default is ubuntu if OSType=Linux or windows2019 if OSType=Windows. And the default Windows OSSKU will be changed to windows2022 after Windows2019 is deprecated. Changing this forces a new resource to be created.

  • osType - (Optional) The Operating System which should be used for this Node Pool. Changing this forces a new resource to be created. Possible values are linux and windows. Defaults to linux.

  • priority - (Optional) The Priority for Virtual Machines within the Virtual Machine Scale Set that powers this Node Pool. Possible values are regular and spot. Defaults to regular. Changing this forces a new resource to be created.

  • proximityPlacementGroupId - (Optional) The ID of the Proximity Placement Group where the Virtual Machine Scale Set that powers this Node Pool will be placed. Changing this forces a new resource to be created.

-> Note: When setting priority to Spot - you must configure an evictionPolicy, spotMaxPrice and add the applicable nodeLabels and nodeTaints as per the Azure Documentation.

  • spotMaxPrice - (Optional) The maximum price you're willing to pay in USD per Virtual Machine. Valid values are 1 (the current on-demand price for a Virtual Machine) or a positive value with up to five decimal places. Changing this forces a new resource to be created.

\~> Note: This field can only be configured when priority is set to spot.

  • tags - (Optional) A mapping of tags to assign to the resource.

\~> At this time there's a bug in the AKS API where Tags for a Node Pool are not stored in the correct case - you may wish to use Terraform's ignoreChanges functionality to ignore changes to the casing until this is fixed in the AKS API.

  • scaleDownMode - (Optional) Specifies how the node pool should deal with scaled-down nodes. Allowed values are delete and deallocate. Defaults to delete.

  • ultraSsdEnabled - (Optional) Used to specify whether the UltraSSD is enabled in the Node Pool. Defaults to false. See the documentation for more information. Changing this forces a new resource to be created.

  • upgradeSettings - (Optional) A upgradeSettings block as documented below.

  • vnetSubnetId - (Optional) The ID of the Subnet where this Node Pool should exist. Changing this forces a new resource to be created.

\~> NOTE: A route table must be configured on this Subnet.

  • windowsProfile - (Optional) A windowsProfile block as documented below. Changing this forces a new resource to be created.

  • workloadRuntime - (Optional) Used to specify the workload runtime. Allowed values are ociContainer and wasmWasi.

\~> Note: WebAssembly System Interface node pools are in Public Preview - more information and details on how to opt into the preview can be found in this article

  • zones - (Optional) Specifies a list of Availability Zones in which this Kubernetes Cluster Node Pool should be located. Changing this forces a new Kubernetes Cluster Node Pool to be created.

If enableAutoScaling is set to true, then the following fields can also be configured:

  • maxCount - (Optional) The maximum number of nodes which should exist within this Node Pool. Valid values are between 0 and 1000 and must be greater than or equal to minCount.

  • minCount - (Optional) The minimum number of nodes which should exist within this Node Pool. Valid values are between 0 and 1000 and must be less than or equal to maxCount.

  • nodeCount - (Optional) The initial number of nodes which should exist within this Node Pool. Valid values are between 0 and 1000 (inclusive) for user pools and between 1 and 1000 (inclusive) for system pools and must be a value in the range minCount - maxCount.

-> NOTE: If you're specifying an initial number of nodes you may wish to use Terraform's ignoreChanges functionality to ignore changes to this field.

If enableAutoScaling is set to false, then the following fields can also be configured:

  • nodeCount - (Optional) The number of nodes which should exist within this Node Pool. Valid values are between 0 and 1000 (inclusive) for user pools and between 1 and 1000 (inclusive) for system pools.

A kubeletConfig block supports the following:

  • allowedUnsafeSysctls - (Optional) Specifies the allow list of unsafe sysctls command or patterns (ending in *). Changing this forces a new resource to be created.

  • containerLogMaxLine - (Optional) Specifies the maximum number of container log files that can be present for a container. must be at least 2. Changing this forces a new resource to be created.

  • containerLogMaxSizeMb - (Optional) Specifies the maximum size (e.g. 10MB) of container log file before it is rotated. Changing this forces a new resource to be created.

  • cpuCfsQuotaEnabled - (Optional) Is CPU CFS quota enforcement for containers enabled? Changing this forces a new resource to be created.

  • cpuCfsQuotaPeriod - (Optional) Specifies the CPU CFS quota period value. Changing this forces a new resource to be created.

  • cpuManagerPolicy - (Optional) Specifies the CPU Manager policy to use. Possible values are none and static, Changing this forces a new resource to be created.

  • imageGcHighThreshold - (Optional) Specifies the percent of disk usage above which image garbage collection is always run. Must be between 0 and 100. Changing this forces a new resource to be created.

  • imageGcLowThreshold - (Optional) Specifies the percent of disk usage lower than which image garbage collection is never run. Must be between 0 and 100. Changing this forces a new resource to be created.

  • podMaxPid - (Optional) Specifies the maximum number of processes per pod. Changing this forces a new resource to be created.

  • topologyManagerPolicy - (Optional) Specifies the Topology Manager policy to use. Possible values are none, bestEffort, restricted or singleNumaNode. Changing this forces a new resource to be created.

A linuxOsConfig block supports the following:

  • swapFileSizeMb - (Optional) Specifies the size of swap file on each node in MB. Changing this forces a new resource to be created.

  • sysctlConfig - (Optional) A sysctlConfig block as defined below. Changing this forces a new resource to be created.

  • transparentHugePageDefrag - (Optional) specifies the defrag configuration for Transparent Huge Page. Possible values are always, defer, defer+madvise, madvise and never. Changing this forces a new resource to be created.

  • transparentHugePageEnabled - (Optional) Specifies the Transparent Huge Page enabled configuration. Possible values are always, madvise and never. Changing this forces a new resource to be created.

A nodeNetworkProfile block supports the following:

  • nodePublicIpTags - (Optional) Specifies a mapping of tags to the instance-level public IPs. Changing this forces a new resource to be created.

-> Note: This requires that the Preview Feature microsoftContainerService/nodePublicIpTagsPreview is enabled and the Resource Provider is re-registered, see the documentation for more information.

A sysctlConfig block supports the following:

\~> For more information, please refer to Linux Kernel Doc.

  • fsAioMaxNr - (Optional) The sysctl setting fs.aio-max-nr. Must be between 65536 and 6553500. Changing this forces a new resource to be created.

  • fsFileMax - (Optional) The sysctl setting fs.file-max. Must be between 8192 and 12000500. Changing this forces a new resource to be created.

  • fsInotifyMaxUserWatches - (Optional) The sysctl setting fs.inotify.max_user_watches. Must be between 781250 and 2097152. Changing this forces a new resource to be created.

  • fsNrOpen - (Optional) The sysctl setting fs.nr_open. Must be between 8192 and 20000500. Changing this forces a new resource to be created.

  • kernelThreadsMax - (Optional) The sysctl setting kernel.threads-max. Must be between 20 and 513785. Changing this forces a new resource to be created.

  • netCoreNetdevMaxBacklog - (Optional) The sysctl setting net.core.netdev_max_backlog. Must be between 1000 and 3240000. Changing this forces a new resource to be created.

  • netCoreOptmemMax - (Optional) The sysctl setting net.core.optmem_max. Must be between 20480 and 4194304. Changing this forces a new resource to be created.

  • netCoreRmemDefault - (Optional) The sysctl setting net.core.rmem_default. Must be between 212992 and 134217728. Changing this forces a new resource to be created.

  • netCoreRmemMax - (Optional) The sysctl setting net.core.rmem_max. Must be between 212992 and 134217728. Changing this forces a new resource to be created.

  • netCoreSomaxconn - (Optional) The sysctl setting net.core.somaxconn. Must be between 4096 and 3240000. Changing this forces a new resource to be created.

  • netCoreWmemDefault - (Optional) The sysctl setting net.core.wmem_default. Must be between 212992 and 134217728. Changing this forces a new resource to be created.

  • netCoreWmemMax - (Optional) The sysctl setting net.core.wmem_max. Must be between 212992 and 134217728. Changing this forces a new resource to be created.

  • netIpv4IpLocalPortRangeMax - (Optional) The sysctl setting net.ipv4.ip_local_port_range max value. Must be between 1024 and 60999. Changing this forces a new resource to be created.

  • netIpv4IpLocalPortRangeMin - (Optional) The sysctl setting net.ipv4.ip_local_port_range min value. Must be between 1024 and 60999. Changing this forces a new resource to be created.

  • netIpv4NeighDefaultGcThresh1 - (Optional) The sysctl setting net.ipv4.neigh.default.gc_thresh1. Must be between 128 and 80000. Changing this forces a new resource to be created.

  • netIpv4NeighDefaultGcThresh2 - (Optional) The sysctl setting net.ipv4.neigh.default.gc_thresh2. Must be between 512 and 90000. Changing this forces a new resource to be created.

  • netIpv4NeighDefaultGcThresh3 - (Optional) The sysctl setting net.ipv4.neigh.default.gc_thresh3. Must be between 1024 and 100000. Changing this forces a new resource to be created.

  • netIpv4TcpFinTimeout - (Optional) The sysctl setting net.ipv4.tcp_fin_timeout. Must be between 5 and 120. Changing this forces a new resource to be created.

  • netIpv4TcpKeepaliveIntvl - (Optional) The sysctl setting net.ipv4.tcp_keepalive_intvl. Must be between 10 and 75. Changing this forces a new resource to be created.

  • netIpv4TcpKeepaliveProbes - (Optional) The sysctl setting net.ipv4.tcp_keepalive_probes. Must be between 1 and 15. Changing this forces a new resource to be created.

  • netIpv4TcpKeepaliveTime - (Optional) The sysctl setting net.ipv4.tcp_keepalive_time. Must be between 30 and 432000. Changing this forces a new resource to be created.

  • netIpv4TcpMaxSynBacklog - (Optional) The sysctl setting net.ipv4.tcp_max_syn_backlog. Must be between 128 and 3240000. Changing this forces a new resource to be created.

  • netIpv4TcpMaxTwBuckets - (Optional) The sysctl setting net.ipv4.tcp_max_tw_buckets. Must be between 8000 and 1440000. Changing this forces a new resource to be created.

  • netIpv4TcpTwReuse - (Optional) Is sysctl setting net.ipv4.tcp_tw_reuse enabled? Changing this forces a new resource to be created.

  • netNetfilterNfConntrackBuckets - (Optional) The sysctl setting net.netfilter.nf_conntrack_buckets. Must be between 65536 and 147456. Changing this forces a new resource to be created.

  • netNetfilterNfConntrackMax - (Optional) The sysctl setting net.netfilter.nf_conntrack_max. Must be between 131072 and 1048576. Changing this forces a new resource to be created.

  • vmMaxMapCount - (Optional) The sysctl setting vm.max_map_count. Must be between 65530 and 262144. Changing this forces a new resource to be created.

  • vmSwappiness - (Optional) The sysctl setting vm.swappiness. Must be between 0 and 100. Changing this forces a new resource to be created.

  • vmVfsCachePressure - (Optional) The sysctl setting vm.vfs_cache_pressure. Must be between 0 and 100. Changing this forces a new resource to be created.

A upgradeSettings block supports the following:

  • maxSurge - (Required) The maximum number or percentage of nodes which will be added to the Node Pool size during an upgrade.

A windowsProfile block supports the following:

  • outboundNatEnabled - (Optional) Should the Windows nodes in this Node Pool have outbound NAT enabled? Defaults to true. Changing this forces a new resource to be created.

-> Note: If a percentage is provided, the number of surge nodes is calculated from the current node count on the cluster. Node surge can allow a cluster to have more nodes than maxCount during an upgrade. Ensure that your cluster has enough IP space during an upgrade.

Attributes Reference

The following attributes are exported:

  • id - The ID of the Kubernetes Cluster Node Pool.

Timeouts

The timeouts block allows you to specify timeouts for certain actions:

  • create - (Defaults to 60 minutes) Used when creating the Kubernetes Cluster Node Pool.
  • update - (Defaults to 60 minutes) Used when updating the Kubernetes Cluster Node Pool.
  • read - (Defaults to 5 minutes) Used when retrieving the Kubernetes Cluster Node Pool.
  • delete - (Defaults to 60 minutes) Used when deleting the Kubernetes Cluster Node Pool.

Import

Kubernetes Cluster Node Pools can be imported using the resourceId, e.g.

terraform import azurerm_kubernetes_cluster_node_pool.pool1 /subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/group1/providers/Microsoft.ContainerService/managedClusters/cluster1/agentPools/pool1