openstack/neutron-lib
Code Issues Proposed changes

api-ref: Correct port binding extension

Browse Source 
Also merges port binding extension into the port API.
port binding extension is an attribute extension, so it is natural
if we can see all port attribute in a single page.

Co-Authored-By: Sindhu Devale <sindhu.devale@intel.com>
Co-Authored-By: csatari <gergely.csatari@nokia.com>
Partially-Implements: blueprint neutron-in-tree-api-ref
Change-Id: Ia6b5966e597f3f619222a27f9a1eca03d6ed59b7
This commit is contained in:
Akihiro Motoki
2017-01-19 01:38:45 +09:00
parent dffe3c9000
commit edf78dbbbe
11 changed files with 231 additions and 126 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
api-ref/source/v2/index.rst
View File

@@ -17,7 +17,6 @@ General API Overview
Layer 2 Networking
##################
.. include:: networks.inc
.. include:: port-binding.inc
.. include:: ports.inc
.. include:: segments.inc
.. include:: trunk.inc

79
api-ref/source/v2/parameters.yaml
View File

@@ -593,6 +593,85 @@ bandwidth_limit_rules:
in: body
required: true
type: array
binding:host_id:
description: |
The ID of the host where the port resides.
in: body
required: true
type: string
binding:host_id-request:
description: |
The ID of the host where the port resides.
The default is an empty string.
in: body
required: false
type: string
binding:profile:
description: |
A dictionary that enables the application running on the specific host to
pass and receive vif port information specific to the networking back-end.
The networking API does not define a specific format of this field.
in: body
required: true
type: string
binding:profile-request:
description: |
A dictionary that enables the application running on the specific host to
pass and receive vif port information specific to the networking back-end.
The networking API does not define a specific format of this field.
The default is an empty dictionary.
in: body
required: false
type: string
binding:vif_details:
description: |
A dictionary which contains additional information on the port.
Currently the following fields are defined: ``port_filter`` and
``ovs_hybrid_plug``.
``port_filter`` is a boolean indicating the networking service
provides port filtering features such as security group and/or
anti MAC/IP spoofing.
``ovs_hybrid_plug`` is a boolean used to inform an API consumer
like nova that the hybrid plugging strategy for OVS should be used.
in: body
required: true
type: object
binding:vif_type:
description: |
The type of which mechanism is used for the port.
An API consumer like nova can use this to determine an appropriate way to
attach a device (for example an interface of a virtual server) to the port.
Available values currently defined includes
``ovs``, ``bridge``, ``macvtap``, ``hw_veb``, ``hostdev_physical``,
``vhostuser``, ``distributed`` and ``other``.
There are also special values: ``unbound`` and ``binding_failed``.
``unbound`` means the port is
not bound to a networking back-end. ``binding_failed`` means an error
that the port failed to be bound to a networking back-end.
in: body
required: true
type: string
binding:vnic_type:
description: |
The type of vNIC which this port should be attached to. This is used to
determine which mechanism driver(s) to be used to bind the port.
The valid values are ``normal``, ``macvtap``, ``direct``, ``baremetal``,
and ``direct-physical``.
What type of vNIC is actually available depends on deployments.
in: body
required: true
type: string
binding:vnic_type-request:
description: |
The type of vNIC which this port should be attached to. This is used to
determine which mechanism driver(s) to be used to bind the port.
The valid values are ``normal``, ``macvtap``, ``direct``, ``baremetal``,
and ``direct-physical``.
What type of vNIC is actually available depends on deployments.
The default is ``normal``.
in: body
required: false
type: string
cidr:
description: |
The CIDR of the subnet.

118
api-ref/source/v2/port-binding.inc
View File

