Attach Network Interface to VM

POST/v2.1/{project_id}/servers/{server_id}/os-interface

Creates a port and attaches it to the VM, or attaches an existing port when you pass port_id. Use it to put a running VM on a second network without rebuilding it.

info

Source: create-interface

Request

Parameters

project_idstringrequiredpath

The UUID of the project.

server_idstringrequiredpath

The UUID of the VM.

interfaceAttachmentobjectrequiredbody

Interface attachment wrapper.

6 fields

port_idstringbody

ID of an existing port to attach. Mutually exclusive with net_id.

net_idstringbody

ID of the network on which to create a port. Mutually exclusive with port_id. If both are omitted, the service uses the network already associated with the VM.

fixed_ipsarraybody

Fixed IP addresses to request. If you request a specific address without net_id, the call returns 400.

port_security_enabledbooleanbody

Enable port security (anti-spoofing and security groups) on the new port.

security_groupsarraybody

Security group IDs for the new port.

tagstringbody

Device role tag readable by the guest through the metadata API or config drive.

Sample Request — automatic IP

curl -ks -H 'Content-Type: application/json' -H 'X-OpenStack-Nova-API-Version: 2.67' \
-H 'X-Auth-Token: gAAAAA<...>' -d '{
  "interfaceAttachment": {
    "net_id": "a1d8d6ae-c89d-4307-8a0c-3cc2ee55d7e3",
    "fixed_ips": [{"ip_version": 4}],
    "port_security_enabled": true,
    "security_groups": ["5e2db579-c3a0-468b-aecd-b7930bf1507e"]
  }
}' https://api.vietnix.cloud:8774/v2.1/{project_id}/servers/{server_id}/os-interface

Sample Request — specific IP

curl -ks -H 'Content-Type: application/json' -H 'X-OpenStack-Nova-API-Version: 2.67' \
-H 'X-Auth-Token: gAAAAA<...>' -d '{
  "interfaceAttachment": {
    "net_id": "0bb6b7a7-da8d-432c-b8d5-12139f7924d1",
    "fixed_ips": [{"ip_address": "192.168.128.20"}]
  }
}' https://api.vietnix.cloud:8774/v2.1/{project_id}/servers/{server_id}/os-interface

Response

Sample Response

Response body

{
  "interfaceAttachment": {
    "port_state": "ACTIVE",
    "fixed_ips": [
      {
        "subnet_id": "d52aa9f4-6a4b-4268-a71d-1a50f9b60aa9",
        "ip_address": "192.168.128.20"
      }
    ],
    "port_id": "ff9edb95-611f-4969-b98a-498f77c0326a",
    "net_id": "0bb6b7a7-da8d-432c-b8d5-12139f7924d1",
    "mac_addr": "fa:16:3e:8d:73:9f"
  }
}

Status Code

Success

Status Code	Description
200 - OK	The interface was attached.

Error

Status Code	Description
400 - Bad Request	port_id and net_id were both set, or a fixed IP was requested without a network.
401 - Unauthorized	User must authenticate before making a request.
403 - Forbidden	Policy does not allow current user to do this operation.
404 - Not Found	The VM, network, or port does not exist.
409 - Conflict	The port is already attached, or the VM is in a status that does not allow attaching.
501 - Not Implemented	Network interfaces are not implemented for this deployment.

note

Attaching a second interface to a VM that already has a default route does not change the default route inside the guest. Configure routing or policy in the guest if the new network must carry outside traffic.