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 load balancer settings

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

Renames the load balancer. name is held by the provider (Octavia) as well as the platform, so a rename is an asynchronous provider change, not a metadata-only edit: the request is accepted with 202, a tracking operation loadbalancer.load_balancer.update is opened, and a worker renames the Octavia load balancer first and the platform record second. Until the operation settles, reads still return the old name; the 202 body is the load balancer as it will read once the rename is applied. A load balancer whose create never reached the provider has nothing to rename there, so only the platform record changes. The data-plane fields of the body (vipSubnet, vipAddress, flavor, listener, pool, monitor) are not yet supported and are rejected with 422 VALIDATION_FAILED rather than ignored. Validation: empty body → 422; load balancer must exist in scope (404); provisioning must not be PENDING_CREATE/PENDING_DELETE (409 CONFLICT); a load balancer in ERROR that exists in the provider is rejected with 409 CONFLICT (the provider refuses to modify it — delete it and create a new one); a data-plane field → 422 VALIDATION_FAILED. Async & state: Always asynchronous: 202 with the LoadBalancer. Poll the operation (or watch resource.updated SSE frames, kind "network.load_balancer") for SUCCEEDED / FAILED. Errors: 401 unauthenticated; 403 caller lacks contributor/owner/admin; 404 unknown LB; 409 state conflict; 412 missing or stale If-Match; 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 REQUIRED for this operation: send the ETag from the last read; a missing or stale value yields 412 PRECONDITION_FAILED.

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

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
If-Match?string

ETag for optimistic concurrency on mutations/deletes; mismatch results in 412.

Request Body

application/json
  1. body

Partial update for a load balancer (Edit action); same field set as create, all optional.

name?string

New load balancer 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
vipSubnet?string

Identifier (UUID) of the subnet hosting the VIP; a subnet NAME is rejected with 422 VALIDATION_FAILED (same rule as create).

vipAddress?string|null
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).

monitor?|null

Response Body

Rename accepted; the load balancer as it will read once the tracking operation settles.

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 PATCH "https://example.com/scopes/string/network/load-balancers/string" \  -H "Content-Type: application/json" \  -d '{}'
{  "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"}