@@ -1,118 +0,0 @@
.. -*- rst -*-
.. needs:method_verification
.. needs:parameter_verification
.. needs:example_verification
.. needs:body_verification
=========================================
Ports binding extended attributes (ports)
=========================================
Lists, creates, shows information for, updates, and deletes ports.
Show port details (port binding)
================================
.. rest_method:: GET /v2.0/ports/{port_id}
Shows details for a port.
Normal response codes: 200
Request
-------
.. rest_parameters:: parameters.yaml
- port_id: port_id-path
Response Example
----------------
.. literalinclude:: samples/ports/port-bind-show-response.json
:language: javascript
Update port (port binding)
==========================
.. rest_method:: PUT /v2.0/ports/{port_id}
Updates a port.
Normal response codes: 200
Error response codes: 404,401,400
Request
-------
.. rest_parameters:: parameters.yaml
- port_id: port_id-path
Request Example
---------------
.. literalinclude:: samples/ports/port-create-request.json
:language: javascript
Response Example
----------------
.. literalinclude:: samples/ports/port-bind-create-update-response.json
:language: javascript
Delete port (port binding)
==========================
.. rest_method:: DELETE /v2.0/ports/{port_id}
Deletes a port.
Error response codes: 409,404,204,401
Request
-------
.. rest_parameters:: parameters.yaml
- port_id: port_id-path
List ports (port binding)
=========================
.. rest_method:: GET /v2.0/ports
Lists ports to which the user has access.
Normal response codes: 200
Error response codes: 401
Request
-------
Response Example
----------------
.. literalinclude:: samples/ports/ports-list-response.json
:language: javascript
Create port (port binding)
==========================
.. rest_method:: POST /v2.0/ports
Creates a port on a network.
Error response codes: 201,403,401,400
Request
-------
Request Example
---------------
.. literalinclude:: samples/ports/port-create-request.json
:language: javascript

81
api-ref/source/v2/ports.inc
View File

