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.
Attach an association to the port (security group or floating IP)
Associates the selected Network Interface with another resource. The UI exposes two attach flows on
the network interface detail page: "Attach" a security group (Security groups tab — pick one of the resource
group's groups and add it to the port's enforced set) and "Associate" / "Associate floating IP"
(Floating IP tab and the list row menu — pick an unassociated address from the available floating-IP
pool and bind it to the port's fixed IP). The target discriminator selects the flow; the updated
port is returned so the UI can refresh immediately, and the new association is visible to subsequent
reads.
Validation: the port must exist and be visible in scopeId → ERR_NOT_FOUND otherwise;
target=security_group requires securityGroupId referencing an existing group, requires the port
to have portSecurity=true, and rejects a group already attached → ERR_CONFLICT;
target=floating_ip requires floatingIp to be an address from the unassociated pool, rejects a
port that already holds a floating IP, and rejects ports on public (provider) networks since their
fixed IP is already publicly routable → ERR_CONFLICT; a missing/mismatched discriminator field →
ERR_VALIDATION (422).
Async & state: Synchronous — 200 with the updated NetworkInterface (securityGroups gains the id,
or floatingIp flips from null to the address). A resource.updated SSE frame is emitted with the
corresponding field patch. No long-running state machine is involved.
Errors: 401 unauthenticated; 403 when the caller lacks contributor/admin rights on the scope;
404 when the port, security group or floating IP does not exist in scope; 409 when the association
already exists, the floating IP is taken, port security is disabled (for SG attach), or the port is
on a public network (for FIP attach); 422 on a malformed body; 500 on backend failure.
Idempotency/Concurrency: Idempotency-Key is optional (recommended) — replaying the same
key returns the original
200 result without double-applying the association.
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.
networkInterfaceId*stringNetwork interface (port) identifier.
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
Discriminated attach payload — attach a security group or associate a floating IP.
target*stringWhich association to create.
"security_group""floating_ip"securityGroupId?stringRequired when target=security_group — id of the group to attach.
floatingIp?stringRequired when target=floating_ip — an unassociated address from the available pool.
Association applied; returns the updated Network Interface.
application/json- response
Network interface (port) read model.
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*stringPort identifier (e.g. port-web01).
name*stringPort name, unique within the project.
description*stringarn*stringResource name, e.g. arn:publiccloud:network:ist-1:{account}:port/{name}.
networkId*stringIdentifier of the network the port lives on.
networkName*stringnetworkExternal*booleanTrue when the network is a public (provider) network.
subnetName*stringsubnetCidr*stringCIDR of the subnet the fixed IP is reserved on.
fixedIp*stringPRIMARY fixed address — the first entry of fixedIps. Not the only one: read fixedIps to see the whole reservation. Empty string until the provider allocates.
fixedIps*array<>The port's FULL fixed-IP reservation as Neutron holds it, in provider order (fixedIp mirrors the first entry). A consumer that shows only fixedIp silently hides every further address, which is how a two-address port read back as a single-address one. Empty until the provider allocates.
mac*stringMAC address under the fa:16:3e OUI, auto-generated at create time.
status*NetworkInterfaceStatusPort lifecycle status. UI labels Active / Down / Build.
"active""down""build"statusReason*|Human-readable, customer-facing reason the last lifecycle command on this port failed (e.g. "The request could not be completed after repeated attempts. Try again, or contact support if it persists."); a create that failed after the port already existed settles down with the reason here. Never raw provider text. Null while healthy, once a later settle clears it, or when the failure carried no detail. Mirrors VirtualNetwork.statusReason.
adminStateUp*booleanAdministrative state; false forces the port down regardless of binding.
portSecurity*booleanAnti-spoofing filter + security-group enforcement flag.
securityGroups*array<string>Attached security-group ids; empty when port security is off.
floatingIp*|Associated floating IP, or null when none is associated.
device*|nullBound device, or null when the port is unattached.
bindingType*NetworkInterfaceBindingTypePort binding type (BindingType). UI labels: Normal (virtio) / Direct (SR-IOV) / MACVTAP.
"normal""direct""macvtap"bindingHost*|Hypervisor the port is bound to, or null when unbound.
mtu*integerEffective MTU (9000 for SR-IOV direct bindings, otherwise the network MTU).
dnsName*stringA name the platform derives from the interface name and region ({name}.{region}. followed by an internal zone). Informational: it is not guaranteed to resolve.
allowedAddressPairs*array<>region*RegionIdPlatform region code (a DNS-label-shaped slug, e.g. ist-1). No longer a closed enum: the set of valid region codes is operator-managed in the platform-region registry, so this carries only a shape guard. The authoritative set of activated regions is read from GET /regions; invalid-shape codes are VALIDATION_FAILED and codes absent from the registry are rejected at the resolving endpoint.
^[a-z][a-z0-9-]{1,39}$createdAt*stringdate-timeupdatedAt*stringdate-timerxMbps*integerCurrent receive throughput in Mb/s (0 when the port is not active).
txMbps*integerCurrent transmit throughput in Mb/s (0 when the port is not active).
pps*integerCurrent packets-per-second (0 when the port is not active).
curl -X POST "https://example.com/scopes/string/network/network-interfaces/string/actions/attach" \ -H "Content-Type: application/json" \ -d '{ "target": "security_group" }'{ "origin": "portal", "id": "string", "name": "string", "description": "string", "arn": "string", "networkId": "string", "networkName": "string", "networkExternal": true, "subnetName": "string", "subnetCidr": "string", "fixedIp": "string", "fixedIps": [ { "ipAddress": "string", "subnetId": "string" } ], "mac": "string", "status": "active", "statusReason": "string", "adminStateUp": true, "portSecurity": true, "securityGroups": [ "string" ], "floatingIp": "string", "device": { "kind": "instance", "id": "string", "name": "string", "owner": "string" }, "bindingType": "normal", "bindingHost": "string", "mtu": 0, "dnsName": "string", "allowedAddressPairs": [ { "ip": "string", "mac": "" } ], "region": "string", "createdAt": "2019-08-24T14:15:22Z", "updatedAt": "2019-08-24T14:15:22Z", "rxMbps": 0, "txMbps": 0, "pps": 0}