Load balancer APIv1

Download OpenAPI

Introduction

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, for example 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 unavailable and balances the load between the rest of the servers thus making your applications always available to users.

Technical Limitations

  • 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.

Master and Backup Load Balancers

Each Load Balancer is implemented with two instances: master and backup, which provide active/passive high 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 ensure that they don't share physical resources and minimize the risk of a simultaneous failure.

IP address, which the frontend listens to, is a 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 using the API and the Command Line Interface (CLI).

In order to set up your environment, you can follow the quickstart steps. For this tutorial, it can be interesting to have jq in your terminal.

For a reminder, the Scaleway Load Balancer is a zoned product.

You can also find your project ID in the Scaleway web console.

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

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

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/zones/$ZONE/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/zones/$ZONE/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 available 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 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.
    • "first" the first server with available slots will be chosen
  • server_ip : A list of IPv4 or IPv6 address of your servers to.

Other backend parameters are documented here: CreateBackend

curl -s -X POST "https://api.scaleway.com/lb/v1/zones/$ZONE/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/zones/$ZONE/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 redirected
  • inbound_port accept connections from this port
curl -X POST "https://api.scaleway.com/lb/v1/zones/$ZONE/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,\"name\":\"main frontend\",\"timeout_client\":5000}" | jq .

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/zones/$ZONE/lbs/$LB_ID/frontends/$FRONTEND_ID"

In order to set up your Scaleway CLI, you can follow the tutorial .

Once you have set it up, you are good to go.

In this step, you can customize the properties of the Load Balancer you are creating (name, type, description, zone, etc.) You can find your project ID in the Scaleway web console.

scw lb lb create name=test-cli type=LB-S

It is important to keep track of your Load Balancer ID for further steps.

As it takes up time to set up a Load Balancer, you will see your Load Balancer in a Pending status upon creation.

If you would like to retrieve your Load Balancer specifications, you can by using the CLI:

scw lb lb get <lb-id>

If you would like to delete the Load Balancer:

scw lb lb delete <lb-id>

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 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.
    • "first" the first server with available slots will be chosen
  • server_ip : A list of IPv4 or IPv6 address of your servers.

Other backend parameters are documented here: CreateBackend

You can create a new backend with the command:

scw lb backend create forward-protocol=tcp forward-port=80 lb-id=<lb-id>> forward-port-algorithm=roundrobin health-check.check-delay=2000 health-check.check-max-retries=3 health-check.check-timeout=1000 health-check.port=80

If you would like to delete the backend:

scw lb backend delete <backend-id>

You can create a frontend for your Load Balancer linked to the backend that you just created:

scw lb frontend create backend-id=<backend-id> lb-id=<lb-id> inbound-port=80

If you want to, you can delete your frontend with the command:

scw lb frontend delete <frontend-id>

Choose in which Availability Zone you want to deploy your Load Balancer

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

Main load balancer object.

List all load balancer offer type

GET
/lb/v1/regions/{region}/lb-types
Path Parameters

region
required string
The region you want to target. Possible values are fr-par, nl-ams and pl-waw.
Query Parameters

page
required number
Page number. The default value is 1.

page_size
number
The number of items to return. The default value is 20.
200 Response

lb_types
array
name
string

stock_status
string
Possible values are unknown, low_stock, out_of_stock and available. The default value is unknown.

description
string

region
deprecated string

zone
string

total_count
number
Response Example
{
"lb_types": [
{
"name": "string",
"stock_status": "unknown",
"description": "string",
"region": "string",
"zone": "string"
}
],
"total_count": 42
}
GET
/lb/v1/regions/{region}/lbs
Path Parameters

region
required string
The region you want to target. Possible values are fr-par, nl-ams and pl-waw.
Query Parameters

name
nullable string
Use this to search by name.

order_by
string
Possible values are created_at_asc, created_at_desc, name_asc and name_desc. The default value is created_at_asc.

page_size
number
Page size. The default value is 20.

page
number
Page number. The default value is 1.

organization_id
nullable string
Filter LBs by organization ID.

project_id
nullable string
Filter LBs by project ID.
200 Response

lbs
array
id
string

name
string

description
string

status
string
Possible values are unknown, ready, pending, stopped, error, locked and migrating. The default value is unknown.

instances
array
id
string

status
string
Possible values are unknown, ready, pending, stopped, error, locked and migrating. The default value is unknown.

ip_address
string

created_at
string

updated_at
string

region
deprecated string

zone
string

organization_id
string

ip
array
id
string

ip_address
string

organization_id
string

lb_id
nullable string

reverse
string

project_id
string

region
deprecated string

zone
string

tags
array

frontend_count
number

backend_count
number

type
string

subscriber
object
id
string
Subscriber ID.

name
string
Subscriber name.

email_config
object
Email address of subscriber. Only one of email_config and webhook_config may be set.
email
required string
Email who receive alert.

webhook_config
object
WebHook URI of subscriber. Only one of email_config and webhook_config may be set.
uri
required string
URI who receive POST request.

