From 50657a87df8b032bac888ac2a577b17b37f82eef Mon Sep 17 00:00:00 2001 From: Steve Baker Date: Mon, 12 Oct 2020 10:11:53 +1300 Subject: [PATCH] Complete the REST API POST documentation 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 --- api-ref/source/baremetal-api-v1-chassis.inc | 9 +- .../baremetal-api-v1-deploy-templates.inc | 10 ++ .../source/baremetal-api-v1-nodes-vifs.inc | 2 + api-ref/source/baremetal-api-v1-nodes.inc | 60 ++++--- .../source/baremetal-api-v1-portgroups.inc | 7 +- api-ref/source/baremetal-api-v1-ports.inc | 1 + api-ref/source/baremetal-api-v1-volume.inc | 4 +- api-ref/source/parameters.yaml | 152 ++++++++++++++++-- 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 adf4b92ac8..02d13c02d8 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 96e28341e9..286e13bdaa 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 22904d4042..98f921bb13 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 fb83d7c68a..9aa8482fe0 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 d558743d37..3b2489222e 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 b7ea31c903..f40d133915 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 203af581be..e71b639ea3 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 860f463ea0..882223d6f8 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,