NavigationContentFooter

Load Balancer API

Introduction

Load Balancers are highly available and fully managed Instances that facilitate the distribution of incoming traffic across multiple servers. Load Balancers allow you to scale your applications while ensuring their continuous availability, even in the event of heavy traffic. They are commonly used to improve the performance and reliability of websites, applications, databases and other services.

A Scaleway Load Balancer has a public IP address which is always reachable: in the event of hardware failure it is rerouted to a backup Instance. The Load Balancer receives incoming traffic at this IP address, monitors the health and availability of its backend servers via health checks, and balances traffic load between all healthy and available backend servers.

You can create as many frontends and backends for each Load Balancer as you wish, with frontends configured to listen on defined ports and forward traffic to specific backends. You can also add certificates to frontends to enable secure, encrypted connections and facilitate SSL bridging or offloading. Backends can be configured to use your protocol of choice (TCP or HTTP) to connect to their backend servers. Additional features such as Access Control Lists (ACLs) and routes allow you to further configure the flow of traffic through your Scaleway Load Balancer.

Concepts

Refer to our dedicated concepts page to find definitions of all Load Balancer-related terminology.

Quickstart

Requirements: To perform the following steps, you must first ensure that:

  • You have a Scaleway account
  • You have created an API key and that the API key has sufficient IAM permissions to perform the actions described on this page
  • You have installed curl
  1. Configure your environment variables.

    Note

    This is an optional step that seeks to simplify your usage of the Load Balancer API.

    export SCW_SECRET_KEY="<API secret key>"
    export SCW_DEFAULT_ZONE="<Scaleway default Availability Zone>"
    export SCW_PROJECT_ID="<Scaleway Project ID>"
  2. Create a Load Balancer: run the following command to create a Load Balancer. You can customize the details in the payload (name, description, tags, etc) as you wish.

    curl -X POST \
    -H "X-Auth-Token: $SCW_SECRET_KEY" \
    -H "Content-Type: application/json" \
    "https://api.scaleway.com/lb/v1/zones/$SCW_DEFAULT_ZONE/lbs" \
    -d '{
    "name":"API Test LB",
    "description": "my new Load Balancer",
    "project_id":"'"$SCW_PROJECT_ID"'",
    "tags":["test","another tag"]
    }'
  3. Get a list of your Load Balancers: run the following command to get a list of all the Load Balancers in your account, with their details:

    curl -X GET \
    -H "Content-Type: application/json" \
    -H "X-Auth-Token: $SCW_SECRET_KEY" \
    "https://api.scaleway.com/lb/v1/zones/$SCW_DEFAULT_ZONE/lbs"
  4. Create a backend for your Load Balancer: run the following command to create a backend for a specified Load Balancer. Ensure that you replace <LOAD-BALANCER-ID> in the URL with the ID of the Load Balancer you want to create a backend for. You can customize the configuration of the backend according to your needs: use the information below to adjust the payload as necessary.

    curl -X POST \
    -H "Content-Type: application/json" \
    -H "X-Auth-Token: $SCW_SECRET_KEY" \
    "https://api.scaleway.com/lb/v1/zones/$SCW_DEFAULT_ZONE/lbs/<LOAD-BALANCER-ID>/backends" \
    -d '{
    "name":"main backend",
    "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":{}
    },
    "server_ip": ["184.224.68.187", "139.7.243.56"]
    }'

    Payload values:

    • name (string): A name for the backend, e.g. "main backend"
    • forward_port (number): The port to use when connecting to a backend server to forward a user session, e.g. 8080
    • forward_port_algorithm (string): The forwarding algorithm to use when determining which backend server to forward a user session to. Must be one of the following:
      • "roundrobin": New sessions are forwarded to each backend server in turn.
      • "leastconn": New sessions are forwarded to the backend server with the fewest current active sessions.
      • "first": New sessions are forwarded to the first backend server found .
    • forward_protocol (string): The protocol to use when connecting to a backend server to forward a user session. Must be one of the following:
      • "tcp": Transmission Control Protocol
      • "http": Hypertext Transfer Protocol
    • health_check (object): The definition of the health check to use to check that backend servers are available and able to receive forwarded user sessions. Must contain the following parameters:
      • "check_delay": The time between two consecutive health checks (in milliseconds)
      • "check_max_retries": The number of consecutive unsuccessful health checks, after which the server will be considered dead
      • "check_timeout:" The maximum time a backend server has to reply to the health check (in milliseconds)
      • "port": The port to use when connecting to a backend server for a health check
      • "<type>_config": The health check type to use. This parameter name must be one of "mysqlconfig", "ldap_config", "redis_config", "tcp_config", "pgsql_config", "http_config" or "https_config". The parameter value may be an empty object, or an object containing further parameters, depending on the health check configuration type selected. See the full documentation below on health checks for further details.
        • Example of valid health_check value {"check_delay":2000,"check_max_retries":3,"check_timeout":1000,"port":80,"tcp_config":{}}
    • server_ip (array): The list of IPv4 or IPv6 addresses of the backend servers to forward user sessions to, e.g. ["184.224.68.187", "139.7.243.56"]
  5. Create a frontend for your Load Balancer: run the following command to create a frontend for a specified Load Balancer. Ensure that you replace <LOAD-BALANCER-ID> in the URL with the ID of the Load Balancer you want to create a frontend for. You can customize the configuration according to your needs: use the information below to adjust the payload as necessary.

    curl -X POST \
    -H "Content-Type: application/json" \
    -H "X-Auth-Token: $SCW_SECRET_KEY" \
    "https://api.scaleway.com/lb/v1/zones/$SCW_DEFAULT_ZONE/lbs/<LOAD-BALANCER-ID>/frontends" \
    -d '{
    "name": "main frontend",
    "backend_id": "6920166d-8665-426e-85a6-f137e7e71e7f",
    "inbound_port": 80,
    "timeout_client": 5000
    }'

    Payload values:

    • name (string): A name for the frontend, e.g. "main frontend"
    • backend_id (number): The ID of the backend to attach to the frontend, e.g. 6920166d-8665-426e-85a6-f137e7e71e7f
    • inbound_port (number): The port that the frontend should listen on for incoming connections, e.g. 80
    • timeout_client (number): The maximum amount of inactivity time, in milliseconds, the frontend should allow before closing the connection, e.g. 5000
  6. Delete your Load Balancer: run the following command to delete a Load Balancer. Ensure that you replace <LOAD-BALANCER-ID> in the URL with the ID of the Load Balancer you want to delete. You can customize the payload to specify whether you want to release (delete) the Flexible IP associated with the Load Balancer or not.

    curl -X DELETE \
    -H "Content-Type: application/json" \
    -H "X-Auth-Token: $SCW_SECRET_KEY" \
    "https://api.scaleway.com/lb/v1/zones/$SCW_DEFAULT_ZONE/lbs/<LOAD-BALANCER-ID>" \
    -d '{
    "release_ip": false
    }'
