Load Balancers

A load balancer distributes incoming TCP traffic from an external IP across a set of target IP addresses on a private network. Each load balancer belongs to a private network, exposes one or more port mappings, and optionally performs health checks against the targets.

Load balancers can be managed directly through the API or automatically via the Cloud Controller Manager when running a Epilayer Kubernetes cluster.

Load Balancer Schema

• id String - A unique identifier for each load balancer. This is automatically generated.
• name String - The human-readable name set for the load balancer.
• region String - The region where the load balancer is located (e.g. NORD-NO-KRS-1).
• mode String - The load balancer mode. Currently always tcp.
• network String - The ID of the private network the load balancer targets reside on.
• ports Array - List of port mappings. See Port Schema.
• health_check Object - Optional health check configuration. See Health Check Schema.
• floating_ip_id String - The ID of the floating IP used as the external IP, if one was specified at creation.
• external_ip String - The external IP assigned to the load balancer. May be null while the load balancer is provisioning.
• status String - The load balancer status. Possible values are creating, active, error and deleting.
• created_at String - A time value given in ISO8601 combined date and time format that represents when the load balancer was created.
• updated_at String - A time value given in ISO8601 combined date and time format that represents when the load balancer was last updated.

Port Schema

• port Integer - The port exposed on the external IP of the load balancer.
• target_port Integer - The port that traffic is forwarded to on each target.
• targets Array - List of target IP addresses (private IPs of your instances).

Health Check Schema

• protocol String - The protocol used for health checks (tcp, http, or https).
• port Integer - The port used for health checks on each target.
• path String - The HTTP path used for http/https health checks. Not required for tcp.

Create a Load Balancer

Please Note: Creating a load balancer results in costs according to Epilayer's pricing.

POST /compute/v1/loadbalancers (HTTP 201 - Created)

Body parameters

• name String _^Required - The human-readable name for the load balancer.
• region String _^Required - The region identifier, see Regions.
• network String _^Required - The private network ID. Targets must be reachable on this network.
• ports Array _^Required - At least one port mapping is required.
• health_check Object _^Optional - Health check configuration.
• floating_ip_id String _^Optional - The ID of an existing floating IP to use as the external IP. When omitted, an ephemeral IP is allocated automatically.

{
  "name": "my-loadbalancer",
  "region": "NORD-NO-KRS-1",
  "network": "3f4e5d6c-7b8a-9012-cdef-1234567890ab",
  "ports": [
    {
      "port": 80,
      "target_port": 8080,
      "targets": ["192.168.10.10", "192.168.10.11"]
    }
  ],
  "health_check": {
    "protocol": "http",
    "port": 8080,
    "path": "/healthz"
  }
}

Response body

{
  "loadbalancer": {
    "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "name": "my-loadbalancer",
    "region": "NORD-NO-KRS-1",
    "mode": "tcp",
    "network": "3f4e5d6c-7b8a-9012-cdef-1234567890ab",
    "ports": [
      {
        "port": 80,
        "target_port": 8080,
        "targets": ["192.168.10.10", "192.168.10.11"]
      }
    ],
    "health_check": {
      "protocol": "http",
      "port": 8080,
      "path": "/healthz"
    },
    "floating_ip_id": null,
    "external_ip": null,
    "status": "creating",
    "created_at": "2024-01-15T10:00:00.000Z",
    "updated_at": "2024-01-15T10:00:00.000Z"
  }
}

The external_ip field will be populated once the load balancer finishes provisioning and its status transitions to active.

List all Load Balancers

GET /compute/v1/loadbalancers (HTTP 200 - OK)

Query parameters

• per_page Integer _^Optional - A positive integer lower or equal to 100 (default: 50).
• page Integer _^Optional - A positive integer to choose the page to return.

Response body

{
  "loadbalancers": [
    {
      "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "name": "my-loadbalancer",
      "region": "NORD-NO-KRS-1",
      "mode": "tcp",
      "network": "3f4e5d6c-7b8a-9012-cdef-1234567890ab",
      "ports": [
        {
          "port": 80,
          "target_port": 8080,
          "targets": ["192.168.10.10", "192.168.10.11"]
        }
      ],
      "health_check": null,
      "floating_ip_id": null,
      "external_ip": "194.61.21.92",
      "status": "active",
      "created_at": "2024-01-15T10:00:00.000Z",
      "updated_at": "2024-01-15T10:01:30.000Z"
    }
  ],
  "total_count": 1,
  "page": 1,
  "per_page": 50
}

