Load balancer APIv1

Load Balancer is a highly available, fully-managed type of instances which allows to scale your applications and ensure their availability. It provides a special public IP address which is always reachable: even if we experience a hardware failure, we will reroute this address to a backup instance, which is pre-configured in advance. You can use this address for your frontends, and the incoming sessions will be balanced between your backend servers.

You can add as many servers to your backends as your needs require. This allows to scale your applications on demand, e. g. increase the capacity of a web-site for high-usage periods and decrease it when your customers are on vacation.

Load Balancer can monitor the availability of your backend servers, detect that one of them is not available anymore, and rebalance the load between the rest of the servers thus making your applications always available to users.

• Your Load Balancer external highly available IP address can only be IPv4. You can, however, use IPv6 between Load Balancer and backend servers.

Each Load Balancer is configured with one or several frontends. Each frontend listens to a configured port and has one or many backends, associated with it, to witch it forwards the flows.

Each Load Balancer is implemented with two instances: master and backup, which provide active/passive hight availability. These instances are synchronously preconfigured, so if the master fails, the backup is always ready to handle the traffic. There is no stateful connection synchronization between master and backup, so all long-living sessions must be reestablished in case of a switchover.

Master and backup are running on different hardware clusters to insure that they don't share physical resources and minimize the risk of a simultaneous failure.

IP address, which the frontend listens to, is a little bit more than just a simple IP address. It is a special highly available address, which is, by default, routed to the master Load Balancer instance. Should the master instances experience a failure, this address is automatically rerouted to the backup one. This action is taken automatically by the Load Balancer control subsystems, so it is transparent to the user.

Highly available IP is automatically created by default, when a Load Balancer is created. It can also be conserved when an LB is deleted and reused later. See CreateLb and DeleteLb API calls documentation for more details on how to do this.

Only one highly available IP per Load Balancer is currently supported. By this time it can only be IPv4, IPv6 support will come later.

Backend is a list of servers between which the flows of a given frontend are balanced. In addition to that backend has multiple parameters like session timeouts, protocol type, associated health-checks etc.

Backend servers can fail. One of the main features of the Load Balancer is to monitor their availability and, in case of a failure, redirect new flows between the active servers in the pool. Health check objects are used to detect backend servers failures. Each health check is an availability test specification, which defines how you determine that a backend server is "Up" or "Down". It can be a given number of missing ICMP echo replies or an unsuccessful HTTP request of a given URL.

For the full list of supported health check types see UpdateHealthCheck

Below you will find a step by step guide on how to create and delete your Load Balancer, add frontends and backends, and configure health checks.

In order to use Scaleway API you need to have curl installed. It is also a good idea to have jq, which will help you to read and parse JSON output. Make sure you have these two tools before you begin. Otherwise use your package manager to install them.

To call Scaleway API, you need an X-Auth-Token. If you don't have one yet, you can create it on the credentials page of your Scaleway account.

Using this token, get your organization ID:

export TOKEN="<Secret key of your token>"
export REGION="<choose your location (nl-ams/fr-par)>"

curl -H "X-Auth-Token: $TOKEN" https://account.scaleway.com/organizations | jq '.organizations[] | "orga_id: " + .id + " orga_name: " + .name'

export ORGANIZATION_ID="<your organization ID>"

You can also find your organization ID in new version of the Scaleway web console.

Customize the name, description, tags and set your organization ID

curl -X POST "https://api.scaleway.com/lb/v1/regions/$REGION/lbs" -H "accept: application/json" -H "X-Auth-Token: $TOKEN" -H "Content-Type: application/json" \
-d "{\"description\":\"YOUR DESCRIPTION\",\"name\":\"TEST\",\"organization_id\":\"$ORGANIZATION_ID\",\"tags\":[\"test\", \"step by step\"]}"

Copy the id field of the response to use at the next steps. For the sake of simplicity we will save the ID to a variable, which we will use in the following examples:

export LB_ID="<your load balancer id>"

To destroy a Load Balancer use the following call:

curl -s -H "X-Auth-Token: $TOKEN" -X DELETE "https://api.scaleway.com/lb/v1/regions/$REGION/lbs/$LB_ID" -H "Content-Type: application/json" -d "{\"release_ip\": false}"

It normally takes less than a second to provision a load balancer, but you always can check the status with the following call.

curl -s "https://api.scaleway.com/lb/v1/regions/$REGION/lbs/$LB_ID" -H "accept: application/json" -H "X-Auth-Token: $TOKEN" -H "Content-Type: application/json" | jq .

In the reply, you will find:

• instances: details of your load balancer cluster status. If both instances have the ready status, it means that the cluster if fully operational and highly available. If one of the instances fail, your traffic will be switched to the other.
• ip_address: This is the public highly available IP address. Use this address as the front-end of your highly availably services.

In order to create a backend you need to customize 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 — string value, specifying of of the following options:
  • "roundrobin" — new sessions are balanced equally between the backend servers;
  • "leastconn" — 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.
• server_ip : A list of IPv4 or IPv6 address of your Scaleway or Online.net servers to.

Other backend parameters are documented here: CreateBackend

curl -s -X POST "https://api.scaleway.com/lb/v1/regions/$REGION/lbs/$LB_ID/backends" -H "accept: application/json" -H "X-Auth-Token: $TOKEN" -H "Content-Type: application/json" \
-d "{\"forward_port\":80,\"forward_port_algorithm\":\"roundrobin\",\"forward_protocol\":\"tcp\",\"health_check\":{\"check_delay\":2000,\"check_max_retries\":3,\"check_timeout\":1000,\"port\":80,\"tcp_config\":{}},\"name\":\"main backend\",\"send_proxy_v2\":false,\"server_ip\":[\"<REPLACE-BY-IP-OF-YOUR-SERVER1>\", \"<REPLACE-BY-IP-OF-YOUR-SERVER2>\"]} | jq ."

Save the id field of the reply.

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

If you want to delete a backend, this is how it can be done.

curl -H "X-Auth-Token: $TOKEN" -X DELETE "https://api.scaleway.com/lb/v1/regions/$REGION/lbs/$LB_ID/backends/$BACKEND_ID"

Creating a frontend is straight-forward. You need to know the IDs of a load balancer and an existing frontend, then specify the inbound_port, on which the frontend will listen for incoming connections. You can also customize the protocol and client timeout. For more details on these options see the CreateFrontend call documentation.

Main fields:

• backend_id — link your frontend to the backend where the traffic will be redirect
• inbound_port — accept connections from this port

curl -X POST "https://api.scaleway.com/lb/v1/regions/$REGION/lbs/$LB_ID/frontends" -H "accept: application/json" -H "X-Auth-Token: $TOKEN" -H "Content-Type: application/json" \
-d "{\"backend_id\":\"$BACKEND_ID\",\"inbound_port\":80,\"inbound_protocol\":\"tcp\",\"name\":\"main frontend\",\"timeout_client\":5000}"

Save the id field of the reply.

export $FRONTEND_ID="<ID of your frontend>"

You can delete a frontend using the following API call

curl -H "X-Auth-Token: $TOKEN" -X DELETE "https://api.scaleway.com/lb/v1/regions/$REGION/lbs/$LB_ID/frontends/$FRONTEND_ID"

Choose in which location you want deploy your load balancer