ssl_compatibility_level
string
Possible values are ssl_compatibility_level_unknown, ssl_compatibility_level_intermediate, ssl_compatibility_level_modern and ssl_compatibility_level_old. The default value is ssl_compatibility_level_unknown.

project_id
string

created_at
string

updated_at
string

private_network_count
number

route_count
number

region
deprecated string

zone
string

total_count
number
Response Example
{
"lbs": [
{
"id": "string",
"name": "string",
"description": "string",
"status": "unknown",
"instances": [
{
"id": "string",
"status": "unknown",
"ip_address": "string",
"created_at": "string",
"updated_at": "string",
"region": "string",
"zone": "string"
}
],
"organization_id": "string",
"ip": [
{
"id": "string",
"ip_address": "string",
"organization_id": "string",
"lb_id": "string",
"reverse": "string",
"project_id": "string",
"region": "string",
"zone": "string"
}
],
"tags": [
"string"
],
"frontend_count": 42,
"backend_count": 42,
"type": "string",
"subscriber": {
"id": "string",
"name": "string",
"email_config": {
"email": "string"
},
"webhook_config": {
"uri": "string"
}
},
"ssl_compatibility_level": "ssl_compatibility_level_unknown",
"project_id": "string",
"created_at": "string",
"updated_at": "string",
"private_network_count": 42,
"route_count": 42,
"region": "string",
"zone": "string"
}
],
"total_count": 42
}
POST
/lb/v1/regions/{region}/lbs
Path Parameters

region
required string
The region you want to target. Possible values are fr-par, nl-ams and pl-waw.
Body

organization_id
deprecated string
Owner of resources. Only one of organization_id and project_id may be set.

project_id
string
Assign the resource to a project ID. Only one of organization_id and project_id may be set.

name
required string
Resource names.

description
string
Resource description.

ip_id
nullable string
Just like for compute instances, when you destroy a load balancer, you can keep its highly available IP address and reuse it for another load balancer later.

tags
array
List of keyword.

type
string
Load balancer offer type.

ssl_compatibility_level
string
Enforces minimal SSL version (in SSL/TLS offloading context). - `intermediate` General-purpose servers with a variety of clients, recommended for almost all systems (Supports Firefox 27, Android 4.4.2, Chrome 31, Edge, IE 11 on Windows 7, Java 8u31, OpenSSL 1.0.1, Opera 20, and Safari 9). - `modern` Services with clients that support TLS 1.3 and don't need backward compatibility (Firefox 63, Android 10.0, Chrome 70, Edge 75, Java 11, OpenSSL 1.1.1, Opera 57, and Safari 12.1). - `old` Compatible with a number of very old clients, and should be used only as a last resort (Firefox 1, Android 2.3, Chrome 1, Edge 12, IE8 on Windows XP, Java 6, OpenSSL 0.9.8, Opera 5, and Safari 1). . Possible values are ssl_compatibility_level_unknown, ssl_compatibility_level_intermediate, ssl_compatibility_level_modern and ssl_compatibility_level_old. The default value is ssl_compatibility_level_unknown.
Request Example
{
"organization_id": "string",
"project_id": "string",
"name": "string",
"description": "string",
"ip_id": "string",
"tags": [
"string"
],
"type": "string",
"ssl_compatibility_level": "ssl_compatibility_level_unknown"
}
200 Response

id
string

name
string

description
string

status
string
Possible values are unknown, ready, pending, stopped, error, locked and migrating. The default value is unknown.

instances
array
id
string

status
string
Possible values are unknown, ready, pending, stopped, error, locked and migrating. The default value is unknown.

ip_address
string

created_at
string

updated_at
string

region
deprecated string

zone
string

organization_id
string

ip
array
id
string

ip_address
string

organization_id
string

lb_id
nullable string

reverse
string

project_id
string

region
deprecated string

zone
string

tags
array

frontend_count
number

backend_count
number

type
string

subscriber
object
id
string
Subscriber ID.

name
string
Subscriber name.

email_config
object
Email address of subscriber. Only one of email_config and webhook_config may be set.
email
required string
Email who receive alert.

webhook_config
object
WebHook URI of subscriber. Only one of email_config and webhook_config may be set.
uri
required string
URI who receive POST request.

ssl_compatibility_level
string
Possible values are ssl_compatibility_level_unknown, ssl_compatibility_level_intermediate, ssl_compatibility_level_modern and ssl_compatibility_level_old. The default value is ssl_compatibility_level_unknown.

project_id
string

created_at
string

updated_at
string

private_network_count
number

route_count
number

region
deprecated string