@@ -6,6 +6,17 @@ Ports
Lists, shows details for, creates, updates, and deletes ports.
Port binding extended attributes
================================
The port binding extension (``binding``) allows administrative users
to specify and retrieve physical binding information of ports.
The extension defines several attributes whose names have a prefix
``binding:`` including ``binding:host_id``, ``binding:vnic_type``,
``binding:vif_type``, ``binding:vif_details``, and ``binding:profile``.
|
Show port details
=================
@@ -39,6 +50,11 @@ Response Parameters
- port: port
- admin_state_up: admin_state_up
- allowed_address_pairs: allowed_address_pairs
- binding:host_id: binding:host_id
- binding:profile: binding:profile
- binding:vif_details: binding:vif_details
- binding:vif_type: binding:vif_type
- binding:vnic_type: binding:vnic_type
- created_at: created_at
- description: description
- device_id: device_id
@@ -62,6 +78,12 @@ Response Example
.. literalinclude:: samples/ports/port-show-response.json
:language: javascript
Response Example (admin user)
-----------------------------
.. literalinclude:: samples/ports/port-bind-show-response.json
:language: javascript
Update port
===========
@@ -99,6 +121,9 @@ Request
- port: port
- admin_state_up: admin_state_up-request
- allowed_address_pairs: allowed_address_pairs-request
- binding:host_id: binding:host_id-request
- binding:profile: binding:profile-request
- binding:vnic_type: binding:vnic_type-request
- description: description-request
- device_id: device_id-request
- device_owner: device_owner-request
@@ -115,6 +140,12 @@ Request Example
.. literalinclude:: samples/ports/port-update-request.json
:language: javascript
Request Example (admin user)
----------------------------
.. literalinclude:: samples/ports/port-bind-update-request.json
:language: javascript
Response Parameters
-------------------
@@ -123,6 +154,11 @@ Response Parameters
- port: port
- admin_state_up: admin_state_up
- allowed_address_pairs: allowed_address_pairs
- binding:host_id: binding:host_id
- binding:profile: binding:profile
- binding:vif_details: binding:vif_details
- binding:vif_type: binding:vif_type
- binding:vnic_type: binding:vnic_type
- created_at: created_at
- description: description
- device_id: device_id
@@ -146,6 +182,12 @@ Response Example
.. literalinclude:: samples/ports/port-update-response.json
:language: javascript
Response Example (admin user)
-----------------------------
.. literalinclude:: samples/ports/port-bind-update-response.json
:language: javascript
Delete port
===========
@@ -208,6 +250,11 @@ Response Parameters
- ports: ports
- admin_state_up: admin_state_up
- allowed_address_pairs: allowed_address_pairs
- binding:host_id: binding:host_id
- binding:profile: binding:profile
- binding:vif_details: binding:vif_details
- binding:vif_type: binding:vif_type
- binding:vnic_type: binding:vnic_type
- created_at: created_at
- description: description
- device_id: device_id
@@ -231,6 +278,12 @@ Response Example
.. literalinclude:: samples/ports/ports-list-response.json
:language: javascript
Response Example (admin user)
-----------------------------
.. literalinclude:: samples/ports/ports-bind-list-response.json
:language: javascript
Create port
===========
@@ -253,6 +306,9 @@ Request
- port: port
- admin_state_up: admin_state_up-request
- allowed_address_pairs: allowed_address_pairs-request
- binding:host_id: binding:host_id-request
- binding:profile: binding:profile-request
- binding:vnic_type: binding:vnic_type-request
- description: description-request
- device_id: device_id-request
- device_owner: device_owner-request
@@ -272,6 +328,12 @@ Request Example
.. literalinclude:: samples/ports/port-create-request.json
:language: javascript
Request Example (admin user)
----------------------------
.. literalinclude:: samples/ports/port-bind-create-request.json
:language: javascript
Response Parameters
-------------------
@@ -280,6 +342,11 @@ Response Parameters
- port: port
- admin_state_up: admin_state_up
- allowed_address_pairs: allowed_address_pairs
- binding:host_id: binding:host_id
- binding:profile: binding:profile
- binding:vif_details: binding:vif_details
- binding:vif_type: binding:vif_type
- binding:vnic_type: binding:vnic_type
- created_at: created_at
- description: description
- device_id: device_id
@@ -303,6 +370,12 @@ Response Example
.. literalinclude:: samples/ports/port-create-response.json
:language: javascript
Response Example (admin user)
-----------------------------
.. literalinclude:: samples/ports/port-bind-create-response.json
:language: javascript
Bulk create ports
=================
@@ -324,6 +397,9 @@ Request
- ports: ports
- admin_state_up: admin_state_up-request
- allowed_address_pairs: allowed_address_pairs-request
- binding:host_id: binding:host_id-request
- binding:profile: binding:profile-request
- binding:vnic_type: binding:vnic_type-request
- description: description-request
- device_id: device_id-request
- device_owner: device_owner-request
@@ -351,6 +427,11 @@ Response Parameters
- ports: ports
- admin_state_up: admin_state_up
- allowed_address_pairs: allowed_address_pairs
- binding:host_id: binding:host_id
- binding:profile: binding:profile
- binding:vif_details: binding:vif_details
- binding:vif_type: binding:vif_type
- binding:vnic_type: binding:vnic_type
- created_at: created_at
- description: description
- device_id: device_id

17
api-ref/source/v2/samples/ports/port-bind-create-request.json Normal file
View File

@@ -0,0 +1,17 @@
{
"port": {
"binding:host_id": "4df8d9ff-6f6f-438f-90a1-ef660d4586ad",
"binding:profile": {
"local_link_information": [
{
"port_id": "Ethernet3/1",
"switch_id": "0a:1b:2c:3d:4e:5f",
"switch_info": "switch1"
}
]
},
"binding:vnic_type": "baremetal",
"device_id": "d90a13da-be41-461f-9f99-1dbcf438fdf2",
"device_owner": "baremetal:none"
}
}

