vultr.cloud.load_balancer module – Manages load balancers on Vultr

Note

This module is part of the vultr.cloud collection (version 1.14.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 vultr.cloud.

To use it in a playbook, specify: vultr.cloud.load_balancer.

New in vultr.cloud 1.14.0

Synopsis
Parameters
Notes
Examples
Return Values

Synopsis

Create, update, or delete load balancers on Vultr.

Parameters

Parameter	Comments
api_endpoint string	URL to API endpint (without trailing slash). Fallback environment variable `VULTR_API_ENDPOINT`. Default: `"https://api.vultr.com/v2"`
api_key string / required	API key of the Vultr API. Fallback environment variable `VULTR_API_KEY`.
api_results_per_page integer added in vultr.cloud 1.14.0	When receiving large numbers of resources, specify how many results should be returned per call to API. This does not determine how many results are returned; all resources are returned according to other filters. Vultr API maximum is 500. Fallback environment variable `VULTR_API_RESULTS_PER_PAGE`. Default: `100`
api_retries integer	Amount of retries in case of the Vultr API retuns an HTTP error code, such as - 429 Too Many Requests - 500 Internal Server Error - 504 Gateway Time-out Fallback environment variable `VULTR_API_RETRIES`. Default: `5`
api_retry_max_delay integer	Retry backoff delay in seconds is exponential up to this max. value, in seconds. Fallback environment variable `VULTR_API_RETRY_MAX_DELAY`. Default: `12`
api_timeout integer	HTTP timeout to Vultr API. Fallback environment variable `VULTR_API_TIMEOUT`. Default: `180`
auto_ssl dictionary	The Auto SSL configuration. Must be using Vultr DNS for Auto SSL.
domain_sub string	Subdomain to append to the domain zone
domain_zone string	The domain zone (ex. example.com)
balancing_algorithm string	The balancing algorithm. Choices: `"roundrobin"` ← (default) `"leastconn"`
firewall_rules list / elements=dictionary	An array of firewall rule objects.
forwarding_rules list / elements=dictionary	An array of forwarding rule objects.
backend_port integer / required	Port on the backend.
backend_protocol string / required	Protocol on the backend.
frontend_port integer / required	Port on the frontend.
frontend_protocol string / required	Protocol on the frontend.
global_regions list / elements=string	Array of Region ids to deploy child Load Balancers to.
health_check dictionary	The health check configuration.
check_interval integer	Interval between health checks in seconds.
healthy_threshold integer	Number of successful health checks before marking as healthy.
path string	Path used for health checks.
port integer	Port used for health checks.
protocol string	Protocol used for health checks.
response_timeout integer	Timeout for health check responses in seconds.
unhealthy_threshold integer	Number of failed health checks before marking as unhealthy.
http2 boolean	If true, this will enable HTTP2 traffic. You must have an HTTPS forwarding rule combo (HTTPS -> HTTPS) to enable this option. Choices: `false` `true`
http3 boolean	If true, this will enable HTTP3/QUIC traffic. You must have HTTP2 enabled. Choices: `false` `true`
instances list / elements=string	Array of Instance IDs to attach to this Load Balancer. Instances will be attached or detached to match your array.
label aliases: name string / required	The label for your Load Balancer.
nodes integer	The number of nodes to add to the load balancer (1-99), must be an odd number. Defaults to 1. Default: `1`
proxy_protocol boolean	If true, you must configure backend nodes to accept Proxy protocol. Choices: `false` ← (default) `true`
region string / required	Region where the load balancer will be created.
ssl_redirect boolean	If true, this will redirect all HTTP traffic to HTTPS. You must have an HTTPS rule and SSL certificate installed on the load balancer to enable this option. Choices: `false` `true`
state string	State of the load balancer. Choices: `"present"` ← (default) `"absent"`
sticky_session dictionary	Enables sticky sessions for your load balancer when a cookie_name is provided.
timeout integer	The maximum time allowed for the connection to remain inactive before timing out in seconds. Defaults to 600. Default: `600`
validate_certs boolean	Validate SSL certs of the Vultr API. Choices: `false` `true` ← (default)
vpc string	ID of the VPC you wish to use. If omitted, defaults to the public network.

Notes

Note

Also see the API documentation on https://www.vultr.com/api/.

Examples

---
- name: Create a basic load balancer
  vultr.cloud.load_balancer:
    label: "example-lb"
    region: "ewr"
    forwarding_rules:
      - frontend_protocol: "http"
        frontend_port: 80
        backend_protocol: "http"
        backend_port: 80
      - frontend_protocol: "https"
        frontend_port: 443
        backend_protocol: "https"
        backend_port: 443
    balancing_algorithm: "roundrobin"
    ssl_redirect: true
    http2: true
    http3: false
    nodes: 1
    timeout: 600
    health_check:
      protocol: "http"
      port: 80
      path: "/"
      check_interval: 15
      response_timeout: 5
      unhealthy_threshold: 3
      healthy_threshold: 2
    proxy_protocol: false
    sticky_session: {}
    instances: []
    vpc: null
    firewall_rules: []
    auto_ssl: {}
    global_regions: []
    state: present

- name: Delete a load balancer
  vultr.cloud.load_balancer:
    label: "example-lb"
    region: "ewr"
    state: absent

Return Values

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

Key	Description
vultr_api dictionary	Response from Vultr API with a few additions/modification. Returned: success
api_account string	Account used in the ini file to select the key. Returned: success Sample: `"default"`
api_endpoint string	Endpoint used for the API requests. Returned: success Sample: `"https://api.vultr.com/v2"`
api_retries integer	Amount of max retries for the API requests. Returned: success Sample: `5`
api_retry_max_delay integer	Exponential backoff delay in seconds between retries up to this max delay value. Returned: success Sample: `12`
api_timeout integer	Timeout used for the API requests. Returned: success Sample: `60`
vultr_load_balancer dictionary	Response from Vultr API. Returned: success
auto_ssl dictionary	Auto SSL configuration. Returned: success
date_created string	Date and time when the load balancer was created. Returned: success Sample: `"2020-10-10T01:56:20+00:00"`
firewall_rules list / elements=dictionary	List of firewall rules. Returned: success
forwarding_rules list / elements=dictionary	List of forwarding rules. Returned: success
generic_info dictionary	Additional generic information about the load balancer. Returned: success
global_regions list / elements=string	List of global regions for the load balancer. Returned: success
has_ssl boolean	Whether SSL is enabled. Returned: success Sample: `false`
health_check dictionary	Health check configuration for the load balancer. Returned: success
http2 boolean	Whether HTTP/2 is enabled. Returned: success Sample: `false`
http3 boolean	Whether HTTP/3 is enabled. Returned: success Sample: `false`
id string	Unique identifier for the load balancer. Returned: success Sample: `"cb676a46-66fd-4dfb-b839-443f2e6c0b60"`
instances list / elements=string	List of instances attached to the load balancer. Returned: success
ipv4 string	IPv4 address assigned to the load balancer. Returned: success Sample: `"192.0.2.123"`
ipv6 string	IPv6 address assigned to the load balancer. Returned: success Sample: `"2001:0db8:5:4973:ffff:ffff:ffff:ffff"`
label string	Name/label of the load balancer. Returned: success Sample: `"Example Load Balancer"`
node_ips dictionary	IP addresses of the nodes. Returned: success
nodes integer	Number of nodes in the load balancer. Returned: success Sample: `1`
region string	Region code where the load balancer is deployed. Returned: success Sample: `"ewr"`
status string	Current status of the load balancer. Returned: success Sample: `"active"`

Authors

Garrett Haughawout (@ghaughawout)

Collection links

© 2012–2018 Michael DeHaan
© 2018–2025 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/projects/ansible/latest/collections/vultr/cloud/load_balancer_module.html