openstack/ironic
Code Issues Proposed changes

Complete the REST API POST documentation

Browse Source 
This change adds missing POST request parameters and makes other minor
corrections to the REST API documentation.

Its possible that some of the parameters for /v1/nodes were never
intended to be available for the POST call, but this docs change is to
document what has been implemented, not the original intention.

Change-Id: I1e35586d20bd3eda4d727931235340dd408c7508
This commit is contained in:
Steve Baker 2020-10-12 10:11:53 +13:00
parent 4896f58a2d
commit 50657a87df
8 changed files with 207 additions and 38 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

9
api-ref/source/baremetal-api-v1-chassis.inc
View File

@ -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
----------------

10
api-ref/source/baremetal-api-v1-deploy-templates.inc
View File

@ -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
---------------

2
api-ref/source/baremetal-api-v1-nodes-vifs.inc
View File

@ -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:**

60
api-ref/source/baremetal-api-v1-nodes.inc
View File

@ -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:**

7
api-ref/source/baremetal-api-v1-portgroups.inc
View File

@ -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:**

1
api-ref/source/baremetal-api-v1-ports.inc
View File

@ -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:**

4
api-ref/source/baremetal-api-v1-volume.inc
View File

@ -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:**

152
api-ref/source/parameters.yaml
View File

@ -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,