UpCloud

Load Balancer Backends

Backends define the pool of servers that receive traffic from the load balancer. Configure health checks, load balancing algorithms, and member servers.

GET/1.3/load-balancer/{lb_uuid}/backends

List backends

Returns a list of backends for a load balancer.

Request

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

Get backend details

Returns details of a specific backend.

Request

GET
/1.3/load-balancer/{lb_uuid}/backends/{name}
curl -X GET https://api.upcloud.com/1.3/load-balancer/0a1b2c3d-4e5f-6789-abcd-ef0123456789/backends/web-backend \
  -u your_username:your_password
POST/1.3/load-balancer/{lb_uuid}/backends

Create backend

Creates a new backend for the load balancer.

Attributes

  • Name
    name
    Type
    string
    Description

    Backend name (1-255 chars). Required.

  • Name
    resolver
    Type
    string
    Description

    DNS resolver name for dynamic members.

  • Name
    members
    Type
    array
    Description

    Backend member configurations.

  • Name
    properties
    Type
    object
    Description

    Backend properties including health checks.

  • Name
    tls_configs
    Type
    array
    Description

    TLS configurations for backend connections.

Backend properties

  • Name
    health_check_type
    Type
    string
    Description

    Type: "tcp", "http", or "https".

  • Name
    health_check_interval
    Type
    integer
    Description

    Check interval in seconds.

  • Name
    health_check_fall
    Type
    integer
    Description

    Failed checks before marking unhealthy.

  • Name
    health_check_rise
    Type
    integer
    Description

    Successful checks before marking healthy.

  • Name
    health_check_url
    Type
    string
    Description

    URL path for HTTP health checks.

  • Name
    health_check_expected_status
    Type
    integer
    Description

    Expected HTTP status code.

Request

POST
/1.3/load-balancer/{lb_uuid}/backends
curl -X POST https://api.upcloud.com/1.3/load-balancer/0a1b2c3d-4e5f-6789-abcd-ef0123456789/backends \
  -u your_username:your_password \
  -H "Content-Type: application/json" \
  -d '{
    "name": "api-backend",
    "properties": {
      "health_check_type": "http",
      "health_check_interval": 10,
      "health_check_fall": 3,
      "health_check_rise": 2,
      "health_check_url": "/health",
      "health_check_expected_status": 200
    }
  }'
PATCH/1.3/load-balancer/{lb_uuid}/backends/{name}

Modify backend

Modifies an existing backend configuration.

Request

PATCH
/1.3/load-balancer/{lb_uuid}/backends/{name}
curl -X PATCH https://api.upcloud.com/1.3/load-balancer/0a1b2c3d-4e5f-6789-abcd-ef0123456789/backends/api-backend \
  -u your_username:your_password \
  -H "Content-Type: application/json" \
  -d '{
    "properties": {
      "health_check_interval": 30
    }
  }'
DELETE/1.3/load-balancer/{lb_uuid}/backends/{name}

Delete backend

Deletes a backend. The backend must not be referenced by any frontend.

Request

DELETE
/1.3/load-balancer/{lb_uuid}/backends/{name}
curl -X DELETE https://api.upcloud.com/1.3/load-balancer/0a1b2c3d-4e5f-6789-abcd-ef0123456789/backends/api-backend \
  -u your_username:your_password
GET/1.3/load-balancer/{lb_uuid}/backends/{backend_name}/members

List members

Returns a list of members for a backend.

Request

GET
/1.3/load-balancer/{lb_uuid}/backends/{backend_name}/members
curl -X GET https://api.upcloud.com/1.3/load-balancer/0a1b2c3d-4e5f-6789-abcd-ef0123456789/backends/web-backend/members \
  -u your_username:your_password
POST/1.3/load-balancer/{lb_uuid}/backends/{backend_name}/members

Create static member

Creates a static backend member with a fixed IP address.

Attributes

  • Name
    name
    Type
    string
    Description

    Member name. Required.

  • Name
    type
    Type
    string
    Description

    Set to "static". Required.

  • Name
    ip
    Type
    string
    Description

    IP address of the server. Required.

  • Name
    port
    Type
    integer
    Description

    Target port (1-65535). Required.

  • Name
    weight
    Type
    integer
    Description

    Load balancing weight (1-100). Default: 100.

  • Name
    max_sessions
    Type
    integer
    Description

    Maximum concurrent sessions.

  • Name
    enabled
    Type
    boolean
    Description

    Whether the member accepts traffic. Default: true.

Request

POST
/1.3/load-balancer/{lb_uuid}/backends/{backend_name}/members
curl -X POST https://api.upcloud.com/1.3/load-balancer/0a1b2c3d-4e5f-6789-abcd-ef0123456789/backends/web-backend/members \
  -u your_username:your_password \
  -H "Content-Type: application/json" \
  -d '{
    "name": "server-3",
    "type": "static",
    "ip": "10.0.0.12",
    "port": 8080,
    "weight": 100,
    "max_sessions": 2000,
    "enabled": true
  }'
POST/1.3/load-balancer/{lb_uuid}/backends/{backend_name}/members

Create dynamic member

Creates a dynamic backend member resolved via DNS. Requires a resolver configured on the backend.

