community.vmware.vmware_cluster module – Manage VMware vSphere clusters

Note

This module is part of the community.vmware collection (version 1.18.2).

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 community.vmware.

To use it in a playbook, specify: community.vmware.vmware_cluster.

Synopsis

  • Adds or removes VMware vSphere clusters.

  • Although this module can manage DRS, HA and VSAN related configurations, this functionality is deprecated and will be removed in 2.12.

  • To manage DRS, HA and VSAN related configurations, use the new modules vmware_cluster_drs, vmware_cluster_ha and vmware_cluster_vsan.

  • All values and VMware object names are case sensitive.

Requirements

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

  • Tested on ESXi 5.5 and 6.5.

  • PyVmomi installed.

Parameters

Parameter

Comments

cluster_name

string / required

The name of the cluster to be managed.

datacenter

aliases: datacenter_name

string / required

The name of the datacenter.

drs_default_vm_behavior

string

Specifies the cluster-wide default DRS behavior for virtual machines.

If set to partiallyAutomated, then vCenter generate recommendations for virtual machine migration and for the placement with a host. vCenter automatically implement placement at power on.

If set to manual, then vCenter generate recommendations for virtual machine migration and for the placement with a host. vCenter should not implement the recommendations automatically.

If set to fullyAutomated, then vCenter should automate both the migration of virtual machines and their placement with a host at power on.

Use drs_default_vm_behavior of community.vmware.vmware_cluster_drs instead.

Deprecated option, will be removed in version 2.12.

Choices:

  • fullyAutomated ← (default)

  • manual

  • partiallyAutomated

drs_enable_vm_behavior_overrides

boolean

Determines whether DRS Behavior overrides for individual virtual machines are enabled.

If set to True, overrides drs_default_vm_behavior.

Use drs_enable_vm_behavior_overrides of community.vmware.vmware_cluster_drs instead.

Deprecated option, will be removed in version 2.12.

Choices:

  • no

  • yes ← (default)

drs_vmotion_rate

integer

Threshold for generated ClusterRecommendations.

Use drs_vmotion_rate of community.vmware.vmware_cluster_drs instead.

Deprecated option, will be removed in version 2.12.

Choices:

  • 1

  • 2

  • 3

  • 4

  • 5

Default: 3

enable_drs

boolean

If set to True, will enable DRS when the cluster is created.

Use enable_drs of community.vmware.vmware_cluster_drs instead.

Deprecated option, will be removed in version 2.12.

Choices:

  • no ← (default)

  • yes

enable_ha

boolean

If set to True will enable HA when the cluster is created.

Use enable_ha of community.vmware.vmware_cluster_ha instead.

Deprecated option, will be removed in version 2.12.

Choices:

  • no ← (default)

  • yes

enable_vsan

boolean

If set to True will enable vSAN when the cluster is created.

Use enable_vsan of community.vmware.vmware_cluster_vsan instead.

Deprecated option, will be removed in version 2.12.

Choices:

  • no ← (default)

  • yes

ha_admission_control_enabled

boolean

Determines if strict admission control is enabled.

It is recommended to set this parameter to True, please refer documentation for more details.

Use slot_based_admission_control, reservation_based_admission_control or failover_host_admission_control of community.vmware.vmware_cluster_ha instead.

Deprecated option, will be removed in version 2.12.

Choices:

  • no

  • yes ← (default)

ha_failover_level

integer

Number of host failures that should be tolerated, still guaranteeing sufficient resources to restart virtual machines on available hosts.

Accepts integer values only.

Use slot_based_admission_control, reservation_based_admission_control or failover_host_admission_control of community.vmware.vmware_cluster_ha instead.

Deprecated option, will be removed in version 2.12.

Default: 2

ha_host_monitoring

string

Indicates whether HA restarts virtual machines after a host fails.

If set to enabled, HA restarts virtual machines after a host fails.

If set to disabled, HA does not restart virtual machines after a host fails.

If enable_ha is set to False, then this value is ignored.

Use ha_host_monitoring of community.vmware.vmware_cluster_ha instead.

Deprecated option, will be removed in version 2.12.

Choices:

  • enabled ← (default)

  • disabled

ha_restart_priority

string

Determines the preference that HA gives to a virtual machine if sufficient capacity is not available to power on all failed virtual machines.

This setting is only valid if ha_vm_monitoring is set to, either vmAndAppMonitoring or vmMonitoringOnly.

If set to disabled, then HA is disabled for this virtual machine.

If set to high, then virtual machine with this priority have a higher chance of powering on after a failure, when there is insufficient capacity on hosts to meet all virtual machine needs.

If set to medium, then virtual machine with this priority have an intermediate chance of powering on after a failure, when there is insufficient capacity on hosts to meet all virtual machine needs.

If set to low, then virtual machine with this priority have a lower chance of powering on after a failure, when there is insufficient capacity on hosts to meet all virtual machine needs.

Use ha_restart_priority of community.vmware.vmware_cluster_ha instead.

Deprecated option, will be removed in version 2.12.

Choices:

  • disabled

  • high

  • low

  • medium ← (default)

ha_vm_failure_interval

integer

The number of seconds after which virtual machine is declared as failed if no heartbeat has been received.

This setting is only valid if ha_vm_monitoring is set to, either vmAndAppMonitoring or vmMonitoringOnly.

Unit is seconds.

Use ha_vm_failure_interval of community.vmware.vmware_cluster_ha instead.

Deprecated option, will be removed in version 2.12.

