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.
Set external gateway (server-picked external network)
Attaches an external gateway to the router WITHOUT naming the external network: the server
picks one at random from the external networks the scope may use as a gateway in the
router's region (the same allow-list router create auto-picks from). This is the form the
console's "Set gateway" action calls; the body carries only the SNAT flag. On success the
router's externalGateway reflects the picked network and its allocated external IP.
Validation: router must exist and be visible in scope → 404 NOT_FOUND; snatEnabled: false is refused 422 VALIDATION_FAILED (field snatEnabled) — the project credential can
only attach a gateway with SNAT on; unknown body properties → 422; no external
network available to the scope in the region → 412
PRECONDITION_FAILED. All checks run before any operation exists, so a refused request has
no side effects.
RBAC: MANAGE on network plus the network:write token scope. A tenant on non-payment
hold is read-only → 403.
Async & state: Asynchronous — returns 202 with the Router in transitional BUILD status;
a tracking Operation (network.router.set_gateway) is opened and the worker settles the
router ACTIVE with the gateway recorded, or ERROR.
Errors: 401 unauthenticated; 403 caller lacks network MANAGE / token scope, or tenant on
hold; 404 unknown router; 409 the same Idempotency-Key is in flight, or was used with a
different body; 412 no eligible external network; 422 invalid body or SNAT disable; 500
internal failure.
Idempotency/Concurrency: Idempotency-Key is optional (recommended); replaying the same
key and body
returns the original 202 response instead of re-issuing the attach.
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.
routerId*stringIdentifier of the router.
region?stringRegion whose external networks are candidates; defaults to the router's own region.
Idempotency-Key?stringOptional; 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.
uuidapplication/json- body
Options for attaching the router's external gateway. SNAT is always on for a gateway the platform attaches; the only accepted snatEnabled value is true.
snatEnabled?booleanSNAT on the newly attached gateway. Only true can be honoured; false is refused 422 VALIDATION_FAILED (field snatEnabled).
trueGateway attach accepted; the router is returned in transitional BUILD status.
application/json- response
Virtual router connecting subnets and reaching external networks.
origin?stringWhere 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.
"portal""api""system""imported"id*stringRouter identifier.
name*stringRouter name (lowercase letters, numbers, hyphens; max 63 chars).
status*NetworkStatusLifecycle status shared by networking resources.
"ACTIVE""DOWN""BUILD""ERROR"statusReason*|Human-readable reason the last lifecycle command on this router failed (e.g. the Neutron message of a refused create or gateway attach); null once a later command settles the router healthy, or when nothing failed. Mirrors VirtualNetwork.statusReason. A router whose create failed after the Neutron router already existed shows the provider's real status, gateway, interfaces and routes, with the failure explained here.
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.
adminStateUp*booleanAdministrative state of the router.
ha*booleanHigh availability (active/standby pair) enabled.
distributed*booleanDistributed virtual router (DVR) mode.
externalGateway*|nullExternal gateway attachment, or null when the router is internal-only.
interfaces*array<>Internal interfaces attached to the router.
routes*array<>Static routes configured on the router.
createdAt*stringCreation timestamp (ISO 8601).
date-timecurl -X POST "https://example.com/scopes/string/network/routers/string/gateways/actions/set-gateway" \ -H "Content-Type: application/json" \ -d '{}'{ "origin": "portal", "id": "string", "name": "string", "status": "ACTIVE", "statusReason": "string", "statusReasonCode": "string", "adminStateUp": true, "ha": true, "distributed": true, "externalGateway": { "externalNetwork": "string", "externalIp": "string", "snatEnabled": true }, "interfaces": [ { "id": "string", "subnet": "string", "network": "string", "fixedIp": "string", "status": "ACTIVE", "platformManaged": true } ], "routes": [ { "id": "string", "destination": "string", "nexthop": "string" } ], "createdAt": "2019-08-24T14:15:22Z"}