Skip to content

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

GET /1.3/load-balancer/plans HTTP/1.1

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

HTTP/1.1 200 OK
[
    {
        "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

GET /1.3/load-balancer/plans/{name} HTTP/1.1

Normal response

HTTP/1.1 200 OK
{
    "name": "development",
    "per_server_max_sessions": 10000,
    "server_number": 1
}

Create service

Creates a new load balancer service.

Request

POST /1.3/load-balancer HTTP/1.1
{
    "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

HTTP/1.1 201 Created

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

GET /1.3/load-balancer HTTP/1.1

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

HTTP/1.1 200 OK
[
    {
        "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:

Get service details

Returns load balancer service details by given {service_uuid}.

Request

GET /1.3/load-balancer/{service_uuid} HTTP/1.1

Normal response

HTTP/1.1 200 OK
{
    "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:

Replace service

Replaces existing load balancer service by given {service_uuid}.

Request

PUT /1.3/load-balancer/{service_uuid} HTTP/1.1
{
    "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"
                }
            ],
            "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": "0aded5c1-c7a3-498a-b9c8-a871611c47a2"
                }
            ],
            "properties": {
                "timeout_client": 15,
                "inbound_proxy_protocol": true
            }
        }
    ],
    "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.5",
                    "port": 8080,
                    "type": "static",
                    "weight": 50