azure.azcollection.azure_rm_aksagentpool module – Manage node pools in Kubernetes kubernetes cluster

Note

This module is part of the azure.azcollection collection (version 2.4.0).

You might already have this collection installed if you are using the ansible package. It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install azure.azcollection. You need further requirements to be able to use this module, see Requirements for details.

To use it in a playbook, specify: azure.azcollection.azure_rm_aksagentpool.

New in azure.azcollection 1.14.0

Synopsis

• Create, update or delete node pools in kubernetes cluster.

Requirements

The below requirements are needed on the host that executes this module.

• python >= 2.7

• The host that executes this module must have the azure.azcollection collection installed via galaxy

• All python packages listed in collection’s requirements.txt must be installed via pip on the host that executes modules from azure.azcollection

• Full installation instructions may be found https://galaxy.ansible.com/azure/azcollection

Parameters

Parameter	Comments
ad_user string	Active Directory username. Use when authenticating with an Active Directory user rather than service principal.
adfs_authority_url string added in azure.azcollection 0.0.1	Azure AD authority url. Use when authenticating with Username/password, and has your own ADFS authority.
api_profile string added in azure.azcollection 0.0.1	Selects an API profile to use when communicating with Azure services. Default value of latest is appropriate for public clouds; future values will allow use with Azure Stack. Default: "latest"
append_tags boolean	Use to control if tags field is canonical or just appends to existing tags. When canonical, any tags not found in the tags parameter will be removed from the object’s metadata. Choices: false true ← (default)
auth_source string added in azure.azcollection 0.0.1	Controls the source of the credentials to use for authentication. Can also be set via the ANSIBLE_AZURE_AUTH_SOURCE environment variable. When set to auto (the default) the precedence is module parameters -> env -> credential_file -> cli. When set to env, the credentials will be read from the environment variables When set to credential_file, it will read the profile from ~/.azure/credentials. When set to cli, the credentials will be sources from the Azure CLI profile. subscription_id or the environment variable AZURE_SUBSCRIPTION_ID can be used to identify the subscription ID if more than one is present otherwise the default az cli subscription is used. When set to msi, the host machine must be an azure resource with an enabled MSI extension. subscription_id or the environment variable AZURE_SUBSCRIPTION_ID can be used to identify the subscription ID if the resource is granted access to more than one subscription, otherwise the first subscription is chosen. The msi was added in Ansible 2.6. Choices: "auto" ← (default) "cli" "credential_file" "env" "msi"
availability_zones list / elements=integer	Availability zones for nodes. Must use VirtualMachineScaleSets AgentPoolType. Choices: 1 2 3
cert_validation_mode string added in azure.azcollection 0.0.1	Controls the certificate validation behavior for Azure endpoints. By default, all modules will validate the server certificate, but when an HTTPS proxy is in use, or against Azure Stack, it may be necessary to disable this behavior by passing ignore. Can also be set via credential file profile or the AZURE_CERT_VALIDATION environment variable. Choices: "ignore" "validate"
client_id string	Azure client ID. Use when authenticating with a Service Principal or Managed Identity (msi). Can also be set via the AZURE_CLIENT_ID environment variable.
cloud_environment string added in azure.azcollection 0.0.1	For cloud environments other than the US public cloud, the environment name (as defined by Azure Python SDK, eg, AzureChinaCloud, AzureUSGovernment), or a metadata discovery endpoint URL (required for Azure Stack). Can also be set via credential file profile or the AZURE_CLOUD_ENVIRONMENT environment variable. Default: "AzureCloud"
cluster_name string / required	The name of the kubernetes cluster.
count integer	Number of agents (VMs) to host docker containers.
disable_instance_discovery boolean added in azure.azcollection 2.3.0	Determines whether or not instance discovery is performed when attempting to authenticate. Setting this to true will completely disable both instance discovery and authority validation. This functionality is intended for use in scenarios where the metadata endpoint cannot be reached such as in private clouds or Azure Stack. The process of instance discovery entails retrieving authority metadata from https://login.microsoft.com/ to validate the authority. By setting this to **True**, the validation of the authority is disabled. As a result, it is crucial to ensure that the configured authority host is valid and trustworthy. Set via credential file profile or the AZURE_DISABLE_INSTANCE_DISCOVERY environment variable. Choices: false ← (default) true
enable_auto_scaling boolean	Whether to enable auto-scaler. Choices: false true
enable_encryption_at_host boolean	This is only supported on certain VM sizes and in certain Azure regions. Choices: false true
enable_fips boolean	Whether enable FIPS node pool. Choices: false true
enable_node_public_ip boolean	Some scenarios may require nodes in a node pool to receive theirown dedicated public IP addresses. A common scenario is for gaming workloads, where a console needs to make a direct connection to a cloud virtual machine to minimize hops. Choices: false true
enable_ultra_ssd boolean	Whether to enable UltraSSD. Choices: false true
gpu_instance_profile string	GPUInstanceProfile to be used to specify GPU MIG instance profile for supported GPU VM SKU. Choices: "MIG1g" "MIG2g" "MIG3g" "MIG4g" "MIG7g"
kubelet_config dictionary	The Kubelet configuration on the agent pool nodes.
allowed_unsafe_sysctls list / elements=string	Allowed list of unsafe sysctls or unsafe sysctl patterns.
container_log_max_files integer	The maximum number of container log files that can be present for a container. The number must be ≥ 2.
container_log_max_size_mb integer	The maximum size of container log file before it is rotated.
cpu_cfs_quota boolean	The default is true. Choices: false true ← (default)
cpu_cfs_quota_period string	The default is 100ms. Valid values are a sequence of decimal numbers with an optional fraction and a unit suffix. Default: "100ms"
cpu_manager_policy string	Kubernetes CPU management policies. The default is none. Choices: "none" ← (default) "static"
fail_swap_on boolean	If set to true it will make the Kubelet fail to start if swap is enabled on the node. Choices: false true
image_gc_high_threshold integer	To disable image garbage collection, set to 100. The default is 85 Default: 85
image_gc_low_threshold integer	This cannot be set higher than imageGcHighThreshold. The default is 80. Default: 80
pod_max_pids integer	The maximum number of processes per pod.
topology_manager_policy string	Kubernetes Topology Manager policies. The default is none. Choices: "none" ← (default) "best-effort" "restricted" "single-numa-node"
kubelet_disk_type string	Determines the placement of emptyDir volumes, container runtime data root, and Kubelet ephemeral storage. Choices: "OS" "Temporary"
linux_os_config dictionary	The OS configuration of Linux agent nodes.
swap_file_size_mb integer	The size in MB of a swap file that will be created on each node.
sysctls dictionary	Sysctl settings for Linux agent nodes.
fs_aio_max_nr integer	Sysctl setting fs.aio-max-nr.
fs_file_max integer	Sysctl setting fs.file-max.
fs_inotify_max_user_watches integer	Sysctl setting fs.inotify.max_user_watches.
fs_nr_open integer	Sysctl setting fs.nr_open.
kernel_threads_max integer	Sysctl setting kernel.threads-max.
net_core_netdev_max_backlog integer	Sysctl setting net.core.netdev_max_backlog.
net_core_optmem_max integer	Sysctl setting net.core.optmem_max.
net_core_rmem_default integer	Sysctl setting net.core.rmem_default.
net_core_rmem_max integer	Sysctl setting net.core.rmem_max.
net_core_somaxconn integer	Sysctl setting net.core.somaxconn.
net_core_wmem_default integer	Sysctl setting net.core.wmem_default.
net_core_wmem_max integer	Sysctl setting net.core.wmem_max.
net_ipv4_ip_local_port_range string	Sysctl setting net.ipv4.ip_local_port_range.
net_ipv4_neigh_default_gc_thresh1 integer	Sysctl setting net.ipv4.neigh.default.gc_thresh1.
net_ipv4_neigh_default_gc_thresh2 integer	Sysctl setting net.ipv4.neigh.default.gc_thresh2.
net_ipv4_neigh_default_gc_thresh3 integer	Sysctl setting net.ipv4.neigh.default.gc_thresh3.
net_ipv4_tcp_fin_timeout integer	Sysctl setting net.ipv4.tcp_fin_timeout.
net_ipv4_tcp_keepalive_probes integer	Sysctl setting net.ipv4.tcp_keepalive_probes.
net_ipv4_tcp_keepalive_time integer	Sysctl setting net.ipv4.tcp_keepalive_time.
net_ipv4_tcp_max_syn_backlog integer	Sysctl setting net.ipv4.tcp_max_syn_backlog.
net_ipv4_tcp_max_tw_buckets integer	Sysctl setting net.ipv4.tcp_max_tw_buckets.
net_ipv4_tcp_tw_reuse boolean	Sysctl setting net.ipv4.tcp_tw_reuse. Choices: false true
net_ipv4_tcpkeepalive_intvl integer	Sysctl setting net.ipv4.tcp_keepalive_intvl.
net_netfilter_nf_conntrack_buckets integer	Sysctl setting net.netfilter.nf_conntrack_buckets.
net_netfilter_nf_conntrack_max integer	sysctl setting net.netfilter.nf_conntrack_max.
vm_max_map_count integer	Sysctl setting vm.max_map_count.
vm_swappiness integer	Sysctl setting vm.swappiness.
vm_vfs_cache_pressure integer	Sysctl setting vm.vfs_cache_pressure.
transparent_huge_page_defrag string	The node agent pool transparent huge page deferag. The default is madvise. Choices: "always" "defer" "defer+madvise" "madvise" ← (default) "never"
transparent_huge_page_enabled string	The node agent pool transparent hugepage. The default is always. Choices: "always" ← (default) "madvise" "never"
log_mode string	Parent argument.
log_path string	Parent argument.
max_count integer	Maximum number of nodes for auto-scaling.
max_pods integer	Maximum number of pods that can run on a node.
min_count integer	Minimum number of nodes for auto-scaling.
mode string	AgentPoolMode represents mode of an agent pool. Choices: "System" "User"
name string / required	The name of the node agent pool.
node_labels dictionary	Agent pool node labels to be persisted across all nodes in agent pool.
node_public_ip_prefix_id string	The Azure Public IP prefix’s ID.
orchestrator_version string	Version of orchestrator specified when creating the managed cluster.
os_disk_size_gb integer	OS Disk Size in GB to be used to specify the disk size for every machine in this master/agent pool.
os_sku string	Specifies an OS SKU. This value must not be specified if OSType is Windows. Choices: "Ubuntu" "CBLMariner"
os_type string	OsType to be used to specify os type. Choices: "Linux" "Windows"
password string	Active Directory user password. Use when authenticating with an Active Directory user rather than service principal.
power_state dictionary	When an Agent Pool is first created it is initially Running. The Agent Pool can be stopped by setting this field to Stopped. A stopped Agent Pool stops all of its VMs and does not accrue billing charges. An Agent Pool can only be stopped if it is Running and provisioning state is Succeeded.
code string	Tells whether the cluster is Running or Stopped. Choices: "Running" "Stopped"
profile string	Security profile found in ~/.azure/credentials file.
proximity_placement_group_id string	The ID for Proximity Placement Group.
resource_group string / required	The name of the resource group.
scale_down_mode string	This also effects the cluster autoscaler behavior. If not specified, it defaults to Delete. Choices: "Delete" ← (default) "Deallocate"
scale_set_eviction_policy string	This cannot be specified unless the scale_set_priority=Spot. If not specified, the default is Delete. Choices: "Delete" "Deallocate"
scale_set_priority string	The Virtual Machine Scale Set priority. If not specified, the default is Regular. Choices: "Spot" "Regular"
secret string	Azure client secret. Use when authenticating with a Service Principal.
spot_max_price float	Possible values are any decimal value greater than zero or -1. Indicates the willingness to pay any on-demand price.
state string	State of the automation runbook. Use present to create or update a automation runbook and use absent to delete. Choices: "present" ← (default) "absent"
subscription_id string	Your Azure subscription Id.
tags dictionary	Dictionary of string:string pairs to assign as metadata to the object. Metadata tags on the object will be updated with any provided values. To remove tags set append_tags option to false. Currently, Azure DNS zones and Traffic Manager services also don’t allow the use of spaces in the tag. Azure Front Door doesn’t support the use of Azure Automation and Azure CDN only support 15 tags on resources.
tenant string	Azure tenant ID. Use when authenticating with a Service Principal.
thumbprint string added in azure.azcollection 1.14.0	The thumbprint of the private key specified in x509_certificate_path. Use when authenticating with a Service Principal. Required if x509_certificate_path is defined.
type_properties_type string	AgentPoolType represents types of an agent pool. Choices: "VirtualMachineScaleSets" "AvailabilitySet"
upgrade_settings dictionary	Settings for upgrading the agentpool.
max_surge string	This can either be set to an integer, sucha as 5 or percentage 50%. If a percentage is specified, it is the percentage of the total agent pool size at the time of the upgrade. For percentages, fractional nodes are rounded up. If not specified, the default is 1.
vm_size string	Size of agent VMs
vnet_subnet_id string	VNet SubnetID specifies the VNet’s subnet identifier.
workload_runtime string	Determines the type of workload a node can run. Choices: "OCIContainer" "WasmWasi"
x509_certificate_path path added in azure.azcollection 1.14.0	Path to the X509 certificate used to create the service principal in PEM format. The certificate must be appended to the private key. Use when authenticating with a Service Principal.

