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
Attaches or re-points the router's external gateway (the "Set gateway" row action in the Routers page) to the
external network identified by gatewayId, allocating an external IP from that network's floating pool,
with SNAT on (snatEnabled: false is refused with 422 VALIDATION_FAILED). On success the router's
externalGateway block reflects the new external network, allocated externalIp, and snatEnabled, enabling north-south traffic for
all connected subnets.
Validation: router must exist and be visible in scope → 404 NOT_FOUND; gatewayId must reference an
existing network flagged as external → 404 NOT_FOUND on unknown reference, 422 VALIDATION_FAILED when the
network is not external; the current router state must permit a gateway change (no deletion or competing
gateway transition in flight) → 409 CONFLICT.
Async & state: Asynchronous — returns 202 with the Router resource showing the new gateway in transitional
form while the dataplane programs it (router status moves through BUILD); resource.updated SSE frames
with kind: network.router patch externalGateway and status to terminal ACTIVE on success or ERROR
if external IP allocation or programming fails.
Errors: 401 unauthenticated; 403 caller lacks contributor/owner/admin rights; 404 unknown router or
unknown gateway network; 409 conflicting gateway transition or deletion in progress; 422 target network is
not an external network, or snatEnabled: false; 500 internal failure.
Idempotency/Concurrency: Idempotency-Key is optional (recommended); replaying the same
key returns the original 202
response (same allocated external IP) instead of re-allocating. Setting the gateway to the already-attached
network is a no-op that completes immediately.
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.
gatewayId*stringIdentifier of the external network to use as the router gateway.
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 change accepted; the router is returned with the gateway in transitional state.
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/string/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"}