community.general.haproxy module – Enable, disable, and set weights for HAProxy backend servers using socket commands

Note

This module is part of the community.general collection (version 9.4.0).

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.general.

To use it in a playbook, specify: community.general.haproxy.

Synopsis

  • Enable, disable, drain and set weights for HAProxy backend servers using socket commands.

Parameters

Parameter

Comments

agent

boolean

added in community.general 1.0.0

Disable/enable agent checks (depending on state value).

Choices:

  • false ← (default)

  • true

backend

string

Name of the HAProxy backend pool.

If this parameter is unset, it will be auto-detected.

drain

boolean

Wait until the server has no active connections or until the timeout determined by wait_interval and wait_retries is reached.

Continue only after the status changes to MAINT.

This overrides the shutdown_sessions option.

Choices:

  • false ← (default)

  • true

fail_on_not_found

boolean

Fail whenever trying to enable/disable a backend host that does not exist.

Choices:

  • false ← (default)

  • true

health

boolean

added in community.general 1.0.0

Disable/enable health checks (depending on state value).

Choices:

  • false ← (default)

  • true

host

string / required

Name of the backend host to change.

shutdown_sessions

boolean

When disabling a server, immediately terminate all the sessions attached to the specified server.

This can be used to terminate long-running sessions after a server is put into maintenance mode. Overridden by the drain option.

Choices:

  • false ← (default)

  • true

socket

path

Path to the HAProxy socket file.

Default: "/var/run/haproxy.sock"

state

string / required

Desired state of the provided backend host.

Note that drain state is supported only by HAProxy version 1.5 or later. When used on versions < 1.5, it will be ignored.

Choices:

  • "disabled"

  • "drain"

  • "enabled"

wait

boolean

Wait until the server reports a status of UP when state=enabled, status of MAINT when state=disabled or status of DRAIN when state=drain.

Choices:

  • false ← (default)

  • true

wait_interval

integer

Number of seconds to wait between retries.

Default: 5

wait_retries

integer

Number of times to check for status after changing the state.

Default: 25

weight

string

The value passed in argument.

If the value ends with the % sign, then the new weight will be relative to the initially configured weight.

Relative weights are only permitted between 0 and 100% and absolute weights are permitted between 0 and 256.

Attributes

Attribute

Support

Description

check_mode

Support: none

Can run in check_mode and return changed status prediction without modifying target.

diff_mode

Support: none

Will return details on what has changed (or possibly needs changing in check_mode), when in diff mode.

Notes

Note

  • Enable, disable and drain commands are restricted and can only be issued on sockets configured for level ‘admin’. For example, you can add the line ‘stats socket /var/run/haproxy.sock level admin’ to the general section of haproxy.cfg. See http://haproxy.1wt.eu/download/1.5/doc/configuration.txt.

  • Depends on netcat (nc) being available; you need to install the appropriate package for your operating system before this module can be used.

Examples

- name: Disable server in 'www' backend pool
  community.general.haproxy:
    state: disabled
    host: '{{ inventory_hostname }}'
    backend: www

- name: Disable server in 'www' backend pool, also stop health/agent checks
  community.general.haproxy:
    state: disabled
    host: '{{ inventory_hostname }}'
    health: true
    agent: true

- name: Disable server without backend pool name (apply to all available backend pool)
  community.general.haproxy:
    state: disabled
    host: '{{ inventory_hostname }}'

- name: Disable server, provide socket file
  community.general.haproxy:
    state: disabled
    host: '{{ inventory_hostname }}'
    socket: /var/run/haproxy.sock
    backend: www

- name: Disable server, provide socket file, wait until status reports in maintenance
  community.general.haproxy:
    state: disabled
    host: '{{ inventory_hostname }}'
    socket: /var/run/haproxy.sock
    backend: www
    wait: true

# Place server in drain mode, providing a socket file.  Then check the server's
# status every minute to see if it changes to maintenance mode, continuing if it
# does in an hour and failing otherwise.
- community.general.haproxy:
    state: disabled
    host: '{{ inventory_hostname }}'
    socket: /var/run/haproxy.sock
    backend: www
    wait: true
    drain: true
    wait_interval: 60
    wait_retries: 60

- name: Disable backend server in 'www' backend pool and drop open sessions to it
  community.general.haproxy:
    state: disabled
    host: '{{ inventory_hostname }}'
    backend: www
    socket: /var/run/haproxy.sock
    shutdown_sessions: true

- name: Disable server without backend pool name (apply to all available backend pool) but fail when the backend host is not found
  community.general.haproxy:
    state: disabled
    host: '{{ inventory_hostname }}'
    fail_on_not_found: true

- name: Enable server in 'www' backend pool
  community.general.haproxy:
    state: enabled
    host: '{{ inventory_hostname }}'
    backend: www

- name: Enable server in 'www' backend pool wait until healthy
  community.general.haproxy:
    state: enabled
    host: '{{ inventory_hostname }}'
    backend: www
    wait: true

- name: Enable server in 'www' backend pool wait until healthy. Retry 10 times with intervals of 5 seconds to retrieve the health
  community.general.haproxy:
    state: enabled
    host: '{{ inventory_hostname }}'
    backend: www
    wait: true
    wait_retries: 10
    wait_interval: 5

- name: Enable server in 'www' backend pool with change server(s) weight
  community.general.haproxy:
    state: enabled
    host: '{{ inventory_hostname }}'
    socket: /var/run/haproxy.sock
    weight: 10
    backend: www

- name: Set the server in 'www' backend pool to drain mode
  community.general.haproxy:
    state: drain
    host: '{{ inventory_hostname }}'
    socket: /var/run/haproxy.sock
    backend: www

Authors

  • Ravi Bhure (@ravibhure)