Agent Pools - Get
Gets the specified managed cluster agent pool.
GET https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ContainerService/managedClusters/{resourceName}/agentPools/{agentPoolName}?api-version=2024-08-01
URI Parameters
Name | In | Required | Type | Description |
---|---|---|---|---|
agent
|
path | True |
string |
The name of the agent pool. Regex pattern: |
resource
|
path | True |
string |
The name of the resource group. The name is case insensitive. |
resource
|
path | True |
string |
The name of the managed cluster resource. Regex pattern: |
subscription
|
path | True |
string uuid |
The ID of the target subscription. The value must be an UUID. |
api-version
|
query | True |
string |
The API version to use for this operation. |
Responses
Name | Type | Description |
---|---|---|
200 OK |
OK |
|
Other Status Codes |
Error response describing why the operation failed. |
Security
azure_auth
Azure Active Directory OAuth2 Flow
Type:
oauth2
Flow:
implicit
Authorization URL:
https://login.microsoftonline.com/common/oauth2/authorize
Scopes
Name | Description |
---|---|
user_impersonation | impersonate your user account |
Examples
Get Agent Pool
Sample request
GET https://management.azure.com/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg1/providers/Microsoft.ContainerService/managedClusters/clustername1/agentPools/agentpool1?api-version=2024-08-01
Sample response
{
"id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourcegroups/rg1/providers/Microsoft.ContainerService/managedClusters/clustername1/agentPools/agentpool1",
"name": "agentpool1",
"properties": {
"provisioningState": "Succeeded",
"count": 3,
"vmSize": "Standard_DS1_v2",
"maxPods": 110,
"osType": "Linux",
"orchestratorVersion": "1.9.6",
"currentOrchestratorVersion": "1.9.6",
"nodeImageVersion": "AKSUbuntu:1604:2020.03.11",
"upgradeSettings": {
"maxSurge": "33%"
}
}
}
Definitions
Name | Description |
---|---|
Agent |
Agent Pool. |
Agent |
The mode of an agent pool. |
Agent |
Network settings of an agent pool. |
Agent |
The security settings of an agent pool. |
Agent |
The type of Agent Pool. |
Agent |
Settings for upgrading an agentpool |
Agent |
The Windows agent pool's specific profile. |
Cloud |
An error response from the Container service. |
Cloud |
An error response from the Container service. |
code |
Tells whether the cluster is Running or Stopped |
Creation |
Data used when creating a target resource from a source resource. |
GPUInstance |
GPUInstanceProfile to be used to specify GPU MIG instance profile for supported GPU VM SKU. |
IPTag |
Contains the IPTag associated with the object. |
Kubelet |
Kubelet configurations of agent nodes. |
Kubelet |
Determines the placement of emptyDir volumes, container runtime data root, and Kubelet ephemeral storage. |
Linux |
OS configurations of Linux agent nodes. |
OSDisk |
The OS disk type to be used for machines in the agent pool. |
OSSKU |
Specifies the OS SKU used by the agent pool. The default is Ubuntu if OSType is Linux. The default is Windows2019 when Kubernetes <= 1.24 or Windows2022 when Kubernetes >= 1.25 if OSType is Windows. |
OSType |
The operating system type. The default is Linux. |
Port |
The port range. |
Power |
Describes the Power State of the cluster |
Protocol |
The network protocol of the port. |
Scale |
Describes how VMs are added to or removed from Agent Pools. See billing states. |
Scale |
The Virtual Machine Scale Set eviction policy. |
Scale |
The Virtual Machine Scale Set priority. |
Sysctl |
Sysctl settings for Linux agent nodes. |
Workload |
Determines the type of workload a node can run. |
AgentPool
Agent Pool.
Name | Type | Default value | Description |
---|---|---|---|
id |
string |
Resource ID. |
|
name |
string |
The name of the resource that is unique within a resource group. This name can be used to access the resource. |
|
properties.availabilityZones |
string[] |
The list of Availability zones to use for nodes. This can only be specified if the AgentPoolType property is 'VirtualMachineScaleSets'. |
|
properties.capacityReservationGroupID |
string |
The fully qualified resource ID of the Capacity Reservation Group to provide virtual machines from a reserved group of Virtual Machines. |
|
properties.count |
integer |
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. |
|
properties.creationData |
CreationData to be used to specify the source Snapshot ID if the node pool will be created/upgraded using a snapshot. |
||
properties.currentOrchestratorVersion |
string |
The version of Kubernetes the Agent Pool is running. |
|
properties.enableAutoScaling |
boolean |
Whether to enable auto-scaler |
|
properties.enableEncryptionAtHost |
boolean |
Whether to enable host based OS and data drive encryption. |
|
properties.enableFIPS |
boolean |
Whether to use a FIPS-enabled OS. |
|
properties.enableNodePublicIP |
boolean |
Whether each node is allocated its own public IP. |
|
properties.enableUltraSSD |
boolean |
Whether to enable UltraSSD |
|
properties.gpuInstanceProfile |
GPUInstanceProfile to be used to specify GPU MIG instance profile for supported GPU VM SKU. |
||
properties.hostGroupID |
string |
The fully qualified resource ID of the Dedicated Host Group to provision virtual machines from, used only in creation scenario and not allowed to changed once set. |
|
properties.kubeletConfig |
Kubelet configurations of agent nodes. |
||
properties.kubeletDiskType |
Determines the placement of emptyDir volumes, container runtime data root, and Kubelet ephemeral storage. |
||
properties.linuxOSConfig |
OS configurations of Linux agent nodes. |
||
properties.maxCount |
integer |
The maximum number of nodes for auto-scaling |
|
properties.maxPods |
integer |
The maximum number of pods that can run on a node. |
|
properties.minCount |
integer |
The minimum number of nodes for auto-scaling |
|
properties.mode |
The mode of an agent pool. |
||
properties.networkProfile |
Network-related settings of an agent pool. |
||
properties.nodeImageVersion |
string |
The version of node image |
|
properties.nodeLabels |
object |
The node labels to be persisted across all nodes in agent pool. |
|
properties.nodePublicIPPrefixID |
string |
The public IP prefix ID which VM nodes should use IPs from. |
|
properties.nodeTaints |
string[] |
The taints added to new nodes during node pool create and scale. For example, key=value:NoSchedule. |
|
properties.orchestratorVersion |
string |
The version of Kubernetes specified by the user. |
|
properties.osDiskSizeGB |
integer |
OS Disk Size in GB to be used to specify the disk size for every machine in the master/agent pool. If you specify 0, it will apply the default osDisk size according to the vmSize specified. |
|
properties.osDiskType |
The OS disk type to be used for machines in the agent pool. |
||
properties.osSKU |
Specifies the OS SKU used by the agent pool. The default is Ubuntu if OSType is Linux. The default is Windows2019 when Kubernetes <= 1.24 or Windows2022 when Kubernetes >= 1.25 if OSType is Windows. |
||
properties.osType | Linux |
The operating system type. The default is Linux. |
|
properties.podSubnetID |
string |
The ID of the subnet which pods will join when launched. |
|
properties.powerState |
Whether the Agent Pool is running or stopped. |
||
properties.provisioningState |
string |
The current deployment or provisioning state. |
|
properties.proximityPlacementGroupID |
string |
The ID for Proximity Placement Group. |
|
properties.scaleDownMode |
The scale down mode to use when scaling the Agent Pool. |
||
properties.scaleSetEvictionPolicy | Delete |
The Virtual Machine Scale Set eviction policy to use. |
|
properties.scaleSetPriority | Regular |
The Virtual Machine Scale Set priority. If not specified, the default is 'Regular'. |
|
properties.securityProfile |
The security settings of an agent pool. |
||
properties.spotMaxPrice |
number |
-1 |
The max price (in US Dollars) you are willing to pay for spot instances. Possible values are any decimal value greater than zero or -1 which indicates default price to be up-to on-demand. |
properties.tags |
object |
The tags to be persisted on the agent pool virtual machine scale set. |
|
properties.type |
The type of Agent Pool. |
||
properties.upgradeSettings |
Settings for upgrading the agentpool |
||
properties.vmSize |
string |
The size of the agent pool VMs. |
|
properties.vnetSubnetID |
string |
The ID of the subnet which agent pool nodes and optionally pods will join on startup. |
|
properties.windowsProfile |
The Windows agent pool's specific profile. |
||
properties.workloadRuntime |
Determines the type of workload a node can run. |
||
type |
string |
Resource type |
AgentPoolMode
The mode of an agent pool.
Name | Type | Description |
---|---|---|
System |
string |
System agent pools are primarily for hosting critical system pods such as CoreDNS and metrics-server. System agent pools osType must be Linux. System agent pools VM SKU must have at least 2vCPUs and 4GB of memory. |
User |
string |
User agent pools are primarily for hosting your application pods. |
AgentPoolNetworkProfile
Network settings of an agent pool.
Name | Type | Description |
---|---|---|
allowedHostPorts |
The port ranges that are allowed to access. The specified ranges are allowed to overlap. |
|
applicationSecurityGroups |
string[] |
The IDs of the application security groups which agent pool will associate when created. |
nodePublicIPTags |
IPTag[] |
IPTags of instance-level public IPs. |
AgentPoolSecurityProfile
The security settings of an agent pool.
Name | Type | Description |
---|---|---|
enableSecureBoot |
boolean |
Secure Boot is a feature of Trusted Launch which ensures that only signed operating systems and drivers can boot. For more details, see aka.ms/aks/trustedlaunch. If not specified, the default is false. |
enableVTPM |
boolean |
vTPM is a Trusted Launch feature for configuring a dedicated secure vault for keys and measurements held locally on the node. For more details, see aka.ms/aks/trustedlaunch. If not specified, the default is false. |
AgentPoolType
The type of Agent Pool.
Name | Type | Description |
---|---|---|
AvailabilitySet |
string |
Use of this is strongly discouraged. |
VirtualMachineScaleSets |
string |
Create an Agent Pool backed by a Virtual Machine Scale Set. |
AgentPoolUpgradeSettings
Settings for upgrading an agentpool
Name | Type | Description |
---|---|---|
drainTimeoutInMinutes |
integer |
The drain timeout for a node |
maxSurge |
string |
The maximum number or percentage of nodes that are surged during upgrade. |
nodeSoakDurationInMinutes |
integer |
The soak duration for a node |
AgentPoolWindowsProfile
The Windows agent pool's specific profile.
Name | Type | Description |
---|---|---|
disableOutboundNat |
boolean |
Whether to disable OutboundNAT in windows nodes |
CloudError
An error response from the Container service.
Name | Type | Description |
---|---|---|
error |
Details about the error. |
CloudErrorBody
An error response from the Container service.
Name | Type | Description |
---|---|---|
code |
string |
An identifier for the error. Codes are invariant and are intended to be consumed programmatically. |
details |
A list of additional details about the error. |
|
message |
string |
A message describing the error, intended to be suitable for display in a user interface. |
target |
string |
The target of the particular error. For example, the name of the property in error. |
code
Tells whether the cluster is Running or Stopped
Name | Type | Description |
---|---|---|
Running |
string |
The cluster is running. |
Stopped |
string |
The cluster is stopped. |
CreationData
Data used when creating a target resource from a source resource.
Name | Type | Description |
---|---|---|
sourceResourceId |
string |
This is the ARM ID of the source object to be used to create the target object. |
GPUInstanceProfile
GPUInstanceProfile to be used to specify GPU MIG instance profile for supported GPU VM SKU.
Name | Type | Description |
---|---|---|
MIG1g |
string |
|
MIG2g |
string |
|
MIG3g |
string |
|
MIG4g |
string |
|
MIG7g |
string |
IPTag
Contains the IPTag associated with the object.
Name | Type | Description |
---|---|---|
ipTagType |
string |
The IP tag type. Example: RoutingPreference. |
tag |
string |
The value of the IP tag associated with the public IP. Example: Internet. |
KubeletConfig
Kubelet configurations of agent nodes.
Name | Type | Description |
---|---|---|
allowedUnsafeSysctls |
string[] |
Allowed list of unsafe sysctls or unsafe sysctl patterns (ending in |
containerLogMaxFiles |
integer |
The maximum number of container log files that can be present for a container. The number must be ≥ 2. |
containerLogMaxSizeMB |
integer |
The maximum size (e.g. 10Mi) of container log file before it is rotated. |
cpuCfsQuota |
boolean |
If CPU CFS quota enforcement is enabled for containers that specify CPU limits. |
cpuCfsQuotaPeriod |
string |
The CPU CFS quota period value. |
cpuManagerPolicy |
string |
The CPU Manager policy to use. |
failSwapOn |
boolean |
If set to true it will make the Kubelet fail to start if swap is enabled on the node. |
imageGcHighThreshold |
integer |
The percent of disk usage after which image garbage collection is always run. |
imageGcLowThreshold |
integer |
The percent of disk usage before which image garbage collection is never run. |
podMaxPids |
integer |
The maximum number of processes per pod. |
topologyManagerPolicy |
string |
The Topology Manager policy to use. |
KubeletDiskType
Determines the placement of emptyDir volumes, container runtime data root, and Kubelet ephemeral storage.
Name | Type | Description |
---|---|---|
OS |
string |
Kubelet will use the OS disk for its data. |
Temporary |
string |
Kubelet will use the temporary disk for its data. |
LinuxOSConfig
OS configurations of Linux agent nodes.
Name | Type | Description |
---|---|---|
swapFileSizeMB |
integer |
The size in MB of a swap file that will be created on each node. |
sysctls |
Sysctl settings for Linux agent nodes. |
|
transparentHugePageDefrag |
string |
Whether the kernel should make aggressive use of memory compaction to make more hugepages available. |
transparentHugePageEnabled |
string |
Whether transparent hugepages are enabled. |
OSDiskType
The OS disk type to be used for machines in the agent pool.
Name | Type | Description |
---|---|---|
Ephemeral |
string |
Ephemeral OS disks are stored only on the host machine, just like a temporary disk. This provides lower read/write latency, along with faster node scaling and cluster upgrades. |
Managed |
string |
Azure replicates the operating system disk for a virtual machine to Azure storage to avoid data loss should the VM need to be relocated to another host. Since containers aren't designed to have local state persisted, this behavior offers limited value while providing some drawbacks, including slower node provisioning and higher read/write latency. |
OSSKU
Specifies the OS SKU used by the agent pool. The default is Ubuntu if OSType is Linux. The default is Windows2019 when Kubernetes <= 1.24 or Windows2022 when Kubernetes >= 1.25 if OSType is Windows.
Name | Type | Description |
---|---|---|
AzureLinux |
string |
Use AzureLinux as the OS for node images. Azure Linux is a container-optimized Linux distro built by Microsoft, visit https://aka.ms/azurelinux for more information. |
CBLMariner |
string |
Deprecated OSSKU. Microsoft recommends that new deployments choose 'AzureLinux' instead. |
Ubuntu |
string |
Use Ubuntu as the OS for node images. |
Windows2019 |
string |
Use Windows2019 as the OS for node images. Unsupported for system node pools. Windows2019 only supports Windows2019 containers; it cannot run Windows2022 containers and vice versa. |
Windows2022 |
string |
Use Windows2022 as the OS for node images. Unsupported for system node pools. Windows2022 only supports Windows2022 containers; it cannot run Windows2019 containers and vice versa. |
OSType
The operating system type. The default is Linux.
Name | Type | Description |
---|---|---|
Linux |
string |
Use Linux. |
Windows |
string |
Use Windows. |
PortRange
The port range.
Name | Type | Description |
---|---|---|
portEnd |
integer |
The maximum port that is included in the range. It should be ranged from 1 to 65535, and be greater than or equal to portStart. |
portStart |
integer |
The minimum port that is included in the range. It should be ranged from 1 to 65535, and be less than or equal to portEnd. |
protocol |
The network protocol of the port. |
PowerState
Describes the Power State of the cluster
Name | Type | Description |
---|---|---|
code |
Tells whether the cluster is Running or Stopped |
Protocol
The network protocol of the port.
Name | Type | Description |
---|---|---|
TCP |
string |
TCP protocol. |
UDP |
string |
UDP protocol. |
ScaleDownMode
Describes how VMs are added to or removed from Agent Pools. See billing states.
Name | Type | Description |
---|---|---|
Deallocate |
string |
Attempt to start deallocated instances (if they exist) during scale up and deallocate instances during scale down. |
Delete |
string |
Create new instances during scale up and remove instances during scale down. |
ScaleSetEvictionPolicy
The Virtual Machine Scale Set eviction policy.
Name | Type | Description |
---|---|---|
Deallocate |
string |
Nodes in the underlying Scale Set of the node pool are set to the stopped-deallocated state upon eviction. Nodes in the stopped-deallocated state count against your compute quota and can cause issues with cluster scaling or upgrading. |
Delete |
string |
Nodes in the underlying Scale Set of the node pool are deleted when they're evicted. |
ScaleSetPriority
The Virtual Machine Scale Set priority.
Name | Type | Description |
---|---|---|
Regular |
string |
Regular VMs will be used. |
Spot |
string |
Spot priority VMs will be used. There is no SLA for spot nodes. See spot on AKS for more information. |
SysctlConfig
Sysctl settings for Linux agent nodes.
Name | Type | Description |
---|---|---|
fsAioMaxNr |
integer |
Sysctl setting fs.aio-max-nr. |
fsFileMax |
integer |
Sysctl setting fs.file-max. |
fsInotifyMaxUserWatches |
integer |
Sysctl setting fs.inotify.max_user_watches. |
fsNrOpen |
integer |
Sysctl setting fs.nr_open. |
kernelThreadsMax |
integer |
Sysctl setting kernel.threads-max. |
netCoreNetdevMaxBacklog |
integer |
Sysctl setting net.core.netdev_max_backlog. |
netCoreOptmemMax |
integer |
Sysctl setting net.core.optmem_max. |
netCoreRmemDefault |
integer |
Sysctl setting net.core.rmem_default. |
netCoreRmemMax |
integer |
Sysctl setting net.core.rmem_max. |
netCoreSomaxconn |
integer |
Sysctl setting net.core.somaxconn. |
netCoreWmemDefault |
integer |
Sysctl setting net.core.wmem_default. |
netCoreWmemMax |
integer |
Sysctl setting net.core.wmem_max. |
netIpv4IpLocalPortRange |
string |
Sysctl setting net.ipv4.ip_local_port_range. |
netIpv4NeighDefaultGcThresh1 |
integer |
Sysctl setting net.ipv4.neigh.default.gc_thresh1. |
netIpv4NeighDefaultGcThresh2 |
integer |
Sysctl setting net.ipv4.neigh.default.gc_thresh2. |
netIpv4NeighDefaultGcThresh3 |
integer |
Sysctl setting net.ipv4.neigh.default.gc_thresh3. |
netIpv4TcpFinTimeout |
integer |
Sysctl setting net.ipv4.tcp_fin_timeout. |
netIpv4TcpKeepaliveProbes |
integer |
Sysctl setting net.ipv4.tcp_keepalive_probes. |
netIpv4TcpKeepaliveTime |
integer |
Sysctl setting net.ipv4.tcp_keepalive_time. |
netIpv4TcpMaxSynBacklog |
integer |
Sysctl setting net.ipv4.tcp_max_syn_backlog. |
netIpv4TcpMaxTwBuckets |
integer |
Sysctl setting net.ipv4.tcp_max_tw_buckets. |
netIpv4TcpTwReuse |
boolean |
Sysctl setting net.ipv4.tcp_tw_reuse. |
netIpv4TcpkeepaliveIntvl |
integer |
Sysctl setting net.ipv4.tcp_keepalive_intvl. |
netNetfilterNfConntrackBuckets |
integer |
Sysctl setting net.netfilter.nf_conntrack_buckets. |
netNetfilterNfConntrackMax |
integer |
Sysctl setting net.netfilter.nf_conntrack_max. |
vmMaxMapCount |
integer |
Sysctl setting vm.max_map_count. |
vmSwappiness |
integer |
Sysctl setting vm.swappiness. |
vmVfsCachePressure |
integer |
Sysctl setting vm.vfs_cache_pressure. |
WorkloadRuntime
Determines the type of workload a node can run.
Name | Type | Description |
---|---|---|
OCIContainer |
string |
Nodes will use Kubelet to run standard OCI container workloads. |
WasmWasi |
string |
Nodes will use Krustlet to run WASM workloads using the WASI provider (Preview). |