zone
string
Response Example
{
"id": "string",
"name": "string",
"description": "string",
"status": "unknown",
"instances": [
{
"id": "string",
"status": "unknown",
"ip_address": "string",
"created_at": "string",
"updated_at": "string",
"region": "string",
"zone": "string"
}
],
"organization_id": "string",
"ip": [
{
"id": "string",
"ip_address": "string",
"organization_id": "string",
"lb_id": "string",
"reverse": "string",
"project_id": "string",
"region": "string",
"zone": "string"
}
],
"tags": [
"string"
],
"frontend_count": 42,
"backend_count": 42,
"type": "string",
"subscriber": {
"id": "string",
"name": "string",
"email_config": {
"email": "string"
},
"webhook_config": {
"uri": "string"
}
},
"ssl_compatibility_level": "ssl_compatibility_level_unknown",
"project_id": "string",
"created_at": "string",
"updated_at": "string",
"private_network_count": 42,
"route_count": 42,
"region": "string",
"zone": "string"
}
GET
/lb/v1/regions/{region}/lbs/{lb_id}
Path Parameters

region
required string
The region you want to target. Possible values are fr-par, nl-ams and pl-waw.

lb_id
required string
Load balancer ID.
200 Response

id
string

name
string

description
string

status
string
Possible values are unknown, ready, pending, stopped, error, locked and migrating. The default value is unknown.

instances
array
id
string

status
string
Possible values are unknown, ready, pending, stopped, error, locked and migrating. The default value is unknown.

ip_address
string

created_at
string

updated_at
string

region
deprecated string

zone
string

organization_id
string

ip
array
id
string

ip_address
string

organization_id
string

lb_id
nullable string

reverse
string

project_id
string

region
deprecated string

zone
string

tags
array

frontend_count
number

backend_count
number

type
string

subscriber
object
id
string
Subscriber ID.

name
string
Subscriber name.

email_config
object
Email address of subscriber. Only one of email_config and webhook_config may be set.
email
required string
Email who receive alert.

webhook_config
object
WebHook URI of subscriber. Only one of email_config and webhook_config may be set.
uri
required string
URI who receive POST request.

ssl_compatibility_level
string
Possible values are ssl_compatibility_level_unknown, ssl_compatibility_level_intermediate, ssl_compatibility_level_modern and ssl_compatibility_level_old. The default value is ssl_compatibility_level_unknown.

project_id
string

created_at
string

updated_at
string

private_network_count
number

route_count
number

region
deprecated string

zone
string
Response Example
{
"id": "string",
"name": "string",
"description": "string",
"status": "unknown",
"instances": [
{
"id": "string",
"status": "unknown",
"ip_address": "string",
"created_at": "string",
"updated_at": "string",
"region": "string",
"zone": "string"
}
],
"organization_id": "string",
"ip": [
{
"id": "string",
"ip_address": "string",
"organization_id": "string",
"lb_id": "string",
"reverse": "string",
"project_id": "string",
"region": "string",
"zone": "string"
}
],
"tags": [
"string"
],
"frontend_count": 42,
"backend_count": 42,
"type": "string",
"subscriber": {
"id": "string",
"name": "string",
"email_config": {
"email": "string"
},
"webhook_config": {
"uri": "string"
}
},
"ssl_compatibility_level": "ssl_compatibility_level_unknown",
"project_id": "string",
"created_at": "string",
"updated_at": "string",
"private_network_count": 42,
"route_count": 42,
"region": "string",
"zone": "string"
}
PUT
/lb/v1/regions/{region}/lbs/{lb_id}
Path Parameters

region
required string
The region you want to target. Possible values are fr-par, nl-ams and pl-waw.

lb_id
required string
Load balancer ID.
Body

name
required string
Resource name.

description
required string
Resource description.

tags
array
List of keywords.

ssl_compatibility_level
string
Enforces minimal SSL version (in SSL/TLS offloading context). - `intermediate` General-purpose servers with a variety of clients, recommended for almost all systems (Supports Firefox 27, Android 4.4.2, Chrome 31, Edge, IE 11 on Windows 7, Java 8u31, OpenSSL 1.0.1, Opera 20, and Safari 9). - `modern` Services with clients that support TLS 1.3 and don't need backward compatibility (Firefox 63, Android 10.0, Chrome 70, Edge 75, Java 11, OpenSSL 1.1.1, Opera 57, and Safari 12.1). - `old` Compatible with a number of very old clients, and should be used only as a last resort (Firefox 1, Android 2.3, Chrome 1, Edge 12, IE8 on Windows XP, Java 6, OpenSSL 0.9.8, Opera 5, and Safari 1). . Possible values are ssl_compatibility_level_unknown, ssl_compatibility_level_intermediate, ssl_compatibility_level_modern and ssl_compatibility_level_old. The default value is ssl_compatibility_level_unknown.
Request Example
{
"name": "string",
"description": "string",
"tags": [
"string"
],
"ssl_compatibility_level": "ssl_compatibility_level_unknown"
}
200 Response

id
string

name
string

description
string

status
string
Possible values are unknown, ready, pending, stopped, error, locked and migrating. The default value is unknown.

instances
array
id
string

status
string
Possible values are unknown, ready, pending, stopped, error, locked and migrating. The default value is unknown.

ip_address
string

created_at
string

updated_at
string

region
deprecated string

zone
string

organization_id
string

ip
array
id
string

ip_address
string

organization_id
string

lb_id
nullable string

reverse
string

project_id
string

region
deprecated string

zone
string

tags
array

frontend_count
number