Requirements
  • You have a Scaleway account
  • You have created an API key and that the API key has sufficient IAM permissions to perform the actions described on this page
  • You have installed curl

Technical information

Availability Zones

Load Balancers can be deployed in the following Availability Zones:

NameAPI ID
Parisfr-par-1 fr-par-2
Amsterdamnl-ams-1 nl-ams-2 nl-ams-3
Warsawpl-waw-1 pl-waw-2 pl-waw-3

The Scaleway Load Balancer API is a zoned API, meaning that each call must specify in its path parameters the Availability Zone for the resources concerned by the call.

Going further

For more help using Scaleway Load Balancers, check out the following resources:

  • Our main documentation
  • The #load-balancer channel on our Slack Community
  • Our support ticketing system.

Load Balancer

The main Load Balancer object. A Scaleway Load Balancer is a representation of a fully-managed, highly-available Instance configured to direct traffic across multiple servers. Use the Load Balancer endpoint to create, list, manage, update, and delete Load Balancers.

GET
/lb/v1/zones/{zone}/lbs
POST
/lb/v1/zones/{zone}/lbs
GET
/lb/v1/zones/{zone}/lbs/{lb_id}
PUT
/lb/v1/zones/{zone}/lbs/{lb_id}
DELETE
/lb/v1/zones/{zone}/lbs/{lb_id}
POST
/lb/v1/zones/{zone}/lbs/{lb_id}/migrate

Frontends

The Load Balancer frontend object. It listens on a configured port and forward requests to one or several backends. You can create multiple frontends for any given Load Balancer, each listening on a different port, and choose to add certificates to them if you wish. Use the frontends endpoint to create, list, manage and delete frontends.

GET
/lb/v1/zones/{zone}/frontends/{frontend_id}
PUT
/lb/v1/zones/{zone}/frontends/{frontend_id}
DELETE
/lb/v1/zones/{zone}/frontends/{frontend_id}
GET
/lb/v1/zones/{zone}/lbs/{lb_id}/frontends
POST
/lb/v1/zones/{zone}/lbs/{lb_id}/frontends

Backends

The Load Balancer backend object. It represents a set of backend servers that the frontend forwards requests to using the specified configuration (port, protocol, proxy protocol etc). You can create multiple backends for each of your Load Balancers. Use the backends endpoint to create backends, list, manage and update them and their healthchecks / backend servers, and delete them as required

GET
/lb/v1/zones/{zone}/backends/{backend_id}
PUT
/lb/v1/zones/{zone}/backends/{backend_id}
DELETE
/lb/v1/zones/{zone}/backends/{backend_id}
PUT
/lb/v1/zones/{zone}/backends/{backend_id}/healthcheck
POST
/lb/v1/zones/{zone}/backends/{backend_id}/servers
PUT
/lb/v1/zones/{zone}/backends/{backend_id}/servers
DELETE
/lb/v1/zones/{zone}/backends/{backend_id}/servers
GET
/lb/v1/zones/{zone}/lbs/{lb_id}/backend-stats
GET
/lb/v1/zones/{zone}/lbs/{lb_id}/backends
POST
/lb/v1/zones/{zone}/lbs/{lb_id}/backends

