Load Balancers

A Managed Load Balancer works as the network-level frontend of your application by directing connections to backend servers. Load balancers are available in every UpCloud zone.

It is recommended to use the hostnames of your load balancer when directing your domain to it. For subdomains, use CNAME. For the primary domain, use ALIAS or whatever is supported by your DNS provider.

GET/1.3/load-balancer/plans

List plans

Returns a list of available load balancer plans.

Query parameters

Name
limit
Type
integer
Description
Number of entries to receive (0-100). Default: 10.
Name
offset
Type
integer
Description
Offset for retrieved results. Default: 0.

Request

GET

/1.3/load-balancer/plans

curl -X GET https://api.upcloud.com/1.3/load-balancer/plans \
  -u your_username:your_password

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

Get plan details

Returns detailed information about a specific load balancer plan.

Request

GET

/1.3/load-balancer/plans/{name}

curl -X GET https://api.upcloud.com/1.3/load-balancer/plans/production-small \
  -u your_username:your_password

GET/1.3/load-balancer

List services

Returns a list of all load balancer services in the account.

Query parameters

Name
limit
Type
integer
Description
Number of entries to receive. Default: 10.
Name
offset
Type
integer
Description
Offset for retrieved results.
Name
label
Type
string
Description
Filter by label (e.g., ?label=env=prod).

Request

GET

/1.3/load-balancer

curl -X GET https://api.upcloud.com/1.3/load-balancer \
  -u your_username:your_password

GET/1.3/load-balancer/{uuid}

Get service details

Returns detailed information about a specific load balancer service.

Request

GET

/1.3/load-balancer/{uuid}

curl -X GET https://api.upcloud.com/1.3/load-balancer/0a1b2c3d-4e5f-6789-abcd-ef0123456789 \
  -u your_username:your_password

POST/1.3/load-balancer

Create service

Creates a new load balancer service.

Attributes

Name
name
Type
string
Description
Service name (1-255 chars). Required.
Name
plan
Type
string
Description
Plan name (e.g., "development", "production-small"). Required.
Name
zone
Type
string
Description
Zone identifier. Required.
Name
configured_status
Type
string
Description
Initial status: "started" or "stopped". Default: "started".
Name
frontends
Type
array
Description
Frontend configurations.
Name
backends
Type
array
Description
Backend configurations.
Name
resolvers
Type
array
Description
DNS resolver configurations.
Name
networks
Type
array
Description
Network configurations. Required.
Name
labels
Type
array
Description
Labels for classification.
Name
maintenance_dow
Type
string
Description
Maintenance day of week.
Name
maintenance_time
Type
string
Description
Maintenance time (HH:MM:SSZ).

Request

POST

/1.3/load-balancer

curl -X POST https://api.upcloud.com/1.3/load-balancer \
  -u your_username:your_password \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-load-balancer",
    "plan": "development",
    "zone": "fi-hel1",
    "configured_status": "started",
    "networks": [
      {
        "name": "public",
        "type": "public",
        "family": "IPv4"
      }
    ],
    "frontends": [
      {
        "name": "http-frontend",
        "mode": "http",
        "port": 80,
        "default_backend": "web-backend"
      }
    ],
    "backends": [
      {
        "name": "web-backend",
        "members": [
          {
            "name": "server-1",
            "type": "static",
            "ip": "10.0.0.10",
            "port": 8080,
            "weight": 100,
            "enabled": true
          }
        ]
      }
    ],
    "labels": [
      {"key": "env", "value": "prod"}
    ]
  }'

PATCH/1.3/load-balancer/{uuid}

Modify service

Modifies an existing load balancer service. Uses JSON Merge Patch semantics.

Attributes

Name
name
Type
string
Description
Service name.
Name
plan
Type
string
Description
Plan name.
Name
configured_status
Type
string
Description
Status: "started" or "stopped".
Name
maintenance_dow
Type
string
Description
Maintenance day of week.
Name
maintenance_time
Type
string
Description
Maintenance time.
Name
labels
Type
array
Description
Labels for classification.

Request

PATCH

/1.3/load-balancer/{uuid}

curl -X PATCH https://api.upcloud.com/1.3/load-balancer/0a1b2c3d-4e5f-6789-abcd-ef0123456789 \
  -u your_username:your_password \
  -H "Content-Type: application/json" \
  -d '{
    "name": "updated-load-balancer",
    "plan": "production-small",
    "maintenance_dow": "sunday",
    "maintenance_time": "04:00:00Z"
  }'

DELETE/1.3/load-balancer/{uuid}

Delete service

Deletes a load balancer service.

Request

DELETE

/1.3/load-balancer/{uuid}

curl -X DELETE https://api.upcloud.com/1.3/load-balancer/0a1b2c3d-4e5f-6789-abcd-ef0123456789 \
  -u your_username:your_password