azure_rm_virtualmachinescaleset

Manage Azure virtual machine scale sets

Collection: azure.azcollection

Full Name: azure.azcollection.azure_rm_virtualmachinescaleset

Synopsis

Manage Azure virtual machine scale sets

Parameters

Name	Type	Required	Default	Description
ad_user	string			Active Directory username. Use when authenticating with an Active Directory user rather than service principal.
adfs_authority_url	string			Azure AD authority url. Use when authenticating with Username/password, and has your own ADFS authority.
admin_password	string			Password for the admin username.
Not required if the os_type is Linux and SSH password authentication is disabled by setting I(ssh_password_enabled=false).
admin_username	string			Admin username used to access the host after it is created. Required when creating a VM.
Not required when I(specialized_image=true) - the OS user identities are baked into the source image.
api_profile	string		`latest`	Selects an API profile to use when communicating with Azure services. Default value of C(latest) is appropriate for public clouds; future values will allow use with Azure Stack.
append_tags	bool		`true`	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.
application_gateway	string			Application gateway name.
application_security_groups	list			Specifies an array of references to application security group. Resource ID of the application security group.
auth_source	string		`auto`	Controls the source of the credentials to use for authentication.
Can also be set via the C(ANSIBLE_AZURE_AUTH_SOURCE) environment variable.
When set to C(auto) (the default) the precedence is module parameters -> C(env) -> C(credential_file) -> C(cli).
When set to C(env), the credentials will be read from the environment variables.
When set to C(credential_file), it will read the profile from C(~/.azure/credentials).
When set to C(cli), the credentials will be sources from the Azure CLI profile. C(subscription_id) or the environment variable C(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 C(msi), the host machine must be an azure resource with an enabled MSI extension. C(subscription_id) or the environment variable C(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 C(msi) was added in Ansible 2.6.
capacity	int		`1`	Capacity of VMSS.
cert_validation_mode	string			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 C(ignore). Can also be set via credential file profile or the C(AZURE_CERT_VALIDATION) environment variable.
client_id	string			Azure client ID. Use when authenticating with a Service Principal or Managed Identity (msi).
Can also be set via the C(AZURE_CLIENT_ID) environment variable.
cloud_environment	string		`AzureCloud`	For cloud environments other than the US public cloud, the environment name (as defined by Azure Python SDK, eg, C(AzureChinaCloud), C(AzureUSGovernment)), or a metadata discovery endpoint URL (required for Azure Stack). Can also be set via credential file profile or the C(AZURE_CLOUD_ENVIRONMENT) environment variable.
custom_data	string			Data which is made available to the virtual machine and used by e.g., C(cloud-init).
Many images in the marketplace are not cloud-init ready. Thus, data sent to I(custom_data) would be ignored.
If the image you are attempting to use is not listed in U(https://docs.microsoft.com/en-us/azure/virtual-machines/linux/using-cloud-init#cloud-init-overview), follow these steps U(https://docs.microsoft.com/en-us/azure/virtual-machines/linux/cloudinit-prepare-custom-image).
data_disks	list			Describes list of data disks.
disable_instance_discovery	bool		`false`	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 C(AZURE_DISABLE_INSTANCE_DISCOVERY) environment variable.
enable_accelerated_networking	bool			Indicates whether user wants to allow accelerated networking for virtual machines in scaleset being created.
ephemeral_os_disk	bool			Parameters of ephemeral disk settings that can be specified for operating system disk.
Ephemeral OS disk is only supported for VMS Instances using Managed Disk.
eviction_policy	string			Specifies the eviction policy for the Azure Spot virtual machine.
Requires priority to be set to Spot.
identity	dict			Identity for the Object
image	raw			Specifies the image used to build the VM.
If a string, the image is sourced from a custom image based on the name.
If a dict with the keys I(publisher), I(offer), I(sku), and I(version), the image is sourced from a Marketplace image. Note that set I(version=latest) to get the most recent version of a given image.
If a dict with the keys I(name) and I(resource_group), the image is sourced from a custom image based on the I(name) and I(resource_group) set. Note that the key I(resource_group) is optional and if omitted, all images in the subscription will be searched for by I(name).
Custom image support was added in Ansible 2.5.
For community images, a dict with the keys I(community_gallery_image_id). Specified the community gallery image unique id for vm demployment.
The I(community_gallery_image_id) can be fetched from shared gallery image GET call.
Required when creating.
load_balancer	string			Load balancer name.
location	string			Valid Azure location. Defaults to location of the resource group.
log_mode	string			Parent argument.
log_path	string			Parent argument.
managed_disk_type	string			Managed disk type.
max_price	float		`-1`	Specifies the maximum price you are willing to pay for a Azure Spot VM/VMSS.
This price is in US Dollars.
C(-1) indicates default price to be up-to on-demand.
Requires priority to be set to Spot.
name	string	yes		Name of the virtual machine.
oidc_token	string			Direct OpenID Connect (OIDC) token (JWT) used for workload identity authentication.
This token is exchanged with Azure AD using OIDC federated identity.
Useful in CI systems (for example GitHub Actions, Azure DevOps) where an OIDC token is provided directly by the platform.
Can also be set via the C(AZURE_FEDERATED_TOKEN) environment variable.
oidc_token_file_path	string			Path to a file containing an OpenID Connect (OIDC) token (JWT) used for workload identity authentication.
The file must contain only raw token.
This method is commonly used in platforms that materialize OIDC tokens as files
Can also be set via the C(AZURE_FEDERATED_TOKEN_FILE) environment variable.
orchestration_mode	string		`Flexible`	Specifies the orchestration mode for the virtual machine scale set.
When I(orchestration_mode=Flexible), I(public_ip_per_vm=True) must be set.
When I(orchestration_mode=Flexible), I(platform_fault_domain_count) must be set.
When I(orchestration_mode=Flexible), I(single_placement_group=False) must be set.
When I(orchestration_mode=Flexible), it cannot be configured I(overprovision).
When I(orchestration_mode=Flexible), it cannot be configured I(upgrade_policy) and configured when I(orchestration_mode=Uniform).
os_disk_caching	string		`ReadOnly`	Type of OS disk caching.
os_disk_encryption_set	string			The resource ID of the disk encryption set for the OS disk.
os_disk_size_gb	int			Specifies the size of the operating system disk in gigabytes.
This can be used to overwrite the size of the disk in a virtual machine image.
os_type	string		`Linux`	Base type of operating system.
overprovision	bool			Specifies whether the Virtual Machine Scale Set should be overprovisioned.
password	string			Active Directory user password. Use when authenticating with an Active Directory user rather than service principal.
plan	dict			Third-party billing plan for the VM.
platform_fault_domain_count	int		`1`	Fault Domain count for each placement group.
priority	string			Priority of the VMSS.
C(None) is the equivalent of Regular VM.
private_ip_address_version	string			Available from Api-Version 2017-03-30 onwards, it represents whether the specific ipconfiguration is C(IPv4) or C(IPv6).
Default is taken as IPv4.
profile	string			Security profile found in ~/.azure/credentials file.
public_ip_per_vm	bool		`false`	Assign a public IP to each virtual machine of the scale set
remove_on_absent	list		`[all]`	When removing a VM using I(state=absent), also remove associated resources.
It can be C(all) or a list with any of the following [’network_interfaces’, ‘virtual_storage’, ‘public_ips’].
Any other input will be ignored.
resource_group	string	yes		Name of the resource group containing the virtual machine scale set.
scale_in_policy	string			define the order in which vmss instances are scaled-in
secret	string			Azure client secret. Use when authenticating with a Service Principal.
security_group	raw			Existing security group with which to associate the subnet.
It can be the security group name which is in the same resource group.
It can be the resource ID.
It can be a dict which contains I(name) and I(resource_group) of the security group.
security_profile	dict			Specifies the Security related profile settings for the virtual machine sclaset.
short_hostname	string			Short host name.
single_placement_group	bool		`false`	When true this limits the scale set to a single placement group, of max size 100 virtual machines.
specialized_image	bool		`false`	Set to C(true) when the source image referenced by I(image) has an C(osState) of C(Specialized). For example a Shared Image Gallery (Azure Compute Gallery) version that already has accounts, hostname and OS-level settings baked in.
When C(true), the module omits the C(osProfile) block from the Virtual Machine Scale Set create request. Azure rejects specialized sources with C(Parameter OSProfile is not allowed with a specialized image) when C(osProfile) is present.
When C(true), these options are ignored during scale set creation - I(admin_username), I(admin_password), I(ssh_public_keys), I(ssh_password_enabled), I(custom_data) and I(short_hostname).
For backward compatibility, the scale set is also created without C(osProfile) when I(admin_username), I(custom_data) and I(ssh_public_keys) are all omitted; setting this option explicitly is preferred as it produces clearer error messages and documents intent.
ssh_password_enabled	bool		`true`	When the os_type is Linux, setting I(ssh_password_enabled=false) will disable SSH password authentication and require use of SSH keys.
ssh_public_keys	list			For I(os_type=Linux) provide a list of SSH keys.
Each item in the list should be a dictionary where the dictionary contains two keys, C(path) and C(key_data).
Set the C(path) to the default location of the authorized_keys files.
On an Enterprise Linux host, for example, the I(path=/home//.ssh/authorized_keys). Set C(key_data) to the actual value of the public key.
state	string		`present`	Assert the state of the virtual machine scale set.
State C(present) will check that the machine exists with the requested configuration. If the configuration of the existing machine does not match, the machine will be updated.
State C(absent) will remove the virtual machine scale set.
subnet_name	string			Subnet name.
subscription_id	string			Your Azure subscription Id.
tags	dict			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.
terminate_event_timeout_minutes	int			timeout time for termination notification event
in range between 5 and 15
thumbprint	string			The thumbprint of the private key specified in I(x509_certificate_path).
Use when authenticating with a Service Principal.
Required if I(x509_certificate_path) is defined.
tier	string			SKU Tier.
upgrade_policy	string			Upgrade policy.
Required when creating the Azure virtual machine scale sets.
virtual_network_name	string			Virtual Network name.
virtual_network_resource_group	string			When creating a virtual machine, if a specific virtual network from another resource group should be used.
Use this parameter to specify the resource group to use.
vm_size	string			A valid Azure VM size value. For example, C(Standard_D4).
The list of choices varies depending on the subscription and location. Check your subscription for available choices.
x509_certificate_path	string			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.
zones	list			A list of Availability Zones for your virtual machine scale set.

Example

yaml

- name: Create VMSS
  azure.azcollection.azure_rm_virtualmachinescaleset:
    resource_group: myResourceGroup
    name: testvmss
    vm_size: Standard_DS1_v2
    capacity: 2
    virtual_network_name: testvnet
    upgrade_policy: Manual
    subnet_name: testsubnet
    terminate_event_timeout_minutes: 10
    scale_in_policy: NewestVM
    admin_username: "{{ username }}"
    ssh_password_enabled: false
    ssh_public_keys:
      - path: /home/adminUser/.ssh/authorized_keys
        key_data: < insert your ssh public key here... >
    managed_disk_type: Standard_LRS
    image:
      offer: 0001-com-ubuntu-server-focal
      publisher: canonical
      sku: 20_04-lts-gen2
      version: latest
    data_disks:
      - lun: 0
        disk_size_gb: 64
        caching: ReadWrite
        managed_disk_type: Standard_LRS

- name: Create VMSS with an image that requires plan information
  azure.azcollection.azure_rm_virtualmachinescaleset:
    resource_group: myResourceGroup
    name: testvmss
    vm_size: Standard_DS1_v2
    capacity: 3
    virtual_network_name: testvnet
    upgrade_policy: Manual
    subnet_name: testsubnet
    admin_username: "{{ username }}"
    ssh_password_enabled: false
    ssh_public_keys:
      - path: /home/adminUser/.ssh/authorized_keys
        key_data: < insert your ssh public key here... >
    managed_disk_type: Standard_LRS
    image:
      offer: cis-ubuntu-linux-1804-l1
      publisher: center-for-internet-security-inc
      sku: Stable
      version: latest
    plan:
      name: cis-ubuntu-linux-1804-l1
      product: cis-ubuntu-linux-1804-l1
      publisher: center-for-internet-security-inc
    data_disks:
      - lun: 0
        disk_size_gb: 64
        caching: ReadWrite
        managed_disk_type: Standard_LRS

- name: Create a VMSS with a custom image
  azure.azcollection.azure_rm_virtualmachinescaleset:
    resource_group: myResourceGroup
    name: testvmss
    vm_size: Standard_DS1_v2
    capacity: 2
    virtual_network_name: testvnet
    upgrade_policy: Manual
    subnet_name: testsubnet
    admin_username: "{{ username }}"
    admin_password: "{{ password }}"
    managed_disk_type: Standard_LRS
    image: customimage001

- name: Create a VMSS with a community gallery image ID
  azure.azcollection.azure_rm_virtualmachinescaleset:
    resource_group: myResourceGroup
    name: testvmss
    vm_size: Standard_D8_v4
    admin_username: testuser
    single_placement_group: false
    platform_fault_domain_count: 1
    public_ip_per_vm: true
    ssh_password_enabled: false
    ssh_public_keys:
      - path: /home/testuser/.ssh/authorized_keys
        key_data: "ssh-rsa ********* xiuxi.sun@qq.com"
    virtual_network_name: VMSStestVnet
    subnet_name: VMSStestSubnet
    managed_disk_type: Standard_LRS
    orchestration_mode: Flexible
    os_disk_caching: ReadWrite
    image:
      community_gallery_image_id: "/CommunityGalleries/yellowbrick-fc7e81f1-87dd-4989-9ca8-03743762e873/Images/Ubuntu-5.15.0-1035-azure_22.04"
    data_disks:
      - lun: 0
        disk_size_gb: 64
        caching: ReadWrite
        managed_disk_type: Standard_LRS

- name: Create a VMSS with over 100 instances
  azure.azcollection.azure_rm_virtualmachinescaleset:
    resource_group: myResourceGroup
    name: testvmss
    vm_size: Standard_DS1_v2
    capacity: 120
    single_placement_group: false
    virtual_network_name: testvnet
    upgrade_policy: Manual
    subnet_name: testsubnet
    admin_username: "{{ username }}"
    admin_password: "{{ password }}"
    managed_disk_type: Standard_LRS
    image: customimage001

- name: Create a VMSS with a custom image from a particular resource group
  azure.azcollection.azure_rm_virtualmachinescaleset:
    resource_group: myResourceGroup
    name: testvmss
    vm_size: Standard_DS1_v2
    capacity: 2
    virtual_network_name: testvnet
    upgrade_policy: Manual
    subnet_name: testsubnet
    admin_username: "{{ username }}"
    admin_password: "{{ password }}"
    managed_disk_type: Standard_LRS
    image:
      name: customimage001
      resource_group: myResourceGroup

- name: Create a VMSS with Spot Instance
  azure.azcollection.azure_rm_virtualmachinescaleset:
    resource_group: myResourceGroup
    name: testvmss
    vm_size: Standard_DS1_v2
    capacity: 5
    priority: Spot
    eviction_policy: Deallocate
    virtual_network_name: testvnet
    upgrade_policy: Manual
    subnet_name: testsubnet
    admin_username: "{{ username }}"
    admin_password: "{{ password }}"
    managed_disk_type: Standard_LRS
    image: customimage001

- name: Create VMSS with security group
  azure.azcollection.azure_rm_virtualmachinescaleset:
    resource_group: "{{ resource_group }}"
    name: testVMSS{{ rpfx }}
    vm_size: Standard_D4s_v3
    admin_username: testuser
    single_placement_group: false
    platform_fault_domain_count: 1
    public_ip_per_vm: true
    ssh_password_enabled: false
    ssh_public_keys:
      - path: /home/testuser/.ssh/authorized_keys
        key_data: "ssh-rsa ****"
    virtual_network_name: VMSStestVnet
    subnet_name: VMSStestSubnet
    managed_disk_type: Standard_LRS
    orchestration_mode: Flexible
    os_disk_caching: ReadWrite
    security_profile:
      uefi_settings:
        secure_boot_enabled: true
        v_tpm_enabled: false
      encryption_at_host: false
      security_type: TrustedLaunch
    image:
      offer: 0001-com-ubuntu-server-jammy
      publisher: Canonical
      sku: 22_04-lts-gen2
      version: latest
    data_disks:
      - lun: 0
        disk_size_gb: 64
        caching: ReadWrite
        managed_disk_type: Standard_LRS

- name: Create a scale set from a Specialized Shared Image Gallery version
  azure.azcollection.azure_rm_virtualmachinescaleset:
    resource_group: myResourceGroup
    name: testvmss-specialized
    vm_size: Standard_DS1_v2
    capacity: 2
    specialized_image: true
    os_type: Linux
    managed_disk_type: Standard_LRS
    image:
      id: >-
        /subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroups/myResourceGroup/providers/Microsoft.Compute/galleries/myGallery/images/myImage/versions/1.0.0
    virtual_network_name: testvnet
    subnet_name: testsubnet