openstack/ironic
Code Issues Proposed changes
bfddae6705
ironic/api-ref/source/baremetal-api-v1-node-management.inc
Devananda van der Veen 28a399a13c Update api-ref for v1.22 
This commit does several things, which were just easier to do together.

- Adds a new "misc" page describing the /v1/lookup and /v1/heartbeat
  resources.
- Adds descriptions of the node.resource_class and
  node.network_interface fields that were introduced into the API but
  not into the documentation.
- Introduces a new script, api-ref/regenerate-samples.sh, which can be
  used with Ironic to automate the generation of most of the sample files
  used in the api-ref documententation.
- Corrects several errors in the sample JSON files that rendered errors
  when using them with curl for POST, PUT, or PATCH.
- Uses the aforementioned regenerate-samples.sh script to regenerate
  most of the JSON result samples, ensuring that they are all up to date
  with the v1.22 API microversion.
- Removes a few old/incorrect "Error Code" listings.
- Updates the index page to remove extraneous wording.

Change-Id: I764cbb43be15f05ba681de6ce1be1ae7c022173d
2016-08-21 11:43:30 -07:00

394 lines
9.9 KiB
ReStructuredText
Raw Blame History

.. -*- rst -*-
=======================
Node Management (nodes)
=======================
Nodes can be managed through several sub-resources.
Maintenance mode can be set by the operator, with an optional "reason" stored
by Ironic.
The supplied ``driver_info`` can be validated to ensure that the selected
``driver`` has all the information it requires to manage the Node.
A Node can be rebooted, turned on, or turned off by requesting a change to its
power state. This is handled asynchronously and tracked in the ``target_power_state``
field after the request is received.
A Node's boot device can be changed, and the set of supported boot devices
can be queried.
A request to change a Node's provision state is also tracked asynchronously;
the ``target_provision_state`` represents the requested state. A Node
may transition through several discrete ``provision_state`` steps before arriving
at the requested state. This can vary between drivers and based on configuration.
For example, a Node in the ``available`` state can have an instance deployed to it
by requesting the provision state of ``active``. During this transition, the Node's
``provision_state`` will temporarily be set to ``deploying``, and depending on the driver,
it may also be ``wait call-back``. When the transitions are complete, ``target_provision_state``
will be set to ``None`` and ``provision_state`` will be set to ``active```.
To destroy the instance, request the provision state of ``delete``. During this
transition, the Node may or may not go through a ``cleaning`` state,
depending on the service configuration.
Validate Node
===============
.. rest_method:: GET /v1/nodes/{node_ident}/validate
Request that Ironic validate whether the Node's ``driver`` has enough information
to manage the Node. This polls each ``interface`` on the driver, and returns
the status of that ``interface`` as an element in the response. Note that each
``driver`` may require different information to be supplied, and not all drivers
support all interfaces.
Normal response codes: 200
.. TODO: add error codes
Request
-------
.. rest_parameters:: parameters.yaml
- node_ident: node_ident
Response
--------
Each element in the response will contain a "result" variable, which will have
a value of "true" or "false", indicating that the interface either has or does
not have sufficient information to function. A value of ``null`` indicates that
the Node's driver does not support that interface.
.. rest_parameters:: parameters.yaml
- power: v_power
- boot: v_boot
- deploy: v_deploy
- console: v_console
- management: v_management
- inspect: v_inspect
- raid: v_raid
**Example node validation response:**
.. literalinclude:: samples/node-validate-response.json
:language: javascript
Set Maintenance Flag
=============================
.. rest_method:: PUT /v1/nodes/{node_ident}/maintenance
Request that Ironic set the maintenance flag on the Node. This will disable
certain automatic actions that the Node's driver may take, and remove
the Node from Nova's available resource pool.
Normal response code: 202
.. TODO: Add link to user / operator documentation on the Maintenance flag
Request
-------
.. rest_parameters:: parameters.yaml
- node_ident: node_ident
- reason: reason
**Example request: mark a node for maintenance:**
.. literalinclude:: samples/node-maintenance-request.json
Clear Maintenance Flag
==============================
.. rest_method:: DELETE /v1/nodes/{node_ident}/maintenance
The maintenance flag is unset by sending a DELETE request to this endpoint.
If the request is accepted, Ironic will also clear the ``maintenance_reason``
field.
Normal response code: 202
.. TODO: Add link to user / operator documentation on the Maintenance flag
Request
-------
.. rest_parameters:: parameters.yaml
- node_ident: node_ident
Set Boot Device
===============
.. rest_method:: PUT /v1/nodes/{node_ident}/management/boot_device
Set the boot device for the given Node, and set it persistently or for one-time
boot. The exact behaviour of this depends on the hardware driver.
.. note:: In some drivers, eg. the ``*_ipmitool`` family, this method initiates a synchronous call
to the hardware management device (BMC). It should be used with caution! This
is `a known bug <https://bugs.launchpad.net/ironic/+bug/1427923>`_.
.. note:: Some drivers do not support one-time boot, and always set the boot device
persistently.
Normal response code: 204
.. TODO: add error codes
Request
-------
.. rest_parameters:: parameters.yaml
- node_ident: node_ident
- boot_device: boot_device
- persistent: persistent
**Example JSON request body to set boot device:**
.. literalinclude:: samples/node-set-boot-device.json
Get Boot Device
===============
.. rest_method:: GET /v1/nodes/{node_ident}/management/boot_device
Get the current boot device for the given Node.
.. note:: In some drivers, eg. the ``*_ipmitool`` family, this method initiates a synchronous call
to the hardware management device (BMC). It should be used with caution! This
is `a known bug <https://bugs.launchpad.net/ironic/+bug/1427923>`_.
Normal response code: 200
.. TODO: add error codes
Request
-------
.. rest_parameters:: parameters.yaml
- node_ident: node_ident
Response
--------
.. rest_parameters:: parameters.yaml
- boot_device: boot_device
- persistent: persistent
**Example JSON response to get boot device:**
.. literalinclude:: samples/node-get-boot-device-response.json
Get Supported Boot Devices
===========================
.. rest_method:: GET /v1/nodes/{node_ident}/management/boot_device/supported
Retrieve the acceptable set of supported boot devices for a specific Node.
Normal response code: 200
.. TODO: add error codes
Request
-------
.. rest_parameters:: parameters.yaml
- node_ident: node_ident
Response
--------
.. rest_parameters:: parameters.yaml
- supported_boot_devices: supported_boot_devices
**Example response listing supported boot devices:**
.. literalinclude:: samples/node-get-supported-boot-devices-response.json
Node State Summary
==================
.. rest_method:: GET /v1/nodes/{node_ident}/states
Get a summary of the Node's current power, provision, raid, and console status.
Normal response code: 200
Request
-------
.. rest_parameters:: parameters.yaml
- node_ident: node_ident
Response
--------
.. rest_parameters:: parameters.yaml
- power_state: power_state
- target_power_state: target_power_state
- provision_state: provision_state
- target_provision_state: target_provision_state
- provision_updated_at: provision_updated_at
- last_error: last_error
- console_enabled: console_enabled
- raid_config: raid_config
- target_raid_config: target_raid_config
**Example node state:**
.. literalinclude:: samples/node-get-state-response.json
Change Node Power State
=======================
.. rest_method:: PUT /v1/nodes/{node_ident}/states/power
Request a change to the Node's power state.
Normal response code: 202
Error codes:
- 409 (NodeLocked, ClientError)
- 400 (InvalidState)
- 406 (NotAcceptable)
- 503 (NoFreeConductorWorkers)
Request
-------
.. rest_parameters:: parameters.yaml
- node_ident: node_ident
- target: power_state
**Example request to power off a Node:**
.. literalinclude:: samples/node-set-power-off.json
Change Node Provision State
===========================
.. rest_method:: PUT /v1/nodes/{node_ident}/states/provision
Request a change to the Node's provision state.
Acceptable target states depend on the Node's current provision state. More
detailed documentation of the Ironic State Machine is available
`in the developer docs <http://docs.openstack.org/developer/ironic/dev/states.html>`_.
Normal response code: 202
Error codes:
- 409 (NodeLocked, ClientError)
- 400 (InvalidState, NodeInMaintenance)
- 406 (NotAcceptable)
- 503 (NoFreeConductorWorkers)
Request
-------
.. rest_parameters:: parameters.yaml
- node_ident: node_ident
- target: requested_provision_state
- configdrive: configdrive
- clean_steps: clean_steps
**Example request to deploy a Node, using a configdrive served via local webserver:**
.. literalinclude:: samples/node-set-active-state.json
**Example request to clean a Node, with custom clean step:**
.. literalinclude:: samples/node-set-clean-state.json
Set RAID Config
===============
.. rest_method:: PUT /v1/nodes/{node_ident}/states/raid
Store the supplied configuration on the Node's ``target_raid_config`` property.
This property must be structured JSON, and will be validated by the driver upon receipt. The request
schema is defined in the `documentation for the RAID feature <http://docs.openstack.org/developer/ironic/deploy/raid.html>`_
.. note:: Calling this API only stores the requested configuration; it will be applied the next time
that the Node transitions through the ``cleaning`` phase.
Added in API microversion: 1.12
Normal response code: 204
.. TODO: add more description, response code, sample response
Request
-------
.. rest_parameters:: parameters.yaml
- node_ident: node_ident
- target_raid_config: target_raid_config
**Example requested RAID config:**
.. literalinclude:: samples/node-set-raid-request.json
.. TODO: add more description, response code, sample response
Get Console
===========
.. rest_method:: GET /v1/nodes/{node_ident}/states/console
Get connection information about the console.
.. TODO: add more description, response code, sample response
Request
-------
.. rest_parameters:: parameters.yaml
- node_ident: node_ident
.. TODO: add more description, response code, sample response
Start/Stop Console
===================
.. rest_method:: PUT /v1/nodes/{node_ident}/states/console
Start or stop the serial console.
.. TODO: add more description, response code, sample response
Request
-------
.. rest_parameters:: parameters.yaml
- node_ident: node_ident
- enabled: console_enabled
View Git Blame Copy Permalink