backend_count
number

type
string

subscriber
object
id
string
Subscriber ID.

name
string
Subscriber name.

email_config
object
Email address of subscriber. Only one of email_config and webhook_config may be set.
email
required string
Email who receive alert.

webhook_config
object
WebHook URI of subscriber. Only one of email_config and webhook_config may be set.
uri
required string
URI who receive POST request.

ssl_compatibility_level
string
Possible values are ssl_compatibility_level_unknown, ssl_compatibility_level_intermediate, ssl_compatibility_level_modern and ssl_compatibility_level_old. The default value is ssl_compatibility_level_unknown.

project_id
string

created_at
string

updated_at
string

private_network_count
number

route_count
number

region
deprecated string

zone
string
Response Example
{
"id": "string",
"name": "string",
"description": "string",
"status": "unknown",
"instances": [
{
"id": "string",
"status": "unknown",
"ip_address": "string",
"created_at": "string",
"updated_at": "string",
"region": "string",
"zone": "string"
}
],
"organization_id": "string",
"ip": [
{
"id": "string",
"ip_address": "string",
"organization_id": "string",
"lb_id": "string",
"reverse": "string",
"project_id": "string",
"region": "string",
"zone": "string"
}
],
"tags": [
"string"
],
"frontend_count": 42,
"backend_count": 42,
"type": "string",
"subscriber": {
"id": "string",
"name": "string",
"email_config": {
"email": "string"
},
"webhook_config": {
"uri": "string"
}
},
"ssl_compatibility_level": "ssl_compatibility_level_unknown",
"project_id": "string",
"created_at": "string",
"updated_at": "string",
"private_network_count": 42,
"route_count": 42,
"region": "string",
"zone": "string"
}
DELETE
/lb/v1/regions/{region}/lbs/{lb_id}
Path Parameters

region
required string
The region you want to target. Possible values are fr-par, nl-ams and pl-waw.

lb_id
required string
Load balancer ID.
Query Parameters

release_ip
boolean
Set true if you don't want to keep this IP address.
204 Response

Empty response
POST
/lb/v1/regions/{region}/lbs/{lb_id}/migrate
Path Parameters

region
required string
The region you want to target. Possible values are fr-par, nl-ams and pl-waw.

lb_id
required string
Load balancer ID.
Body

type
required string
Load balancer type (check /lb-types to list all type).
Request Example
{
"type": "string"
}
200 Response

id
string

name
string

description
string

status
string
Possible values are unknown, ready, pending, stopped, error, locked and migrating. The default value is unknown.

instances
array
id
string

status
string
Possible values are unknown, ready, pending, stopped, error, locked and migrating. The default value is unknown.

ip_address
string

created_at
string

updated_at
string

region
deprecated string

zone
string

organization_id
string

ip
array
id
string

ip_address
string

organization_id
string

lb_id
nullable string

reverse
string

project_id
string

region
deprecated string

zone
string

tags
array

frontend_count
number

backend_count
number

type
string

subscriber
object
id
string
Subscriber ID.

name
string
Subscriber name.

email_config
object
Email address of subscriber. Only one of email_config and webhook_config may be set.
email
required string
Email who receive alert.

webhook_config
object
WebHook URI of subscriber. Only one of email_config and webhook_config may be set.
uri
required string
URI who receive POST request.

ssl_compatibility_level
string
Possible values are ssl_compatibility_level_unknown, ssl_compatibility_level_intermediate, ssl_compatibility_level_modern and ssl_compatibility_level_old. The default value is ssl_compatibility_level_unknown.

project_id
string

created_at
string

updated_at
string

private_network_count
number

route_count
number

region
deprecated string

zone
string
Response Example
{
"id": "string",
"name": "string",
"description": "string",
"status": "unknown",
"instances": [
{
"id": "string",
"status": "unknown",
"ip_address": "string",
"created_at": "string",
"updated_at": "string",
"region": "string",
"zone": "string"
}
],
"organization_id": "string",
"ip": [
{
"id": "string",
"ip_address": "string",
"organization_id": "string",
"lb_id": "string",
"reverse": "string",
"project_id": "string",
"region": "string",
"zone": "string"
}
],
"tags": [
"string"
],
"frontend_count": 42,
"backend_count": 42,
"type": "string",
"subscriber": {
"id": "string",
"name": "string",
"email_config": {
"email": "string"
},
"webhook_config": {
"uri": "string"
}
},
"ssl_compatibility_level": "ssl_compatibility_level_unknown",
"project_id": "string",
"created_at": "string",
"updated_at": "string",
"private_network_count": 42,
"route_count": 42,
"region": "string",
"zone": "string"
}

Load balancer frontend objects.

GET
/lb/v1/regions/{region}/frontends/{frontend_id}
Path Parameters

region
required string
The region you want to target. Possible values are fr-par, nl-ams and pl-waw.

frontend_id
required string
Frontend ID.
200 Response

id
string

name
string

inbound_port
number

backend
object
id
string

name
string

forward_protocol
string
Possible values are tcp and http. The default value is tcp.

