Exoscale network-load-balancer API
A Network Load Balancer (NLB) is a Layer 4 (TCP/UDP) load balancer that distributes incoming traffic to Compute instances managed by an Instance Pool.
OpenAPI Specification
openapi: 3.0.0
info:
version: 2.0.0
termsOfService: https://exoscale.com/terms
contact:
email: support@exoscale.com
name: Exoscale Support
url: https://portal.exoscale.com/tickets
title: Exoscale ai-api-key network-load-balancer API
description: Infrastructure automation API, allowing programmatic access to all Exoscale products and services.
servers:
- url: https://api-{zone}.exoscale.com/v2
variables:
zone:
default: ch-gva-2
enum:
- ch-gva-2
- ch-dk-2
- de-fra-1
- de-muc-1
- at-vie-1
- at-vie-2
- bg-sof-1
- hr-zag-1
tags:
- description: "A Network Load Balancer (NLB) is a Layer 4 (TCP/UDP)\n load balancer that distributes incoming traffic to Compute\n instances managed by an Instance Pool."
parent: compute
externalDocs:
description: Read more
url: https://community.exoscale.com/documentation/compute/network-load-balancer/
name: network-load-balancer
x-display-name: Network Load Balancer
x-weight: 180
x-icon: exo-nlb
paths:
/load-balancer/{id}/service/{service-id}:
delete:
tags:
- network-load-balancer
responses:
'200':
description: '200'
content:
application/json:
schema:
$ref: '#/components/schemas/operation'
description: ''
parameters:
- in: path
required: true
name: id
schema:
type: string
format: uuid
- in: path
required: true
name: service-id
schema:
type: string
format: uuid
summary: Delete a Load Balancer Service
operationId: delete-load-balancer-service
put:
tags:
- network-load-balancer
responses:
'200':
description: '200'
content:
application/json:
schema:
$ref: '#/components/schemas/operation'
description: ''
parameters:
- in: path
required: true
name: id
schema:
type: string
format: uuid
- in: path
required: true
name: service-id
schema:
type: string
format: uuid
summary: Update a Load Balancer Service
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
type: string
maxLength: 255
description: Load Balancer Service name
description:
type: string
maxLength: 255
description: Load Balancer Service description
protocol:
type: string
enum:
- tcp
- udp
description: Network traffic protocol
strategy:
type: string
enum:
- round-robin
- maglev-hash
- source-hash
description: Load balancing strategy
port:
type: integer
format: int64
minimum: 1
maximum: 65535
exclusiveMinimum: false
exclusiveMaximum: false
description: Port exposed on the Load Balancer's public IP
target-port:
type: integer
format: int64
minimum: 1
maximum: 65535
exclusiveMinimum: false
exclusiveMaximum: false
description: Port on which the network traffic will be forwarded to on the receiving instance
healthcheck:
$ref: '#/components/schemas/load-balancer-service-healthcheck'
description: Healthcheck configuration
operationId: update-load-balancer-service
get:
tags:
- network-load-balancer
responses:
'200':
description: '200'
content:
application/json:
schema:
$ref: '#/components/schemas/load-balancer-service'
description: ''
parameters:
- in: path
required: true
name: id
schema:
type: string
format: uuid
- in: path
required: true
name: service-id
schema:
type: string
format: uuid
summary: Retrieve Load Balancer Service details
operationId: get-load-balancer-service
/load-balancer:
post:
tags:
- network-load-balancer
responses:
'200':
description: '200'
content:
application/json:
schema:
$ref: '#/components/schemas/operation'
description: ''
parameters: []
summary: Create a Load Balancer
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
description:
type: string
maxLength: 255
description: Load Balancer description
name:
type: string
maxLength: 255
minLength: 1
description: Load Balancer name
labels:
$ref: '#/components/schemas/labels'
description: Load balancer labels
required:
- name
operationId: create-load-balancer
get:
tags:
- network-load-balancer
responses:
'200':
description: '200'
content:
application/json:
schema:
type: object
properties:
load-balancers:
type: array
items:
$ref: '#/components/schemas/load-balancer'
description: ''
parameters: []
summary: List Load Balancers
operationId: list-load-balancers
/load-balancer/{id}/{field}:
delete:
tags:
- network-load-balancer
responses:
'200':
description: '200'
content:
application/json:
schema:
$ref: '#/components/schemas/operation'
description: ''
parameters:
- in: path
required: true
name: id
schema:
type: string
format: uuid
- in: path
required: true
name: field
schema:
type: string
enum:
- description
- labels
summary: Reset a Load Balancer field to its default value
operationId: reset-load-balancer-field
/load-balancer/{id}/service/{service-id}/{field}:
delete:
tags:
- network-load-balancer
responses:
'200':
description: '200'
content:
application/json:
schema:
$ref: '#/components/schemas/operation'
description: ''
parameters:
- in: path
required: true
name: id
schema:
type: string
format: uuid
- in: path
required: true
name: service-id
schema:
type: string
format: uuid
- in: path
required: true
name: field
schema:
type: string
enum:
- description
summary: Reset a Load Balancer Service field to its default value
operationId: reset-load-balancer-service-field
/load-balancer/{id}/service:
post:
tags:
- network-load-balancer
responses:
'200':
description: '200'
content:
application/json:
schema:
$ref: '#/components/schemas/operation'
description: ''
parameters:
- in: path
required: true
name: id
schema:
type: string
format: uuid
summary: Add a Load Balancer Service
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
type: string
maxLength: 255
minLength: 1
description: Load Balancer Service name
description:
type: string
maxLength: 255
description: Load Balancer Service description
instance-pool:
$ref: '#/components/schemas/instance-pool'
description: Instance Pool to forward traffic to
protocol:
type: string
enum:
- tcp
- udp
description: Network traffic protocol
strategy:
type: string
enum:
- round-robin
- maglev-hash
- source-hash
description: Load balancing strategy
port:
type: integer
format: int64
minimum: 1
maximum: 65535
exclusiveMinimum: false
exclusiveMaximum: false
description: Port exposed on the Load Balancer's public IP
target-port:
type: integer
format: int64
minimum: 1
maximum: 65535
exclusiveMinimum: false
exclusiveMaximum: false
description: Port on which the network traffic will be forwarded to on the receiving instance
healthcheck:
$ref: '#/components/schemas/load-balancer-service-healthcheck'
description: Healthcheck configuration
required:
- name
- instance-pool
- protocol
- strategy
- port
- target-port
- healthcheck
operationId: add-service-to-load-balancer
/load-balancer/{id}:
put:
tags:
- network-load-balancer
responses:
'200':
description: '200'
content:
application/json:
schema:
$ref: '#/components/schemas/operation'
description: ''
parameters:
- in: path
required: true
name: id
schema:
type: string
format: uuid
summary: Update a Load Balancer
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
type: string
maxLength: 255
minLength: 1
description: Load Balancer name
description:
type: string
maxLength: 255
description: Load Balancer description
labels:
$ref: '#/components/schemas/labels'
operationId: update-load-balancer
delete:
tags:
- network-load-balancer
responses:
'200':
description: '200'
content:
application/json:
schema:
$ref: '#/components/schemas/operation'
description: ''
parameters:
- in: path
required: true
name: id
schema:
type: string
format: uuid
summary: Delete a Load Balancer
operationId: delete-load-balancer
get:
tags:
- network-load-balancer
responses:
'200':
description: '200'
content:
application/json:
schema:
$ref: '#/components/schemas/load-balancer'
description: ''
parameters:
- in: path
required: true
name: id
schema:
type: string
format: uuid
summary: Retrieve Load Balancer details
operationId: get-load-balancer
components:
schemas:
load-balancer-service-healthcheck:
type: object
properties:
mode:
type: string
enum:
- tcp
- http
- https
description: Healthcheck mode
interval:
type: integer
format: int64
minimum: 5
maximum: 300
exclusiveMinimum: false
exclusiveMaximum: false
description: 'Healthcheck interval (default: 10). Must be greater than or equal to Timeout'
uri:
type: string
maxLength: 255
minLength: 1
description: An endpoint to use for the HTTP healthcheck, e.g. '/status'
port:
type: integer
format: int64
minimum: 1
maximum: 65535
exclusiveMinimum: false
exclusiveMaximum: false
description: Healthcheck port
timeout:
type: integer
format: int64
minimum: 2
maximum: 60
exclusiveMinimum: false
exclusiveMaximum: false
description: 'Healthcheck timeout value (default: 2). Must be lower than or equal to Interval'
retries:
type: integer
format: int64
minimum: 1
maximum: 20
exclusiveMinimum: false
exclusiveMaximum: false
description: Number of retries before considering a Service failed
tls-sni:
type: string
maxLength: 255
minLength: 1
description: SNI domain for HTTPS healthchecks
description: Load Balancer Service healthcheck
instance-type-ref:
type: object
properties:
id:
type: string
format: uuid
description: Instance type ID
description: Instance type reference
labels:
type: object
additionalProperties:
type: string
deploy-target-ref:
type: object
properties:
id:
type: string
format: uuid
description: Deploy target ID
description: Deploy target reference
private-network-ref:
type: object
properties:
id:
type: string
format: uuid
description: Private network ID
description: Private network reference
security-group-ref:
type: object
properties:
id:
type: string
format: uuid
description: Security group ID
description: Security group reference
public-ip-assignment:
type: string
enum:
- inet4
- dual
- none
anti-affinity-group-ref:
type: object
properties:
id:
type: string
format: uuid
description: Anti-affinity group ID
description: Anti-affinity group reference
template-ref:
type: object
properties:
id:
type: string
format: uuid
description: Template ID
description: Template reference
ssh-key-ref:
type: object
properties:
name:
type: string
maxLength: 255
minLength: 1
description: SSH key name
description: SSH key reference
load-balancer-service:
type: object
properties:
description:
type: string
maxLength: 255
description: Load Balancer Service description
protocol:
type: string
enum:
- tcp
- udp
description: Network traffic protocol
name:
type: string
maxLength: 255
minLength: 1
description: Load Balancer Service name
state:
type: string
enum:
- creating
- deleting
- running
- updating
- error
readOnly: true
description: Load Balancer Service state
target-port:
type: integer
format: int64
minimum: 0
exclusiveMinimum: true
description: Port on which the network traffic will be forwarded to on the receiving instance
port:
type: integer
format: int64
minimum: 0
exclusiveMinimum: true
description: Port exposed on the Load Balancer's public IP
instance-pool:
$ref: '#/components/schemas/instance-pool'
description: Instance Pool to forward network traffic to
strategy:
type: string
enum:
- round-robin
- maglev-hash
- source-hash
description: Load balancing strategy
healthcheck:
$ref: '#/components/schemas/load-balancer-service-healthcheck'
description: Healthcheck configuration
id:
type: string
format: uuid
readOnly: true
description: Load Balancer Service ID
healthcheck-status:
type: array
items:
$ref: '#/components/schemas/load-balancer-server-status'
readOnly: true
description: Healthcheck status per backend server
description: Load Balancer Service
elastic-ip-ref:
type: object
properties:
id:
type: string
format: uuid
description: Elastic IP ID
description: Elastic IP reference
instance-pool:
type: object
properties:
application-consistent-snapshot-enabled:
type: boolean
description: Enable application consistent snapshots
anti-affinity-groups:
type: array
items:
$ref: '#/components/schemas/anti-affinity-group-ref'
description: Instance Pool Anti-affinity Groups
description:
type: string
maxLength: 255
minLength: 1
description: Instance Pool description
public-ip-assignment:
$ref: '#/components/schemas/public-ip-assignment'
description: Instance Pool public IP assignment
labels:
$ref: '#/components/schemas/labels'
description: Instance Pool Labels
security-groups:
type: array
items:
$ref: '#/components/schemas/security-group-ref'
description: Instance Pool Security Groups
elastic-ips:
type: array
items:
$ref: '#/components/schemas/elastic-ip-ref'
description: Instances Elastic IPs
name:
type: string
maxLength: 255
minLength: 1
description: Instance Pool name
instance-type:
$ref: '#/components/schemas/instance-type-ref'
description: Instances type
min-available:
type: integer
format: int64
minimum: 0
exclusiveMinimum: false
description: Minimum number of running instances
private-networks:
type: array
items:
$ref: '#/components/schemas/private-network-ref'
description: Instance Pool Private Networks
template:
$ref: '#/components/schemas/template-ref'
description: Instances template
state:
type: string
enum:
- scaling-up
- scaling-down
- destroying
- creating
- suspended
- running
- updating
readOnly: true
description: Instance Pool state
size:
type: integer
format: int64
minimum: 0
exclusiveMinimum: true
description: Number of instances
ssh-key:
$ref: '#/components/schemas/ssh-key-ref'
description: Instances SSH key
instance-prefix:
type: string
maxLength: 30
minLength: 1
description: 'The instances created by the Instance Pool will be prefixed with this value (default: pool)'
user-data:
type: string
minLength: 1
description: Instances Cloud-init user-data
manager:
$ref: '#/components/schemas/manager'
readOnly: true
description: Instance Pool manager
instances:
type: array
items:
$ref: '#/components/schemas/instance-ref'
readOnly: true
description: Instances
deploy-target:
$ref: '#/components/schemas/deploy-target-ref'
description: Instance Pool Deploy Target
ipv6-enabled:
type: boolean
description: Enable IPv6 for instances
id:
type: string
format: uuid
readOnly: true
description: Instance Pool ID
disk-size:
type: integer
format: int64
minimum: 10
maximum: 51200
exclusiveMinimum: false
exclusiveMaximum: false
description: Instances disk size in GiB
ssh-keys:
type: array
items:
$ref: '#/components/schemas/ssh-key-ref'
description: Instances SSH keys
description: Instance Pool
load-balancer:
type: object
properties:
id:
type: string
format: uuid
readOnly: true
description: Load Balancer ID
description:
type: string
maxLength: 255
description: Load Balancer description
name:
type: string
maxLength: 255
minLength: 1
description: Load Balancer name
state:
type: string
enum:
- creating
- migrated
- deleting
- running
- migrating
- error
readOnly: true
description: Load Balancer state
created-at:
type: string
format: date-time
readOnly: true
description: Load Balancer creation date
ip:
type: string
format: ipv4
readOnly: true
description: Load Balancer public IP
services:
type: array
items:
$ref: '#/components/schemas/load-balancer-service'
description: Load Balancer Services
labels:
$ref: '#/components/schemas/labels'
description: Load Balancer Labels
description: Load Balancer
manager:
type: object
properties:
id:
type: string
format: uuid
description: Manager ID
type:
type: string
enum:
- sks-nodepool
- instance-pool
description: Manager type
description: Resource manager
load-balancer-server-status:
type: object
properties:
public-ip:
type: string
format: ipv4
description: Backend server public IP
status:
type: string
enum:
- failure
- success
description: Status of the instance's healthcheck
description: Load Balancer Service status
operation:
type: object
properties:
id:
type: string
format: uuid
readOnly: true
description: Operation ID
reason:
type: string
enum:
- incorrect
- unknown
- unavailable
- forbidden
- busy
- fault
- partial
- not-found
- interrupted
- unsupported
- conflict
readOnly: true
description: Operation failure reason
reference:
type: object
properties:
id:
type: string
format: uuid
description: Reference ID
link:
type: string
readOnly: true
description: Link to the referenced resource
command:
type: string
description: Command name
description: Related resource reference
readOnly: true
message:
type: string
readOnly: true
description: Operation message
state:
type: string
enum:
- failure
- pending
- success
- timeout
readOnly: true
description: Operation status
description: Operation
instance-ref:
type: object
properties:
id:
type: string
format: uuid
description: Instance ID
description: Target Instance
x-topics:
- title: API Request Signature
content: '
In order to authenticate legitimate users, the Exoscale API requires incoming requests to be signed using valid Exoscale API account credentials with the following mechanism.
## Signature Mechanism
The *message* (i.e. content) to sign contains several segments concatenated using a line return character (`\n`).
All segments must be included and in the described order. For cases where a segment doesn''t fit the context of the request (e.g. no request body) **an empty line must be used instead**.
* Request method and request URL (path only), separated by a space character
* Request body
* Request URL parameters (Query String) values, concatenated without separator. The matching parameter names have to be specified in the resulting signature header `signed-query-args=` pragma, separated by semicolons (e.g. `p1;p2;pN`).
* Request header values, concatenated without separator (none at the moment, leave empty)
* Request expiration date in UNIX timestamp format
Example *message* to sign for `GET /v2/resource/a02baf5a-a3e4-49a0-857b-8a08d276c1c0?p1=v1&p2=v2`:
```
GET /v2/resource/a02baf5a-a3e4-49a0-857b-8a08d276c1c0
v1v2
1599140767
```
The two blank lines above are due to the absence of a request body and signed headers.
Example *message* to [create a security group](https://community.exoscale.com/reference/api/compute/security-group/#create-security-group)
```
POST /v2/security-group
{"name": "my-security-group"}
1599140767
```
The two blank lines above are due to the absence of query parameters and signed headers.
The request signature consists of the base64-encoded [HMAC](https://en.wikipedia.org/wiki/HMAC) hash of the UTF-8 encoded *message* and the Exoscale API secret using the SHA265 function:
```
signature = BASE64_ENCODE(HMAC_SHA256(Exoscale API secret, message))
```
Finally, the computed signature must be added to the API request in a `Authorization` header such as:
```
Authorization: EXO2-HMAC-SHA256 credential=<Exoscale API key>,expires=<expiration date UNIX timestamp>,signature=<signature>
```
Example API query:
```
GET /v2/resource/a02baf5a-a3e4-49a0-857b-8a08d276c1c0?p1=v1&p2=v2 HTTP/1.1
Host: api-ch-gva-2.exoscale.com
Authorization: EXO2-HMAC-SHA256 credential=EXO29147e9f89102b7ac1e88514,signed-query-args=p1;p2,expires=1599140767,signature=2AOBQsbElQb4FpKT/FM/9T4NobjlmZkSGvvdUth/xlY=
```
## Reference Implementations
You can look up the following existing reference implementations:
* Go: [github.com/exoscale/egoscale/api/v2 > `SecurityProviderExoscale.signRequest`](https://github.com/exoscale/egoscale/blob/master/v2/api/security.go)
* Python: [requests-exoscale-auth > `ExoscaleV2Auth`](https://github.com/exoscale/requests-exoscale-auth/blob/master/exoscale_auth.py)
'
- title: Zone local resources
content: '
The API is deployed across all Exoscale zones. When performing a compute call, you should use the relevant zone for your resource.
For example: https://api-de-fra-1.exoscale.com/v2/instance would return only the instances from `de-fra-1`, https://api-ch-gva-2.exoscale.com/v2/instance from `ch-gva-2`.
To obtain a list of all instances across all zones, you would need to do the corresponding request for each zone.
'