Notes

Note

• For authentication with Azure you can pass parameters, set environment variables, use a profile stored in ~/.azure/credentials, or log in before you run your tasks or playbook with az login.

• Authentication is also possible using a service principal or Active Directory user.

• To authenticate via service principal, pass subscription_id, client_id, secret and tenant or set environment variables AZURE_SUBSCRIPTION_ID, AZURE_CLIENT_ID, AZURE_SECRET and AZURE_TENANT.

• To authenticate via Active Directory user, pass ad_user and password, or set AZURE_AD_USER and AZURE_PASSWORD in the environment.

• Alternatively, credentials can be stored in ~/.azure/credentials. This is an ini file containing a [default] section and the following keys: subscription_id, client_id, secret and tenant or subscription_id, ad_user and password. It is also possible to add additional profiles. Specify the profile by passing profile or setting AZURE_PROFILE in the environment.

See Also

See also

Sign in with Azure CLI

How to authenticate using the az login command.

Examples

- name: Add new node agent pool
  azure_rm_aksagentpool:
    resource_group: "{{ resource_group }}"
    cluster_name: aksfred01
    name: default-new
    count: 2
    vm_size: Standard_B2s
    type_properties_type: VirtualMachineScaleSets
    mode: System
    node_labels: {"release":"stable"}
    max_pods: 42
    orchestrator_version: 1.23.5
    availability_zones:
      - 1
      - 2
