Configure balancing rules via the API

Reviewed on 18 June 2024 • Published on 27 November 2023

You can configure balancing rules via the Scaleway API when you create a backend. You have access to the following parameters:

forward_port — Load Balancer with forward user sessions to this port. For example, you can use port 8080 on a backend, while your front-end port is 80.
forward_port_algorithm — A string value, specifying one of the following options:
- "roundrobin" — New sessions are balanced equally between the backend servers.
- "leastconn" — This mode will take into account the number of active sessions, established to each of the servers, and will forward new ones to the server, which has the least.
- "first" — The first server with available slots will be chosen.
server_ip- A list of IPv4 or IPv6 address of your servers to redirect the load to.

This page shows you an example of a curl command to create a backend and configure it with your desired balancing rules.

Before you start

To complete the actions presented below, you must have:

A Scaleway account
Owner status or IAM permissions allowing you to perform actions in the intended Organization

Setting up your environment

Before configuring the Load Balancer from the API, prepare your environment to facilitate usage of the API.

Ensure you have generated an API key, and that you have the secret key at hand.
Decide the Availability Zone for your Load Balancer.
Ensure that you have created a Load Balancer and noted its Load Balancer ID.

Set these elements as environment variables as follows:

export SCW_SECRET_KEY="<YOUR SECRET KEY>"
export SCW_DEFAULT_ZONE="<YOUR AVAILABILITY ZONE>"
export LB_ID="<YOUR LOAD BALANCER ID>"

Creating a backend

Use the following command to create a backend. Modify the parameters as you require. Ensure you replace <YOUR BACKEND SERVER IP> with the IP address of your backend server.

For help on possible parameter values, see the API documentation. For assistance with configuring backends generally, see our [dedicated documentation]](/network/load-balancer/reference-content/configuring-backends/).


curl -X POST \
  -H "X-Auth-Token: $SCW_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "forward_port": 42,
    "forward_port_algorithm": "roundrobin",
    "forward_protocol": "tcp",
    "health_check": {
        "check_delay": "3000",
        "check_max_retries": 42,
        "check_send_proxy": false,
        "check_timeout": "1000",
        "port": 42,
        "tcp_config": {},
        "transient_check_delay": "2.5s"
    },
    "name": "My New Backend",
    "server_ip": [
        "<YOUR BACKEND SERVER IP>"
    ],
    "sticky_sessions": "none"
  }' \
  "https://api.scaleway.com/lb/v1/zones/$SCW_DEFAULT_ZONE/lbs/$LB_ID/backends"

A JSON object is returned to you as a response, containing the ID of your newly created backend. You may wish to save this for further use:

export $BACKEND_ID="<ID of your backend>"

Deleting a backend

To delete the backend, run the following command:


curl -X DELETE \
  -H "X-Auth-Token: $SCW_SECRET_KEY" \
  "https://api.scaleway.com/lb/v1/zones/$SCW_DEFAULT_ZONE/backends/$BACKEND_ID"