18
api-ref/source/v2/samples/ports/port-bind-create-update-response.json → api-ref/source/v2/samples/ports/port-bind-create-response.json
View File

@@ -2,14 +2,22 @@
"port": {
"admin_state_up": true,
"allowed_address_pairs": [],
"binding:host_id": "",
"binding:profile": {},
"binding:host_id": "4df8d9ff-6f6f-438f-90a1-ef660d4586ad",
"binding:profile": {
"local_link_information": [
{
"port_id": "Ethernet3/1",
"switch_id": "0a:1b:2c:3d:4e:5f",
"switch_info": "switch1"
}
]
},
"binding:vif_details": {},
"binding:vif_type": "unbound",
"binding:vnic_type": "normal",
"binding:vnic_type": "other",
"description": "",
"device_id": "",
"device_owner": "",
"device_id": "d90a13da-be41-461f-9f99-1dbcf438fdf2",
"device_owner": "baremetal:none",
"fixed_ips": [
{
"ip_address": "10.0.0.2",

4
api-ref/source/v2/samples/ports/port-bind-show-response.json
View File

@@ -10,6 +10,7 @@
},
"binding:vif_type": "ovs",
"binding:vnic_type": "normal",
"created_at": "2016-03-08T20:19:41",
"description": "",
"device_id": "5e3898d7-11be-483e-9732-b2f5eccd2b2e",
"device_owner": "network:router_interface",
@@ -28,6 +29,7 @@
"project_id": "7e02058126cc4950b75f9970368ba177",
"security_groups": [],
"status": "ACTIVE",
"tenant_id": "7e02058126cc4950b75f9970368ba177"
"tenant_id": "7e02058126cc4950b75f9970368ba177",
"updated_at": "2016-03-08T20:19:41"
}
}

7
api-ref/source/v2/samples/ports/port-bind-update-request.json Normal file
View File

@@ -0,0 +1,7 @@
{
"port": {
"binding:host_id": "test_for_port_update_host",
"device_id": "d90a13da-be41-461f-9f99-1dbcf438fdf2",
"device_owner": "compute:nova"
}
}

31
api-ref/source/v2/samples/ports/port-bind-update-response.json Normal file
View File

@@ -0,0 +1,31 @@
{
"port": {
"admin_state_up": true,
"allowed_address_pairs": [],
"binding:host_id": "test_for_port_update_host",
"binding:profile": {},
"binding:vif_details": {},
"binding:vif_type": "binding_failed",
"binding:vnic_type": "normal",
"description": "",
"device_id": "d90a13da-be41-461f-9f99-1dbcf438fdf2",
"device_owner": "compute:nova",
"extra_dhcp_opts": [],
"fixed_ips": [
{
"ip_address": "20.20.0.4",
"subnet_id": "898dec4a-74df-4193-985f-c76721bcc746"
}
],
"id": "43c831e0-19ce-4a76-9a49-57b57e69428b",
"mac_address": "fa:16:3e:11:11:5e",
"name": "test-for-port-update",
"network_id": "883fc383-5ea1-4c8b-8916-e1ddb0a9f365",
"project_id": "522eda8d23124b25bf03fe44f1986b74",
"security_groups": [
"ce0179d6-8a94-4f7c-91c2-f3038e2acbd0"
],
"status": "DOWN",
"tenant_id": "522eda8d23124b25bf03fe44f1986b74"
}
}

1
api-ref/source/v2/samples/ports/port-update-request.json
View File

@@ -1,7 +1,6 @@
{
"port": {
"admin_state_up": true,
"binding:host_id": "test_for_port_update_host",
"device_id": "d90a13da-be41-461f-9f99-1dbcf438fdf2",
"device_owner": "compute:nova",
"name": "test-for-port-update"

0
api-ref/source/v2/samples/ports/ports-bind-show-response.json → api-ref/source/v2/samples/ports/ports-bind-list-response.json
View File