Merge "Complete the REST API POST documentation"

8 files changed, 207 insertions, 38 deletions

diff --git a/api-ref/source/baremetal-api-v1-chassis.inc b/api-ref/source/baremetal-api-v1-chassis.inc
index adf4b92ac..02d13c02d 100644
--- a/api-ref/source/baremetal-api-v1-chassis.inc
+++ b/api-ref/source/baremetal-api-v1-chassis.inc
@@ -167,7 +167,7 @@ Request
 
 .. rest_parameters:: parameters.yaml
 
-   - chassis: req_chassis
+   - uuid: req_uuid
    - description: req_description
    - extra: req_extra
 
@@ -228,10 +228,13 @@ Response Parameters
 
 .. rest_parameters:: parameters.yaml
 
-   - uuid: uuid
-   - chassis: chassis
    - description: description
+   - links: links
    - extra: extra
+   - created_at: created_at
+   - updated_at: updated_at
+   - nodes: nodes
+   - uuid: uuid
 
 Response Example
 ----------------
diff --git a/api-ref/source/baremetal-api-v1-deploy-templates.inc b/api-ref/source/baremetal-api-v1-deploy-templates.inc
index 96e28341e..286e13bda 100644
--- a/api-ref/source/baremetal-api-v1-deploy-templates.inc
+++ b/api-ref/source/baremetal-api-v1-deploy-templates.inc
@@ -36,6 +36,16 @@ Request
    - uuid: req_uuid
    - extra: req_extra
 
+Request Step
+------------
+
+.. rest_parameters:: parameters.yaml
+
+   - interface: deploy_template_step_interface
+   - step: deploy_template_step_step
+   - args: deploy_template_step_args
+   - priority: deploy_template_step_priority
+
 Request Example
 ---------------
 
diff --git a/api-ref/source/baremetal-api-v1-nodes-vifs.inc b/api-ref/source/baremetal-api-v1-nodes-vifs.inc
index 22904d404..98f921bb1 100644
--- a/api-ref/source/baremetal-api-v1-nodes-vifs.inc
+++ b/api-ref/source/baremetal-api-v1-nodes-vifs.inc
@@ -60,6 +60,8 @@ Request
 .. rest_parameters:: parameters.yaml
 
     - id: req_node_vif_ident
+    - port_uuid: req_node_vif_port_uuid
+    - portgroup_uuid: req_node_vif_portgroup_uuid
     - node_ident: node_ident
 
 **Example request to attach a VIF to a Node:**
diff --git a/api-ref/source/baremetal-api-v1-nodes.inc b/api-ref/source/baremetal-api-v1-nodes.inc
index fb83d7c68..9aa8482fe 100644
--- a/api-ref/source/baremetal-api-v1-nodes.inc
+++ b/api-ref/source/baremetal-api-v1-nodes.inc
@@ -113,28 +113,40 @@ Request
 
 .. rest_parameters:: parameters.yaml
 
-   - boot_interface: req_boot_interface
-   - conductor_group: req_conductor_group
-   - console_interface: req_console_interface
-   - deploy_interface: req_deploy_interface
-   - driver_info: req_driver_info
-   - driver: req_driver_name
-   - extra: req_extra
-   - inspect_interface: req_inspect_interface
-   - management_interface: req_management_interface
-   - name: node_name
-   - network_interface: req_network_interface
-   - power_interface: req_power_interface
-   - properties: req_properties
-   - raid_interface: req_raid_interface
-   - rescue_interface: req_rescue_interface
-   - resource_class: req_resource_class_create
-   - storage_interface: req_storage_interface
-   - uuid: req_uuid
-   - vendor_interface: req_vendor_interface
-   - owner: owner
-   - description: n_description
-   - lessee: lessee
+    - boot_interface: req_boot_interface
+    - conductor_group: req_conductor_group
+    - console_interface: req_console_interface
+    - deploy_interface: req_deploy_interface
+    - driver_info: req_driver_info
+    - driver: req_driver_name
+    - extra: req_extra
+    - inspect_interface: req_inspect_interface
+    - management_interface: req_management_interface
+    - name: node_name
+    - network_interface: req_network_interface
+    - power_interface: req_power_interface
+    - properties: req_properties
+    - raid_interface: req_raid_interface
+    - rescue_interface: req_rescue_interface
+    - resource_class: req_resource_class_create
+    - storage_interface: req_storage_interface
+    - uuid: req_uuid
+    - vendor_interface: req_vendor_interface
+    - owner: owner
+    - description: req_n_description
+    - lessee: lessee
+    - automated_clean: req_automated_clean
+    - bios_interface: req_bios_interface
+    - chassis_uuid: req_chassis_uuid
+    - instance_info: req_instance_info
+    - instance_uuid: req_instance_uuid
+    - maintenance: req_maintenance
+    - maintenance_reason: maintenance_reason
+    - network_data: network_data
+    - protected: protected
+    - protected_reason: protected_reason
+    - retired: retired
+    - retired_reason: retired_reason
 
 **Example Node creation request with a dynamic driver:**
 
