stephrobert.scaleway.lb_backend module – Manage a Scaleway Load Balancer backend

Note

This module is part of the stephrobert.scaleway collection (version 0.7.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 stephrobert.scaleway. You need further requirements to be able to use this module, see Requirements for details.

To use it in a playbook, specify: stephrobert.scaleway.lb_backend.

New in stephrobert.scaleway 0.1.0

Synopsis

  • Update a backend of a given Load Balancer, specified by its backend ID.

  • The module reads the resource first and writes the whole body, because this operation replaces the resource: fields you do not set keep the value the API returns. A second run reports no change.

Requirements

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

  • scaleway >= 2.9.0

Parameters

Parameter

Comments

access_key

string

Scaleway API access key.

api_allow_insecure

boolean

Allow the API endpoint to be reached without verifying its TLS certificate.

Falls back to the Scaleway configuration file, then to false.

Choices:

  • false

  • true

api_timeout

integer

Seconds allowed for a single API call, connection and read.

Without a limit a silent connection would hang the module forever: the Scaleway SDK issues its requests with no timeout at all.

This bounds a single call, not a whole wait. Modules that can wait for a state bound the overall wait separately.

Default: 60

api_url

string

URL of the Scaleway API endpoint.

Point it at a local emulator to exercise a playbook without credentials.

Falls back to the Scaleway configuration file, then to https://api.scaleway.com. It carries no module default on purpose: a default is never unset, so it would always override the profile.

backend_id

string / required

Backend ID.

config_file

path

Path to the Scaleway configuration file.

failover_host

string

Scaleway Object Storage bucket website to be served as failover if all backend servers are down, e.g. failover-website.s3-website.fr-par.scw.cloud.

To clear this field, write `failover_host: “”`; omit the option to leave the current value untouched.

Setting it to null is refused: this API reads null as “field not provided” and would change nothing.

forward_port

integer / required

Port to be used by the backend when forwarding traffic to backend servers.

forward_port_algorithm

string / required

Load balancing algorithm to be used when determining which backend server to forward new traffic to.

Choices:

  • "roundrobin"

  • "leastconn"

  • "first"

forward_protocol

string / required

Protocol to be used by the backend when forwarding traffic to backend servers.

Choices:

  • "tcp"

  • "http"

host

string

added in stephrobert.scaleway 0.5.0

Host value to use when connecting to backend servers. When connecting to backend servers, use this value as the HTTP Host header or TLS SNI. This allows routing to specific services on the backend server that are configured to respond to particular hostnames.

To clear this field, write `host: “”`; omit the option to leave the current value untouched.

Setting it to null is refused: this API reads null as “field not provided” and would change nothing.

ignore_ssl_server_verify

boolean

Defines whether the server certificate verification should be ignored.

The contract marks this field clearable, but bool has no empty value, so the API cannot clear it. Setting it to null is refused: this API reads null as “field not provided” and would change nothing.

Choices:

  • false

  • true

max_connections

integer

Maximum number of connections allowed per backend server.

The contract marks this field clearable, but int has no empty value, so the API cannot clear it. Setting it to null is refused: this API reads null as “field not provided” and would change nothing.

max_retries

integer

Number of retries when a backend server connection failed.

The contract marks this field clearable, but int has no empty value, so the API cannot clear it. Setting it to null is refused: this API reads null as “field not provided” and would change nothing.

name

string / required

Backend name.

on_marked_down_action

string

Action to take when a backend server is marked as down.

Choices:

  • "on_marked_down_action_none"

  • "shutdown_sessions"

organization_id

string

Default Organization ID used when an operation does not name one.

profile

string

Name of the profile to read in the Scaleway configuration file.

project_id

string

Default Project ID used when an operation does not name one.

proxy_protocol

string

Protocol to use between the Load Balancer and backend servers. Allows the backend servers to be informed of the client’s real IP address. The PROXY protocol must be supported by the backend servers’ software.

Choices:

  • "proxy_protocol_unknown"

  • "proxy_protocol_none"

  • "proxy_protocol_v1"

  • "proxy_protocol_v2"

  • "proxy_protocol_v2_ssl"

  • "proxy_protocol_v2_ssl_cn"

redispatch_attempt_count

integer

Whether to use another backend server on each attempt.

The contract marks this field clearable, but int has no empty value, so the API cannot clear it. Setting it to null is refused: this API reads null as “field not provided” and would change nothing.

secret_key

string

Scaleway API secret key.

send_proxy_v2

boolean

Deprecated in favor of proxy_protocol field.

Deprecated by the Scaleway API contract.

Choices:

  • false

  • true

ssl_bridging

boolean

Defines whether to enable SSL bridging between the Load Balancer and backend servers.

The contract marks this field clearable, but bool has no empty value, so the API cannot clear it. Setting it to null is refused: this API reads null as “field not provided” and would change nothing.

Choices:

  • false

  • true

sticky_sessions

string / required

Defines whether to activate sticky sessions (binding a particular session to a particular backend server) and the method to use if so. None disables sticky sessions. Cookie-based uses an HTTP cookie to stick a session to a backend server. Table-based uses the source (client) IP address to stick a session to a backend server.

Choices:

  • "none"

  • "cookie"

  • "table"

string

Cookie name for cookie-based sticky sessions.

timeout_connect

float

Maximum allowed time for establishing a connection to a backend server. (in milliseconds)

timeout_queue

string

Maximum time for a request to be left pending in queue when `max_connections` is reached. (in seconds)

To clear this field, write `timeout_queue: “”`; omit the option to leave the current value untouched.

Setting it to null is refused: this API reads null as “field not provided” and would change nothing.

timeout_server

float

Maximum allowed time for a backend server to process a request. (in milliseconds)

timeout_tunnel

float

Maximum allowed tunnel inactivity time after Websocket is established (takes precedence over client and server timeout). (in milliseconds)

user_agent

string

Value of the User-Agent header sent to the API.

zone

string / required

The zone you want to target

Choices:

  • "fr-par-1"

  • "fr-par-2"

  • "nl-ams-1"

  • "nl-ams-2"

  • "nl-ams-3"

  • "pl-waw-1"

  • "pl-waw-2"

  • "pl-waw-3"

Attributes

Attribute

Support

Description

check_mode

Support: full

In check mode the module reads the resource and compares it, then reports what it would write without writing it.

diff_mode

Support: full

The module reports the fields that differ, read through the same projection the comparison uses.

Notes

Note

  • Every option can be set from its environment variable, respectively SCW_PROFILE, SCW_CONFIG_PATH, SCW_ACCESS_KEY, SCW_SECRET_KEY, SCW_API_URL, SCW_DEFAULT_ORGANIZATION_ID and SCW_DEFAULT_PROJECT_ID.

  • Module options take precedence over environment variables, which take precedence over the configuration file.

Examples

# The module reads the resource, compares, and writes only what
# differs: run it twice and the second run reports no change.
#
# Check mode compares without writing, and `--diff` shows what would
# change. A parameter you do not pass is a parameter the module does
# not touch.

- name: Update a Scaleway Load Balancer backend
  stephrobert.scaleway.lb_backend:
    zone: fr-par-1
    backend_id: 11111111-2222-3333-4444-555555555555
    forward_port: 80
    forward_port_algorithm: roundrobin
    forward_protocol: tcp
    name: my-backend
    sticky_sessions: none
  register: result
- name: Preview the change on a Scaleway Load Balancer backend without writing
  stephrobert.scaleway.lb_backend:
    zone: fr-par-1
    backend_id: 11111111-2222-3333-4444-555555555555
    forward_port: 80
    forward_port_algorithm: roundrobin
    forward_protocol: tcp
    name: my-backend
    sticky_sessions: none
  register: result
  check_mode: true
  diff: true

Return Values

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

Key

Description

resource

dictionary

Get the full details of a given backend, specified by its backend ID. The response contains the backend’s full configuration parameters including protocol, port and forwarding algorithm.

Returned: success

created_at

string

Date at which the backend was created. (RFC 3339 format)

Returned: when the API returns it

failover_host

string

Scaleway Object Storage bucket website to be served as failover if all backend servers are down, e.g. failover-website.s3-website.fr-par.scw.cloud.

Returned: when the API returns it

forward_port

integer

Port used by the backend when forwarding traffic to backend servers.

Returned: when the API returns it

forward_port_algorithm

string

Load balancing algorithm to use when determining which backend server to forward new traffic to.

Returned: when the API returns it

forward_protocol

string

Protocol used by the backend when forwarding traffic to backend servers.

Returned: when the API returns it

health_check

dictionary

Object defining the health check to be carried out by the backend when checking the status and health of backend servers.

Returned: when the API returns it

host

string

Host value to use when connecting to backend servers. When connecting to backend servers, use this value as the HTTP Host header or TLS SNI. This allows routing to specific services on the backend server that are configured to respond to particular hostnames.

Returned: when the API returns it

id

string

Backend ID.

Returned: when the API returns it

ignore_ssl_server_verify

boolean

Defines whether the server certificate verification should be ignored.

Returned: when the API returns it

lb

dictionary

Load Balancer the backend is attached to.

Returned: when the API returns it

max_connections

integer

Maximum number of connections allowed per backend server.

Returned: when the API returns it

max_retries

integer

Number of retries when a backend server connection failed.

Returned: when the API returns it

name

string

Name of the backend.

Returned: when the API returns it

on_marked_down_action

string

Action to take when a backend server is marked as down.

Returned: when the API returns it

pool

list / elements=string

List of IP addresses of backend servers attached to this backend.

Returned: when the API returns it

proxy_protocol

string

Protocol to use between the Load Balancer and backend servers. Allows the backend servers to be informed of the client’s real IP address. The PROXY protocol must be supported by the backend servers’ software.

Returned: when the API returns it

redispatch_attempt_count

integer

Whether to use another backend server on each attempt.

Returned: when the API returns it

send_proxy_v2

boolean

Deprecated in favor of proxy_protocol field.

Deprecated by the Scaleway API contract.

Returned: when the API returns it

ssl_bridging

boolean

Defines whether to enable SSL bridging between the Load Balancer and backend servers.

Returned: when the API returns it

sticky_sessions

string

Defines whether sticky sessions (binding a particular session to a particular backend server) are activated and the method to use if so. None disables sticky sessions. Cookie-based uses an HTTP cookie to stick a session to a backend server. Table-based uses the source (client) IP address to stick a session to a backend server.

Returned: when the API returns it

string

Cookie name for cookie-based sticky sessions.

Returned: when the API returns it

timeout_connect

float

Maximum allowed time for establishing a connection to a backend server. (in milliseconds)

Returned: when the API returns it

timeout_queue

string

Maximum time for a request to be left pending in queue when `max_connections` is reached. (in seconds)

Returned: when the API returns it

timeout_server

float

Maximum allowed time for a backend server to process a request. (in milliseconds)

Returned: when the API returns it

timeout_tunnel

float

Maximum allowed tunnel inactivity time after Websocket is established (takes precedence over client and server timeout). (in milliseconds)

Returned: when the API returns it

updated_at

string

Date at which the backend was updated. (RFC 3339 format)

Returned: when the API returns it

Authors

  • Stéphane Robert (@stephrobert)