Azure Kubernetes Service Agent Pools API

openapi: 3.1.0
info:
  title: Azure Kubernetes Service REST Agent Pools API
  description: REST API for managing Azure Kubernetes Service (AKS) resources including managed clusters, agent pools, maintenance configurations, snapshots, private endpoint connections, and trusted access role bindings. AKS simplifies deploying a managed Kubernetes cluster in Azure by offloading operational overhead such as health monitoring and maintenance.
  version: '2025-10-01'
  contact:
    name: Microsoft Azure Support
    url: https://azure.microsoft.com/en-us/support/options/
  license:
    name: Microsoft API License
    url: https://azure.microsoft.com/en-us/support/legal/
  x-apisguru-categories:
  - cloud
  - containers
  - kubernetes
  x-logo:
    url: https://azure.microsoft.com/images/aks-icon.png
servers:
- url: https://management.azure.com
  description: Azure Resource Manager
security:
- azure_auth:
  - user_impersonation
tags:
- name: Agent Pools
  description: Operations for managing agent pools (node pools) within AKS clusters
  externalDocs:
    url: https://learn.microsoft.com/en-us/rest/api/aks/agent-pools
paths:
  ? /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ContainerService/managedClusters/{resourceName}/agentPools
  : get:
      operationId: AgentPools_List
      summary: Azure Kubernetes Service List Agent Pools
      description: Gets a list of agent pools in the specified managed cluster.
      tags:
      - Agent Pools
      parameters:
      - $ref: '#/components/parameters/SubscriptionIdParameter'
      - $ref: '#/components/parameters/ResourceGroupNameParameter'
      - $ref: '#/components/parameters/ResourceNameParameter'
      - $ref: '#/components/parameters/ApiVersionParameter'
      responses:
        '200':
          description: OK. The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentPoolListResult'
              examples:
                AgentpoolsList200Example:
                  summary: Default AgentPools_List 200 response
                  x-microcks-default: true
                  value:
                    value:
                    - id: abc123
                      name: Example Title
                      type: example_value
                    nextLink: example_value
        default:
          description: Error response describing why the operation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CloudError'
              examples:
                AgentpoolsListdefaultExample:
                  summary: Default AgentPools_List default response
                  x-microcks-default: true
                  value:
                    error:
                      code: example_value
                      message: example_value
                      target: example_value
                      details:
                      - code: example_value
                        message: example_value
                        target: example_value
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  ? /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ContainerService/managedClusters/{resourceName}/agentPools/{agentPoolName}
  : get:
      operationId: AgentPools_Get
      summary: Azure Kubernetes Service Get an Agent Pool
      description: Gets the specified managed cluster agent pool.
      tags:
      - Agent Pools
      parameters:
      - $ref: '#/components/parameters/SubscriptionIdParameter'
      - $ref: '#/components/parameters/ResourceGroupNameParameter'
      - $ref: '#/components/parameters/ResourceNameParameter'
      - $ref: '#/components/parameters/AgentPoolNameParameter'
      - $ref: '#/components/parameters/ApiVersionParameter'
      responses:
        '200':
          description: OK. The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentPool'
              examples:
                AgentpoolsGet200Example:
                  summary: Default AgentPools_Get 200 response
                  x-microcks-default: true
                  value:
                    id: abc123
                    name: Example Title
                    type: example_value
                    properties:
                      provisioningState: example_value
                      count: 10
                      vmSize: example_value
                      osDiskSizeGB: 10
                      osDiskType: Managed
                      kubeletDiskType: OS
                      maxPods: 10
                      osType: Linux
                      osSKU: Ubuntu
                      type: VirtualMachineScaleSets
                      mode: System
                      orchestratorVersion: example_value
                      currentOrchestratorVersion: example_value
                      nodeImageVersion: example_value
                      enableAutoScaling: true
                      minCount: 10
                      maxCount: 10
                      scaleSetPriority: Spot
                      scaleSetEvictionPolicy: Delete
                      spotMaxPrice: 42.5
                      scaleDownMode: Delete
                      vnetSubnetID: '500123'
                      podSubnetID: '500123'
                      enableNodePublicIP: true
                      nodePublicIPPrefixID: '500123'
                      enableEncryptionAtHost: true
                      enableFIPS: true
                      enableUltraSSD: true
                      nodeLabels: example_value
                      nodeTaints:
                      - {}
                      tags: example_value
                      proximityPlacementGroupID: '500123'
                      availabilityZones:
                      - {}
                      workloadRuntime: OCIContainer
                      messageOfTheDay: example_value
        default:
          description: Error response describing why the operation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CloudError'
              examples:
                AgentpoolsGetdefaultExample:
                  summary: Default AgentPools_Get default response
                  x-microcks-default: true
                  value:
                    error:
                      code: example_value
                      message: example_value
                      target: example_value
                      details:
                      - code: example_value
                        message: example_value
                        target: example_value
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    put:
      operationId: AgentPools_CreateOrUpdate
      summary: Azure Kubernetes Service Create or Update an Agent Pool
      description: Creates or updates an agent pool in the specified managed cluster.
      tags:
      - Agent Pools
      parameters:
      - $ref: '#/components/parameters/SubscriptionIdParameter'
      - $ref: '#/components/parameters/ResourceGroupNameParameter'
      - $ref: '#/components/parameters/ResourceNameParameter'
      - $ref: '#/components/parameters/AgentPoolNameParameter'
      - $ref: '#/components/parameters/ApiVersionParameter'
      - name: if-match
        in: header
        description: The request should only proceed if an entity matches this string.
        schema:
          type: string
        example: example_value
      - name: if-none-match
        in: header
        description: The request should only proceed if no entity matches this string.
        schema:
          type: string
        example: example_value
      requestBody:
        required: true
        description: The agent pool to create or update.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentPool'
            examples:
              AgentpoolsCreateorupdateRequestExample:
                summary: Default AgentPools_CreateOrUpdate request
                x-microcks-default: true
                value:
                  id: abc123
                  name: Example Title
                  type: example_value
                  properties:
                    provisioningState: example_value
                    count: 10
                    vmSize: example_value
                    osDiskSizeGB: 10
                    osDiskType: Managed
                    kubeletDiskType: OS
                    maxPods: 10
                    osType: Linux
                    osSKU: Ubuntu
                    type: VirtualMachineScaleSets
                    mode: System
                    orchestratorVersion: example_value
                    currentOrchestratorVersion: example_value
                    nodeImageVersion: example_value
                    enableAutoScaling: true
                    minCount: 10
                    maxCount: 10
                    scaleSetPriority: Spot
                    scaleSetEvictionPolicy: Delete
                    spotMaxPrice: 42.5
                    scaleDownMode: Delete
                    vnetSubnetID: '500123'
                    podSubnetID: '500123'
                    enableNodePublicIP: true
                    nodePublicIPPrefixID: '500123'
                    enableEncryptionAtHost: true
                    enableFIPS: true
                    enableUltraSSD: true
                    nodeLabels: example_value
                    nodeTaints:
                    - {}
                    tags: example_value
                    proximityPlacementGroupID: '500123'
                    availabilityZones:
                    - {}
                    workloadRuntime: OCIContainer
                    messageOfTheDay: example_value
      responses:
        '200':
          description: OK. The update operation has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentPool'
              examples:
                AgentpoolsCreateorupdate200Example:
                  summary: Default AgentPools_CreateOrUpdate 200 response
                  x-microcks-default: true
                  value:
                    id: abc123
                    name: Example Title
                    type: example_value
                    properties:
                      provisioningState: example_value
                      count: 10
                      vmSize: example_value
                      osDiskSizeGB: 10
                      osDiskType: Managed
                      kubeletDiskType: OS
                      maxPods: 10
                      osType: Linux
                      osSKU: Ubuntu
                      type: VirtualMachineScaleSets
                      mode: System
                      orchestratorVersion: example_value
                      currentOrchestratorVersion: example_value
                      nodeImageVersion: example_value
                      enableAutoScaling: true
                      minCount: 10
                      maxCount: 10
                      scaleSetPriority: Spot
                      scaleSetEvictionPolicy: Delete
                      spotMaxPrice: 42.5
                      scaleDownMode: Delete
                      vnetSubnetID: '500123'
                      podSubnetID: '500123'
                      enableNodePublicIP: true
                      nodePublicIPPrefixID: '500123'
                      enableEncryptionAtHost: true
                      enableFIPS: true
                      enableUltraSSD: true
                      nodeLabels: example_value
                      nodeTaints:
                      - {}
                      tags: example_value
                      proximityPlacementGroupID: '500123'
                      availabilityZones:
                      - {}
                      workloadRuntime: OCIContainer
                      messageOfTheDay: example_value
        '201':
          description: Created. The create operation has succeeded.
          headers:
            Azure-AsyncOperation:
              description: URL to query for status of the asynchronous operation.
              schema:
                type: string
            Retry-After:
              description: Suggested delay in seconds to check on operation status.
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentPool'
              examples:
                AgentpoolsCreateorupdate201Example:
                  summary: Default AgentPools_CreateOrUpdate 201 response
                  x-microcks-default: true
                  value:
                    id: abc123
                    name: Example Title
                    type: example_value
                    properties:
                      provisioningState: example_value
                      count: 10
                      vmSize: example_value
                      osDiskSizeGB: 10
                      osDiskType: Managed
                      kubeletDiskType: OS
                      maxPods: 10
                      osType: Linux
                      osSKU: Ubuntu
                      type: VirtualMachineScaleSets
                      mode: System
                      orchestratorVersion: example_value
                      currentOrchestratorVersion: example_value
                      nodeImageVersion: example_value
                      enableAutoScaling: true
                      minCount: 10
                      maxCount: 10
                      scaleSetPriority: Spot
                      scaleSetEvictionPolicy: Delete
                      spotMaxPrice: 42.5
                      scaleDownMode: Delete
                      vnetSubnetID: '500123'
                      podSubnetID: '500123'
                      enableNodePublicIP: true
                      nodePublicIPPrefixID: '500123'
                      enableEncryptionAtHost: true
                      enableFIPS: true
                      enableUltraSSD: true
                      nodeLabels: example_value
                      nodeTaints:
                      - {}
                      tags: example_value
                      proximityPlacementGroupID: '500123'
                      availabilityZones:
                      - {}
                      workloadRuntime: OCIContainer
                      messageOfTheDay: example_value
        default:
          description: Error response describing why the operation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CloudError'
              examples:
                AgentpoolsCreateorupdatedefaultExample:
                  summary: Default AgentPools_CreateOrUpdate default response
                  x-microcks-default: true
                  value:
                    error:
                      code: example_value
                      message: example_value
                      target: example_value
                      details:
                      - code: example_value
                        message: example_value
                        target: example_value
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      operationId: AgentPools_Delete
      summary: Azure Kubernetes Service Delete an Agent Pool
      description: Deletes an agent pool in the specified managed cluster.
      tags:
      - Agent Pools
      parameters:
      - $ref: '#/components/parameters/SubscriptionIdParameter'
      - $ref: '#/components/parameters/ResourceGroupNameParameter'
      - $ref: '#/components/parameters/ResourceNameParameter'
      - $ref: '#/components/parameters/AgentPoolNameParameter'
      - $ref: '#/components/parameters/ApiVersionParameter'
      responses:
        '202':
          description: Accepted. The delete operation will complete asynchronously.
          headers:
            Azure-AsyncOperation:
              description: URL to query for status of the asynchronous operation.
              schema:
                type: string
            Location:
              description: URL to query for the operation result.
              schema:
                type: string
            Retry-After:
              description: Suggested delay in seconds to check on operation status.
              schema:
                type: integer
        '204':
          description: No Content. The resource does not exist.
        default:
          description: Error response describing why the operation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CloudError'
              examples:
                AgentpoolsDeletedefaultExample:
                  summary: Default AgentPools_Delete default response
                  x-microcks-default: true
                  value:
                    error:
                      code: example_value
                      message: example_value
                      target: example_value
                      details:
                      - code: example_value
                        message: example_value
                        target: example_value
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  ? /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ContainerService/managedClusters/{resourceName}/agentPools/{agentPoolName}/upgradeProfiles/default
  : get:
      operationId: AgentPools_GetUpgradeProfile
      summary: Azure Kubernetes Service Get the Upgrade Profile for an Agent Pool
      description: Gets the upgrade profile for an agent pool.
      tags:
      - Agent Pools
      parameters:
      - $ref: '#/components/parameters/SubscriptionIdParameter'
      - $ref: '#/components/parameters/ResourceGroupNameParameter'
      - $ref: '#/components/parameters/ResourceNameParameter'
      - $ref: '#/components/parameters/AgentPoolNameParameter'
      - $ref: '#/components/parameters/ApiVersionParameter'
      responses:
        '200':
          description: OK. The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentPoolUpgradeProfile'
              examples:
                AgentpoolsGetupgradeprofile200Example:
                  summary: Default AgentPools_GetUpgradeProfile 200 response
                  x-microcks-default: true
                  value:
                    id: abc123
                    name: Example Title
                    type: example_value
                    properties:
                      kubernetesVersion: example_value
                      osType: Linux
                      upgrades:
                      - kubernetesVersion: example_value
                        isPreview: true
                      latestNodeImageVersion: example_value
        default:
          description: Error response describing why the operation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CloudError'
              examples:
                AgentpoolsGetupgradeprofiledefaultExample:
                  summary: Default AgentPools_GetUpgradeProfile default response
                  x-microcks-default: true
                  value:
                    error:
                      code: example_value
                      message: example_value
                      target: example_value
                      details:
                      - code: example_value
                        message: example_value
                        target: example_value
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  ? /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ContainerService/managedClusters/{resourceName}/agentPools/{agentPoolName}/availableAgentPoolVersions
  : get:
      operationId: AgentPools_GetAvailableAgentPoolVersions
      summary: Azure Kubernetes Service Get Available Agent Pool Versions
      description: Gets a list of supported Kubernetes versions for the specified agent pool.
      tags:
      - Agent Pools
      parameters:
      - $ref: '#/components/parameters/SubscriptionIdParameter'
      - $ref: '#/components/parameters/ResourceGroupNameParameter'
      - $ref: '#/components/parameters/ResourceNameParameter'
      - $ref: '#/components/parameters/AgentPoolNameParameter'
      - $ref: '#/components/parameters/ApiVersionParameter'
      responses:
        '200':
          description: OK. The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentPoolAvailableVersions'
              examples:
                AgentpoolsGetavailableagentpoolversions200Example:
                  summary: Default AgentPools_GetAvailableAgentPoolVersions 200 response
                  x-microcks-default: true
                  value:
                    id: abc123
                    name: Example Title
                    type: example_value
                    properties:
                      agentPoolVersions:
                      - default: true
                        kubernetesVersion: example_value
                        isPreview: true
        default:
          description: Error response describing why the operation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CloudError'
              examples:
                AgentpoolsGetavailableagentpoolversionsdefaultExample:
                  summary: Default AgentPools_GetAvailableAgentPoolVersions default response
                  x-microcks-default: true
                  value:
                    error:
                      code: example_value
                      message: example_value
                      target: example_value
                      details:
                      - code: example_value
                        message: example_value
                        target: example_value
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  ? /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ContainerService/managedClusters/{resourceName}/agentPools/{agentPoolName}/upgradeNodeImageVersion
  : post:
      operationId: AgentPools_UpgradeNodeImageVersion
      summary: Azure Kubernetes Service Upgrade Node Image Version
      description: Upgrades the node image version of an agent pool to the latest.
      tags:
      - Agent Pools
      parameters:
      - $ref: '#/components/parameters/SubscriptionIdParameter'
      - $ref: '#/components/parameters/ResourceGroupNameParameter'
      - $ref: '#/components/parameters/ResourceNameParameter'
      - $ref: '#/components/parameters/AgentPoolNameParameter'
      - $ref: '#/components/parameters/ApiVersionParameter'
      responses:
        '200':
          description: OK. The agent pool node image has been upgraded.
        '202':
          description: Accepted. The operation will complete asynchronously.
          headers:
            Azure-AsyncOperation:
              description: URL to query for status of the asynchronous operation.
              schema:
                type: string
            Location:
              description: URL to query for the operation result.
              schema:
                type: string
            Retry-After:
              description: Suggested delay in seconds.
              schema:
                type: integer
        default:
          description: Error response describing why the operation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CloudError'
              examples:
                AgentpoolsUpgradenodeimageversiondefaultExample:
                  summary: Default AgentPools_UpgradeNodeImageVersion default response
                  x-microcks-default: true
                  value:
                    error:
                      code: example_value
                      message: example_value
                      target: example_value
                      details:
                      - code: example_value
                        message: example_value
                        target: example_value
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  ? /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ContainerService/managedClusters/{resourceName}/agentPools/{agentPoolName}/abort
  : post:
      operationId: AgentPools_AbortLatestOperation
      summary: Azure Kubernetes Service Abort Latest Operation on an Agent Pool
      description: Aborts the currently running operation on the agent pool.
      tags:
      - Agent Pools
      parameters:
      - $ref: '#/components/parameters/SubscriptionIdParameter'
      - $ref: '#/components/parameters/ResourceGroupNameParameter'
      - $ref: '#/components/parameters/ResourceNameParameter'
      - $ref: '#/components/parameters/AgentPoolNameParameter'
      - $ref: '#/components/parameters/ApiVersionParameter'
      responses:
        '202':
          description: Accepted. The operation will complete asynchronously.
          headers:
            Azure-AsyncOperation:
              description: URL to query for status of the asynchronous operation.
              schema:
                type: string
            Location:
              description: URL to query for the operation result.
              schema:
                type: string
            Retry-After:
              description: Suggested delay in seconds.
              schema:
                type: integer
        '204':
          description: No Content. No operation running.
        default:
          description: Error response describing why the operation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CloudError'
              examples:
                AgentpoolsAbortlatestoperationdefaultExample:
                  summary: Default AgentPools_AbortLatestOperation default response
                  x-microcks-default: true
                  value:
                    error:
                      code: example_value
                      message: example_value
                      target: example_value
                      details:
                      - code: example_value
                        message: example_value
                        target: example_value
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  ? /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ContainerService/managedClusters/{resourceName}/agentPools/{agentPoolName}/deleteMachines
  : post:
      operationId: AgentPools_DeleteMachines
      summary: Azure Kubernetes Service Delete Specific Machines in an Agent Pool
      description: Deletes specific machines in an agent pool.
      tags:
      - Agent Pools
      parameters:
      - $ref: '#/components/parameters/SubscriptionIdParameter'
      - $ref: '#/components/parameters/ResourceGroupNameParameter'
      - $ref: '#/components/parameters/ResourceNameParameter'
      - $ref: '#/components/parameters/AgentPoolNameParameter'
      - $ref: '#/components/parameters/ApiVersionParameter'
      requestBody:
        required: true
        description: The machine names to delete.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentPoolDeleteMachinesParameter'
            examples:
              AgentpoolsDeletemachinesRequestExample:
                summary: Default AgentPools_DeleteMachines request
                x-microcks-default: true
                value:
                  machineNames:
                  - example_value
      responses:
        '202':
          description: Accepted. The operation will complete asynchronously.
          headers:
            Azure-AsyncOperation:
              description: URL to query for status of the asynchronous operation.
              schema:
                type: string
            Location:
              description: URL to query for the operation result.
              schema:
                type: string
            Retry-After:
              description: Suggested delay in seconds.
              schema:
                type: integer
        default:
          description: Error response describing why the operation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CloudError'
              examples:
                AgentpoolsDeletemachinesdefaultExample:
                  summary: Default AgentPools_DeleteMachines default response
                  x-microcks-default: true
                  value:
                    error:
                      code: example_value
                      message: example_value
                      target: example_value
                      details:
                      - code: example_value
                        message: example_value
                        target: example_value
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    AgentPoolAvailableVersions:
      type: object
      description: The available agent pool versions.
      properties:
        id:
          type: string
          readOnly: true
          description: The ID of the agent pool version list.
          example: abc123
        name:
          type: string
          readOnly: true
          description: The name of the agent pool version list.
          example: Example Title
        type:
          type: string
          readOnly: true
          description: The resource type.
          example: example_value
        properties:
          type: object
          properties:
            agentPoolVersions:
              type: array
              items:
                type: object
                properties:
                  default:
                    type: boolean
                    description: Whether this version is the default.
                  kubernetesVersion:
                    type: string
                    description: The Kubernetes version.
                  isPreview:
                    type: boolean
                    description: Whether this version is in preview.
          example: example_value
    AgentPoolDeleteMachinesParameter:
      type: object
      description: The parameters for deleting machines in an agent pool.
      required:
      - machineNames
      properties:
        machineNames:
          type: array
          items:
            type: string
          description: The list of machine names to delete.
          example: []
    CloudError:
      type: object
      description: An error response from the Container service.
      properties:
        error:
          type: object
          description: Details about the error.
          properties:
            code:
              type: string
              description: An identifier for the error. Codes are invariant and are intended to be consumed programmatically.
            message:
              type: string
              description: A message describing the error, intended to be suitable for display in a user interface.
            target:
              type: string
              description: The target of the particular error. For example, the name of the property in error.
            details:
              type: array
              items:
                type: object
                properties:
                  code:
                    type: string
                  message:
                    type: string
                  target:
                    type: string
              description: A list of additional details about the error.
          example: example_value
    AgentPoolUpgradeSettings:
      type: object
      description: Settings for upgrading an agentpool.
      properties:
        maxSurge:
          type: string
          description: The maximum number or percentage of nodes that are surged during upgrade. This can either be set

# --- truncated at 32 KB (43 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/microsoft-azure-kubernetes-service/refs/heads/main/openapi/microsoft-azure-kubernetes-service-agent-pools-api-openapi.yml