@@ -208,7 +220,11 @@ microversion 1.48.
     - lessee: lessee
     - description: n_description
     - allocation_uuid: allocation_uuid
+    - automated_clean: automated_clean
+    - bios_interface: bios_interface
     - network_data: network_data
+    - retired: retired
+    - retired_reason: retired_reason
 
 **Example JSON representation of a Node:**
 
diff --git a/api-ref/source/baremetal-api-v1-portgroups.inc b/api-ref/source/baremetal-api-v1-portgroups.inc
index d558743d3..3b2489222 100644
--- a/api-ref/source/baremetal-api-v1-portgroups.inc
+++ b/api-ref/source/baremetal-api-v1-portgroups.inc
@@ -88,7 +88,12 @@ Request
 
     - node_uuid: req_node_uuid
     - address: req_portgroup_address
-    - name: portgroup_name
+    - name: req_portgroup_name
+    - mode: req_portgroup_mode
+    - standalone_ports_supported: req_standalone_ports_supported
+    - properties: req_portgroup_properties
+    - extra: req_extra
+    - uuid: req_uuid
 
 **Example Portgroup creation request:**
 
diff --git a/api-ref/source/baremetal-api-v1-ports.inc b/api-ref/source/baremetal-api-v1-ports.inc
index b7ea31c90..f40d13391 100644
--- a/api-ref/source/baremetal-api-v1-ports.inc
+++ b/api-ref/source/baremetal-api-v1-ports.inc
@@ -121,6 +121,7 @@ Request
     - physical_network: req_physical_network
     - extra: req_extra
     - is_smartnic: req_is_smartnic
+    - uuid: req_uuid
 
 **Example Port creation request:**
 
diff --git a/api-ref/source/baremetal-api-v1-volume.inc b/api-ref/source/baremetal-api-v1-volume.inc
index 203af581b..e71b639ea 100644
--- a/api-ref/source/baremetal-api-v1-volume.inc
+++ b/api-ref/source/baremetal-api-v1-volume.inc
@@ -118,6 +118,7 @@ Request
     - type: volume_connector_type
     - connector_id: volume_connector_connector_id
     - extra: req_extra
+    - uuid: req_uuid
 
 **Example Volume connector creation request:**
 
@@ -322,10 +323,11 @@ Request
 
     - node_uuid: req_node_uuid
     - volume_type: volume_target_volume_type
-    - properties: volume_target_properties
+    - properties: req_volume_target_properties
     - boot_index: volume_target_boot_index
     - volume_id: volume_target_volume_id
     - extra: req_extra
+    - uuid: req_uuid
 
 **Example Volume target creation request:**
 
diff --git a/api-ref/source/parameters.yaml b/api-ref/source/parameters.yaml
index 860f463ea..882223d6f 100644
--- a/api-ref/source/parameters.yaml
+++ b/api-ref/source/parameters.yaml
@@ -493,6 +493,18 @@ allocation_uuid:
   in: body
   required: true
   type: string
+automated_clean:
+  description: |
+    Indicates whether the node will perform automated clean or not.
+  in: body
+  required: true
+  type: boolean
+bios_interface:
+  description: |
+    The bios interface to be used for this node.
+  in: body
+  required: true
+  type: string
 bios_setting_name:
   description: |
     The name of a Bios setting for a Node, eg. "virtualization".
@@ -721,18 +733,35 @@ deploy_template_name:
   in: body
   required: true
   type: string
+deploy_template_step_args:
+  description: |
+    A dictionary of arguments that are passed to the deploy step method.
+  in: body
+  required: true
+  type: object
+deploy_template_step_interface:
+  description: |
+    The name of the driver interface.
+  in: body
+  required: true
+  type: string
+deploy_template_step_priority:
+  description: |
+    A non-negative integer priority for the step. A value of ``0`` will
+    disable that step.
+  in: body
+  required: true
+  type: integer
+deploy_template_step_step:
+  description: |
+    The name of the deploy step method on the driver interface.
+  in: body
+  required: true
+  type: string
 deploy_template_steps:
   description: |
-    The deploy steps of the deploy template. Must be a list containing at least
-    one deploy step.
-
-    A deploy step is a dictionary with required keys ``interface``, ``step``,
-    ``args``, and ``priority``.  The value for ``interface`` is the name of the
-    driver interface.  The value for ``step`` is the name of the deploy step
-    method on the driver interface. The value for ``args`` is a dictionary of
-    arguments that are passed to the deploy step method. The value for
-    ``priority`` is a non-negative integer priority for the step. A value of
-    ``0`` for ``priority`` will disable that step.
+    The deploy steps of the deploy template. Must be a list of dictionaries
+    containing at least one deploy step. See `Request Step`_ for step parameters.
   in: body
   required: true
   type: array
