Networking

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.

Update backend pool

PATCH
/scopes/{scopeId}/network/load-balancers/{loadBalancerId}/pools/{poolId}

Updates one backend pool of the load balancer ("Save pool" in the Backend pools tab): name, algorithm (ROUND_ROBIN | LEAST_CONNECTIONS | SOURCE_IP) and sessionPersistence (SOURCE_IP | HTTP_COOKIE | APP_COOKIE | null for none). Every one of these lives in the provider (Octavia), so the update is asynchronous: the request is accepted with 202, a tracking operation loadbalancer.load_balancer.pool.update is opened, and a worker applies the fields to the Octavia pool before updating the platform record. protocol cannot change on an existing pool. Validation: empty body → 422; parent LB and pool must exist in the scope (404); the LB must accept child changes — not PENDING_CREATE/PENDING_DELETE, not ERROR, and already present in the provider (409 CONFLICT); a protocol change or an invalid enum value → 422 VALIDATION_FAILED. Async & state: Always asynchronous: 202 with the pool as it will read once applied. Poll the operation (or watch resource.updated SSE frames, kind "network.load_balancer", patch to pools). Errors: 401 unauthenticated; 403 insufficient role; 404 unknown LB or pool; 409 state conflict; 422 invalid fields; 500 backend failure. Idempotency/Concurrency: Idempotency-Key is optional; a retry with the same key and body replays the original 202, a different body under the same key is 409. If-Match is not evaluated for pool updates.

Authorization

bearerToken
headerAuthorizationBearer <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.

Path Parameters

scopeId*string

Opaque ownership+authorization scope resolving to tenant + subscription + project.

loadBalancerId*string
poolId*string

Header Parameters

Idempotency-Key?string

Optional; recommended for safe retries. When sent, the same key+body within 24h replays the original result and the same key with a different body is 409 CONFLICT; keys are unique per tenant. When an API token or service-account (bearer) caller omits it, the request is applied once with no replay protection (a retry may apply it again). A console session gets one from the edge.

Formatuuid

Request Body

application/json
  1. body

Partial update for a backend pool; only supplied fields change.

name?string

New backend pool name.

Match^[^\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}])?$
Length1 <= length <= 255
protocol?LbPoolProtocol

Backend pool protocol.

Value in"HTTP""HTTPS""TCP""PROXY"
algorithm?LbAlgorithm

Load-balancing algorithm.

Value in"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.

Match^[A-Za-z0-9!#$%&*+.^_`|~-]{1,255}$

Response Body

Update accepted; the pool as it will read once the tracking operation settles.

application/json
  1. response

Backend pool of a load balancer, with embedded members and optional health monitor.

id*string
name*string
protocol*LbPoolProtocol

Backend pool protocol.

Value in"HTTP""HTTPS""TCP""PROXY"
algorithm*LbAlgorithm

Load-balancing algorithm.

Value in"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*LbOperating

Operating (health) state of a load balancer or one of its sub-resources.

Value in"ONLINE""DEGRADED""OFFLINE""ERROR""NO_MONITOR"
members*array<>
monitor*|null
curl -X PATCH "https://example.com/scopes/string/network/load-balancers/string/pools/string" \  -H "Content-Type: application/json" \  -d '{}'
{  "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"  }}