17. Managed Load Balancer
A Managed load balancer works as the network level frontend of customer application by directing connections to the backend servers.
The Managed load balancer API allows customer to manage their services. Managed load balancers are available in every UpCloud zone. The API requests and responses payload are in JSON format only.
API follows JSON Merge Patch semantics. Note when modifying nested structures payload should contain entire array, which in a sense is PUT within PATCH for them.
JSON Merge Patch uses null to explicitly indicate property deletion while absent properties are ignored, i.e. not modified.
It is recommended to use the hostnames of your load balancer when directing your domain to it. This ensures utilization of all addresses that the load balancer might possess.
For the subdomains of your domain, use CNAME. For the primary domain, you might need to use ALIAS, or whatever is supported by your DNS provider.
List plans
Returns a list of available load balancer plans.
Request
Query parameters
| Attribute | Accepted value | Default value | Required | Description |
|---|---|---|---|---|
| limit | 0-100 | 10 | no | Number of entries to receive at most. |
| offset | >= 0 | 0 | no | Offset for retrieved results. |
Normal response
[
{
"name": "development",
"per_server_max_sessions": 10000,
"server_number": 1
},
{
"name": "production",
"per_server_max_sessions": 50000,
"server_number": 2
}
]
Get plan details
Returns load balancer plan details by given {name}.
Request
Normal response
Create service
Creates a new load balancer service.
Request
{
"name": "example-service",
"plan": "development",
"zone": "fi-hel1",
"configured_status": "started",
"maintenance_dow": "sunday",
"maintenance_time": "20:01:01Z",
"networks": [
{
"name": "example-network-1",
"type": "public",
"family": "IPv4"
},
{
"name": "example-network-2",
"type": "private",
"family": "IPv4",
"uuid": "03631160-d57a-4926-ad48-a2f828229dcb"
}
],
"frontends": [
{
"name": "example-frontend",
"mode": "http",
"port": 443,
"default_backend": "example-backend-1",
"networks": [
{
"name": "example-network-1"
}
],
"rules": [
{
"name": "example-rule-1",
"priority": 100,
"matchers": [
{
"type": "path",
"match_path": {
"method": "exact",
"value": "/app"
}
}
],
"actions": [
{
"type": "use_backend",
"action_use_backend": {
"backend": "example-backend-2"
}
}
]
}
],
"tls_configs": [
{
"name": "example-tls-config",
"certificate_bundle_uuid": "0a73c569-a2d1-481a-917f-b0fdafd78136"
}
],
"properties": {
"timeout_client": 5,
"inbound_proxy_protocol": false
}
}
],
"backends": [
{
"name": "example-backend-1",
"members": [
{
"name": "example-member-1",
"ip": "172.16.1.4",
"port": 8000,
"type": "static",
"weight": 100,
"max_sessions": 1000,
"enabled": true
},
{
"name": "example-member-2",
"ip": "172.16.1.6",
"port": 8080,
"type": "static",
"weight": 50,
"max_sessions": 500,
"enabled": true
}
],
"properties": {
"timeout_server": 10,
"timeout_tunnel": 3600,
"outbound_proxy_protocol": "",
"health_check_tls_verify": false,
"health_check_type": "http",
"health_check_on_down": "",
"health_check_interval": 10,
"health_check_fall": 5,
"health_check_rise": 5,
"health_check_url": "http://somehost/health",
"health_check_expected_status": 200,
"sticky_session_cookie_name": "x-session",
"tls_enabled": false,
"tls_verify": false,
"tls_use_system_ca": false
}
},
{
"name": "example-backend-2",
"resolver": "example-resolver",
"tls_configs": [],
"members": [
{
"name": "member.example.com",
"port": 8000,
"type": "dynamic",
"max_sessions": 1000,
"weight": 100,
"enabled": true
}
]
}
],
"resolvers": [
{
"name": "example-resolver",
"nameservers": [
"172.16.1.4:53"
],
"retries": 5,
"timeout": 30,
"timeout_retry": 10,
"cache_valid": 180,
"cache_invalid": 10
}
],
"labels": [
{
"key": "env",
"value": "staging"
},
{
"key": "foo",
"value": "bar"
}
]
}
Attributes
| Attribute | Accepted value | Required | Description |
|---|---|---|---|
| name | 1-64 characters, regexp pattern ^[a-zA-Z0-9_-]+$ |
yes | The name of the service must be unique within customer account. |
| plan | A valid plan identifier, e.g. development |
yes | Plan which the service will have, see plans. |
| zone | A valid zone identifier, e.g. fi-hel1 |
yes | Zone in which the service will be hosted, e.g. fi-hel1. |
| configured_status | started / stopped |
yes | Service status managed by the customer. |
| networks | An array of 1-8 network objects | yes | Attached Networks from where traffic consumed and routed. Private networks must reside in loadbalancer zone. |
| frontends | An array of 0-100 frontend objects | no | Frontends receive the traffic before dispatching it to the backends. |
| backends | An array of 0-100 backend objects | no | Backends are groups of customer servers whose traffic should be balanced. |
| resolvers | An array of 0-100 resolver objects | no | Domain Name Resolvers must be configured in case of customer uses dynamic type members |
| labels | An array of 0-255 labels objects | no | Labels used for service filtering, see labels usage |
| maintenance_dow | A valid day of the week in lowercase monday/tuesday/wednesday/thursday/friday/saturday/sunday |
no | The day of the week on which maintenance will be performed. If not provided, we will randomly select a weekend day. |
| maintenance_time | A valid time format in UTC HH:MM:SSZ |
no | The time at which the maintenance will begin in UTC. A 2-hour timeframe has been allocated for maintenance. During this period, the multi-node production plans will not experience any downtime, while the one-node plans will have a downtime of 1-2 minutes. If not provided, we will randomly select an off-peak time. |
| network_uuid | A valid network identifier in UUID format | no | (Deprecated) Private network UUID where traffic will be routed. Must reside in loadbalancer zone. The field will be deprecated soon, please consider using networks field instead. |
Normal response
Error response
| HTTP status | Error code | Description |
|---|---|---|
| 402 Payment required | INSUFFICIENT_CREDITS | Customer account does not have enough credits for the requested action. |
| 400 Bad Request | INVALID_REQUEST | Validation error. |
List services
Returns a list of load balancer services.
Request
Query parameters
| Attribute | Accepted value | Default value | Required | Description |
|---|---|---|---|---|
| limit | 0-100 | 10 | no | Number of entries to receive at most. |
| offset | >= 0 | 0 | no | Offset for retrieved results. |
| label | String representation of a label. | no | Filter by label. See labels usage. |
Normal response
[
{
"backends": [
{
"created_at": "2022-10-04T16:11:14.569638Z",
"members": [
{
"created_at": "2022-10-04T16:11:14.569638Z",
"enabled": true,
"ip": "172.16.1.4",
"max_sessions": 1000,
"name": "example-member-1",
"port": 8000,
"type": "static",
"updated_at": "2022-10-04T16:11:14.569638Z",
"weight": 100
},
{
"created_at": "2022-10-04T16:11:14.569638Z",
"enabled": true,
"ip": "172.16.1.6",
"max_sessions": 500,
"name": "example-member-2",
"port": 8080,
"type": "static",
"updated_at": "2022-10-04T16:11:14.569638Z",
"weight": 50
}
],
"name": "example-backend-1",
"properties": {
"health_check_expected_status": 200,
"health_check_fall": 5,
"health_check_interval": 10,
"health_check_rise": 5,
"health_check_tls_verify": false,
"health_check_type": "http",
"health_check_on_down": "",
"health_check_url": "/health",
"sticky_session_cookie_name": "x-session",
"timeout_server": 10,
"timeout_tunnel": 3600,
"tls_enabled": false,
"tls_verify": false,
"tls_use_system_ca": false
},
"updated_at": "2022-10-04T16:11:14.569638Z"
},
{
"created_at": "2022-10-04T16:11:14.569638Z",
"members": [
{
"created_at": "2022-10-04T16:11:14.569638Z",
"enabled": true,
"ip": "",
"max_sessions": 1000,
"name": "member.example.com",
"port": 8000,
"type": "dynamic",
"updated_at": "2022-10-04T16:11:14.569638Z",
"weight": 100
}
],
"name": "example-backend-2",
"properties": {
"health_check_expected_status": 200,
"health_check_fall": 3,
"health_check_interval": 10,
"health_check_rise": 3,
"health_check_tls_verify": false,
"health_check_type": "tcp",
"health_check_on_down": "",
"health_check_url": "/",
"sticky_session_cookie_name": "",
"timeout_server": 10,
"timeout_tunnel": 3600,
"tls_enabled": false,
"tls_verify": false,
"tls_use_system_ca": false
},
"resolver": "example-resolver",
"tls_configs": [],
"updated_at": "2022-10-04T16:11:14.569638Z"
}
],
"configured_status": "started",
"created_at": "2022-10-04T16:11:14.569638Z",
"dns_name": "lb-0a498284629e4629a55d0415a6e89dda-1.upcloudlb.com",
"maintenance_dow": "sunday",
"maintenance_time": "20:01:01Z",
"frontends": [
{
"created_at": "2022-10-04T16:11:14.569638Z",
"default_backend": "example-backend-1",
"mode": "http",
"name": "example-frontend",
"networks": [
{
"name": "example-network-1"
}
],
"port": 443,
"properties": {
"timeout_client": 5
},
"rules": [
{
"actions": [
{
"type": "use_backend",
"action_use_backend": {
"backend": "example-backend-2"
}
}
],
"created_at": "2022-10-04T16:11:14.569638Z",
"matchers": [
{
"type": "path",
"inverse": false,
"match_path": {
"method": "exact",
"value": "/app"
}
}
],
"name": "example-rule-1",
"priority": 100,
"updated_at": "2022-10-04T16:11:14.569638Z"
}
],
"tls_configs": [
{
"certificate_bundle_uuid": "0a73c569-a2d1-481a-917f-b0fdafd78136",
"created_at": "2022-10-04T16:11:14.569638Z",
"name": "example-tls-config",
"updated_at": "2022-10-04T16:11:14.569638Z"
}
],
"updated_at": "2022-10-04T16:11:14.569638Z"
}
],
"labels": [
{
"key": "env",
"value": "staging"
},
{
"key": "foo",
"value": "bar"
}
],
"name": "example-service",
"networks": [
{
"created_at": "2022-10-04T16:11:14.569638Z",
"dns_name": "lb-0a498284629e4629a55d0415a6e89dda-1.upcloudlb.com",
"family": "IPv4",
"name": "example-network-1",
"type": "public",
"updated_at": "2022-10-04T16:11:14.569638Z"
},
{
"created_at": "2022-10-04T16:11:14.569638Z",
"dns_name": "lb-0a498284629e4629a55d0415a6e89dda-2.upcloudlb.com",
"family": "IPv4",
"name": "example-network-2",
"type": "private",
"updated_at": "2022-10-04T16:11:14.569638Z",
"uuid": "03631160-d57a-4926-ad48-a2f828229dcb"
}
],
"nodes": [
{
"networks": [
{
"ip_addresses": [
{
"address": "100.127.5.146",
"listen": true
}
],
"name": "example-network-1",
"type": "public"
},
{
"ip_addresses": [
{
"address": "172.16.1.44",
"listen": false
},
{
"address": "172.16.1.45",
"listen": true
}
],
"name": "example-network-2",
"type": "private"
}
],
"operational_state": "running"
}
],
"operational_state": "pending",
"plan": "development",
"resolvers": [
{
"cache_invalid": 10,
"cache_valid": 180,
"created_at": "2022-10-04T16:11:14.569638Z",
"name": "example-resolver",
"nameservers": [
"172.16.1.4:53"
],
"retries": 5,
"timeout": 30,
"timeout_retry": 10,
"updated_at": "2022-10-04T16:11:14.569638Z"
}
],
"updated_at": "2022-10-04T16:36:09.933249Z",
"uuid": "0a498284-629e-4629-a55d-0415a6e89dda",
"zone": "fi-hel1"
}
]
Notes:
- Please see service configured statuses and operational states description.
Get service details
Returns load balancer service details by given {service_uuid}.
Request
Normal response
{
"backends": [
{
"created_at": "2022-10-04T16:11:14.569638Z",
"members": [
{
"created_at": "2022-10-04T16:11:14.569638Z",
"enabled": true,
"ip": "172.16.1.4",
"max_sessions": 1000,
"name": "example-member-1",
"port": 8000,
"type": "static",
"updated_at": "2022-10-04T16:11:14.569638Z",
"weight": 100
},
{
"created_at": "2022-10-04T16:11:14.569638Z",
"enabled": true,
"ip": "172.16.1.6",
"max_sessions": 500,
"name": "example-member-2",
"port": 8080,
"type": "static",
"updated_at": "2022-10-04T16:11:14.569638Z",
"weight": 50
}
],
"name": "example-backend-1",
"properties": {
"health_check_expected_status": 200,
"health_check_fall": 5,
"health_check_interval": 10,
"health_check_rise": 5,
"health_check_tls_verify": false,
"health_check_type": "http",
"health_check_on_down": "",
"health_check_url": "/health",
"sticky_session_cookie_name": "x-session",
"timeout_server": 10,
"timeout_tunnel": 3600,
"tls_enabled": false,
"tls_verify": false,
"tls_use_system_ca": false
},
"updated_at": "2022-10-04T16:11:14.569638Z"
},
{
"created_at": "2022-10-04T16:11:14.569638Z",
"members": [
{
"created_at": "2022-10-04T16:11:14.569638Z",
"enabled": true,
"ip": "",
"max_sessions": 1000,
"name": "member.example.com",
"port": 8000,
"type": "dynamic",
"updated_at": "2022-10-04T16:11:14.569638Z",
"weight": 100
}
],
"name": "example-backend-2",
"properties": {
"health_check_expected_status": 200,
"health_check_fall": 3,
"health_check_interval": 10,
"health_check_rise": 3,
"health_check_tls_verify": false,
"health_check_type": "tcp",
"health_check_on_down": "",
"health_check_url": "//:8080",
"sticky_session_cookie_name": "",
"timeout_server": 10,
"timeout_tunnel": 3600,
"tls_enabled": false,
"tls_verify": false,
"tls_use_system_ca": false
},
"resolver": "example-resolver",
"tls_configs": [],
"updated_at": "2022-10-04T16:11:14.569638Z"
}
],
"configured_status": "started",
"created_at": "2022-10-04T16:11:14.569638Z",
"dns_name": "lb-0a498284629e4629a55d0415a6e89dda-1.upcloudlb.com",
"maintenance_dow": "sunday",
"maintenance_time": "20:01:01Z",
"frontends": [
{
"created_at": "2022-10-04T16:11:14.569638Z",
"default_backend": "example-backend-1",
"mode": "http",
"name": "example-frontend",
"networks": [
{
"name": "example-network-1"
}
],
"port": 443,
"properties": {
"timeout_client": 5
},
"rules": [
{
"actions": [
{
"type": "use_backend",
"action_use_backend": {
"backend": "example-backend-2"
}
}
],
"created_at": "2022-10-04T16:11:14.569638Z",
"matchers": [
{
"type": "path",
"inverse": false,
"match_path": {
"method": "exact",
"value": "/app"
}
}
],
"name": "example-rule-1",
"priority": 100,
"updated_at": "2022-10-04T16:11:14.569638Z"
}
],
"tls_configs": [
{
"certificate_bundle_uuid": "0a73c569-a2d1-481a-917f-b0fdafd78136",
"created_at": "2022-10-04T16:11:14.569638Z",
"name": "example-tls-config",
"updated_at": "2022-10-04T16:11:14.569638Z"
}
],
"updated_at": "2022-10-04T16:11:14.569638Z"
}
],
"labels": [
{
"key": "env",
"value": "staging"
},
{
"key": "foo",
"value": "bar"
}
],
"name": "example-service",
"networks": [
{
"created_at": "2022-10-04T16:11:14.569638Z",
"dns_name": "lb-0a498284629e4629a55d0415a6e89dda-1.upcloudlb.com",
"family": "IPv4",
"name": "example-network-1",
"type": "public",
"updated_at": "2022-10-04T16:11:14.569638Z"
},
{
"created_at": "2022-10-04T16:11:14.569638Z",
"dns_name": "lb-0a498284629e4629a55d0415a6e89dda-2.upcloudlb.com",
"family": "IPv4",
"name": "example-network-2",
"type": "private",
"updated_at": "2022-10-04T16:11:14.569638Z",
"uuid": "03631160-d57a-4926-ad48-a2f828229dcb"
}
],
"nodes": [
{
"networks": [
{
"ip_addresses": [
{
"address": "100.127.5.146",
"listen": true
}
],
"name": "example-network-1",
"type": "public"
},
{
"ip_addresses": [
{
"address": "172.16.1.44",
"listen": false
},
{
"address": "172.16.1.45",
"listen": true
}
],
"name": "example-network-2",
"type": "private"
}
],
"operational_state": "running"
}
],
"operational_state": "pending",
"plan": "development",
"resolvers": [
{
"cache_invalid": 10,
"cache_valid": 180,
"created_at": "2022-10-04T16:11:14.569638Z",
"name": "example-resolver",
"nameservers": [
"172.16.1.4:53"
],
"retries": 5,
"timeout": 30,
"timeout_retry": 10,
"updated_at": "2022-10-04T16:11:14.569638Z"
}
],
"updated_at": "2022-10-04T16:36:09.933249Z",
"uuid": "0a498284-629e-4629-a55d-0415a6e89dda",
"zone": "fi-hel1"
}
Notes:
- Please see service configured statuses and operational states description.
Replace service
Replaces existing load balancer service by given {service_uuid}.
Request
{
"name": "example-service",
"plan": "development",
"configured_status": "started",
"maintenance_dow": "sunday",
"maintenance_time": "20:01:01Z",
"frontends": [
{
"name": "example-frontend",
"mode": "http",
"port": 443,
"default_backend": "example-backend-1",
"networks": [
{
"name": "example-network-1"
}
<