Default: 30

ha_vm_max_failure_window

integer

The number of seconds for the window during which up to ha_vm_max_failures resets can occur before automated responses stop.

This setting is only valid if ha_vm_monitoring is set to, either vmAndAppMonitoring or vmMonitoringOnly.

Unit is seconds.

Default specifies no failure window.

Use ha_vm_max_failure_window of community.vmware.vmware_cluster_ha instead.

Deprecated option, will be removed in version 2.12.

Default: -1

ha_vm_max_failures

integer

Maximum number of failures and automated resets allowed during the time that ha_vm_max_failure_window specifies.

This setting is only valid if ha_vm_monitoring is set to, either vmAndAppMonitoring or vmMonitoringOnly.

Use ha_vm_max_failures of community.vmware.vmware_cluster_ha instead.

Deprecated option, will be removed in version 2.12.

Default: 3

ha_vm_min_up_time

integer

The number of seconds for the virtual machine’s heartbeats to stabilize after the virtual machine has been powered on.

This setting is only valid if ha_vm_monitoring is set to, either vmAndAppMonitoring or vmMonitoringOnly.

Unit is seconds.

Use ha_vm_min_up_time of community.vmware.vmware_cluster_ha instead.

Deprecated option, will be removed in version 2.12.

Default: 120

ha_vm_monitoring

string

Indicates the state of virtual machine health monitoring service.

If set to vmAndAppMonitoring, HA response to both virtual machine and application heartbeat failure.

If set to vmMonitoringDisabled, virtual machine health monitoring is disabled.

If set to vmMonitoringOnly, HA response to virtual machine heartbeat failure.

If enable_ha is set to False, then this value is ignored.

Use ha_vm_monitoring of community.vmware.vmware_cluster_ha instead.

Deprecated option, will be removed in version 2.12.

Choices:

  • vmAndAppMonitoring

  • vmMonitoringOnly

  • vmMonitoringDisabled ← (default)

hostname

string

The hostname or IP address of the vSphere vCenter or ESXi server.

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

Environment variable support added in Ansible 2.6.

ignore_drs

boolean

If set to True, DRS will not be configured; all explicit and default DRS related configurations will be ignored.

Choices:

  • no ← (default)

  • yes

ignore_ha

boolean

If set to True, HA will not be configured; all explicit and default HA related configurations will be ignored.

Choices:

  • no ← (default)

  • yes

ignore_vsan

boolean

If set to True, VSAN will not be configured; all explicit and default VSAN related configurations will be ignored.

Choices:

  • no ← (default)

  • yes

password

aliases: pass, pwd

string

The password of the vSphere vCenter or ESXi server.

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

Environment variable support added in Ansible 2.6.

port

integer

The port number of the vSphere vCenter or ESXi server.

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

Environment variable support added in Ansible 2.6.

Default: 443

proxy_host

string

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.

This feature depends on a version of pyvmomi greater than v6.7.1.2018.12

proxy_port

integer

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.

state

string

Create present or remove absent a VMware vSphere cluster.

Choices:

  • absent

  • present ← (default)

username

aliases: admin, user

string

The username of the vSphere vCenter or ESXi server.

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

Environment variable support added in Ansible 2.6.

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.

Environment variable support added in Ansible 2.6.

If set to true, please make sure Python >= 2.7.9 is installed on the given machine.

Choices:

  • no

  • yes ← (default)

vsan_auto_claim_storage

boolean

Determines whether the VSAN service is configured to automatically claim local storage on VSAN-enabled hosts in the cluster.

Use vsan_auto_claim_storage of community.vmware.vmware_cluster_vsan instead.

Deprecated option, will be removed in version 2.12.

Choices:

  • no ← (default)

  • yes

Notes

Note

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

See Also

See also

community.vmware.vmware_cluster_drs

The official documentation on the community.vmware.vmware_cluster_drs module.

community.vmware.vmware_cluster_ha

The official documentation on the community.vmware.vmware_cluster_ha module.

community.vmware.vmware_cluster_vsan

The official documentation on the community.vmware.vmware_cluster_vsan module.

Examples

- name: Create Cluster
  community.vmware.vmware_cluster:
    hostname: '{{ vcenter_hostname }}'
    username: '{{ vcenter_username }}'
    password: '{{ vcenter_password }}'
    datacenter_name: datacenter
    cluster_name: cluster
    enable_ha: true
    enable_drs: true
    enable_vsan: true
  delegate_to: localhost

- name: Create Cluster with additional changes
  community.vmware.vmware_cluster:
    hostname: "{{ vcenter_hostname }}"
    username: "{{ vcenter_username }}"
    password: "{{ vcenter_password }}"
    datacenter_name: DC0
    cluster_name: "{{ cluster_name }}"
    enable_ha: True
    ha_vm_monitoring: vmMonitoringOnly
    enable_drs: True
    drs_default_vm_behavior: partiallyAutomated
    enable_vsan: True
  register: cl_result
  delegate_to: localhost

- name: Delete Cluster
  community.vmware.vmware_cluster:
    hostname: "{{ vcenter_hostname }}"
    username: "{{ vcenter_username }}"
    password: "{{ vcenter_password }}"
    datacenter_name: datacenter
    cluster_name: cluster
    enable_ha: true
    enable_drs: true
    enable_vsan: true
    state: absent
  delegate_to: localhost

Authors

  • Joseph Callen (@jcpowermac)

  • Abhijeet Kasurde (@Akasurde)