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 5.8.3).
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.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 |
|---|---|
Disable/enable agent checks (depending on state value). Choices:
|
|
Name of the HAProxy backend pool. If this parameter is unset, it will be auto-detected. |
|
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 This overrides the shutdown_sessions option. Choices:
|
|
Fail whenever trying to enable/disable a backend host that does not exist. Choices:
|
|
Disable/enable health checks (depending on state value). Choices:
|
|
Name of the backend host to change. |
|
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:
|
|
Path to the HAProxy socket file. Default: |
|
Desired state of the provided backend host. Note that It is supported only by HAProxy version 1.5 or later, When used on versions < 1.5, it will be ignored. Choices:
|
|
Wait until the server reports a status of Choices:
|
|
Number of seconds to wait between retries. Default: |
|
Number of times to check for status after changing the state. Default: |
|
The value passed in argument. If the value ends with the Relative weights are only permitted between 0 and 100% and absolute weights are permitted between 0 and 256. |
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
Collection links
Issue Tracker Repository (Sources) Submit a bug report Request a feature Communication