- name: Create a node agent pool with custom config
  azure_rm_aksagentpool:
    resource_group: "{{ resource_group }}"
    cluster_name: "min{{ rpfx }}"
    name: default-new2
    count: 1
    vm_size: Standard_B2s
    type_properties_type: VirtualMachineScaleSets
    mode: System
    node_labels: {"release":"stable"}
    max_pods: 42
    enable_auto_scaling: true
    min_count: 1
    max_count: 10
    orchestrator_version: 1.23.5
    availability_zones:
      - 1
    kubelet_config:
      cpu_manager_policy: static
      cpu_cfs_quota: true
      fail_swap_on: false
    linux_os_config:
      transparent_huge_page_enabled: madvise
      swap_file_size_mb: 1500
      transparent_huge_page_defrag: defer+madvise
- name: Delete node agent pool
  azure_rm_aksagentpool:
    resource_group: "{{ resource_group }}"
    cluster_name: aksfred01
    name: default-new

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key	Description
aks_agent_pools complex	Details for a node pool in the managed Kubernetes cluster. Returned: always
availability_zones list / elements=string	Availability zones for nodes. Must use VirtualMachineScaleSets AgentPoolType. Returned: always Sample: [1, 2]
cluster_name string	The cluster name. Returned: always Sample: "testcluster"
count integer	Number of agents (VMs) to host docker containers. Returned: always Sample: 2
enable_auto_scaling string	Whether to enable auto-scaler. Returned: always
enable_encryption_at_host boolean	This is only supported on certain VM sizes and in certain Azure regions. Returned: always Sample: false
enable_node_public_ip string	Enable public IP for nodes. Returned: always Sample: "bool"
enable_ultra_ssd boolean	Whether enable FIPS node pool. Returned: always Sample: false
gpu_instance_profile string	GPUInstanceProfile to be used to specify GPU MIG instance profile for supported GPU VM SKU. Returned: always Sample: "MIG1g"
id string	Resource ID. Returned: always Sample: "/subscriptions/xxx-xxxf/resourcegroups/myRG/providers/Microsoft.ContainerService/managedClusters/cluster/agentPools/default"
kubelet_config dictionary	The Kubelet configuration on the agent pool nodes. Returned: always Sample: {"cpu_cfs_quota": true, "cpu_cfs_quota_period": "100ms", "cpu_manager_policy": "static", "fail_swap_on": false, "image_gc_high_threshold": 85, "image_gc_low_threshold": 80, "topology_manager_policy": "none"}
kubelet_disk_type string	Determines the placement of emptyDir volumes, container runtime data root, and Kubelet ephemeral storage. Returned: always Sample: "OS"
linux_os_config dictionary	The OS configuration of Linux agent nodes. Returned: always Sample: {"swap_file_size_mb": 1500, "sysctls": {}, "transparent_huge_page_defrag": "defer+madvise", "transparent_huge_page_enabled": "madvise"}
max_count integer	Maximum number of nodes for auto-scaling. Returned: always Sample: 10
max_pods integer	Maximum number of pods that can run on a node. Returned: always Sample: 42
min_count integer	Minimum number of nodes for auto-scaling. Returned: always Sample: 1
mode string	AgentPoolMode represents mode of an agent pool. Returned: always Sample: "System"
name string	Resource name. Returned: always Sample: "default"
node_image_version string	Version of node image. Returned: always Sample: "AKSUbuntu-1804gen2containerd-2022.08.23"
node_labels list / elements=string	Agent pool node labels to be persisted across all nodes in agent pool. Returned: always Sample: [{"release": "stable"}]
node_public_ip_prefix_id string	The Azure Public IP prefix’s ID. Returned: always Sample: "/subscriptions/xxx-xxx/resourceGroups/myRG/providers/Microsoft.Network/publicIPPrefixes/pip01"
node_taints string	Taints added to new nodes during node pool create and scale. Returned: always
orchestrator_version string	Version of orchestrator specified when creating the managed cluster. Returned: always Sample: "1.22.11"
os_disk_size_gb integer	OS Disk Size in GB to be used to specify the disk size for every machine in this master/agent pool. Returned: always Sample: 128
os_sku string	The node agent pool’s SKU. Returned: always Sample: "Ubuntu"
os_type string	OsType to be used to specify os type. Returned: always Sample: "Linux"
power_state dictionary	The agent pool’s power state. Returned: always Sample: {"code": "Running"}
provisioning_state string	The current deployment or provisioning state, which only appears in the response. Returned: always Sample: "Succeeded"
proximity_placement_group_id string	The ID for Proximity Placement Group. Returned: always Sample: "/subscriptions/xxx-xxx/resourceGroups/myRG/providers/Microsoft.Compute/proximityPlacementGroups/proxi01"
resource_group string	Resource group name. Returned: always Sample: "myRG"
scale_down_mode string	This also effects the cluster autoscaler behavior. Returned: always Sample: "Delete"
scale_set_eviction_policy string	ScaleSetEvictionPolicy to be used to specify eviction policy for Spot virtual machine scale set. Returned: always
scale_set_priority string	caleSetPriority to be used to specify virtual machine scale set priority. Returned: always
spot_max_price float	SpotMaxPrice to be used to specify the maximum price you are willing to pay in US Dollars. Returned: always
tags dictionary	The tags of the node agent pool. Returned: always Sample: {"key1": "value1", "key2": "value2"}
type string	Resource Type. Returned: always Sample: "Microsoft.ContainerService/managedClusters/agentPools"
type_properties_type string	AgentPoolType represents types of an agent pool. Returned: always Sample: "VirtualMachineScaleSets"
upgrade_settings string	Settings for upgrading the agentpool. Returned: always
vm_size string	Size of agent VMs. Returned: always Sample: "Standard_B2s"
vnet_subnet_id string	VNet SubnetID specifies the VNet’s subnet identifier. Returned: always
workload_runtime string	Determines the type of workload a node can run. Returned: always Sample: "OCIContainer"

Authors

• xuzhang3 (@xuzhang3)

• Fred Sun (@Fred-sun)

Collection links

• Issue Tracker
• Homepage
• Repository (Sources)