Preview — pending review
This reference is generated from the platform API contract and is still under review. Operations, fields, and descriptions can change before publication.
Add backend pool
Adds a new backend pool to the load balancer from the inline "Add pool" row in the Backend pools tab:
name, protocol (HTTP | HTTPS | TCP | PROXY) and balancing algorithm (ROUND_ROBIN | LEAST_CONNECTIONS |
SOURCE_IP). The pool starts with no members, no health monitor, sessionPersistence=null and
operating=NO_MONITOR; it becomes discoverable in the LB's pools array when accepted and can then receive
targets and a monitor.
Validation: parent load balancer must exist in the scope and not be PENDING_DELETE (404 / 409
CONFLICT); name non-empty and unique among the LB's pools (409 CONFLICT); protocol and algorithm
must be one of the supported enum values (422 VALIDATION_FAILED); sessionPersistence, when supplied,
must be SOURCE_IP, HTTP_COOKIE or APP_COOKIE (422); contributor/owner/admin role is required (403).
Async & state: Asynchronous — returns 202 with the LbPool resource (operating=NO_MONITOR) while the
parent LB passes through provisioning=PENDING_UPDATE → ACTIVE. resource.updated SSE frames (kind
"network.load_balancer", patch to pools and provisioning) refresh the pools table.
Errors: 401 unauthenticated; 403 insufficient role; 404 unknown load balancer; 409 duplicate pool name
or LB state conflict; 422 invalid protocol/algorithm/persistence; 500 backend failure.
Idempotency/Concurrency: Idempotency-Key is required; replaying the same key returns the originally
created pool instead of creating a duplicate.
bearerTokenAuthorizationBearer <token>An API token (pc_live_…) or a service-account key (sak_live_…), created in Identity & Access Management and sent as Authorization: Bearer <token>. Requests are rate limited per credential and per tenant: every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset, and a refused request gets 429 RATE_LIMITED with Retry-After.
scopeId*stringOpaque ownership+authorization scope resolving to tenant + subscription + project.
loadBalancerId*stringIdempotency-Key*stringRequired: this operation creates a new resource asynchronously, so a retry without the key would create a second one. Same key+body within 24h replays the original result; the same key with a different body is 409 CONFLICT. Keys are unique per tenant (the same key in two tenants is two different requests). An API token or service-account (bearer) caller MUST send it -- a request without it is refused with 400 IDEMPOTENCY_KEY_REQUIRED (ErrIdempotencyKeyRequired); reuse the same key on every retry of one logical request. A console session gets one from the edge.
uuidapplication/json- body
Inline "Add pool" row payload; the pool starts with no members, no monitor and sessionPersistence=null.
name*stringBackend pool name; unique within the load balancer.
^[^\p{C}\p{Z}\x{10000}-\x{10FFFF}](?:[^\p{C}\p{Zl}\p{Zp}\x{10000}-\x{10FFFF}]*[^\p{C}\p{Z}\x{10000}-\x{10FFFF}])?$1 <= length <= 255protocol*LbPoolProtocolBackend pool protocol.
"HTTP""HTTPS""TCP""PROXY"algorithm*LbAlgorithmLoad-balancing algorithm.
"ROUND_ROBIN""LEAST_CONNECTIONS""SOURCE_IP"sessionPersistence?|cookieName?|Name of the application cookie Octavia sticks sessions to. Required when sessionPersistence is APP_COOKIE (422 VALIDATION_FAILED otherwise) and refused with any other persistence.
^[A-Za-z0-9!#$%&*+.^_`|~-]{1,255}$Pool creation accepted; pool returned while the LB reconfigures.
application/json- response
Backend pool of a load balancer, with embedded members and optional health monitor.
id*stringname*stringprotocol*LbPoolProtocolBackend pool protocol.
"HTTP""HTTPS""TCP""PROXY"algorithm*LbAlgorithmLoad-balancing algorithm.
"ROUND_ROBIN""LEAST_CONNECTIONS""SOURCE_IP"sessionPersistence*|Session persistence mode (SOURCE_IP, HTTP_COOKIE, APP_COOKIE) or null for none.
cookieName?|The APP_COOKIE cookie name, or null.
operating*LbOperatingOperating (health) state of a load balancer or one of its sub-resources.
"ONLINE""DEGRADED""OFFLINE""ERROR""NO_MONITOR"members*array<>monitor*|nullcurl -X POST "https://example.com/scopes/string/network/load-balancers/string/pools" \ -H "Idempotency-Key: 497f6eca-6276-4993-bfeb-53cbbbba6f08" \ -H "Content-Type: application/json" \ -d '{ "name": "string", "protocol": "HTTP", "algorithm": "ROUND_ROBIN" }'{ "id": "string", "name": "string", "protocol": "HTTP", "algorithm": "ROUND_ROBIN", "sessionPersistence": "string", "cookieName": "string", "operating": "ONLINE", "members": [ { "id": "string", "name": "string", "address": "string", "port": 0, "weight": 0, "operating": "ONLINE", "backupMember": true } ], "monitor": { "id": "string", "type": "HTTP", "delay": 0, "timeout": 0, "maxRetries": 0, "httpMethod": "string", "urlPath": "string", "expectedCodes": "string", "operating": "ONLINE" }}