diff options
Diffstat (limited to 'api-ref/source/baremetal-api-v1-nodes.inc')
| -rw-r--r-- | api-ref/source/baremetal-api-v1-nodes.inc | 358 |
1 files changed, 259 insertions, 99 deletions
diff --git a/api-ref/source/baremetal-api-v1-nodes.inc b/api-ref/source/baremetal-api-v1-nodes.inc index 03e35f490..6bb3f5c20 100644 --- a/api-ref/source/baremetal-api-v1-nodes.inc +++ b/api-ref/source/baremetal-api-v1-nodes.inc @@ -4,213 +4,373 @@ Nodes (nodes) ============= +List, Searching, Creating, Updating, and Deleting of bare metal Node resources +are done through the ``/v1/nodes`` resource. There are also several sub-resources, +which allow further actions to be performed on a bare metal Node. +A Node is the canonical representation of a discretely allocatable server, +capable of running an Operating System. Each Node must be associated with a +``driver``; this informs Ironic what protocol to use when managing the Node. - -Show node details -================= - -.. rest_method:: GET /v1/nodes/{node_id} - -Shows details for a node. - - -Normal response codes: 200 -Error response codes:413,405,404,403,401,400,503, - - -Request -------- - -.. rest_parameters:: parameters.yaml - - - node_id: node_id - - fields: fields - - - - -Response Example ----------------- - -.. literalinclude:: samples/node-show-response.json - :language: javascript - - - - - - +Beginning with API microversion 1.6, a Node may be referenced both by its UUID +and by a unique human-readable "name" in any request. Throughout this +documentation, this is referred to as the ``node_ident``. Responses clearly +indicate whether a given field is a ``uuid`` or a ``name``. +Create Node +=========== +.. rest_method:: POST /v1/nodes +Creates a new Node resource. -Update node -=========== +This method requires that a ``driver`` be supplied in the request body. Most +subresources of a Node (eg, ``properties``, ``driver_info``, etc) may be +supplied when the Node is created, or the resource may be updated later. -.. rest_method:: PATCH /v1/nodes/{node_id} +API microversion 1.2 introduced the new ``available`` state name, which replaced +``None`` as the status of an unprovisioned Node. All clients should be updated to +use the new ``available`` state name. -Updates a node. +Nodes in the ``available`` state may have workloads provisioned on them; they are +"available" for use. +API microversion 1.11 changed the default initial state of newly-created Nodes +from ``available`` to ``enroll``. This provides users a workflow to verify the +manageability of a Node and perform necessary operational functions (eg, building +a RAID array) before making the Node available for provisioning. -Normal response codes: 200 -Error response codes:413,415,405,404,403,401,400,503,409, +Normal response codes: 201 +.. TODO: add error codes Request ------- .. rest_parameters:: parameters.yaml - - node_id: node_id - - + - driver: r_driver_name +**Example Node creation request:** -Response Example ----------------- - -.. literalinclude:: samples/node-show-response.json +.. literalinclude:: samples/node-create-request.json :language: javascript +Response +-------- + +The response will contain the complete Node record, with the supplied data, +and any defaults added for non-specified fields. Most fields default to "null" +or "". +API microversion 1.5 introduced the ``name`` field. +API microversion 1.7 introduced the ``clean_step`` field` +API microversion 1.12 introduced support for the ``raid_config`` and +``target_raid_config`` fields. +The list and example below are representative of the response as of API microversion 1.16. +.. rest_parameters:: parameters.yaml + - uuid: node_uuid + - name: node_name + - power_state: power_state + - target_power_state: target_power_state + - provision_state: provision_state + - target_provision_state: target_provision_state + - maintenance: maintenance + - maintenance_reason: maintenance_reason + - last_error: last_error + - reservation: reservation + - driver: driver_name + - driver_info: driver_info + - driver_internal_info: driver_internal_info + - properties: n_properties + - instance_info: instance_info + - instance_uuid: instance_uuid + - chassis_uuid: chassis_uuid + - extra: extra + - console_enabled: console_enabled + - raid_config: raid_config + - target_raid_config: target_raid_config + - clean_step: clean_step + - links: links + - ports: n_ports + - states: n_states + +**Example JSON representation of a Node:** + +.. literalinclude:: samples/node-create-response.json + :language: javascript +List Nodes +========== +.. rest_method:: GET /v1/nodes +Return a list of bare metal Nodes, with some useful information about +each Node. Some filtering is possible by passing in flags with the request. +By default, this query will return the name, uuid, instance uuid, power state, +provision state, and maintenance setting for each Node. -Delete node -=========== +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. -.. rest_method:: DELETE /v1/nodes/{node_id} +API microversion 1.9 added the ``provision_state`` Request parameter, allowing +the list of returned Nodes to be filtered by their current state. -Deletes a node. +API microversion 1.16 added the ``driver`` Request parameter, allowing +the list of returned Nodes to be filtered by their driver name. -Error response codes:204,413,415,405,404,403,401,400,503,409, +Normal response codes: 200 +.. TODO: add error codes Request ------- .. rest_parameters:: parameters.yaml - - node_id: node_id - - - - - - - - + - instance_uuid: r_instance_uuid + - maintenance: r_maintenance + - associated: r_associated + - provision_state: r_provision_state + - driver: r_driver + - fields: fields + - limit: limit + - marker: marker + - sort_dir: sort_dir + - sort_key: sort_key +Response +-------- +.. rest_parameters:: parameters.yaml + - uuid: uuid + - name: node_name + - instance_uuid: instance_uuid + - power_state: power_state + - provision_state: provision_state + - maintenance: maintenance + - links: links +**Example list of Nodes:** +.. literalinclude:: samples/nodes-list-response.json + :language: javascript -List nodes with details -======================= +List Nodes Detailed +=================== .. rest_method:: GET /v1/nodes/detail -Lists all nodes with details. +Return a list of bare metal Nodes with complete details. Some filtering is +possible by passing in flags with the request. +This method is particularly useful to locate the Node associated to a given +Nova instance, eg. with a request to ``v1/nodes/detail?instance_uuid={NOVA INSTANCE UUID}`` Normal response codes: 200 -Error response codes:413,405,404,403,401,400,503, +.. TODO: add error codes Request ------- +.. rest_parameters:: parameters.yaml + - instance_uuid: r_instance_uuid + - maintenance: r_maintenance + - associated: r_associated + - provision_state: r_provision_state + - driver: r_driver + - limit: limit + - marker: marker + - sort_dir: sort_dir + - sort_key: sort_key +Response +-------- +.. rest_parameters:: parameters.yaml -Response Example ----------------- + - uuid: node_uuid + - name: node_name + - power_state: power_state + - target_power_state: target_power_state + - provision_state: provision_state + - target_provision_state: target_provision_state + - maintenance: maintenance + - maintenance_reason: maintenance_reason + - last_error: last_error + - reservation: reservation + - driver: driver_name + - driver_info: driver_info + - driver_internal_info: driver_internal_info + - properties: n_properties + - instance_info: instance_info + - instance_uuid: instance_uuid + - chassis_uuid: chassis_uuid + - extra: extra + - console_enabled: console_enabled + - raid_config: raid_config + - target_raid_config: target_raid_config + - clean_step: clean_step + - links: links + - ports: n_ports + - states: n_states + +**Example detailed list of Nodes:** .. literalinclude:: samples/nodes-list-details-response.json :language: javascript +Show Node Details +================= +.. rest_method:: GET /v1/nodes/{node_ident} +Shows details for a node. By default, this will return the full representation +of the resource; an optional ``fields`` parameter can be supplied to return +only the specified set. +Normal response codes: 200 - - - - - -Create node -=========== - -.. rest_method:: POST /v1/nodes - -Creates a node. - -Error response codes:201,413,415,405,404,403,401,400,503,409, - +.. TODO: add error codes Request ------- +.. rest_parameters:: parameters.yaml + - node_ident: node_ident + - fields: fields +Response +-------- +.. rest_parameters:: parameters.yaml + - uuid: node_uuid + - name: node_name + - power_state: power_state + - target_power_state: target_power_state + - provision_state: provision_state + - target_provision_state: target_provision_state + - maintenance: maintenance + - maintenance_reason: maintenance_reason + - last_error: last_error + - reservation: reservation + - driver: driver_name + - driver_info: driver_info + - driver_internal_info: driver_internal_info + - properties: n_properties + - instance_info: instance_info + - instance_uuid: instance_uuid + - chassis_uuid: chassis_uuid + - extra: extra + - console_enabled: console_enabled + - raid_config: raid_config + - target_raid_config: target_raid_config + - clean_step: clean_step + - links: links + - ports: n_ports + - states: n_states + +**Example JSON representation of a Node:** +.. literalinclude:: samples/node-show-response.json + :language: javascript +Update Node +=========== +.. rest_method:: PATCH /v1/nodes/{node_ident} +Updates the information stored about a Node. - - - - - -List nodes -========== - -.. rest_method:: GET /v1/nodes - -Lists all nodes. - +Note that this endpoint can not be used to request state changes, which are +managed through sub-resources. Normal response codes: 200 -Error response codes:413,405,404,403,401,400,503, +.. TODO: add error codes 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 + - node_ident: node_ident +**Example PATCH document updating Node driver_info:** -Response Example ----------------- +.. literalinclude:: samples/node-update-driver-info-request.json -.. literalinclude:: samples/nodes-list-response.json - :language: javascript +Response +-------- + +.. rest_parameters:: parameters.yaml + - uuid: node_uuid + - name: node_name + - power_state: power_state + - target_power_state: target_power_state + - provision_state: provision_state + - target_provision_state: target_provision_state + - maintenance: maintenance + - maintenance_reason: maintenance_reason + - last_error: last_error + - reservation: reservation + - driver: driver_name + - driver_info: driver_info + - driver_internal_info: driver_internal_info + - properties: n_properties + - instance_info: instance_info + - instance_uuid: instance_uuid + - chassis_uuid: chassis_uuid + - extra: extra + - console_enabled: console_enabled + - raid_config: raid_config + - target_raid_config: target_raid_config + - clean_step: clean_step + - links: links + - ports: n_ports + - states: n_states + +**Example JSON representation of a Node:** + +.. literalinclude:: samples/node-update-driver-info-response.json + :language: javascript +Delete Node +=========== +.. rest_method:: DELETE /v1/nodes/{node_ident} +Deletes a node. +Normal response codes: 204 +.. TODO: add error codes +Request +------- +.. rest_parameters:: parameters.yaml + - node_ident: node_ident
\ No newline at end of file |