Manage a Linode NodeBalancer.
NOTE: UDP NodeBalancer may not currently be available to all users.
| Field |
Type |
Required |
Description |
api_token |
str |
Required |
The Linode account personal access token. It is necessary to run the module.
It can be exposed by the environment variable LINODE_API_TOKEN instead.
See details in Usage. |
- name: Create a Linode NodeBalancer
linode.cloud.nodebalancer:
label: my-loadbalancer
region: us-east
tags: [ prod-env ]
state: present
configs:
- port: 80
protocol: http
algorithm: roundrobin
nodes:
- label: node1
address: 0.0.0.0:80- name: Create a NodeBalancer with a reserved IP
linode.cloud.nodebalancer:
label: my-loadbalancer
region: us-east
ipv4: "192.0.2.141"
state: present- name: Create a NodeBalancer with IPv6 backends
linode.cloud.nodebalancer:
label: my-ipv6-loadbalancer
region: us-east
type: common
backend_connectivity: ipv6
state: present- name: Create a NodeBalancer with VPC connectivity
linode.cloud.nodebalancer:
label: my-vpc-loadbalancer
region: us-east
backend_connectivity: vpc
vpcs:
- subnet_id: 12345
ipv4_range: 10.0.0.0/24
state: present- name: Delete the NodeBalancer
linode.cloud.nodebalancer:
label: my-loadbalancer
region: us-east
state: absent
| Field |
Type |
Required |
Description |
label |
str |
Required |
The unique label to give this NodeBalancer. |
state |
str |
Required |
The desired state of the target. (Choices: present, absent) |
client_conn_throttle |
int |
Optional |
Throttle connections per second. Set to 0 (zero) to disable throttling. (Updatable) |
client_udp_sess_throttle |
int |
Optional |
Throttle UDP sessions per second (0-20). Set to 0 (zero) to disable throttling. (Updatable) |
region |
str |
Optional |
The ID of the Region to create this NodeBalancer in. |
type |
str |
Optional |
The type of NodeBalancer to create. Defaults to common and cannot be changed after creation. Premium and Enterprise NodeBalancers may not be available to all users. (Choices: common, premium, premium_40gb, enterprise) |
backend_connectivity |
str |
Optional |
How this NodeBalancer connects to backend nodes. If omitted, the API infers the value from VPC attachments or configured nodes. This cannot be changed after creation. (Choices: legacy, ipv6, vpc) |
vpcs (sub-options) |
list |
Optional |
VPC subnets to attach to this NodeBalancer. Required when backend_connectivity is vpc and cannot be changed after creation. |
ipv4 |
str |
Optional |
A reserved IPv4 address to assign to this NodeBalancer on creation. The address must be a reserved, unassigned IPv4 address owned by the account. NOTE: This field is only used at creation time. |
firewall_id |
int |
Optional |
The ID of the Firewall to assign this NodeBalancer to. |
tags |
list |
Optional |
Tags to assign to this NodeBalancer. (Updatable) |
configs (sub-options) |
list |
Optional |
A list of configs to apply to the NodeBalancer. (Updatable) |
| Field |
Type |
Required |
Description |
subnet_id |
int |
Required |
The ID of the VPC subnet to attach to this NodeBalancer. |
ipv4_range |
str |
Optional |
The IPv4 range in the subnet that this NodeBalancer can use. |
| Field |
Type |
Required |
Description |
algorithm |
str |
Optional |
What algorithm this NodeBalancer should use for routing traffic to backends. (Choices: roundrobin, leastconn, source, ring_hash; Updatable) |
check |
str |
Optional |
The type of check to perform against backends to ensure they are serving requests. (Choices: none, connection, http, http_body; Updatable) |
check_attempts |
int |
Optional |
How many times to attempt a check before considering a backend to be down. (Updatable) |
check_body |
str |
Optional |
This value must be present in the response body of the check in order for it to pass. If this value is not present in the response body of a check request, the backend is considered to be down. (Updatable) |
check_interval |
int |
Optional |
How often, in seconds, to check that backends are up and serving requests. (Updatable) |
check_passive |
bool |
Optional |
If true, any response from this backend with a 5xx status code will be enough for it to be considered unhealthy and taken out of rotation. (Updatable) |
check_path |
str |
Optional |
The URL path to check on each backend. If the backend does not respond to this request it is considered to be down. (Updatable) |
check_timeout |
int |
Optional |
How long, in seconds, to wait for a check attempt before considering it failed. (Updatable) |
udp_check_port |
int |
Optional |
Specifies the port on the backend node used for active health checks, which may differ from the port serving traffic. (Updatable) |
cipher_suite |
str |
Optional |
What ciphers to use for SSL connections served by this NodeBalancer. (Choices: recommended, legacy, none; Updatable) |
port |
int |
Optional |
The port this Config is for. (Updatable) |
protocol |
str |
Optional |
The protocol this port is configured to serve. (Choices: http, https, tcp, udp; Updatable) |
proxy_protocol |
str |
Optional |
ProxyProtocol is a TCP extension that sends initial TCP connection information such as source/destination IPs and ports to backend devices. (Choices: none, v1, v2; Updatable) |
recreate |
bool |
Optional |
If true, the config will be forcibly recreated on every run. This is useful for updates to redacted fields (ssl_cert, ssl_key) (Default: False) |
ssl_cert |
str |
Optional |
The PEM-formatted public SSL certificate (or the combined PEM-formatted SSL certificate and Certificate Authority chain) that should be served on this NodeBalancerConfig’s port. (Updatable) |
ssl_key |
str |
Optional |
The PEM-formatted private key for the SSL certificate set in the ssl_cert field. (Updatable) |
stickiness |
str |
Optional |
Controls how session stickiness is handled on this port. (Choices: none, table, http_cookie, session, source_ip; Updatable) |
nodes (sub-options) |
list |
Optional |
A list of nodes to apply to this config. These can alternatively be configured through the nodebalancer_node module. (Updatable) |
| Field |
Type |
Required |
Description |
label |
str |
Required |
The label for this node. |
address |
str |
Required |
The IP address where this backend can be reached. The address must match the NodeBalancer's backend connectivity. For legacy, use a private IPv4 address. For ipv6, use a public IPv6 address in [IPv6]:port format. For vpc, use an address in the attached VPC subnet. (Updatable) |
weight |
int |
Optional |
Nodes with a higher weight will receive more traffic. (Updatable) |
mode |
str |
Optional |
The mode this NodeBalancer should use when sending traffic to this backend. (Choices: accept, reject, drain, backup; Updatable) |
-
node_balancer - The NodeBalancer in JSON serialized form.
- Sample Response:
{
"client_conn_throttle": 0,
"created": "2018-01-01T00:01:01",
"hostname": "192.0.2.1.ip.linodeusercontent.com",
"id": 12345,
"ipv4": "12.34.56.78",
"ipv6": null,
"label": "balancer12345",
"type": "common",
"backend_connectivity": "ipv6",
"backend_ipv6_prefix": "2600:3c22:1:20:0:3039::/96",
"region": "us-east",
"tags": [
"example tag",
"another example"
],
"transfer": {
"in": 28.91200828552246,
"out": 3.5487728118896484,
"total": 32.46078109741211
},
"updated": "2018-03-01T00:01:01"
}
- See the Linode API response documentation for a list of returned fields
-
configs - A list of configs applied to the NodeBalancer.
- Sample Response:
[
{
"algorithm": "roundrobin",
"check": "http_body",
"check_attempts": 3,
"check_body": "it works",
"check_interval": 90,
"check_passive": true,
"check_path": "/test",
"check_timeout": 10,
"cipher_suite": "recommended",
"id": 4567,
"nodebalancer_id": 12345,
"nodes_status": {
"down": 0,
"up": 4
},
"port": 80,
"protocol": "http",
"proxy_protocol": "none",
"ssl_cert": null,
"ssl_commonname": null,
"ssl_fingerprint": null,
"ssl_key": null,
"stickiness": "http_cookie"
}
]
- See the Linode API response documentation for a list of returned fields
-
nodes - A list of configs applied to the NodeBalancer.
- Sample Response:
[
{
"address": "192.168.210.120:80",
"config_id": 4567,
"id": 54321,
"label": "node54321",
"mode": "accept",
"nodebalancer_id": 12345,
"status": "UP",
"weight": 50
}
]
- See the Linode API response documentation for a list of returned fields
-
firewalls - A list IDs for firewalls attached to this NodeBalancer.