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 a VPN service on a router
Creates one VPN service anchored on a router in the active scope. The service is a standalone resource:
it is created before any connection exists and may then carry many site connections.
The service deliberately carries no subnet. neutron-VPNaaS's own validator
(validate_ipsec_conn_optional_args) makes the two models mutually exclusive: a service WITH a subnet
forces every connection to use flat peerCidrs and forbids endpoint groups, while a service WITHOUT a
subnet requires both a local and a peer endpoint group. This API models endpoint groups as first-class
resources, so the service is always created subnet-less and the local subnet is carried by the
connection's local endpoint group.
Validation: name must be non-empty and unique within the scope (duplicate -> 409 CONFLICT); routerId
must reference an existing router in the scope that HAS an external gateway (unknown -> 404 NOT_FOUND,
gateway-less -> 422 VALIDATION_FAILED, field routerId) - a site-to-site service cannot be anchored
without one, and accepting it would only wedge the record in PENDING_CREATE.
Async & state: Asynchronous; returns 202 with the service in provisioningState PENDING_CREATE. neutron
reports a fresh service as PENDING_CREATE and only activates it once a connection attaches, so status
stays PENDING_CREATE until then - that is the provider's behaviour, not a stalled record.
Errors: 401; 403; 404 unknown router; 409 duplicate name; 422 gateway-less router or field-level
validation failure; 500 on backend failure.
Idempotency/Concurrency: Idempotency-Key is required; a replay returns the original 202.
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.
Idempotency-Key*stringRequired: 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.
uuidapplication/json- body
Payload for creating a VPN service on a router. No subnet is accepted - see the VpnService description for why the endpoint-group model requires a subnet-less service.
name*stringService display name; must be unique within the scope.
^[^\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}])?$1 <= length <= 255description?stringFree-text description.
length <= 255""routerId*stringIdentifier (or name) of a router in this scope that HAS an external gateway. A site-to-site service cannot be anchored without one.
1 <= lengthadminStateUp?booleanWhether the service starts administratively up.
trueCreation accepted; returns the new VPN service in provisioningState PENDING_CREATE.
application/json- response
A VPN service - the anchor that terminates tunnels on one router, mirroring neutron-VPNaaS vpnservices. One service may carry many site connections. It deliberately has NO subnet: neutron's validator makes a subnet-bearing service and endpoint groups mutually exclusive, and this API models endpoint groups as first-class resources, so the local subnet is always carried by the connection's local endpoint group.
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*stringPlatform identifier of the VPN service.
name*stringService display name, unique within the scope.
^[^\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}])?$1 <= length <= 255description*stringFree-text description; empty string when unset.
routerId*stringIdentifier of the router this service terminates tunnels on; the router must have an external gateway.
routerName*stringDisplay name of that router, resolved from the networking read model.
externalV4Ip?|The router's external gateway IPv4 address, read from neutron's external_v4_ip - the tunnel's local endpoint, and the address the remote peer must be configured with. Null until neutron has reported it.
adminStateUp*booleanAdministrative state of the service; false brings every tunnel on it down.
status?|nullneutron's own status for the service, verbatim. Null until the provider has reported one. A freshly created service stays PENDING_CREATE until the first site connection attaches - that is neutron's behaviour, not a stalled record.
statusReason?|The provider's own message from the last failed write; null when the last write succeeded.
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.
provisioningState*stringLifecycle state of this platform record.
"PENDING_CREATE""PENDING_UPDATE""PENDING_DELETE""READY""ERROR"providerId?|neutron's UUID for this service; null until the worker has created it.
usedByCount*integerHow many IPsec site connections terminate on this service. Non-zero means a delete will be refused with 409 DEPENDENCY_BLOCKED.
curl -X POST "https://example.com/scopes/string/network/vpn/services" \ -H "Idempotency-Key: 497f6eca-6276-4993-bfeb-53cbbbba6f08" \ -H "Content-Type: application/json" \ -d '{ "name": "string", "routerId": "string" }'{ "origin": "portal", "id": "string", "name": "string", "description": "string", "routerId": "string", "routerName": "string", "externalV4Ip": "string", "adminStateUp": true, "status": "ACTIVE", "statusReason": "string", "statusReasonCode": "string", "provisioningState": "PENDING_CREATE", "providerId": "string", "usedByCount": 0}