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 endpoint group (exactly one endpoint)
Creates one VPN endpoint group naming one end of a tunnel. type subnet takes one tenant subnet id and is
used as the LOCAL end; type cidr takes one remote CIDR and is used as the PEER end. neutron's attribute
map also lists network, router and vlan types, but the IPsec reference driver implements only subnet and
cidr (_get_local_subnets / _get_peer_cidrs reject anything else), so only those two are offered - an
API that accepted a type the driver cannot honour would be presenting an option that silently fails.
Exactly one endpoint per group. Neutron's schema accepts a list, but with more than one subnet or CIDR
in a group only one tunnel is actually brought up and the remaining endpoints silently pass no traffic.
A second endpoint is therefore rejected with 422 VALIDATION_FAILED, field endpoints, and a message that
says why and what to do instead: create a second endpoint group and a second site connection for the
second subnet. The rule is enforced here, on the server - not left to the UI.
Validation: name must be non-empty and unique in the scope (409 CONFLICT); type must be subnet or
cidr; endpoints must contain exactly one element (more -> 422 field endpoints); for type subnet the
endpoint must be a subnet id that exists in the scope (unknown -> 404 NOT_FOUND); for type cidr it must
be valid CIDR notation (-> 422). Endpoints are immutable once created (neutron marks them allow_put
false), so they are validated strictly here.
Async & state: Asynchronous; 202 with provisioningState PENDING_CREATE, settled to READY or ERROR by
the worker.
Errors: 401; 403; 404 unknown subnet; 409 duplicate name; 422 wrong type, bad CIDR or more than one
endpoint; 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 endpoint group. A group may carry several endpoints; put every subnet that should reach the same peer into ONE group and build ONE site connection on it. Building a second connection to the same peer gateway instead does not work - its CHILD_SA is refused TS_UNACCEPTABLE and it carries no traffic.
name*stringGroup 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""type*stringsubnet for the local end, cidr for the peer end. neutron's attribute map also lists network, router and vlan, but the IPsec driver implements only these two.
"subnet""cidr"endpoints*array<string>One or more endpoints - subnet ids in this scope for type subnet, CIDRs such as 10.20.1.0/24 for type cidr. Duplicates are rejected 422. For type subnet every subnet must be attached to the SAME router, because a site connection terminates on one VPN service and that service terminates on one router: a subnet the router does not serve would be written into the tunnel's traffic selectors and then carry nothing.
1 <= itemsCreation accepted; returns the new endpoint group in provisioningState PENDING_CREATE.
application/json- response
A VPN endpoint group - one end of a tunnel, mirroring the neutron-VPNaaS endpoint_groups resource. type subnet names tenant subnets and is used as the LOCAL end; type cidr names remote networks and is used as the PEER end. Groups are reusable across site connections. A group may hold SEVERAL endpoints: one site connection then covers all of them on a single CHILD_SA, which is the only arrangement that actually carries traffic for more than one subnet against the same peer gateway.
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 endpoint group.
name*stringGroup 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.
type*stringWhich end of the tunnel this group describes.
"subnet""cidr"endpoints*array<string>One or more endpoints - subnet ids for type subnet, CIDRs for type cidr. Immutable once created (neutron marks it allow_put false).
1 <= itemsendpointLabel?|Human-readable rendering of the endpoints - each subnet's name and CIDR for a subnet group, resolved from the networking read model, comma-separated when there is more than one. Null when no subnet can be resolved; the raw endpoints above are always present.
provisioningState*stringLifecycle state of this platform record.
"PENDING_CREATE""PENDING_UPDATE""PENDING_DELETE""READY""ERROR"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.
providerId?|neutron's UUID for this endpoint group; null until the worker has created it.
usedByCount*integerHow many IPsec site connections use this group as their local or peer end. Non-zero means a delete will be refused with 409 DEPENDENCY_BLOCKED.
curl -X POST "https://example.com/scopes/string/network/vpn/endpoint-groups" \ -H "Idempotency-Key: 497f6eca-6276-4993-bfeb-53cbbbba6f08" \ -H "Content-Type: application/json" \ -d '{ "name": "string", "type": "subnet", "endpoints": [ "string" ] }'{ "origin": "portal", "id": "string", "name": "string", "description": "string", "type": "subnet", "endpoints": [ "string" ], "endpointLabel": "string", "provisioningState": "PENDING_CREATE", "statusReason": "string", "statusReasonCode": "string", "providerId": "string", "usedByCount": 0}