Route

The Load Balancer route object. It represents a configuration on a particular frontend to direct traffic to a particular backend if certain conditions are fulfilled. Conditions must be based on SNI for direction to TCP backends, or HTTP host headers for direction to HTTP backends. Use the routes endpoint to create, edit, list, get and delete your routes.

GET
/lb/v1/zones/{zone}/routes
POST
/lb/v1/zones/{zone}/routes
GET
/lb/v1/zones/{zone}/routes/{route_id}
PUT
/lb/v1/zones/{zone}/routes/{route_id}
DELETE
/lb/v1/zones/{zone}/routes/{route_id}

IP addresses

The Load Balancer IP address object. It represents a flexible IP address which can be attached to a Load Balancer. Use this endpoint to create, list, get, update and delete your Load Balancer IP addresses.

GET
/lb/v1/zones/{zone}/ips
POST
/lb/v1/zones/{zone}/ips
GET
/lb/v1/zones/{zone}/ips/{ip_id}
PATCH
/lb/v1/zones/{zone}/ips/{ip_id}
DELETE
/lb/v1/zones/{zone}/ips/{ip_id}

Stats

Load balancer statistics (deprecated).

GET
/lb/v1/zones/{zone}/lbs/{lb_id}/stats

ACLs

The Load Balancer ACL object. It represents an Access Control List rule, which tells a given frontend to allow or deny incoming traffic based on the traffic's source IP address and/or HTTP path and header. Use this endpoint to create, list, get, update and delete ACLs.

GET
/lb/v1/zones/{zone}/acls/{acl_id}
PUT
/lb/v1/zones/{zone}/acls/{acl_id}
DELETE
/lb/v1/zones/{zone}/acls/{acl_id}
GET
/lb/v1/zones/{zone}/frontends/{frontend_id}/acls
POST
/lb/v1/zones/{zone}/frontends/{frontend_id}/acls
PUT
/lb/v1/zones/{zone}/frontends/{frontend_id}/acls

Certificate

The Load Balancer certificate object. It represents an SSL/TLS certificate for your Load Balancer which can be used by a frontend to establish secure, encrypted connections for incoming traffic. Use this endpoint to create Let's Encrypt certificates or import custom certificates for your Load Balancer, and update, list, get and delete them as required.

GET
/lb/v1/zones/{zone}/certificates/{certificate_id}
PUT
/lb/v1/zones/{zone}/certificates/{certificate_id}
DELETE
/lb/v1/zones/{zone}/certificates/{certificate_id}
GET
/lb/v1/zones/{zone}/lbs/{lb_id}/certificates
POST
/lb/v1/zones/{zone}/lbs/{lb_id}/certificates

Load Balancer Types

The Load Balancer offer type object. It represents the different commercial types of Load Balancer offered by Scaleway, each with different specifications and pricing. Use this endpoint to list all Load Balancer offer types.

GET
/lb/v1/zones/{zone}/lb-types

Alert Subscribers

The Alert Subscribers object. It represents a subscription to alerts about Scaleway incidents impacting a given Load Balancer. Use this endpoint to create subscribers (email addresses or webhooks), subscribe / unsubscribe them to alerts for a particular Load Balancer, and update, list, get and delete subscribers.

POST
/lb/v1/zones/{zone}/lb/{lb_id}/subscribe
DELETE
/lb/v1/zones/{zone}/lb/{lb_id}/unsubscribe
DELETE
/lb/v1/zones/{zone}/lb/subscription/{subscriber_id}
GET
/lb/v1/zones/{zone}/subscribers
POST
/lb/v1/zones/{zone}/subscribers
GET
/lb/v1/zones/{zone}/subscribers/{subscriber_id}
PUT
/lb/v1/zones/{zone}/subscribers/{subscriber_id}

Private Networks

The Private Network object. It represents Scaleway Private Networks which can be attached to/detached from a Load Balancer. Use this endpoint to list the Private Networks attached to a Load Balancer, and to attach/detach a Load Balancer to/from a Private Network. To create new Private Networks, use the dedicated Private Networks API.

GET
/lb/v1/zones/{zone}/lbs/{lb_id}/private-networks
POST
/lb/v1/zones/{zone}/lbs/{lb_id}/private-networks/{private_network_id}/attach
POST
/lb/v1/zones/{zone}/lbs/{lb_id}/private-networks/{private_network_id}/detach
API DocsScaleway consoleDedibox consoleScaleway LearningScaleway.comPricingBlogCareers
© 2023-2024 – Scaleway