6e82b2118a
This updates the API root documentation, which was non-existent, and the Node documentation significantly, replacing many of the samples and adding more verbiage to each property. It's not perfect, but this is vastly more correct than the current docs. Change-Id: Iaeb1c80ac0655fc0d73fa495ed43e3c02b345495
394 lines
9.9 KiB
ReStructuredText
394 lines
9.9 KiB
ReStructuredText
.. -*- 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-get-or-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-or-set-boot-device.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
|