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.

Create load balancer

POST
/scopes/{scopeId}/network/load-balancers

Provisions a new load balancer in the active scope from the load balancer creation wizard payload: LB name, VIP subnet and optional fixed VIP address (auto-allocated from the subnet when omitted), flavor (lb.small | lb.standard | lb.large), a first listener (protocol, port, TLS certificate for TERMINATED_HTTPS, connection limit), a first backend pool (protocol, algorithm, session persistence), initial members (address/port/weight) and an optional health monitor (type, delay, timeout, max retries, URL path, expected codes). On acceptance the resource appears in the scoped list with provisioning=PENDING_CREATE. Validation: name non-empty and unique within the scope (409); vipSubnet is the subnet's IDENTIFIER (UUID) — a subnet name is rejected up front with 422 VALIDATION_FAILED — and must reference an accessible subnet, and vipAddress, when given, must be a free address inside it (422 VALIDATION_FAILED / 404 for an unknown subnet); flavor must be a size the region offers (GET /regions/{region}/load-balancer-sizes) → 422 VALIDATION_FAILED on flavor otherwise; listener port 1-65535; tlsCertificate required when listener protocol is TERMINATED_HTTPS; monitor urlPath/expectedCodes only valid for HTTP/HTTPS monitor types. Async & state: Asynchronous — returns 202 with the LoadBalancer resource in provisioning=PENDING_CREATE, operating=OFFLINE. Terminal states: ACTIVE/ONLINE on success, ERROR on failure. resource.updated SSE frames (kind "network.load_balancer", patches to provisioning/operating) drive the UI refresh. Errors: 401 unauthenticated; 403 caller lacks contributor/owner/admin on the scope; 404 referenced VIP subnet or TLS certificate not found; 409 QUOTA_EXCEEDED when the scope's load-balancer quota is exhausted; 422 for any field validation failure; 500 on provisioning-control-plane failure. Idempotency/Concurrency: Idempotency-Key is required; replaying the same key returns the original 202 response without creating a duplicate LB.

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.

Header Parameters

Idempotency-Key*string

Required: 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.

Formatuuid

Request Body

application/json
  1. body

Payload of the load balancer creation wizard (steps 1-5). The listener/pool protocol pair must be one Octavia accepts: HTTP → HTTP|PROXY, HTTPS (TLS passthrough) → HTTPS|TCP|PROXY, TERMINATED_HTTPS → HTTP|PROXY, TCP → HTTP|HTTPS|TCP|PROXY; any other pair is refused 422 VALIDATION_FAILED (field pool.protocol) before anything is created.

name*string

Load balancer name; unique within the scope.

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
vipSubnet*string

Identifier (UUID) of the subnet hosting the VIP, e.g. 8c1f9d4e-2a3b-4c5d-9e8f-0a1b2c3d4e5f. This is the subnet ID as returned by the subnet list/detail endpoints — a subnet NAME is rejected with 422 VALIDATION_FAILED.

vipAddress?|

Fixed VIP address; auto-allocated from the subnet when omitted.

flavor*LbFlavor

Load balancer flavor.

Value in"lb.small""lb.standard""lb.large"
listener*

First-listener configuration from the create-load-balancer wizard (step 2).

pool*

First-pool configuration from the create-load-balancer wizard (step 3).

members?array<>

Initial backend members (wizard step 4).

monitor?|null

Optional health monitor (wizard step 5).

publicIp?boolean

When true, allocate a new public (floating) IP from the region's external pool and bind it to the load balancer's VIP port once the load balancer is ACTIVE. The address is billed like any floating IP and is released when the load balancer is deleted. Association failures (for example a VIP subnet with no router to the external network) are non-fatal: the load balancer still SUCCEEDS without a public IP and the operation carries a warning. Omitted/false leaves the load balancer on its private VIP; a floating IP can be associated later with POST /network/floating-ips/{id}/actions/associate {targetId: }.

Defaultfalse

Response Body

Creation accepted; load balancer returned in provisioning=PENDING_CREATE.

application/json
  1. response

Load balancer read model with embedded listeners and pools, as rendered by the Load balancers page and the load balancer detail page.

origin?string

Where the resource was made -- portal for a create on the console, api for an object made straight against the OpenStack API (CLI, Terraform, the Kubernetes cloud provider) that discovery adopted. Informational; nothing behaves differently. Absent from a backend that predates it, which means portal.

Value in"portal""api""system""imported"
id*string
name*string
description*string
vip*string

Virtual IP address.

vipSubnet*string

Identifier (UUID) of the subnet hosting the VIP — the same value that was supplied on create and that the platform passes to the provider as the VIP subnet id, not a display name.

floatingIp*|

Attached public floating IP, or null.

provisioning*LbProvisioning

Provisioning lifecycle state of a load balancer.

Value in"ACTIVE""PENDING_CREATE""PENDING_UPDATE""PENDING_DELETE""ERROR"
operating*LbOperating

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

Value in"ONLINE""DEGRADED""OFFLINE""ERROR""NO_MONITOR"
statusReasonCode*|

Machine-readable companion to statusReason: a small, OPEN vocabulary of codes the console can branch on without parsing the human text, deliberately a plain string rather than a closed enum so a code the client does not recognize yet degrades to the generic failure message. Today the only value is cancelled: the resource is in its failure state because its create operation was CANCELLED; a provider object the create had already built may be left in place, and the resource's DELETE removes it. Reported only while the resource is in that failure state; null otherwise.

flavor*string

The PRODUCT size the load balancer was created with (lb.small, lb.standard, lb.large). An LB adopted from Octavia reads the size its Octavia flavor maps to, the default size when it runs on the provider default, else the Octavia flavor's own label.

listeners*array<>
pools*array<>
createdAt*string
Formatdate-time
curl -X POST "https://example.com/scopes/string/network/load-balancers" \  -H "Idempotency-Key: 497f6eca-6276-4993-bfeb-53cbbbba6f08" \  -H "Content-Type: application/json" \  -d '{    "name": "string",    "vipSubnet": "string",    "flavor": "lb.small",    "listener": {      "protocol": "HTTP",      "port": 443    },    "pool": {      "protocol": "HTTP",      "algorithm": "ROUND_ROBIN"    }  }'
{  "origin": "portal",  "id": "string",  "name": "string",  "description": "string",  "vip": "string",  "vipSubnet": "string",  "floatingIp": "string",  "provisioning": "ACTIVE",  "operating": "ONLINE",  "statusReasonCode": "string",  "flavor": "string",  "listeners": [    {      "id": "string",      "name": "string",      "protocol": "HTTP",      "port": 0,      "defaultPool": "string",      "connectionLimit": 0,      "tlsCertificate": "string",      "operating": "ONLINE"    }  ],  "pools": [    {      "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"      }    }  ],  "createdAt": "2019-08-24T14:15:22Z"}