Add portgroup to api-ref

This patch updates api-ref documentations to reflect
portgroup changes.

Related-Bug: #1618754
Co-Authored-By: Vladyslav Drok <vdrok@mirantis.com>
Change-Id: Id34344df9d3e68efe891c2be4a0b362be6557202

api-ref/regenerate-samples.sh

@@ -11,19 +11,26 @@ fi
 OS_AUTH_TOKEN=$(openstack token issue | grep ' id ' | awk '{print $4}')
 IRONIC_URL="http://127.0.0.1:6385"
 
+IRONIC_API_VERSION="1.24"
+
 export OS_AUTH_TOKEN IRONIC_URL
 
+DOC_CHASSIS_UUID="dff29d23-1ded-43b4-8ae1-5eebb3e30de1"
+DOC_NODE_UUID="6d85703a-565d-469a-96ce-30b6de53079d"
+DOC_PORT_UUID="d2b30520-907d-46c8-bfee-c5586e6fb3a1"
+DOC_PORTGROUP_UUID="e059deab-6e86-40d1-9e70-62d525f16728"
+
 function GET {
     # GET $RESOURCE
     curl -s -H "X-Auth-Token: $OS_AUTH_TOKEN" \
-            -H 'X-OpenStack-Ironic-API-Version: 1.22' \
+            -H "X-OpenStack-Ironic-API-Version: $IRONIC_API_VERSION" \
             ${IRONIC_URL}/$1 | jq -S '.'
 }
 
 function POST {
     # POST $RESOURCE $FILENAME
     curl -s -H "X-Auth-Token: $OS_AUTH_TOKEN" \
-            -H 'X-OpenStack-Ironic-API-Version: 1.22' \
+            -H "X-OpenStack-Ironic-API-Version: $IRONIC_API_VERSION" \
             -H "Content-Type: application/json" \
             -X POST --data @$2 \
             ${IRONIC_URL}/$1 | jq -S '.'
@@ -32,7 +39,7 @@ function POST {
 function PATCH {
     # POST $RESOURCE $FILENAME
     curl -s -H "X-Auth-Token: $OS_AUTH_TOKEN" \
-            -H 'X-OpenStack-Ironic-API-Version: 1.22' \
+            -H "X-OpenStack-Ironic-API-Version: $IRONIC_API_VERSION" \
             -H "Content-Type: application/json" \
             -X PATCH --data @$2 \
             ${IRONIC_URL}/$1 | jq -S '.'
@@ -41,7 +48,7 @@ function PATCH {
 function PUT {
     # PUT $RESOURCE $FILENAME
     curl -s -H "X-Auth-Token: $OS_AUTH_TOKEN" \
-            -H 'X-OpenStack-Ironic-API-Version: 1.22' \
+            -H "X-OpenStack-Ironic-API-Version: $IRONIC_API_VERSION" \
             -H "Content-Type: application/json" \
             -X PUT --data @$2 \
             ${IRONIC_URL}/$1
@@ -122,12 +129,35 @@ GET v1/nodes/$NID > node-show-response.json
 # Put the Node in maintenance mode, then continue doing everything else
 PUT v1/nodes/$NID/maintenance node-maintenance-request.json
 
+############
+# PORTGROUPS
+
+# Before we can create a portgroup, we must
+# write NODE ID into the create request document body
+sed -i "s/.*node_uuid.*/    \"node_uuid\": \"$NID\",/" portgroup-create-request.json
+
+POST v1/portgroups portgroup-create-request.json > portgroup-create-response.json
+PGID=$(cat portgroup-create-response.json | grep '"uuid"' | sed 's/.*"\([0-9a-f\-]*\)",*/\1/')
+if [ "$PGID" == "" ]; then
+    exit 1
+else
+    echo "Portgroup created. UUID: $PGID"
+fi
+
+GET v1/portgroups > portgroup-list-response.json
+GET v1/portgroups/detail > portgroup-list-detail-response.json
+PATCH v1/portgroups/$PGID portgroup-update-request.json > portgroup-update-response.json
+
+# skip GET $PGID because same result as POST
+# skip DELETE
+
 ###########
 # PORTS
 
 # Before we can create a port, we must
-# write NODE ID into the create request document body
+# write NODE ID and PORTGROUP ID into the create request document body
 sed -i "s/.*node_uuid.*/    \"node_uuid\": \"$NID\",/" port-create-request.json
+sed -i "s/.*portgroup_uuid.*/    \"portgroup_uuid\": \"$PGID\",/" port-create-request.json
 
 POST v1/ports port-create-request.json > port-create-response.json
 PID=$(cat port-create-response.json | grep '"uuid"' | sed 's/.*"\([0-9a-f\-]*\)",*/\1/')
@@ -150,6 +180,15 @@ PATCH v1/ports/$PID port-update-request.json > port-update-response.json
 GET v1/nodes/$NID/ports > node-port-list-response.json
 GET v1/nodes/$NID/ports/detail > node-port-detail-response.json
 
+#####################
+# NODE PORTGROUP APIs
+GET v1/nodes/$NID/portgroups > node-portgroup-list-response.json
+GET v1/nodes/$NID/portgroups/detail > node-portgroup-detail-response.json
+
+#####################
+# PORTGROUPS PORT APIs
+GET v1/portgroups/$PGID/ports > portgroup-port-list-response.json
+GET v1/portgroups/$PGID/ports/detail > portgroup-port-detail-response.json
 
 ############
 # LOOKUP API
@@ -169,3 +208,11 @@ PATCH v1/nodes/$NID node-update-driver-info-request.json > node-update-driver-in
 GET v1/nodes/$NID/management/boot_device/supported > node-get-supported-boot-devices-response.json
 PUT v1/nodes/$NID/management/boot_device node-set-boot-device.json
 GET v1/nodes/$NID/management/boot_device > node-get-boot-device-response.json
+
+
+#####################
+# Replace automatically generated UUIDs by already used in documentation
+sed -i "s/$CID/$DOC_CHASSIS_UUID/" *.json
+sed -i "s/$NID/$DOC_NODE_UUID/" *.json
+sed -i "s/$PID/$DOC_PORT_UUID/" *.json
+sed -i "s/$PGID/$DOC_PORTGROUP_UUID/" *.json

api-ref/source/baremetal-api-v1-nodes-portgroups.inc

@@ -0,0 +1,98 @@
+.. -*- rst -*-
+
+==============================================
+Listing Portgroups by Node (nodes, portgroups)
+==============================================
+
+Given a Node identifier (``uuid`` or ``name``), the API exposes the list of,
+and details of, all Portgroups associated with that Node.
+
+These endpoints do not allow modification of the Portgroups; that should be done
+by accessing the Portgroup resources under the ``/v1/portgroups`` endpoint.
+
+Portgroup resource was added in API microversion 1.24, if using older
+version, all the requests return ``Not Found (404)`` error code.
+
+
+List Portgroups by Node
+=======================
+
+.. rest_method:: GET /v1/nodes/{node_ident}/portgroups
+
+Return a list of bare metal Portgroups associated with ``node_ident``.
+
+Normal response code: 200
+
+Error codes: 400,401,403,404,406
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+    - node_ident: node_ident
+    - fields: fields
+    - limit: limit
+    - marker: marker
+    - sort_dir: sort_dir
+    - sort_key: sort_key
+
+Response
+--------
+
+.. rest_parameters:: parameters.yaml
+
+    - portgroups: portgroups
+    - uuid: uuid
+    - address: portgroup_address
+    - name: portgroup_name
+    - links: links
+
+**Example list of a Node's Portgroups:**
+
+.. literalinclude:: samples/node-portgroup-list-response.json
+
+
+List detailed Portgroups by Node
+================================
+
+.. rest_method:: GET /v1/nodes/{node_ident}/portgroups/detail
+
+Return a detailed list of bare metal Portgroups associated with ``node_ident``.
+
+Normal response code: 200
+
+Error codes: 400,401,403,404,406
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+    - node_ident: node_ident
+    - limit: limit
+    - marker: marker
+    - sort_dir: sort_dir
+    - sort_key: sort_key
+
+Response
+--------
+
+.. rest_parameters:: parameters.yaml
+
+    - portgroups: portgroups
+    - uuid: uuid
+    - address: portgroup_address
+    - name: portgroup_name
+    - node_uuid: node_uuid
+    - standalone_ports_supported: standalone_ports_supported
+    - internal_info: portgroup_internal_info
+    - extra: extra
+    - ports: n_ports
+    - created_at: created_at
+    - updated_at: updated_at
+    - links: links
+
+**Example details of a Node's Portgroups:**
+
+.. literalinclude:: samples/node-portgroup-detail-response.json

api-ref/source/baremetal-api-v1-nodes.inc

@@ -83,6 +83,8 @@ API microversion 1.21 introduced the ``resource_class`` field, which may be used
 store a resource designation for the proposed OpenStack Placement Engine. This
 field has no effect within Ironic.
 
+API microversion 1.24 introduced the ``/nodes/{node_ident}/portgroups`` endpoint.
+
 
 The list and example below are representative of the response as of API microversion 1.22.
 
@@ -112,6 +114,7 @@ The list and example below are representative of the response as of API microver
     - clean_step: clean_step
     - links: links
     - ports: n_ports
+    - portgroups: n_portgroups
     - states: n_states
     - network_interface: network_interface
     - resource_class: resource_class
@@ -246,6 +249,7 @@ Response
     - clean_step: clean_step
     - links: links
     - ports: n_ports
+    - portgroups: n_portgroups
     - states: n_states
     - network_interface: network_interface
     - resource_class: resource_class
@@ -306,6 +310,7 @@ Response
     - clean_step: clean_step
     - links: links
     - ports: n_ports
+    - portgroups: n_portgroups
     - states: n_states
     - network_interface: network_interface
     - resource_class: resource_class
@@ -373,6 +378,7 @@ Response
     - clean_step: clean_step
     - links: links
     - ports: n_ports
+    - portgroups: n_portgroups
     - states: n_states
     - network_interface: network_interface
     - resource_class: resource_class

api-ref/source/baremetal-api-v1-portgroups-ports.inc

@@ -0,0 +1,98 @@
+.. -*- rst -*-
+
+=============================================
+Listing Ports by Portgroup (portgroup, ports)
+=============================================
+
+Given a Portgroup identifier (``uuid`` or ``name``), the API exposes the list of,
+and details of, all Ports associated with that Portgroup.
+
+These endpoints do not allow modification of the Ports; that should be done
+by accessing the Port resources under the ``/v1/ports`` endpoint.
+
+``/v1/portgroups/{portgroup_ident}/ports`` endpoint was added in API
+microversion 1.24, if using older version, all the requests return
+``Not Found (404)`` error code.
+
+
+List Ports by Portgroup
+=======================
+
+.. rest_method:: GET /v1/portgroups/{portgroup_ident}/ports
+
+Return a list of bare metal Ports associated with ``portgroup_ident``.
+
+Normal response code: 200
+
+Error codes: 400,401,403,404,406
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+    - portgroup_ident: portgroup_ident
+    - 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 list of a Portgroup's Ports:**
+
+.. literalinclude:: samples/portgroup-port-list-response.json
+
+
+List detailed Ports by Portgroup
+================================
+
+.. rest_method:: GET /v1/portgroups/{portgroup_ident}/ports/detail
+
+Return a detailed list of bare metal Ports associated with ``portgroup_ident``.
+
+Normal response code: 200
+
+Error codes: 400,401,403,404,406
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+    - portgroup_ident: portgroup_ident
+    - 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
+    - local_link_connection: local_link_connection
+    - pxe_enabled: pxe_enabled
+    - internal_info: internal_info
+    - extra: extra
+    - portgroup_uuid: uuid
+    - created_at: created_at
+    - updated_at: updated_at
+    - links: links
+
+**Example details of a Portgroup's Ports:**
+
+.. literalinclude:: samples/portgroup-port-detail-response.json

api-ref/source/baremetal-api-v1-portgroups.inc

@@ -0,0 +1,251 @@
+.. -*- rst -*-
+
+=======================
+Portgroups (portgroups)
+=======================
+
+Starting with API version 1.23 ports can be combined into portgroups to support
+static LAG or MLAG configurations.
+Listing, Searching, Creating, Updating, and Deleting of bare metal Portgroup
+resources are done through the ``v1/portgroups`` resource.
+
+All Portgroups must be associated with 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 (for example, in the process of
+deploying) or are in a state that would be non-deterministically affected by
+such a change (for example, there is an active user instance on the Node).
+
+
+List Portgroups
+===============
+
+.. rest_method:: GET /v1/portgroups
+
+Return a list of bare metal Portgroups. Some filtering is possible by passing in
+some parameters with the request.
+
+By default, this query will return the UUID, name and address for each Portgroup.
+
+Normal response code: 200
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+    - node: r_portgroup_node_ident
+    - address: r_portgroup_address
+    - fields: fields
+    - limit: limit
+    - marker: marker
+    - sort_dir: sort_dir
+    - sort_key: sort_key
+
+Response
+--------
+
+.. rest_parameters:: parameters.yaml
+
+    - portgroups: portgroups
+    - uuid: uuid
+    - address: portgroup_address
+    - name: portgroup_name
+    - links: links
+
+**Example Portgroup list response:**
+
+.. literalinclude:: samples/portgroup-list-response.json
+   :language: javascript
+
+
+Create Portgroup
+================
+
+.. rest_method:: POST /v1/portgroups
+
+Creates a new Portgroup resource.
+
+This method requires a Node UUID and the physical hardware address for the
+Portgroup (MAC address in most cases).
+
+Normal response code: 201
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+    - node_uuid: node_uuid
+    - address: portgroup_address
+
+**Example Portgroup creation request:**
+
+.. literalinclude:: samples/portgroup-create-request.json
+   :language: javascript
+
+Response
+--------
+
+.. rest_parameters:: parameters.yaml
+
+    - uuid: uuid
+    - name: portgroup_name
+    - address: portgroup_address
+    - node_uuid: node_uuid
+    - standalone_ports_supported: standalone_ports_supported
+    - internal_info: portgroup_internal_info
+    - extra: extra
+    - created_at: created_at
+    - updated_at: updated_at
+    - links: links
+
+**Example Portgroup creation response:**
+
+.. literalinclude:: samples/portgroup-create-response.json
+   :language: javascript
+
+
+List Detailed Portgroups
+========================
+
+.. rest_method:: GET /v1/portgroups/detail
+
+Return a list of bare metal Portgroups, with detailed information.
+
+Normal response code: 200
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+    - node: r_portgroup_node_ident
+    - address: r_portgroup_address
+    - limit: limit
+    - marker: marker
+    - sort_dir: sort_dir
+    - sort_key: sort_key
+
+Response
+--------
+
+.. rest_parameters:: parameters.yaml
+
+    - portgroups: portgroups
+    - name: portgroup_name
+    - uuid: uuid
+    - address: portgroup_address
+    - node_uuid: node_uuid
+    - standalone_ports_supported: standalone_ports_supported
+    - internal_info: portgroup_internal_info
+    - extra: extra
+    - created_at: created_at
+    - updated_at: updated_at
+    - links: links
+
+**Example detailed Portgroup list response:**
+
+.. literalinclude:: samples/portgroup-list-detail-response.json
+   :language: javascript
+
+
+Show Portgroup Details
+======================
+
+.. rest_method:: GET /v1/portgroups/{portgroup_id}
+
+Show details for the given Portgroup.
+
+Normal response code: 200
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+    - portgroup_id: portgroup_ident
+    - fields: fields
+
+Response
+--------
+
+.. rest_parameters:: parameters.yaml
+
+    - uuid: uuid
+    - name: portgroup_name
+    - address: portgroup_address
+    - node_uuid: node_uuid
+    - standalone_ports_supported: standalone_ports_supported
+    - internal_info: portgroup_internal_info
+    - extra: extra
+    - created_at: created_at
+    - updated_at: updated_at
+    - links: links
+
+**Example Portgroup details:**
+
+.. literalinclude:: samples/portgroup-create-response.json
+   :language: javascript
+
+
+Update a Portgroup
+==================
+
+.. rest_method:: PATCH /v1/portgroups/{portgroup_id}
+
+Update a Portgroup.
+
+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
+
+    - portgroup_id: portgroup_ident
+
+**Example Portgroup update request:**
+
+.. literalinclude:: samples/portgroup-update-request.json
+   :language: javascript
+
+Response
+--------
+
+.. rest_parameters:: parameters.yaml
+
+    - uuid: uuid
+    - name: portgroup_name
+    - address: portgroup_address
+    - node_uuid: node_uuid
+    - standalone_ports_supported: standalone_ports_supported
+    - internal_info: portgroup_internal_info
+    - extra: extra
+    - created_at: created_at
+    - updated_at: updated_at
+    - links: links
+
+**Example Portgroup update response:**
+
+.. literalinclude:: samples/portgroup-update-response.json
+   :language: javascript
+
+
+Delete Portgroup
+================
+
+.. rest_method:: DELETE /v1/portgroups/{portgroup_id}
+
+Delete a Portgroup.
+
+Normal response code: 204
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+    - portgroup_id: portgroup_ident

api-ref/source/baremetal-api-v1-ports.inc

@@ -37,6 +37,8 @@ fields.
 
 .. TODO: add pxe_enabled and local_link_connection to all sample files
 
+API microversion 1.24 added the portgroup_uuid field.
+
 Normal response code: 200
 
 Request
@@ -46,6 +48,7 @@ Request
 
     - node: r_port_node_ident
     - node_uuid: r_port_node_uuid
+    - portgroup: r_port_portgroup_ident
     - address: r_port_address
     - fields: fields
     - limit: limit
@@ -102,6 +105,7 @@ Response
     - uuid: uuid
     - address: port_address
     - node_uuid: node_uuid
+    - portgroup_uuid: portgroup_uuid
     - local_link_connection: local_link_connection
     - pxe_enabled: pxe_enabled
     - internal_info: internal_info
@@ -127,6 +131,9 @@ Return a list of bare metal Ports, with detailed information.
 ``node_uuid`` and ``node`` are specified in the request, ``node_uuid``
 will be used to filter results.
 
+``portgroup`` query parameter and ``portgroup_uuid`` response field
+were added in API microversion 1.24.
+
 Normal response code: 200
 
 Request
@@ -136,6 +143,7 @@ Request
 
     - node: r_port_node_ident
     - node_uuid: r_port_node_uuid
+    - portgroup: r_port_portgroup_ident
     - address: r_port_address
     - limit: limit
     - marker: marker
@@ -151,6 +159,7 @@ Response
     - uuid: uuid
     - address: port_address
     - node_uuid: node_uuid
+    - portgroup_uuid: portgroup_uuid
     - local_link_connection: local_link_connection
     - pxe_enabled: pxe_enabled
     - internal_info: internal_info
@@ -176,6 +185,9 @@ 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.
 
+``portgroup`` query parameter and ``portgroup_uuid`` response field
+were added in API microversion 1.24.
+
 Normal response code: 200
 
 Request
@@ -194,6 +206,7 @@ Response
     - uuid: uuid
     - address: port_address
     - node_uuid: node_uuid
+    - portgroup_uuid: portgroup_uuid
     - local_link_connection: local_link_connection
     - pxe_enabled: pxe_enabled
     - internal_info: internal_info
@@ -240,6 +253,7 @@ Response
     - uuid: uuid
     - address: port_address
     - node_uuid: node_uuid
+    - portgroup_uuid: portgroup_uuid
     - local_link_connection: local_link_connection
     - pxe_enabled: pxe_enabled
     - internal_info: internal_info

api-ref/source/index.rst

@@ -10,8 +10,11 @@
 .. include:: baremetal-api-v1-nodes.inc
 .. include:: baremetal-api-v1-node-management.inc
 .. include:: baremetal-api-v1-node-passthru.inc
+.. include:: baremetal-api-v1-portgroups.inc
+.. include:: baremetal-api-v1-nodes-portgroups.inc
 .. include:: baremetal-api-v1-ports.inc
 .. include:: baremetal-api-v1-nodes-ports.inc
+.. include:: baremetal-api-v1-portgroups-ports.inc
 .. include:: baremetal-api-v1-drivers.inc
 .. include:: baremetal-api-v1-driver-passthru.inc
 .. include:: baremetal-api-v1-chassis.inc

api-ref/source/parameters.yaml

@@ -68,6 +68,12 @@ port_ident:
   in: path
   required: true
   type: string
+portgroup_ident:
+  description: |
+    The UUID or Name of the portgroup. Added in API microversion 1.23.
+  in: path
+  required: true
+  type: string
 
 
 callback_url:
@@ -188,6 +194,46 @@ r_port_node_uuid:
   in: query
   required: false
   type: string
+r_port_portgroup_ident:
+  description: |
+    Filter the list of returned Ports, and only return the ones associated
+    with this specific Portgroup (name or UUID), or an empty set if not found.
+    Added in API microversion 1.24.
+  in: query
+  required: false
+  type: string
+r_port_portgroup_uuid:
+  description: |
+    Filter the list of returned Ports, and only return the ones associated
+    with this specific Portgroup UUID, or an empty set if not found.
+    Added in API microversion 1.24.
+  in: query
+  required: false
+  type: string
+r_portgroup_address:
+  description: |
+    Filter the list of returned Portgroups, and only return the ones with the
+    specified physical hardware address, typically MAC, or an empty set if not
+    found. Added in API microversion 1.23.
+  in: query
+  required: false
+  type: string
+r_portgroup_node_ident:
+  description: |
+    Filter the list of returned Portgroups, and only return the ones associated
+    with this specific node (name or UUID), or an empty set if not found.
+    Added in API microversion 1.23.
+  in: query
+  required: false
+  type: string
+r_portgroup_node_uuid:
+  description: |
+    Filter the list of returned Portgroups, and only return the ones associated
+    with this specific node UUID, or an empty set if not found. Added in API
+    microversion 1.23.
+  in: query
+  required: false
+  type: string
 r_provision_state:
   description: |
     Filter the list of returned nodes, and only return those with the specified
@@ -432,6 +478,13 @@ maintenance_reason:
   in: body
   required: false
   type: string
+n_portgroups:
+  description: |
+    Links to the collection of portgroups on this node.
+    Added in API microversion 1.24.
+  in: body
+  required: true
+  type: array
 n_ports:
   description: |
     Links to the collection of ports on this node
@@ -525,6 +578,39 @@ port_address:
   in: body
   required: true
   type: string
+portgroup_address:
+  description: |
+    Physical hardware address of this Portgroup, typically the hardware
+    MAC address. Added in API microversion 1.23.
+  in: body
+  required: true
+  type: string
+portgroup_internal_info:
+  description: |
+    Internal metadata set and stored by the Portgroup. This field is read-only.
+    Added in API microversion 1.23.
+  in: body
+  required: true
+  type: JSON
+portgroup_name:
+  description: |
+    Human-readable identifier for the Portgroup resource. May be undefined.
+    Added in API microversion 1.23.
+  in: body
+  required: false
+  type: string
+portgroup_uuid:
+  description: |
+    UUID of the Portgroup this resource belongs to. Added in API microversion 1.23.
+  in: body
+  required: true
+  type: string
+portgroups:
+  description: |
+    A collection of Portgroup resources. Added in API microversion 1.23.
+  in: body
+  required: true
+  type: array
 ports:
   description: |
     A collection of Port resources.
@@ -606,6 +692,13 @@ resource_class:
   in: body
   required: true
   type: string
+standalone_ports_supported:
+  description: |
+    Indicates whether ports that are members of this portgroup can be
+    used as stand-alone ports. Added in API microversion 1.23.
+  in: body
+  required: true
+  type: boolean
 supported_boot_devices:
   description: |
     List of boot devices which this Node's driver supports.

api-ref/source/samples/api-root-response.json

@@ -9,7 +9,7 @@
     ],
     "min_version": "1.1",
     "status": "CURRENT",
-    "version": "1.22"
+    "version": "1.24"
   },
   "description": "Ironic is an OpenStack project which aims to provision baremetal machines.",
   "name": "OpenStack Ironic API",
@@ -24,7 +24,7 @@
       ],
       "min_version": "1.1",
       "status": "CURRENT",
-      "version": "1.22"
+      "version": "1.24"
     }
   ]
 }