forward_port
number

forward_port_algorithm
string
Possible values are roundrobin, leastconn and first. The default value is roundrobin.

sticky_sessions
string
Possible values are none, cookie and table. The default value is none.


health_check
object
mysql_config
object
The check requires MySQL >=3.22, for older versions, use TCP check. Only one of mysql_config, ldap_config, redis_config, tcp_config, pgsql_config, http_config and https_config may be set.
user
string

ldap_config
object
The response is analyzed to find an LDAPv3 response message. Only one of mysql_config, ldap_config, redis_config, tcp_config, pgsql_config, http_config and https_config may be set.

redis_config
object
The response is analyzed to find the +PONG response message. Only one of mysql_config, ldap_config, redis_config, tcp_config, pgsql_config, http_config and https_config may be set.

check_max_retries
number

tcp_config
object
Only one of mysql_config, ldap_config, redis_config, tcp_config, pgsql_config, http_config and https_config may be set.

pgsql_config
object
Only one of mysql_config, ldap_config, redis_config, tcp_config, pgsql_config, http_config and https_config may be set.
user
string

http_config
object
Only one of mysql_config, ldap_config, redis_config, tcp_config, pgsql_config, http_config and https_config may be set.
uri
string

method
string

code
nullable number

https_config
object
Only one of mysql_config, ldap_config, redis_config, tcp_config, pgsql_config, http_config and https_config may be set.
uri
string

method
string

code
nullable number

port
number

check_timeout
number
(in milliseconds).

check_delay
number
(in milliseconds).

check_send_proxy
boolean
It defines whether the healthcheck should be done considering the proxy protocol.

pool
array

lb
object
id
string

name
string

description
string

status
string
Possible values are unknown, ready, pending, stopped, error, locked and migrating. The default value is unknown.

instances
array
id
string

status
string
Possible values are unknown, ready, pending, stopped, error, locked and migrating. The default value is unknown.

ip_address
string

created_at
string

updated_at
string

region
deprecated string

zone
string

organization_id
string

ip
array
id
string

ip_address
string

organization_id
string

lb_id
nullable string

reverse
string

project_id
string

region
deprecated string

zone
string

tags
array

frontend_count
number

backend_count
number

type
string

subscriber
object
id
string
Subscriber ID.

name
string
Subscriber name.

email_config
object
Email address of subscriber. Only one of email_config and webhook_config may be set.
email
required string
Email who receive alert.

webhook_config
object
WebHook URI of subscriber. Only one of email_config and webhook_config may be set.
uri
required string
URI who receive POST request.

ssl_compatibility_level
string
Possible values are ssl_compatibility_level_unknown, ssl_compatibility_level_intermediate, ssl_compatibility_level_modern and ssl_compatibility_level_old. The default value is ssl_compatibility_level_unknown.

project_id
string

created_at
string

updated_at
string

private_network_count
number

route_count
number

region
deprecated string

zone
string

send_proxy_v2
deprecated boolean

timeout_server
number
(in milliseconds).

timeout_connect
number
(in milliseconds).

timeout_tunnel
number
(in milliseconds).

on_marked_down_action
string
Possible values are on_marked_down_action_none and shutdown_sessions. The default value is on_marked_down_action_none.

proxy_protocol
string
Possible values are proxy_protocol_unknown, proxy_protocol_none, proxy_protocol_v1, proxy_protocol_v2, proxy_protocol_v2_ssl and proxy_protocol_v2_ssl_cn. The default value is proxy_protocol_unknown.

created_at
string

updated_at
string

lb
object
id
string

name
string

description
string

status
string
Possible values are unknown, ready, pending, stopped, error, locked and migrating. The default value is unknown.

instances
array
id
string

status
string
Possible values are unknown, ready, pending, stopped, error, locked and migrating. The default value is unknown.

ip_address
string

created_at
string

updated_at
string

region
deprecated string

zone
string

organization_id
string

ip
array
id
string

ip_address
string

organization_id
string

lb_id
nullable string

reverse
string

project_id
string

region
deprecated string

zone
string

tags
array

frontend_count
number

backend_count
number

type
string

subscriber
object
id
string
Subscriber ID.

name
string
Subscriber name.

email_config
object
Email address of subscriber. Only one of email_config and webhook_config may be set.
email
required string
Email who receive alert.

webhook_config
object
WebHook URI of subscriber. Only one of email_config and webhook_config may be set.
uri
required string
URI who receive POST request.

ssl_compatibility_level
string
Possible values are ssl_compatibility_level_unknown, ssl_compatibility_level_intermediate, ssl_compatibility_level_modern and ssl_compatibility_level_old. The default value is ssl_compatibility_level_unknown.

project_id
string

created_at
string

updated_at
string

private_network_count
number

route_count
number

region
deprecated string

zone
string

timeout_client
number
(in milliseconds).

