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.
Remove an association from the port
Removes an existing association from the selected Network Interface. The primary UI flow is the
header "Detach" action, which unbinds the attached device (instance NIC, load-balancer VIP or router
interface) after confirmation — the port then survives unattached with its fixed IP reserved. The
same endpoint serves the symmetric removals visible on the detail tabs: detaching a security group
from the enforced set, disassociating the floating IP (the address returns to the available pool),
and removing an allowed address pair by its IP. The updated port is returned and the change is
visible to subsequent reads.
Validation: the port must exist and be visible in scopeId → ERR_NOT_FOUND otherwise; the
current state must permit detach — target=device requires a non-null device binding,
target=floating_ip requires an associated floating IP, target=security_group requires
securityGroupId to be currently attached, and target=address_pair requires addressPairIp to be
in the allowed list → ERR_CONFLICT when the named association does not exist; a missing/mismatched
discriminator field → ERR_VALIDATION (422).
Async & state: Synchronous — 200 with the updated NetworkInterface (device/floatingIp set to
null, or the security-group / address-pair entry removed); detaching the device flips the port
status from active to down. A resource.updated SSE frame is emitted with the corresponding
field patch. Backends that must drain a device binding may instead answer 202 with an Operation;
the synchronous 200 shape is the default. This deployment takes that 202 branch for
target=device on an instance NIC — the unbinding is Nova's, so the platform's own
compute.instance.network_interface.detach command performs it and its Operation is returned.
A device owned by another resource's lifecycle (a load-balancer VIP, a router interface, the DHCP
port) is 409 naming the endpoint that can release it.
Errors: 401 unauthenticated; 403 when the caller lacks contributor/admin rights on the scope;
404 unknown port; 409 when the requested association does not currently exist or the resource state
forbids detaching; 422 on a malformed body; 500 on backend failure.
Idempotency/Concurrency: Idempotency-Key is optional (recommended) — the UI can retry,
and replaying the same key
returns the original result without erroring on the now-removed 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 detach payload — unbind the device, detach a security group, disassociate the floating IP, or remove an address pair.
target*stringWhich association to remove.
"device""security_group""floating_ip""address_pair"securityGroupId?stringRequired when target=security_group — id of the attached group to remove.
addressPairIp?stringRequired when target=address_pair — IP of the allowed address pair to remove.
Association removed; 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/detach" \ -H "Content-Type: application/json" \ -d '{ "target": "device" }'{ "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}