vmware.vmware.cluster_ha module – Manage High Availability services (HA) on VMware vSphere clusters

Note

This module is part of the vmware.vmware collection (version 1.11.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 vmware.vmware.

To use it in a playbook, specify: vmware.vmware.cluster_ha.

Synopsis

  • Manages HA on VMware vSphere clusters.

Parameters

Parameter

Comments

admission_control_cpu_reserve_percentage

integer

Percentage of CPU resources in the cluster to reserve for failover.

Only used if admission_control_policy is cluster_resource.

By default, the admission_control_failover_level is used by vSphere to automatically calculate this value. Setting this option overrides that behavior.

admission_control_dedicated_hosts

list / elements=string

List of ESXi hosts to use as dedicated failover hosts.

The list should be the names of ESXi hosts as seen in vCenter.

Required if (and only used if) admission_control_policy is dedicated_host.

admission_control_failover_level

integer

The number of host failures that should be tolerated by the cluster.

The maximum is one less than the total number of hosts.

Only used if admission_control_policy is cluster_resource or vm_slots.

Default: 1

admission_control_memory_reserve_percentage

integer

Percentage of memory resources in the cluster to reserve for failover.

Only used if admission_control_policy is cluster_resource.

By default, the admission_control_failover_level is used by vSphere to automatically calculate this value. Setting this option overrides that behavior.

admission_control_policy

string

Configures a the policy type used for HA admission control.

Admission control is a policy used by vSphere HA to ensure failover capacity within a cluster.

Raising the number of potential host failures will increase the availability constraints and capacity reserved.

Choices:

  • "vm_slots"

  • "cluster_resource"

  • "dedicated_host"

advanced_settings

dictionary

A dictionary of advanced HA settings.

Default: {}

cluster

aliases: cluster_name

string / required

The name of the cluster to be managed.

datacenter

aliases: datacenter_name

string / required

The name of the datacenter.

enable

boolean

Whether to enable HA.

Choices:

  • false

  • true ← (default)

host_failure_response

dictionary

Configures how VM workflows should be managed if an ESXi host is in a failure state.

default_vm_restart_priority

string

Set the default priority HA gives to a virtual machine if sufficient capacity is not available to power on all failed virtual machines.

Used only when vm_monitoring.mode is vmAndAppMonitoring or vmMonitoringOnly.

Choices:

  • "lowest"

  • "low"

  • "medium" ← (default)

  • "high"

  • "highest"

restart_vms

boolean

If true, HA will restart virtual machines after a host fails and comes back online.

Choices:

  • false

  • true ← (default)

host_isolation_response

string

Specify how VMs should be handled if an ESXi host determines it can no longer reach the rest of the cluster.

If set to none, no action is taken.

If set to powerOff, VMs are powered off via the hypervisor.

If set to shutdown, VMs are shut down via the guest operating system.

Choices:

  • "none" ← (default)

  • "powerOff"

  • "shutdown"

hostname

string

The hostname or IP address of the vSphere vCenter server.

If the value is not specified in the task, the value of environment variable VMWARE_HOST will be used instead.

password

aliases: pass, pwd

string

The password of the vSphere vCenter server.

If the value is not specified in the task, the value of environment variable VMWARE_PASSWORD will be used instead.

port

integer

The port number of the vSphere vCenter server.

If the value is not specified in the task, the value of environment variable VMWARE_PORT will be used instead.

Default: 443

proxy_host

string

The address of a proxy that will receive all HTTPS requests and relay them.

The format is a hostname or a IP.

If the value is not specified in the task, the value of environment variable VMWARE_PROXY_HOST will be used instead.

proxy_port

integer

The port of the HTTP proxy that will receive all HTTPS requests and relay them.

If the value is not specified in the task, the value of environment variable VMWARE_PROXY_PORT will be used instead.

storage_apd_response

dictionary

Configures what steps are taken when storage All Paths Down (APD) events occur.

delay

integer

Set the response recovery delay time in seconds if storage is in an APD failure state.

This is only used if storage_apd_response=restartConservative or storage_apd_response=restartAggressive.

Default: 180

mode

string

Set the response in the event of All Paths Down (APD) for storage.

APD differs from PDL, in that APD is assumed to be a transient outage and PDL is permanent.

disabled means no action will be taken

warning means no action will be taken, but events will be generated for logging purposes.

restartConservative means VMs will be powered off if HA determines another host can support the VM.

restartAggressive means VMs will be powered off if HA determines the VM can be restarted on a different host, or if HA cannot detect the resources on other hosts because of network connectivity loss.

Choices:

  • "disabled"

  • "warning" ← (default)

  • "restartConservative"

  • "restartAggressive"

restart_vms

boolean

If true, VMs will be restarted when possible if storage is in an APD failure state.

This is only used if storage_apd_response is restartConservative restartAggressive.

Choices:

  • false

  • true ← (default)

storage_pdl_response_mode

string

Set the response in the event of permanent Device Loss (PDL) for storage.

APD differs from PDL, in that APD is assumed to be a transient outage and PDL is permanent.

disabled means no action will be taken

warning means no action will be taken, but events will be generated for logging purposes.

restart means all VMs will be powered off. If hosts still have access to the datastore, affected VMs will be restarted on that host.

Choices:

  • "disabled"

  • "warning" ← (default)

  • "restart"

username

aliases: admin, user

string

The username of the vSphere vCenter server.

If the value is not specified in the task, the value of environment variable VMWARE_USER will be used instead.

validate_certs

boolean

Allows connection when SSL certificates are not valid. Set to false when certificates are not trusted.

If the value is not specified in the task, the value of environment variable VMWARE_VALIDATE_CERTS will be used instead.

Choices:

  • false

  • true ← (default)

vm_monitoring

dictionary

Configures how VMs are monitored to determine health status, and what actions should be taken if they are unhealthy.

failure_interval

integer

The number of seconds to wait after a VM heartbeat fails before declaring the VM as unhealthy.

Valid only when vm_monitoring.mode is vmAndAppMonitoring or vmMonitoringOnly.

Default: 30

maximum_resets

integer

The maximum number of automated resets allowed in response to a VM becoming unhealthy

Valid only when vm_monitoring.mode is vmAndAppMonitoring or vmMonitoringOnly.

Default: 3

maximum_resets_window

integer

The number of seconds during in which vm_monitoring.maximum_resets resets can occur before automated responses stop.

Valid only when vm_monitoring.mode is vmAndAppMonitoring or vmMonitoringOnly.

The default value of -1 specifies no window.

Default: -1

minimum_uptime

integer

The number of seconds to wait for the VM’s heartbeat to stabilize after it was powered reset.

Valid only when vm_monitoring.mode is vmAndAppMonitoring or vmMonitoringOnly.

Default: 120

mode

string

Sets the state of the virtual machine health monitoring service.

If set to vmAndAppMonitoring, HA will respond to both VM and vApp heartbeat failures.

If set to vmMonitoringDisabled, HA will only respond to vApp heartbeat failures.

If set to vmMonitoringOnly, HA will only respond to VM heartbeat failures.

Choices:

  • "vmAndAppMonitoring"

  • "vmMonitoringOnly"

  • "vmMonitoringDisabled" ← (default)

Notes

Note

  • All modules require API write access and hence are not supported on a free ESXi license.

  • All variables and VMware object names are case sensitive.

  • Modules may rely on the ‘requests’ python library, which does not use the system certificate store by default. You can specify the certificate store by setting the REQUESTS_CA_BUNDLE environment variable. Example: ‘export REQUESTS_CA_BUNDLE=/path/to/your/ca_bundle.pem’

Examples

- name: Enable HA With vCenter Defaults
  vmware.vmware.cluster_ha:
    hostname: "{{ vcenter_hostname }}"
    username: "{{ vcenter_username }}"
    password: "{{ vcenter_password }}"
    datacenter: DC01
    cluster: my-cluster

- name: Disable HA
  vmware.vmware.cluster_ha:
    hostname: "{{ vcenter_hostname }}"
    username: "{{ vcenter_username }}"
    password: "{{ vcenter_password }}"
    datacenter: DC01
    cluster: my-cluster
    enable: false

- name: Set HA Settings In Cluster
  vmware.vmware.cluster_ha:
    hostname: "{{ vcenter_hostname }}"
    username: "{{ vcenter_username }}"
    password: "{{ vcenter_password }}"
    datacenter: DC01
    cluster: my-cluster
    host_failure_response:
      restart_vms: true
      default_vm_restart_priority: low
    host_isolation_response: powerOff
    admission_control_policy: dedicated_host
    admission_control_dedicated_hosts:
      - DC0_C0_H0
      - DC0_C0_H1
    vm_monitoring:
      mode: vmAndAppMonitoring
    storage_apd_response:
      mode: restartConservative
      delay: 100
      restart_vms: true
    storage_pdl_response_mode: restart

# If you do not set a parameter and it has no default, the module will ignore
# the corresponding vCenter setting when checking for config diffs and applying new configs
- name: Only Manage Host Failure Settings
  vmware.vmware.cluster_ha:
    hostname: "{{ vcenter_hostname }}"
    username: "{{ vcenter_username }}"
    password: "{{ vcenter_password }}"
    datacenter: DC01
    cluster: my-cluster
    host_failure_response:
      restart_vms: true
      default_vm_restart_priority: low

Return Values

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

Key

Description

result

dictionary

Information about the HA config update task, if something changed

If nothing changed, an empty dictionary is returned

Returned: On success

Sample: {"result": {"completion_time": "2025-01-23T21:27:39.156434+00:00", "entity_name": "my-cluster-name", "error": null, "result": null, "state": "success"}}

Authors

  • Ansible Cloud Team (@ansible-collections)