certificate
object
type
string
Type of certificate (Let's encrypt or custom). Possible values are letsencryt and custom. The default value is letsencryt.

id
string
Certificate ID.

common_name
string
Main domain name of certificate.

subject_alternative_name
array
Alternative domain names.

fingerprint
string
Identifier (SHA-1) of the certificate.

not_valid_before
string
Validity bounds.

not_valid_after
string
Validity bounds.

status
string
Status of certificate. Possible values are pending, ready and error. The default value is pending.

lb
object
Load balancer object.
id
string

name
string

description
string

status
string
Possible values are unknown, ready, pending, stopped, error, locked and migrating. The default value is unknown.

instances
array
id
string

status
string
Possible values are unknown, ready, pending, stopped, error, locked and migrating. The default value is unknown.

ip_address
string

created_at
string

updated_at
string

region
deprecated string

zone
string

organization_id
string

ip
array
id
string

ip_address
string

organization_id
string

lb_id
nullable string

reverse
string

project_id
string

region
deprecated string

zone
string

tags
array

frontend_count
number

backend_count
number

type
string

subscriber
object
id
string
Subscriber ID.

name
string
Subscriber name.

email_config
object
Email address of subscriber. Only one of email_config and webhook_config may be set.
email
required string
Email who receive alert.

webhook_config
object
WebHook URI of subscriber. Only one of email_config and webhook_config may be set.
uri
required string
URI who receive POST request.

ssl_compatibility_level
string
Possible values are ssl_compatibility_level_unknown, ssl_compatibility_level_intermediate, ssl_compatibility_level_modern and ssl_compatibility_level_old. The default value is ssl_compatibility_level_unknown.

project_id
string

created_at
string

updated_at
string

private_network_count
number

route_count
number

region
deprecated string

zone
string

name
string
Certificate name.

created_at
string
Date at which the certificate was created.

updated_at
string
Date at which the certificate was last updated.

certificate_ids
array

created_at
string

updated_at
string
Response Example
{
"id": "string",
"name": "string",
"inbound_port": 42,
"backend": {
"id": "string",
"name": "string",
"forward_protocol": "tcp",
"forward_port": 42,
"forward_port_algorithm": "roundrobin",
"sticky_sessions": "none",
"sticky_sessions_cookie_name": "string",
"health_check": {
"mysql_config": {
"user": "string"
},
"ldap_config": {},
"redis_config": {},
"check_max_retries": 42,
"tcp_config": {},
"pgsql_config": {
"user": "string"
},
"http_config": {
"uri": "string",
"method": "string",
"code": 42
},
"https_config": {
"uri": "string",
"method": "string",
"code": 42
},
"port": 42,
"check_timeout": 42,
"check_delay": 42,
"check_send_proxy": "boolean"
},
"pool": [
"string"
],
"lb": {
"id": "string",
"name": "string",
"description": "string",
"status": "unknown",
"instances": [
{
"id": "string",
"status": "unknown",
"ip_address": "string",
"created_at": "string",
"updated_at": "string",
"region": "string",
"zone": "string"
}
],
"organization_id": "string",
"ip": [
{
"id": "string",
"ip_address": "string",
"organization_id": "string",
"lb_id": "string",
"reverse": "string",
"project_id": "string",
"region": "string",
"zone": "string"
}
],
"tags": [
"string"
],
"frontend_count": 42,
"backend_count": 42,
"type": "string",
"subscriber": {
"id": "string",
"name": "string",
"email_config": {
"email": "string"
},
"webhook_config": {
"uri": "string"
}
},
"ssl_compatibility_level": "ssl_compatibility_level_unknown",
"project_id": "string",
"created_at": "string",
"updated_at": "string",
"private_network_count": 42,
"route_count": 42,
"region": "string",
"zone": "string"
},
"send_proxy_v2": "boolean",
"timeout_server": 42,
"timeout_connect": 42,
"timeout_tunnel": 42,
"on_marked_down_action": "on_marked_down_action_none",
"proxy_protocol": "proxy_protocol_unknown",
"created_at": "string",
"updated_at": "string"
},
"lb": {
"id": "string",
"name": "string",
"description": "string",
"status": "unknown",
"instances": [
{
"id": "string",
"status": "unknown",
"ip_address": "string",
"created_at": "string",
"updated_at": "string",
"region": "string",
"zone": "string"
}
],
"organization_id": "string",
"ip": [
{
"id": "string",
"ip_address": "string",
"organization_id": "string",
"lb_id": "string",
"reverse": "string",
"project_id": "string",
"region": "string",
"zone": "string"
}
],
"tags": [
"string"
],
"frontend_count": 42,
"backend_count": 42,
"type": "string",
"subscriber": {
"id": "string",
"name": "string",
"email_config": {
"email": "string"
},
"webhook_config": {
"uri": "string"
}
},
"ssl_compatibility_level": "ssl_compatibility_level_unknown",
"project_id": "string",
"created_at": "string",
"updated_at": "string",
"private_network_count": 42,
"route_count": 42,
"region": "string",
"zone": "string"
},
"timeout_client": 42,
"certificate": {
"type": "letsencryt",
"id": "string",
"common_name": "string",
"subject_alternative_name": [
"string"
],
"fingerprint": "string",
"not_valid_before": "string",
"not_valid_after": "string",
"status": "pending",
"lb": {
"id": "string",
"name": "string",
"description": "string",
"status": "unknown",
"instances": [
{
"id": "string",
"status": "unknown",
"ip_address": "string",
"created_at": "string",
"updated_at": "string",
"region": "string",
"zone": "string"
}
],
"organization_id": "string",
"ip": [
{
"id": "string",
"ip_address": "string",
"organization_id": "string",
"lb_id": "string",
"reverse": "string",
"project_id": "string",
"region": "string",
"zone": "string"
}
],
"tags": [
"string"
],
"frontend_count": 42,
"backend_count": 42,
"type": "string",
"subscriber": {
"id": "string",
"name": "string",
"email_config": {
"email": "string"
},
"webhook_config": {
"uri": "string"
}
},
"ssl_compatibility_level": "ssl_compatibility_level_unknown",
"project_id": "string",
"created_at": "string",
"updated_at": "string",
"private_network_count": 42,
"route_count": 42,
"region": "string",
"zone": "string"
},
"name": "string",
"created_at": "string",
"updated_at": "string"
},
"certificate_ids": [
"string"
],
"created_at": "string",
"updated_at": "string"
}
PUT
/lb/v1/regions/{region}/frontends/{frontend_id}
Path Parameters

region
required string
The region you want to target. Possible values are fr-par, nl-ams and pl-waw.

frontend_id
required string
Frontend ID.
Body

name
required string
Resource name.

inbound_port
required number
TCP port to listen on the front side.

backend_id
required string
Backend ID.

timeout_client
number
Client session maximum inactivity time (in milliseconds).

certificate_id
deprecated string
Certificate ID, deprecated in favor of `certificate_ids` array!.

certificate_ids
nullable array
List of certificate IDs to bind on the frontend.
Request Example
{
"name": "string",
"inbound_port": 42,
"backend_id": "string",
"timeout_client": 42,
"certificate_id": "string",
"certificate_ids": [
"string"
]
}
200 Response

id
string

name
string

inbound_port
number

backend
object
id
string

name
string

forward_protocol
string
Possible values are tcp and http. The default value is tcp.

forward_port
number

forward_port_algorithm
string
Possible values are roundrobin, leastconn and first. The default value is roundrobin.

sticky_sessions
string
Possible values are none, cookie and table. The default value is none.


health_check
object
mysql_config
object
The check requires MySQL >=3.22, for older versions, use TCP check. Only one of mysql_config, ldap_config, redis_config, tcp_config, pgsql_config, http_config and https_config may be set.
user
string

ldap_config
object
The response is analyzed to find an LDAPv3 response message. Only one of mysql_config, ldap_config, redis_config, tcp_config, pgsql_config, http_config and https_config may be set.

redis_config
object
The response is analyzed to find the +PONG response message. Only one of mysql_config, ldap_config, redis_config, tcp_config, pgsql_config, http_config and https_config may be set.

check_max_retries
number

tcp_config
object
Only one of mysql_config, ldap_config, redis_config, tcp_config, pgsql_config, http_config and https_config may be set.

pgsql_config
object
Only one of mysql_config, ldap_config, redis_config, tcp_config, pgsql_config, http_config and https_config may be set.
user
string

http_config
object
Only one of mysql_config, ldap_config, redis_config, tcp_config, pgsql_config, http_config and https_config may be set.
uri
string

method
string

code
nullable number

https_config
object
Only one of mysql_config, ldap_config, redis_config, tcp_config, pgsql_config, http_config and https_config may be set.
uri
string

method
string

code
nullable number

port
number

check_timeout
number
(in milliseconds).

check_delay
number
(in milliseconds).

check_send_proxy
boolean
It defines whether the healthcheck should be done considering the proxy protocol.

pool
array

lb
object
id
string

name
string

description
string

status
string
Possible values are unknown, ready, pending, stopped, error, locked and migrating. The default value is unknown.

instances
array
id
string

status
string
Possible values are unknown, ready, pending, stopped, error, locked and migrating. The default value is unknown.

ip_address
string

created_at
string

updated_at
string

region
deprecated string

zone
string

organization_id
string

ip
array
id
string

ip_address
string

organization_id
string

lb_id
nullable string

reverse
string

project_id
string

region
deprecated string

zone
string

tags
array

frontend_count
number

backend_count
number

type
string

subscriber
object
id
string
Subscriber ID.

name
string
Subscriber name.

email_config
object
Email address of subscriber. Only one of email_config and webhook_config may be set.
email
required string
Email who receive alert.

webhook_config
object
WebHook URI of subscriber. Only one of email_config and webhook_config may be set.
uri
required string
URI who receive POST request.

ssl_compatibility_level
string
Possible values are ssl_compatibility_level_unknown, ssl_compatibility_level_intermediate, ssl_compatibility_level_modern and ssl_compatibility_level_old. The default value is ssl_compatibility_level_unknown.

project_id
string

created_at
string

updated_at
string

private_network_count
number

route_count
number

region
deprecated string

zone
string

send_proxy_v2
deprecated boolean

timeout_server
number
(in milliseconds).

timeout_connect
number
(in milliseconds).

timeout_tunnel
number
(in milliseconds).

on_marked_down_action
string
Possible values are on_marked_down_action_none and shutdown_sessions. The default value is on_marked_down_action_none.

proxy_protocol
string
Possible values are proxy_protocol_unknown, proxy_protocol_none, proxy_protocol_v1, proxy_protocol_v2, proxy_protocol_v2_ssl and proxy_protocol_v2_ssl_cn. The default value is proxy_protocol_unknown.

created_at
string

updated_at
string

lb
object
id
string

name
string

description
string

status
string
Possible values are unknown, ready, pending, stopped, error, locked and migrating. The default value is unknown.

instances
array
id
string

status
string
Possible values are unknown, ready, pending, stopped, error, locked and migrating. The default value is unknown.

ip_address
string

created_at
string

updated_at
string

region
deprecated string

zone
string

organization_id
string

ip
array
id
string

ip_address
string

organization_id
string

lb_id
nullable string

reverse
string

project_id
string

region
deprecated string

zone
string

tags
array

frontend_count
number

backend_count
number

type
string

subscriber
object
id
string
Subscriber ID.

name
string
Subscriber name.

email_config
object
Email address of subscriber. Only one of email_config and webhook_config may be set.
email
required string
Email who receive alert.

webhook_config
object
WebHook URI of subscriber. Only one of email_config and webhook_config may be set.
uri
required string
URI who receive POST request.

ssl_compatibility_level
string
Possible values are ssl_compatibility_level_unknown, ssl_compatibility_level_intermediate, ssl_compatibility_level_modern and ssl_compatibility_level_old. The default value is ssl_compatibility_level_unknown.

project_id
string

created_at
string

updated_at
string

private_network_count
number

route_count
number

region
deprecated string

zone
string

timeout_client
number
(in milliseconds).

certificate
object
type
string
Type of certificate (Let's encrypt or custom). Possible values are letsencryt and custom. The default value is letsencryt.

id
string
Certificate ID.

common_name
string
Main domain name of certificate.

subject_alternative_name
array
Alternative domain names.

fingerprint
string
Identifier (SHA-1) of the certificate.

not_valid_before
string
Validity bounds.

not_valid_after
string
Validity bounds.

status
string
Status of certificate. Possible values are pending, ready and error. The default value is pending.

lb
object
Load balancer object.
id
string

name
string

description
string

status
string
Possible values are unknown, ready, pending, stopped, error, locked and migrating. The default value is unknown.

instances
array
id
string

status
string
Possible values are unknown, ready, pending, stopped, error, locked and migrating. The default value is unknown.

ip_address
string

created_at
string

updated_at
string

region
deprecated string

zone
string

organization_id
string

ip
array
id
string

ip_address
string

organization_id
string

lb_id
nullable string

reverse
string

project_id
string

region
deprecated string

zone
string

tags
array

frontend_count
number

backend_count
number

type
string

subscriber
object
id
string
Subscriber ID.

name
string
Subscriber name.

email_config
object
Email address of subscriber. Only one of email_config and webhook_config may be set.
email
required string
Email who receive alert.

webhook_config
object
WebHook URI of subscriber. Only one of email_config and webhook_config may be set.
uri
required string
URI who receive POST request.

ssl_compatibility_level
string
Possible values are ssl_compatibility_level_unknown, ssl_compatibility_level_intermediate, ssl_compatibility_level_modern and ssl_compatibility_level_old. The default value is ssl_compatibility_level_unknown.

project_id
string

created_at
string

updated_at
string

private_network_count
number

route_count
number

region
deprecated string

zone
string

name
string
Certificate name.

created_at
string
Date at which the certificate was created.

updated_at
string
Date at which the certificate was last updated.

certificate_ids
array

created_at
string

updated_at
string
Response Example
{
"id": "string",
"name": "string",
"inbound_port": 42,
"backend": {
"id": "string",
"name": "string",
"forward_protocol": "tcp",
"forward_port": 42,
"forward_port_algorithm": "roundrobin",
"sticky_sessions": "none",
"sticky_sessions_cookie_name": "string",
"health_check": {
"mysql_config": {
"user": "string"
},
"ldap_config": {},
"redis_config": {},
"check_max_retries": 42,
"tcp_config": {},
"pgsql_config": {
"user": "string"
},
"http_config": {
"uri": "string",
"method": "string",
"code": 42
},
"https_config": {
"uri": "string",
"method": "string",
"code": 42
},
"port": 42,
"check_timeout": 42,
"check_delay": 42,
"check_send_proxy": "boolean"
},
"pool": [
"string"
],
"lb": {
"id": "string",
"name": "string",
"description": "string",
"status": "unknown",
"instances": [
{
"id": "string",
"status": "unknown",
"ip_address": "string",
"created_at": "string",
"updated_at": "string",
"region": "string",
"zone": "string"
}
],
"organization_id": "string",