@@ -1212,7 +1241,7 @@ portgroup_name:
   description: |
     Human-readable identifier for the Portgroup resource. May be undefined.
   in: body
-  required: false
+  required: true
   type: string
 portgroup_properties:
   description: |
@@ -1344,6 +1373,18 @@ req_allocation_traits:
   in: body
   required: false
   type: array
+req_automated_clean:
+  description: |
+    Indicates whether the node will perform automated clean or not.
+  in: body
+  required: false
+  type: boolean
+req_bios_interface:
+  description: |
+    The bios interface to be used for this node.
+  in: body
+  required: false
+  type: string
 req_boot_device:
   description: |
     The boot device for a Node, eg. "pxe" or "disk".
@@ -1369,6 +1410,12 @@ req_chassis:
   in: body
   required: true
   type: array
+req_chassis_uuid:
+  description: |
+    UUID of the chassis associated with this Node. May be empty or None.
+  in: body
+  required: false
+  type: string
 req_conductor_group:
   description: |
     The conductor group for a node. Case-insensitive string up to 255
@@ -1427,6 +1474,21 @@ req_inspect_interface:
   in: body
   required: false
   type: string
+req_instance_info:
+  description: |
+    Information used to customize the deployed image. May include root partition
+    size, a base 64 encoded config drive, and other metadata. Note that this field
+    is erased automatically when the instance is deleted (this is done by requesting
+    the Node provision state be changed to DELETED).
+  in: body
+  required: false
+  type: JSON
+req_instance_uuid:
+  description: |
+    UUID of the Nova instance associated with this Node.
+  in: body
+  required: false
+  type: string
 req_is_smartnic:
   description: |
     Indicates whether the Port is a Smart NIC port.
@@ -1443,12 +1505,28 @@ req_local_link_connection:
   in: body
   required: false
   type: JSON
+req_maintenance:
+  description: |
+    Whether or not this Node is currently in "maintenance mode". Setting a Node
+    into maintenance mode removes it from the available resource pool and halts
+    some internal automation. This can happen manually (eg, via an API request)
+    or automatically when Ironic detects a hardware fault that prevents communication
+    with the machine.
+  in: body
+  required: false
+  type: boolean
 req_management_interface:
   description: |
     Interface for out-of-band node management, e.g. "ipmitool".
   in: body
   required: false
   type: string
+req_n_description:
+  description: |
+    Informational text about this node.
+  in: body
+  required: false
+  type: string
 req_network_interface:
   description: |
     Which Network Interface provider to use when plumbing the network
@@ -1468,6 +1546,20 @@ req_node_vif_ident:
   in: body
   required: true
   type: string
+req_node_vif_port_uuid:
+  description: |
+    The UUID of a port to attach the VIF to. Cannot be specified with
+    ``portgroup_uuid``.
+  in: body
+  required: false
+  type: string
+req_node_vif_portgroup_uuid:
+  description: |
+    The UUID of a portgroup to attach the VIF to. Cannot be specified with
+    ``port_uuid``.
+  in: body
+  required: false
+  type: string
 req_persistent:
   description: |
     Whether the boot device should be set only for the next reboot, or
@@ -1496,6 +1588,28 @@ req_portgroup_address:
   in: body
   required: false
   type: string
+req_portgroup_mode:
+  description: |
+    Mode of the port group. For possible values, refer to
+    https://www.kernel.org/doc/Documentation/networking/bonding.txt. If not
+    specified in a request to create a port group, it will be set to the value
+    of the ``[DEFAULT]default_portgroup_mode`` configuration option. When set,
+    can not be removed from the port group.
+  in: body
+  required: false
+  type: string
+req_portgroup_name:
+  description: |
+    Human-readable identifier for the Portgroup resource. May be undefined.
+  in: body
+  required: false
+  type: string
+req_portgroup_properties:
+  description: |
+    Key/value properties related to the port group's configuration.
+  in: body
+  required: false
+  type: JSON
 req_portgroup_uuid:
   description: |
     UUID of the Portgroup this resource belongs to.
@@ -1546,6 +1660,13 @@ req_resource_class_create:
   in: body
   required: false
   type: string
+req_standalone_ports_supported:
+  description: |
+    Indicates whether ports that are members of this portgroup can be
+    used as stand-alone ports.
+  in: body
+  required: false
+  type: boolean
 req_storage_interface:
   description: |
     Interface used for attaching and detaching volumes on this node, e.g.
@@ -1581,6 +1702,15 @@ req_vendor_interface:
   in: body
   required: false
   type: string
+req_volume_target_properties:
+  description: |
+    A set of physical information of the volume such as the identifier
+    (eg. IQN) and LUN number of the volume. This information is used to connect
+    the node to the volume by the storage interface. The contents depend on the
+    volume type.
+  in: body
+  required: false
+  type: object
 requested_provision_state:
   description: |
     One of the provisioning verbs: manage, provide, inspect, clean, active,