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.
Update network interface configuration
Partially updates the selected Network Interface with the configuration the UI exposes: rename /
re-describe (Edit action), toggle administrative state ("Set admin down" / "Set admin up"), enable or
disable port security, replace the attached security-group set, and replace the allowed address-pair
list (VRRP/VIP IP+MAC entries managed on the "Allowed address pairs" tab). Omitted fields are left
unchanged; the updated resource is returned for immediate UI refresh and is visible to subsequent
reads.
Validation: the port must exist, be visible in scopeId, and its current state must permit
update → ERR_NOT_FOUND / ERR_CONFLICT otherwise; name, when present, must match ^[a-z0-9-]{1,60}$
(not required to be unique); description at most 255 characters; securityGroups ids must resolve to existing groups and are
rejected when portSecurity is (or becomes) false; each allowedAddressPairs[].ip must be a valid
IPv4 address or CIDR and not duplicate an existing pair; allowedAddressPairs[].mac, when non-empty,
must be a valid MAC (empty string defaults to the port MAC). Violations → ERR_VALIDATION (422).
Async & state: Synchronous — 200 with the updated NetworkInterface. Setting adminStateUp=false
transitions the port status to down; setting it back true returns it to active when a device is
bound. A resource.updated SSE frame is emitted with the changed-field patch.
Errors: 401 unauthenticated; 403 when the caller lacks contributor/admin rights; 404 unknown
port; 409 when the new name collides or the current state forbids the change; 412 when If-Match does
not match the current ETag; 422 on field validation failure; 500 on backend failure.
Idempotency/Concurrency: This operation does not use Idempotency-Key; it may be omitted
and a sent one is ignored. A repeated identical PATCH re-applies the same fields (same end
state) and bumps the ETag, so resending a request that already succeeded with its original
If-Match gets 412. If-Match with the last seen ETag is honored; a stale tag yields 412
PRECONDITION_FAILED.
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.
If-Match?stringETag for optimistic concurrency on mutations/deletes; mismatch results in 412.
application/json- body
Partial update payload for PATCH; omitted fields are left unchanged.
name?string^[a-z0-9-]{1,60}$description?stringlength <= 255adminStateUp?booleanUI "Set admin down" / "Set admin up" toggle.
portSecurity?booleansecurityGroups?array<string>Replacement set of attached security-group ids.
allowedAddressPairs?array<>Replacement list of allowed address pairs.
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 PATCH "https://example.com/scopes/string/network/network-interfaces/string" \ -H "Content-Type: application/json" \ -d '{}'{ "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}