2e51f95263
Currently there are a few missing fields and API microversion notes in the ports API reference. This change resolves those issues. All ports microversion notes have been changed to use the active voice. Change-Id: If16c8e311e439e88fbbdd693c12e0f7992af5044
319 lines
7.2 KiB
ReStructuredText
319 lines
7.2 KiB
ReStructuredText
.. -*- rst -*-
|
|
|
|
=============
|
|
Ports (ports)
|
|
=============
|
|
|
|
Listing, Searching, Creating, Updating, and Deleting of bare metal Port
|
|
resources are done through the ``ports`` resource.
|
|
|
|
All Ports must be associated to a Node when created. This association
|
|
can be changed, though the request may be rejected if either the current
|
|
or destination Node are in a transitive state (e.g., in the process of
|
|
deploying) or are in a state that would be non-deterministically affected by
|
|
such a change (e.g., there is an active user instance on the Node).
|
|
|
|
|
|
List Ports
|
|
==========
|
|
|
|
.. rest_method:: GET /v1/ports
|
|
|
|
Return a list of bare metal Ports. Some filtering is possible by passing in
|
|
some parameters with the request.
|
|
|
|
By default, this query will return the uuid and address for each Port.
|
|
|
|
API microversion 1.6 added the ``node`` query parameter. If both ``node_uuid``
|
|
and ``node`` are specified in the request, ``node_uuid`` will be used to filter
|
|
results.
|
|
|
|
API microversion 1.8 added the ``fields`` request parameter. When specified,
|
|
this causes the content of the response to include only the specified fields,
|
|
rather than the default set.
|
|
|
|
API microversion 1.19 added the ``pxe_enabled`` and ``local_link_connection``
|
|
fields.
|
|
|
|
API microversion 1.24 added the ``portgroup_uuid`` field.
|
|
|
|
API microversion 1.34 added the ``physical_network`` field.
|
|
|
|
Normal response code: 200
|
|
|
|
Request
|
|
-------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- node: r_port_node_ident
|
|
- node_uuid: r_port_node_uuid
|
|
- portgroup: r_port_portgroup_ident
|
|
- address: r_port_address
|
|
- fields: fields
|
|
- limit: limit
|
|
- marker: marker
|
|
- sort_dir: sort_dir
|
|
- sort_key: sort_key
|
|
|
|
Response
|
|
--------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- ports: ports
|
|
- uuid: uuid
|
|
- address: port_address
|
|
- links: links
|
|
|
|
**Example Port list response:**
|
|
|
|
.. literalinclude:: samples/port-list-response.json
|
|
:language: javascript
|
|
|
|
|
|
Create Port
|
|
===========
|
|
|
|
.. rest_method:: POST /v1/ports
|
|
|
|
Creates a new Port resource.
|
|
|
|
This method requires a Node UUID and the physical hardware address for the Port
|
|
(MAC address in most cases).
|
|
|
|
API microversion 1.19 added the ``pxe_enabled`` and ``local_link_connection``
|
|
request and response fields.
|
|
|
|
API microversion 1.24 added the ``portgroup_uuid`` request and response fields.
|
|
|
|
API microversion 1.34 added the ``physical_network`` request and response
|
|
fields.
|
|
|
|
Normal response code: 201
|
|
|
|
Request
|
|
-------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- node_uuid: node_uuid
|
|
- address: port_address
|
|
- portgroup_uuid: portgroup_uuid
|
|
- local_link_connection: local_link_connection
|
|
- pxe_enabled: pxe_enabled
|
|
- physical_network: physical_network
|
|
- extra: extra
|
|
|
|
**Example Port creation request:**
|
|
|
|
.. literalinclude:: samples/port-create-request.json
|
|
:language: javascript
|
|
|
|
Response
|
|
--------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- uuid: uuid
|
|
- address: port_address
|
|
- node_uuid: node_uuid
|
|
- portgroup_uuid: portgroup_uuid
|
|
- local_link_connection: local_link_connection
|
|
- pxe_enabled: pxe_enabled
|
|
- physical_network: physical_network
|
|
- internal_info: internal_info
|
|
- extra: extra
|
|
- created_at: created_at
|
|
- updated_at: updated_at
|
|
- links: links
|
|
|
|
**Example Port creation response:**
|
|
|
|
.. literalinclude:: samples/port-create-response.json
|
|
:language: javascript
|
|
|
|
|
|
List Detailed Ports
|
|
===================
|
|
|
|
.. rest_method:: GET /v1/ports/detail
|
|
|
|
Return a list of bare metal Ports, with detailed information.
|
|
|
|
API microversion 1.6 added the ``node`` query parameter. If both ``node_uuid``
|
|
and ``node`` are specified in the request, ``node_uuid`` will be used to filter
|
|
results.
|
|
|
|
API microversion 1.19 added the ``pxe_enabled`` and ``local_link_connection``
|
|
response fields.
|
|
|
|
API microversion 1.24 added the ``portgroup`` query parameter and
|
|
``portgroup_uuid`` response field.
|
|
|
|
API microversion 1.34 added the ``physical_network`` response field.
|
|
|
|
Normal response code: 200
|
|
|
|
Request
|
|
-------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- node: r_port_node_ident
|
|
- node_uuid: r_port_node_uuid
|
|
- portgroup: r_port_portgroup_ident
|
|
- address: r_port_address
|
|
- limit: limit
|
|
- marker: marker
|
|
- sort_dir: sort_dir
|
|
- sort_key: sort_key
|
|
|
|
Response
|
|
--------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- ports: ports
|
|
- uuid: uuid
|
|
- address: port_address
|
|
- node_uuid: node_uuid
|
|
- portgroup_uuid: portgroup_uuid
|
|
- local_link_connection: local_link_connection
|
|
- pxe_enabled: pxe_enabled
|
|
- physical_network: physical_network
|
|
- internal_info: internal_info
|
|
- extra: extra
|
|
- created_at: created_at
|
|
- updated_at: updated_at
|
|
- links: links
|
|
|
|
**Example detailed Port list response:**
|
|
|
|
.. literalinclude:: samples/port-list-detail-response.json
|
|
:language: javascript
|
|
|
|
|
|
Show Port Details
|
|
=================
|
|
|
|
.. rest_method:: GET /v1/ports/{port_id}
|
|
|
|
Show details for the given Port.
|
|
|
|
API microversion 1.8 added the ``fields`` request parameter. When specified,
|
|
this causes the content of the response to include only the specified fields,
|
|
rather than the default set.
|
|
|
|
API microversion 1.19 added the ``pxe_enabled`` and ``local_link_connection``
|
|
response fields.
|
|
|
|
API microversion 1.24 added the ``portgroup_uuid`` response field.
|
|
|
|
API microversion 1.34 added the ``physical_network`` response field.
|
|
|
|
Normal response code: 200
|
|
|
|
Request
|
|
-------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- port_id: port_ident
|
|
- fields: fields
|
|
|
|
Response
|
|
--------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- uuid: uuid
|
|
- address: port_address
|
|
- node_uuid: node_uuid
|
|
- portgroup_uuid: portgroup_uuid
|
|
- local_link_connection: local_link_connection
|
|
- pxe_enabled: pxe_enabled
|
|
- physical_network: physical_network
|
|
- internal_info: internal_info
|
|
- extra: extra
|
|
- created_at: created_at
|
|
- updated_at: updated_at
|
|
- links: links
|
|
|
|
**Example Port details:**
|
|
|
|
.. literalinclude:: samples/port-create-response.json
|
|
:language: javascript
|
|
|
|
|
|
Update a Port
|
|
=============
|
|
|
|
.. rest_method:: PATCH /v1/ports/{port_id}
|
|
|
|
Update a Port.
|
|
|
|
API microversion 1.19 added the ``pxe_enabled`` and ``local_link_connection``
|
|
fields.
|
|
|
|
API microversion 1.24 added the ``portgroup_uuid`` field.
|
|
|
|
API microversion 1.34 added the ``physical_network`` field.
|
|
|
|
Normal response code: 200
|
|
|
|
Request
|
|
-------
|
|
|
|
The BODY of the PATCH request must be a JSON PATCH document, adhering to
|
|
`RFC 6902 <https://tools.ietf.org/html/rfc6902>`_.
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- port_id: port_ident
|
|
|
|
**Example Port update request:**
|
|
|
|
.. literalinclude:: samples/port-update-request.json
|
|
:language: javascript
|
|
|
|
Response
|
|
--------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- uuid: uuid
|
|
- address: port_address
|
|
- node_uuid: node_uuid
|
|
- portgroup_uuid: portgroup_uuid
|
|
- local_link_connection: local_link_connection
|
|
- pxe_enabled: pxe_enabled
|
|
- physical_network: physical_network
|
|
- internal_info: internal_info
|
|
- extra: extra
|
|
- created_at: created_at
|
|
- updated_at: updated_at
|
|
- links: links
|
|
|
|
**Example Port update response:**
|
|
|
|
.. literalinclude:: samples/port-update-response.json
|
|
:language: javascript
|
|
|
|
|
|
Delete Port
|
|
===========
|
|
|
|
.. rest_method:: DELETE /v1/ports/{port_id}
|
|
|
|
Delete a Port.
|
|
|
|
Normal response code: 204
|
|
|
|
Request
|
|
-------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- port_id: port_ident
|