Get a Load Balancer

GET /compute/v1/loadbalancers/{loadbalancer_id} (HTTP 200 - OK)

Path parameters

• loadbalancer_id String - Load balancer ID.

Response body

See Load Balancer Schema.

Update a Load Balancer

Update the port mappings, health check, name, or floating IP of a load balancer. The network and region cannot be changed.

PATCH /compute/v1/loadbalancers/{loadbalancer_id} (HTTP 200 - OK)

Path parameters

• loadbalancer_id String - Load balancer ID.

Body parameters

• name String _^Optional - New name for the load balancer.
• ports Array _^Optional - Replaces the full list of port mappings (at least one required when provided).
• health_check Object _^Optional - New health check configuration.
• floating_ip_id String _^Optional - ID of a floating IP to assign as the external IP.

{
  "ports": [
    {
      "port": 80,
      "target_port": 8080,
      "targets": ["192.168.10.10", "192.168.10.11", "192.168.10.12"]
    },
    {
      "port": 443,
      "target_port": 8443,
      "targets": ["192.168.10.10", "192.168.10.11", "192.168.10.12"]
    }
  ]
}

Response body

{
  "loadbalancer": {
    "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "name": "my-loadbalancer",
    "region": "NORD-NO-KRS-1",
    "mode": "tcp",
    "network": "3f4e5d6c-7b8a-9012-cdef-1234567890ab",
    "ports": [
      {
        "port": 80,
        "target_port": 8080,
        "targets": ["192.168.10.10", "192.168.10.11", "192.168.10.12"]
      },
      {
        "port": 443,
        "target_port": 8443,
        "targets": ["192.168.10.10", "192.168.10.11", "192.168.10.12"]
      }
    ],
    "health_check": null,
    "floating_ip_id": null,
    "external_ip": "194.61.21.92",
    "status": "active",
    "created_at": "2024-01-15T10:00:00.000Z",
    "updated_at": "2024-01-15T11:00:00.000Z"
  }
}

Delete a Load Balancer

DELETE /compute/v1/loadbalancers/{loadbalancer_id} (HTTP 204 - No Content)

Path parameters

• loadbalancer_id String - Load balancer ID.

Examples (cURL)

# Create a load balancer
curl -H "Authorization: Bearer $TOKEN" \
  -X POST "https://public-api.krs-1.epilayer.eu/compute/v1/loadbalancers" \
  -H "Content-Type: application/json" \
  --data-raw '{
    "name": "my-loadbalancer",
    "region": "NORD-NO-KRS-1",
    "network": "3f4e5d6c-7b8a-9012-cdef-1234567890ab",
    "ports": [
      {
        "port": 80,
        "target_port": 8080,
        "targets": ["192.168.10.10", "192.168.10.11"]
      }
    ]
  }'

# List all load balancers
curl -H "Authorization: Bearer $TOKEN" \
  "https://public-api.krs-1.epilayer.eu/compute/v1/loadbalancers"

# Get a load balancer
curl -H "Authorization: Bearer $TOKEN" \
  "https://public-api.krs-1.epilayer.eu/compute/v1/loadbalancers/<loadbalancer_id>"

# Update the targets on an existing load balancer
curl -H "Authorization: Bearer $TOKEN" \
  -X PATCH "https://public-api.krs-1.epilayer.eu/compute/v1/loadbalancers/<loadbalancer_id>" \
  -H "Content-Type: application/json" \
  --data-raw '{
    "ports": [
      {
        "port": 80,
        "target_port": 8080,
        "targets": ["192.168.10.10", "192.168.10.11", "192.168.10.12"]
      }
    ]
  }'

# Delete a load balancer
curl -H "Authorization: Bearer $TOKEN" \
  -X DELETE "https://public-api.krs-1.epilayer.eu/compute/v1/loadbalancers/<loadbalancer_id>"