Create interface¶

Overview¶

Attach created network port to VM instance.

Classification¶

Create

API Operation Object¶

os-interface

Synchronous / Asynchronous¶

synchronous

Request¶

HTTP Request Method¶

POST

HTTP Request Path¶

{api_endpoint}/v2/{project_id}/servers/{server_id}/os-interface

HTTP Request Header¶

Format¶

Accept-Encoding: gzip, deflate, compress (optional)
Accept: application/json
X-Auth-Token: <token_id>
Content-Type: application/json

HTTP Request Body¶

Format¶

* The request body can be specified in four patterns.

<<port_id>>

{
    "interfaceAttachment": {
        "port_id": "<port_id>"
    }
}

<<network_id>>

{
    "interfaceAttachment": {
        "net_id": "<net_id>"
    }
}

<<IP_address>>

{
    "interfaceAttachment": {
        "net_id": "<net_id>",
        "fixed_ips": [
            {
                "ip_address": "<IP_address>"
            }
        ]
    }
}

<<none_param>>

{
    "interfaceAttachment": {}
}

Request Parameter¶

Request Parameters¶
name	style	format	description	required/optional	default value	action for invalid parameter	response code for invalid parameter
project_id	URL	UUID(3)	Project id	required	-	Terminate	400, 404
server_id	URL	UUID	instance id	required	-	Terminate	404
token_id	Header	String(token_id)	Keystone authentication token.	required	-	Terminate	401
port_id	URL	UUID	Port id of add interface to the VM instance.	optional*	-	Terminate	400, 500
net_id	URL	UUID	Network id of add interface to the VM instance.	optional	-	Terminate	400, 500
ip_address	URL	IPv4 address/IPv6 address	IP address of add interface to the VM instance.	optional	-	Terminate	400, 500
fixed_ips	URL	String	Fixed IP addresses with subnet IDs.	optional	-	Terminate	400, 500

* If the network is two or more can be used, specify required.

Response¶

HTTP Response Header¶

Format¶

HTTP/1.1 <response_code> <message>       (ex. 200 Accepted)

<response_code>: see "HTTP Responses" section
<message>: message based on the response code
- skip auto insert field such as "X-Compute-Request-Id" and "Content-Length", "Date"

Response Code¶

Response Codes¶
response code	condition
200	normal end
400	net_id and port_id are both entry in body
-	port is in-use
-	already associated with a port on the specified network
-	network to be used is multiple detection (neutron settings "allow_duplicate_networks" = False case only)
401	unauthorized
403	not authorized to perform the requested action
409	specified instance has been locked
-	instance status is invalid(status isn't ACTIVE,PAUSED,STOPPED)
500	failed to attach interface
-	specified port is not found
-	specified network is not found
501	network driver does not support this function

HTTP Response Body¶

Format¶

{
    "interfaceAttachment": {
        "fixed_ips": [
            {
                "ip_address": "<ip_address>",
                "subnet_id": "<subnet_id>"
            }
        ],
        "mac_addr": "<mac_address>",
        "net_id": "<net_id>",
        "port_id": "<port_id>",
        "port_state": "<port_status>"
    }
}

Response Parameter¶

Response Parameters¶
item	format	description
ip_address	IPv4 address	IP address of Subnet associated with the attached port
subnet_id	UUID	Subnet associated with the attached port
mac_addr	MAC address	MAC address of the attached port
net_id	UUID	Network Id of the attached port
port_id	UUID	Id of the attached port
port_state	String	Status of the attached port

Sample API Request and Response¶

Sample API Request¶

Request URI¶

https://example.com/v2/{project_id}/servers/{server_id}/os-interface

Request Header¶

Accept-Encoding: gzip, deflate, compress (optional)
Accept: application/json
X-Auth-Token: ajk3adjiown02
Content-Type: application/json

Request Body¶

{
    "interfaceAttachment": {
        "port_id": "<port_id>"
    }
}

Sample API Response¶

Response Header¶

HTTP/1.1 200 Accepted

<response_code>: see "HTTP Responses" section
<message>: message based on the response code
- skip auto insert field such as "X-Compute-Request-Id" and "Content-Length", "Date"

Response Body¶

{
    "interfaceAttachment": {
        "fixed_ips": [
            {
                "ip_address": "<ip_address>",
                "subnet_id": "<subnet_id>"
            }
        ],
        "mac_addr": "<mac_address>",
        "net_id": "<net_id>",
        "port_id": "<port_id>",
        "port_state": "<port_status>"
    }
}

Execution Example¶

HTTP Request¶

POST /v2/e4ee5a9bdf934e35b62c8b995152feee/servers/b6d94eb6-0759-4277-892e-fae5fd8ca8bd/os-interface HTTP/1.1
User-Agent: curl/7.35.0
Host: localhost:8774
Content-Type: application/json
Accept: application/json
X-Auth-Token: 802103f4cdcb4398965d2a1976b47325
Content-Length: 78

{ "interfaceAttachment": { "port_id": "c20c7086-eb16-4b3b-96e4-4da2f5037bcf"}}

HTTP Response¶

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 279
X-Compute-Request-Id: req-d85b685d-5147-4294-a77e-4796cc16f37b
Date: Wed, 29 Oct 2014 08:22:14 GMT

{ "interfaceAttachment": {"port_state": "DOWN", "fixed_ips": [{"subnet_id": "3b6e6d1f-848b-489f-ac16-69801915c65d", "ip_address": "172.16.0.2"}], "port_id": "c20c7086-eb16-4b3b-96e4-4da2f5037bcf", "net_id": "e7372598-ff0f-4013-84b5-82b0e3641f7a", "mac_addr": "fa:16:3e:b9:1b:1b"}}

Error Execution Example¶

HTTP Request¶

POST /v2/ad355aa6ed3e4cf5ae0fa0df652bc290/servers/aef82e69-0b3e-4056-b1b6-c37d5a278183/os-interface HTTP/1.1
User-Agent: curl/7.35.0
Host: 192.168.56.250:8774
X-Auth-Token: 247558b04ebb4114baefa1f22fa180ed
Content-type: application/json
Accept: application/json

HTTP Response¶

HTTP/1.1 400 Bad Request
Content-Length: 188
Content-Type: application/json; charset=UTF-8
X-Compute-Request-Id: req-555fd7da-8d2c-4616-bc99-77b60c4b7ba1
Date: Thu, 15 Oct 2015 06:23:57 GMT

{"badRequest": {"message": "Malformed request URL: URL's project_id 'ad355aa6ed3e4cf5ae0fa0df652bc290' doesn't match Context's project_id 'ad355aa6ed3e4cf5ae0fa0df652bc291'", "code": 400}}

List interfaces

Detach interface