Attributes

  • Name
    name
    Type
    string
    Description

    Member name. Required.

  • Name
    type
    Type
    string
    Description

    Set to "dynamic". Required.

  • Name
    weight
    Type
    integer
    Description

    Load balancing weight (1-100). Default: 100.

  • Name
    max_sessions
    Type
    integer
    Description

    Maximum concurrent sessions.

  • Name
    enabled
    Type
    boolean
    Description

    Whether the member accepts traffic. Default: true.

Request

POST
/1.3/load-balancer/{lb_uuid}/backends/{backend_name}/members
curl -X POST https://api.upcloud.com/1.3/load-balancer/0a1b2c3d-4e5f-6789-abcd-ef0123456789/backends/web-backend/members \
  -u your_username:your_password \
  -H "Content-Type: application/json" \
  -d '{
    "name": "dynamic-servers",
    "type": "dynamic",
    "weight": 100,
    "enabled": true
  }'
PATCH/1.3/load-balancer/{lb_uuid}/backends/{backend_name}/members/{member_name}

Modify member

Modifies a backend member configuration.

Request

PATCH
/1.3/load-balancer/{lb_uuid}/backends/{backend_name}/members/{member_name}
curl -X PATCH https://api.upcloud.com/1.3/load-balancer/0a1b2c3d-4e5f-6789-abcd-ef0123456789/backends/web-backend/members/server-1 \
  -u your_username:your_password \
  -H "Content-Type: application/json" \
  -d '{
    "weight": 50,
    "enabled": false
  }'
DELETE/1.3/load-balancer/{lb_uuid}/backends/{backend_name}/members/{member_name}

Delete member

Deletes a member from the backend.

Request

DELETE
/1.3/load-balancer/{lb_uuid}/backends/{backend_name}/members/{member_name}
curl -X DELETE https://api.upcloud.com/1.3/load-balancer/0a1b2c3d-4e5f-6789-abcd-ef0123456789/backends/web-backend/members/server-1 \
  -u your_username:your_password
GET/1.3/load-balancer/{lb_uuid}/backends/{backend_name}/tls-configs

List TLS configs

Returns a list of TLS configurations for a backend. Backend TLS configs are used for encrypted connections between the load balancer and backend servers.

Request

GET
/1.3/load-balancer/{lb_uuid}/backends/{backend_name}/tls-configs
curl -X GET https://api.upcloud.com/1.3/load-balancer/0a1b2c3d-4e5f-6789-abcd-ef0123456789/backends/web-backend/tls-configs \
  -u your_username:your_password
GET/1.3/load-balancer/{lb_uuid}/backends/{backend_name}/tls-configs/{name}

Get TLS config details

Returns details of a specific backend TLS configuration.

Request

GET
/1.3/load-balancer/{lb_uuid}/backends/{backend_name}/tls-configs/{name}
curl -X GET https://api.upcloud.com/1.3/load-balancer/0a1b2c3d-4e5f-6789-abcd-ef0123456789/backends/web-backend/tls-configs/backend-tls \
  -u your_username:your_password
POST/1.3/load-balancer/{lb_uuid}/backends/{backend_name}/tls-configs

Create TLS config

Creates a TLS configuration for encrypted backend connections.

Attributes

  • Name
    name
    Type
    string
    Description

    TLS config name (1-255 chars).

  • Name
    certificate_bundle_uuid
    Type
    string
    Description

    UUID of the certificate bundle for client authentication.

Request

POST
/1.3/load-balancer/{lb_uuid}/backends/{backend_name}/tls-configs
curl -X POST https://api.upcloud.com/1.3/load-balancer/0a1b2c3d-4e5f-6789-abcd-ef0123456789/backends/web-backend/tls-configs \
  -u your_username:your_password \
  -H "Content-Type: application/json" \
  -d '{
    "name": "backend-tls",
    "certificate_bundle_uuid": "abc123-def456-789012"
  }'
PATCH/1.3/load-balancer/{lb_uuid}/backends/{backend_name}/tls-configs/{name}

Modify TLS config

Modifies an existing backend TLS configuration.

Attributes

  • Name
    name
    Type
    string
    Description

    Updated TLS config name.

  • Name
    certificate_bundle_uuid
    Type
    string
    Description

    Updated certificate bundle UUID.

Request

PATCH
/1.3/load-balancer/{lb_uuid}/backends/{backend_name}/tls-configs/{name}
curl -X PATCH https://api.upcloud.com/1.3/load-balancer/0a1b2c3d-4e5f-6789-abcd-ef0123456789/backends/web-backend/tls-configs/backend-tls \
  -u your_username:your_password \
  -H "Content-Type: application/json" \
  -d '{
    "certificate_bundle_uuid": "new-bundle-uuid-123456"
  }'
DELETE/1.3/load-balancer/{lb_uuid}/backends/{backend_name}/tls-configs/{name}

Delete TLS config

Deletes a TLS configuration from a backend.

Request

DELETE
/1.3/load-balancer/{lb_uuid}/backends/{backend_name}/tls-configs/{name}
curl -X DELETE https://api.upcloud.com/1.3/load-balancer/0a1b2c3d-4e5f-6789-abcd-ef0123456789/backends/web-backend/tls-configs/backend-tls \
  -u your_username:your_password