api-ref/source/samples/api-v1-root-response.json

@@ -67,6 +67,16 @@
       "rel": "bookmark"
     }
   ],
+  "portgroups": [
+    {
+      "href": "http://127.0.0.1:6385/v1/portgroups/",
+      "rel": "self"
+    },
+    {
+      "href": "http://127.0.0.1:6385/portgroups/",
+      "rel": "bookmark"
+    }
+  ],
   "ports": [
     {
       "href": "http://127.0.0.1:6385/v1/ports/",

api-ref/source/samples/node-create-response.json

@@ -28,6 +28,16 @@
   "maintenance_reason": null,
   "name": "test_node",
   "network_interface": "flat",
+  "portgroups": [
+    {
+      "href": "http://127.0.0.1:6385/v1/nodes/6d85703a-565d-469a-96ce-30b6de53079d/portgroups",
+      "rel": "self"
+    },
+    {
+      "href": "http://127.0.0.1:6385/nodes/6d85703a-565d-469a-96ce-30b6de53079d/portgroups",
+      "rel": "bookmark"
+    }
+  ],
   "ports": [
     {
       "href": "http://127.0.0.1:6385/v1/nodes/6d85703a-565d-469a-96ce-30b6de53079d/ports",

api-ref/source/samples/node-port-detail-response.json

@@ -21,6 +21,7 @@
         "switch_info": "switch1"
       },
       "node_uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
+      "portgroup_uuid": "e43c722c-248e-4c6e-8ce8-0d8ff129387a",
       "pxe_enabled": true,
       "updated_at": "2016-08-18T22:28:50.148137+00:00",
       "uuid": "d2b30520-907d-46c8-bfee-c5586e6fb3a1"

api-ref/source/samples/node-portgroup-detail-response.json

@@ -0,0 +1,35 @@
+{
+  "portgroups": [
+    {
+      "address": "22:22:22:22:22:22",
+      "created_at": "2016-08-18T22:28:48.165105+00:00",
+      "extra": {},
+      "internal_info": {},
+      "links": [
+        {
+          "href": "http://127.0.0.1:6385/v1/portgroups/e43c722c-248e-4c6e-8ce8-0d8ff129387a",
+          "rel": "self"
+        },
+        {
+          "href": "http://127.0.0.1:6385/portgroups/e43c722c-248e-4c6e-8ce8-0d8ff129387a",
+          "rel": "bookmark"
+        }
+      ],
+      "name": "test_portgroup",
+      "node_uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
+      "ports": [
+        {
+          "href": "http://127.0.0.1:6385/v1/portgroups/e43c722c-248e-4c6e-8ce8-0d8ff129387a/ports",
+          "rel": "self"
+        },
+        {
+          "href": "http://127.0.0.1:6385/portgroups/e43c722c-248e-4c6e-8ce8-0d8ff129387a/ports",
+          "rel": "bookmark"
+        }
+      ],
+      "standalone_ports_supported": true,
+      "updated_at": "2016-11-04T17:46:09+00:00",
+      "uuid": "e43c722c-248e-4c6e-8ce8-0d8ff129387a"
+    }
+  ]
+}

api-ref/source/samples/node-portgroup-list-response.json

@@ -0,0 +1,19 @@
+{
+  "portgroups": [
+    {
+      "address": "22:22:22:22:22:22",
+      "links": [
+        {
+          "href": "http://127.0.0.1:6385/v1/portgroups/e43c722c-248e-4c6e-8ce8-0d8ff129387a",
+          "rel": "self"
+        },
+        {
+          "href": "http://127.0.0.1:6385/portgroups/e43c722c-248e-4c6e-8ce8-0d8ff129387a",
+          "rel": "bookmark"
+        }
+      ],
+      "name": "test_portgroup",
+      "uuid": "e43c722c-248e-4c6e-8ce8-0d8ff129387a"
+    }
+  ]
+}

api-ref/source/samples/node-show-response.json

@@ -30,6 +30,16 @@
   "maintenance_reason": null,
   "name": "test_node",
   "network_interface": "flat",
+  "portgroups": [
+    {
+      "href": "http://127.0.0.1:6385/v1/nodes/6d85703a-565d-469a-96ce-30b6de53079d/portgroups",
+      "rel": "self"
+    },
+    {
+      "href": "http://127.0.0.1:6385/nodes/6d85703a-565d-469a-96ce-30b6de53079d/portgroups",
+      "rel": "bookmark"
+    }
+  ],
   "ports": [
     {
       "href": "http://127.0.0.1:6385/v1/nodes/6d85703a-565d-469a-96ce-30b6de53079d/ports",

api-ref/source/samples/node-update-driver-info-response.json

@@ -32,6 +32,16 @@
   "maintenance_reason": "Replacing the hard drive",
   "name": "test_node",
   "network_interface": "flat",
+  "portgroups": [
+    {
+      "href": "http://127.0.0.1:6385/v1/nodes/6d85703a-565d-469a-96ce-30b6de53079d/portgroups",
+      "rel": "self"
+    },
+    {
+      "href": "http://127.0.0.1:6385/nodes/6d85703a-565d-469a-96ce-30b6de53079d/portgroups",
+      "rel": "bookmark"
+    }
+  ],
   "ports": [
     {
       "href": "http://127.0.0.1:6385/v1/nodes/6d85703a-565d-469a-96ce-30b6de53079d/ports",

api-ref/source/samples/nodes-list-details-response.json

@@ -32,6 +32,16 @@
       "maintenance_reason": null,
       "name": "test_node",
       "network_interface": "flat",
+      "portgroups": [
+        {
+          "href": "http://127.0.0.1:6385/v1/nodes/6d85703a-565d-469a-96ce-30b6de53079d/portgroups",
+          "rel": "self"
+        },
+        {
+          "href": "http://127.0.0.1:6385/nodes/6d85703a-565d-469a-96ce-30b6de53079d/portgroups",
+          "rel": "bookmark"
+        }
+      ],
       "ports": [
         {
           "href": "http://127.0.0.1:6385/v1/nodes/6d85703a-565d-469a-96ce-30b6de53079d/ports",

api-ref/source/samples/port-create-request.json

@@ -1,9 +1,10 @@
 {
     "node_uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
+    "portgroup_uuid": "e43c722c-248e-4c6e-8ce8-0d8ff129387a",
     "address": "11:11:11:11:11:11",
     "local_link_connection": {
         "switch_id": "0a:1b:2c:3d:4e:5f",
         "port_id": "Ethernet3/1",
         "switch_info": "switch1"
     }
-}
+}

api-ref/source/samples/port-create-response.json

@@ -19,6 +19,7 @@
     "switch_info": "switch1"
   },
   "node_uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
+  "portgroup_uuid": "e43c722c-248e-4c6e-8ce8-0d8ff129387a",
   "pxe_enabled": true,
   "updated_at": null,
   "uuid": "d2b30520-907d-46c8-bfee-c5586e6fb3a1"

api-ref/source/samples/port-list-detail-response.json

@@ -21,6 +21,7 @@
         "switch_info": "switch1"
       },
       "node_uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
+      "portgroup_uuid": "e43c722c-248e-4c6e-8ce8-0d8ff129387a",
       "pxe_enabled": true,
       "updated_at": null,
       "uuid": "d2b30520-907d-46c8-bfee-c5586e6fb3a1"

api-ref/source/samples/port-update-response.json

@@ -19,6 +19,7 @@
     "switch_info": "switch1"
   },
   "node_uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
+  "portgroup_uuid": "e43c722c-248e-4c6e-8ce8-0d8ff129387a",
   "pxe_enabled": true,
   "updated_at": "2016-08-18T22:28:50+00:00",
   "uuid": "d2b30520-907d-46c8-bfee-c5586e6fb3a1"

api-ref/source/samples/portgroup-create-request.json

@@ -0,0 +1,5 @@
+{
+    "node_uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
+    "address": "11:11:11:11:11:11",
+    "name": "test_portgroup"
+}

api-ref/source/samples/portgroup-create-response.json

@@ -0,0 +1,31 @@
+{
+  "address": "11:11:11:11:11:11",
+  "created_at": "2016-08-18T22:28:48.165105+00:00",
+  "extra": {},
+  "internal_info": {},
+  "links": [
+    {
+      "href": "http://127.0.0.1:6385/v1/portgroups/e43c722c-248e-4c6e-8ce8-0d8ff129387a",
+      "rel": "self"
+    },
+    {
+      "href": "http://127.0.0.1:6385/portgroups/e43c722c-248e-4c6e-8ce8-0d8ff129387a",
+      "rel": "bookmark"
+    }
+  ],
+  "name": "test_portgroup",
+  "node_uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
+  "ports": [
+    {
+      "href": "http://127.0.0.1:6385/v1/portgroups/e43c722c-248e-4c6e-8ce8-0d8ff129387a/ports",
+      "rel": "self"
+    },
+    {
+      "href": "http://127.0.0.1:6385/portgroups/e43c722c-248e-4c6e-8ce8-0d8ff129387a/ports",
+      "rel": "bookmark"
+    }
+  ],
+  "standalone_ports_supported": true,
+  "updated_at": null,
+  "uuid": "e43c722c-248e-4c6e-8ce8-0d8ff129387a"
+}

api-ref/source/samples/portgroup-list-detail-response.json

@@ -0,0 +1,35 @@
+{
+  "portgroups": [
+    {
+      "address": "11:11:11:11:11:11",
+      "created_at": "2016-08-18T22:28:48.165105+00:00",
+      "extra": {},
+      "internal_info": {},
+      "links": [
+        {
+          "href": "http://127.0.0.1:6385/v1/portgroups/e43c722c-248e-4c6e-8ce8-0d8ff129387a",
+          "rel": "self"
+        },
+        {
+          "href": "http://127.0.0.1:6385/portgroups/e43c722c-248e-4c6e-8ce8-0d8ff129387a",
+          "rel": "bookmark"
+        }
+      ],
+      "name": "test_portgroup",
+      "node_uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
+      "ports": [
+        {
+          "href": "http://127.0.0.1:6385/v1/portgroups/e43c722c-248e-4c6e-8ce8-0d8ff129387a/ports",
+          "rel": "self"
+        },
+        {
+          "href": "http://127.0.0.1:6385/portgroups/e43c722c-248e-4c6e-8ce8-0d8ff129387a/ports",
+          "rel": "bookmark"
+        }
+      ],
+      "standalone_ports_supported": true,
+      "updated_at": null,
+      "uuid": "e43c722c-248e-4c6e-8ce8-0d8ff129387a"
+    }
+  ]
+}

api-ref/source/samples/portgroup-list-response.json

@@ -0,0 +1,19 @@
+{
+  "portgroups": [
+    {
+      "address": "11:11:11:11:11:11",
+      "links": [
+        {
+          "href": "http://127.0.0.1:6385/v1/portgroups/e43c722c-248e-4c6e-8ce8-0d8ff129387a",
+          "rel": "self"
+        },
+        {
+          "href": "http://127.0.0.1:6385/portgroups/e43c722c-248e-4c6e-8ce8-0d8ff129387a",
+          "rel": "bookmark"
+        }
+      ],
+      "name": "test_portgroup",
+      "uuid": "e43c722c-248e-4c6e-8ce8-0d8ff129387a"
+    }
+  ]
+}

api-ref/source/samples/portgroup-port-detail-response.json

@@ -0,0 +1,30 @@
+{
+  "ports": [
+    {
+      "address": "22:22:22:22:22:22",
+      "created_at": "2016-08-18T22:28:48.165105+00:00",
+      "extra": {},
+      "internal_info": {},
+      "links": [
+        {
+          "href": "http://127.0.0.1:6385/v1/ports/d2b30520-907d-46c8-bfee-c5586e6fb3a1",
+          "rel": "self"
+        },
+        {
+          "href": "http://127.0.0.1:6385/ports/d2b30520-907d-46c8-bfee-c5586e6fb3a1",
+          "rel": "bookmark"
+        }
+      ],
+      "local_link_connection": {
+        "port_id": "Ethernet3/1",
+        "switch_id": "0a:1b:2c:3d:4e:5f",
+        "switch_info": "switch1"
+      },
+      "node_uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
+      "portgroup_uuid": "e43c722c-248e-4c6e-8ce8-0d8ff129387a",
+      "pxe_enabled": true,
+      "updated_at": "2016-11-04T17:46:09+00:00",
+      "uuid": "d2b30520-907d-46c8-bfee-c5586e6fb3a1"
+    }
+  ]
+}

api-ref/source/samples/portgroup-port-list-response.json

@@ -0,0 +1,18 @@
+{
+  "ports": [
+    {
+      "address": "22:22:22:22:22:22",
+      "links": [
+        {
+          "href": "http://127.0.0.1:6385/v1/ports/d2b30520-907d-46c8-bfee-c5586e6fb3a1",
+          "rel": "self"
+        },
+        {
+          "href": "http://127.0.0.1:6385/ports/d2b30520-907d-46c8-bfee-c5586e6fb3a1",
+          "rel": "bookmark"
+        }
+      ],
+      "uuid": "d2b30520-907d-46c8-bfee-c5586e6fb3a1"
+    }
+  ]
+}

api-ref/source/samples/portgroup-update-request.json

@@ -0,0 +1,7 @@
+[
+   {
+      "path" : "/address",
+      "value" : "22:22:22:22:22:22",
+      "op" : "replace"
+   }
+]

api-ref/source/samples/portgroup-update-response.json

@@ -0,0 +1,31 @@
+{
+  "address": "22:22:22:22:22:22",
+  "created_at": "2016-08-18T22:28:48.165105+00:00",
+  "extra": {},
+  "internal_info": {},
+  "links": [
+    {
+      "href": "http://127.0.0.1:6385/v1/portgroups/e43c722c-248e-4c6e-8ce8-0d8ff129387a",
+      "rel": "self"
+    },
+    {
+      "href": "http://127.0.0.1:6385/portgroups/e43c722c-248e-4c6e-8ce8-0d8ff129387a",
+      "rel": "bookmark"
+    }
+  ],
+  "name": "test_portgroup",
+  "node_uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
+  "ports": [
+    {
+      "href": "http://127.0.0.1:6385/v1/portgroups/e43c722c-248e-4c6e-8ce8-0d8ff129387a/ports",
+      "rel": "self"
+    },
+    {
+      "href": "http://127.0.0.1:6385/portgroups/e43c722c-248e-4c6e-8ce8-0d8ff129387a/ports",
+      "rel": "bookmark"
+    }
+  ],
+  "standalone_ports_supported": true,
+  "updated_at": "2016-11-04T17:46:09+00:00",
+  "uuid": "e43c722c-248e-4c6e-8ce8-0d8ff129387a"
+}