openstack/ironic
Code Issues Proposed changes

Update the api-ref documentation for Root and Nodes

Browse Source 
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
This commit is contained in:
Devananda van der Veen 2016-05-04 17:32:52 -07:00
parent a496a6bae0
commit 6e82b2118a
30 changed files with 1832 additions and 446 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -4,7 +4,13 @@
Chassis (chassis) Chassis (chassis)
================= =================
Chassis operations. The Chassis resource type was originally conceived as a means to group Node
resources. Support for this continues to exist in the REST API, however, it is
very minimal. The Chassis object does not provide any functionality today
aside from a means to list a group of Nodes.
Use of this resource is discouraged, and may be deprecated and removed in a
future release.
List chassis with details List chassis with details
@ -14,11 +20,9 @@ List chassis with details
Lists all chassis with details. Lists all chassis with details.
Normal response codes: 200 Normal response codes: 200
Error response codes:413,405,404,403,401,400,503, Error response codes:413,405,404,403,401,400,503,
Request Request
------- -------
@ -29,7 +33,6 @@ Request
- sort_dir: sort_dir - sort_dir: sort_dir
- sort_key: sort_key - sort_key: sort_key
Response Parameters Response Parameters
------------------- -------------------
@ -40,8 +43,6 @@ Response Parameters
- description: description - description: description
- extra: extra - extra: extra
Response Example Response Example
---------------- ----------------
@ -49,15 +50,6 @@ Response Example
:language: javascript :language: javascript
Show chassis details Show chassis details
==================== ====================
@ -65,11 +57,9 @@ Show chassis details
Shows details for a chassis. Shows details for a chassis.
Normal response codes: 200 Normal response codes: 200
Error response codes:413,405,404,403,401,400,503, Error response codes:413,405,404,403,401,400,503,
Request Request
------- -------
@ -77,7 +67,6 @@ Request
- fields: fields - fields: fields
Response Parameters Response Parameters
------------------- -------------------
@ -88,24 +77,12 @@ Response Parameters
- description: description - description: description
- extra: extra - extra: extra
Response Example Response Example
---------------- ----------------
.. literalinclude:: samples/chassis-show-response.json .. literalinclude:: samples/chassis-show-response.json
:language: javascript :language: javascript
Update chassis Update chassis
============== ==============
@ -113,11 +90,9 @@ Update chassis
Updates a chassis. Updates a chassis.
Normal response codes: 200 Normal response codes: 200
Error response codes:413,415,405,404,403,401,400,503,409, Error response codes:413,415,405,404,403,401,400,503,409,
Request Request
------- -------
@ -133,8 +108,6 @@ Request Example
.. literalinclude:: samples/chassis-update-request.json .. literalinclude:: samples/chassis-update-request.json
:language: javascript :language: javascript
Response Parameters Response Parameters
------------------- -------------------
@ -149,8 +122,6 @@ Response Parameters
- nodes: nodes - nodes: nodes
- uuid: uuid - uuid: uuid
Response Example Response Example
---------------- ----------------
@ -158,17 +129,6 @@ Response Example
:language: javascript :language: javascript
Delete chassis Delete chassis
============== ==============
@ -178,25 +138,9 @@ Deletes a chassis.
Error response codes:204,413,415,405,404,403,401,400,503,409, Error response codes:204,413,415,405,404,403,401,400,503,409,
Request Request
------- -------
Create chassis Create chassis
============== ==============
@ -206,7 +150,6 @@ Creates a chassis.
Error response codes:201,413,415,405,404,403,401,400,503,409, Error response codes:201,413,415,405,404,403,401,400,503,409,
Request Request
------- -------
@ -222,8 +165,6 @@ Request Example
.. literalinclude:: samples/chassis-create-request.json .. literalinclude:: samples/chassis-create-request.json
:language: javascript :language: javascript
Response Parameters Response Parameters
------------------- -------------------
@ -237,19 +178,6 @@ Response Parameters
- nodes: nodes - nodes: nodes
- uuid: uuid - uuid: uuid
List chassis List chassis
============ ============
@ -257,11 +185,9 @@ List chassis
Lists all chassis. Lists all chassis.
Normal response codes: 200 Normal response codes: 200
Error response codes:413,405,404,403,401,400,503, Error response codes:413,405,404,403,401,400,503,
Request Request
------- -------
@ -273,7 +199,6 @@ Request
- sort_key: sort_key - sort_key: sort_key
- fields: fields - fields: fields
Response Parameters Response Parameters
------------------- -------------------
@ -284,20 +209,8 @@ Response Parameters
- description: description - description: description
- extra: extra - extra: extra
Response Example Response Example
---------------- ----------------
.. literalinclude:: samples/chassis-list-response.json .. literalinclude:: samples/chassis-list-response.json
:language: javascript :language: javascript

393
api-ref/source/baremetal-api-v1-node-management.inc Normal file
View File

@ -0,0 +1,393 @@
.. -*- 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

84
api-ref/source/baremetal-api-v1-node-passthru.inc Normal file
View File

@ -0,0 +1,84 @@
.. -*- rst -*-
============================
Node Vendor Passthru (nodes)
============================
Each driver MAY support vendor-specific extensions, called "passthru" methods.
Internally, Ironic's driver API supports flexibly exposing functions via the
common HTTP methods GET, PUT, POST, and DELETE. To call a passthru method,
the query string must contain the name of the method, eg.
``/vendor_passthru?method=reset_bmc``. The contents of the HTTP request are
forwarded to the Node's driver and validated there.
Ironic's REST API provides a means to discover these methods, but does not provide
support, testing, or documentation for these endpoints. The Ironic development
team does not guarantee any compatibility within these methods between releases,
though we encourage driver authors to provide documentation and support for them.
Besides the endpoints documented here, all other resources and endpoints
under the heading ``vendor_passthru`` should be considered
unsupported APIs, and could be changed without warning by the driver authors.
List Methods
============
.. rest_method:: GET /v1/nodes/{node_ident}/vendor_passthru/methods
Retrieve a list of the available vendor passthru methods for the given Node. The
response will indicate which HTTP method(s) each vendor passthru method allows,
whether the method call will be synchronous or asynchronous, and whether the
response will include any attachment.
Normal response code: 200
.. TODO: add error codes
Request
-------
.. rest_parameters:: parameters.yaml
- node_ident: node_ident
Response
--------
**Example passthru methods listing:**
.. literalinclude:: samples/node-vendor-passthru-response.json
Call a Method
=============
.. rest_method:: METHOD /v1/nodes/{node_ident}/vendor_passthru?method={method_name}
The HTTP METHOD may be one of GET, POST, PUT, DELETE, depending on the driver
and method.
This endpoint passes the request directly to the Node's hardware driver. The
HTTP BODY must be parseable JSON, which will be converted to parameters passed
to that function. Unparseable JSON, missing parameters, or excess parameters
will cause the request to be rejected with an HTTP 400 error.
Normal response code: 200 202
.. TODO: add error codes
Request
-------
.. rest_parameters:: parameters.yaml
- node_ident: node_ident
- method_name: method_name
All other parameters should be passed in the BODY. Parameter list varies by method_name.
Response
--------
Varies.

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

@ -4,213 +4,373 @@
Nodes (nodes) 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.
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``.
Show node details
=================
.. rest_method:: GET /v1/nodes/{node_id} Create Node
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
Update node
===========
.. rest_method:: PATCH /v1/nodes/{node_id}
Updates a node.
Normal response codes: 200
Error response codes:413,415,405,404,403,401,400,503,409,
Request
-------
.. rest_parameters:: parameters.yaml
- node_id: node_id
Response Example
----------------
.. literalinclude:: samples/node-show-response.json
:language: javascript
Delete node
===========
.. rest_method:: DELETE /v1/nodes/{node_id}
Deletes a node.
Error response codes:204,413,415,405,404,403,401,400,503,409,
Request
-------
.. rest_parameters:: parameters.yaml
- node_id: node_id
List nodes with details
=======================
.. rest_method:: GET /v1/nodes/detail
Lists all nodes with details.
Normal response codes: 200
Error response codes:413,405,404,403,401,400,503,
Request
-------
Response Example
----------------
.. literalinclude:: samples/nodes-list-details-response.json
:language: javascript
Create node
=========== ===========
.. rest_method:: POST /v1/nodes .. rest_method:: POST /v1/nodes
Creates a node. Creates a new Node resource.
Error response codes:201,413,415,405,404,403,401,400,503,409, 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.
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.
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: 201
.. TODO: add error codes
Request Request
------- -------
.. rest_parameters:: parameters.yaml
- driver: r_driver_name
**Example Node creation request:**
.. 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
List nodes
========== ==========
.. rest_method:: GET /v1/nodes .. rest_method:: GET /v1/nodes
Lists all 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.
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.
API microversion 1.9 added the ``provision_state`` Request parameter, allowing
the list of returned Nodes to be filtered by their current state.
API microversion 1.16 added the ``driver`` Request parameter, allowing
the list of returned Nodes to be filtered by their driver name.
Normal response codes: 200 Normal response codes: 200
Error response codes:413,405,404,403,401,400,503,
.. TODO: add error codes
Request Request
------- -------
.. rest_parameters:: parameters.yaml
- 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
Response Example - 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 .. literalinclude:: samples/nodes-list-response.json
:language: javascript :language: javascript
List Nodes Detailed
===================
.. rest_method:: GET /v1/nodes/detail
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
.. 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
- 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
.. 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.
Note that this endpoint can not be used to request state changes, which are
managed through sub-resources.
Normal response codes: 200
.. 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:**
.. literalinclude:: samples/node-update-driver-info-request.json
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

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

@ -24,7 +24,7 @@ Request
.. rest_parameters:: parameters.yaml .. rest_parameters:: parameters.yaml
- port_id: port_id - port_id: uuid
- fields: fields - fields: fields
@ -61,7 +61,7 @@ Request
.. rest_parameters:: parameters.yaml .. rest_parameters:: parameters.yaml
- port_id: port_id - port_id: uuid
@ -97,7 +97,7 @@ Request
.. rest_parameters:: parameters.yaml .. rest_parameters:: parameters.yaml
- port_id: port_id - port_id: uuid

78
api-ref/source/baremetal-api-versions.inc Normal file
View File

@ -0,0 +1,78 @@
.. -*- rst -*-
============
API versions
============
Concepts
========
In order to bring new features to users over time, the Ironic API
supports versioning. There are two kinds of versions in Ironic.
- ''major versions'', which have dedicated urls.
- ''microversions'', which can be requested through the use of the
``X-OpenStack-Ironic-API-Version`` header.
Beginning with the Kilo release, all API requests support the
``X-OpenStack-Ironic-API-Version`` header. This header SHOULD be supplied
with every request; in the absence of this header, each request is treated
as though coming from an older pre-Kilo client. This was done to preserve
backwards compatibility as we introduced new features in the server.
List API versions
=================
.. rest_method:: GET /
This fetches all the information about all known major API versions in the
deployment. Links to more specific information will be provided for each major
API version, as well as information about supported min and max microversions.
Normal response codes: 200
Request
-------
Response Example
----------------
.. rest_parameters:: parameters.yaml
- description: description
- versions: versions
- version: version
- id: id
- links: links
- min_version: x-openstack-ironic-api-min-version
.. literalinclude:: samples/api-root-response.json
:language: javascript
Show v1 API
===========
.. rest_method:: GET /v1/
Show all the resources within the Ironic v1 API.
Normal response codes: 200
Request
-------
Response Example
----------------
.. rest_parameters:: parameters.yaml
- id: id
- links: links
- openstack-request-id: openstack-request-id
- x-openstack-ironic-api-version: header_version
- x-openstack-ironic-api-min-version: x-openstack-ironic-api-min-version
- x-openstack-ironic-api-max-version: x-openstack-ironic-api-max-version
.. literalinclude:: samples/api-v1-root-response.json
:language: javascript

15
api-ref/source/index.rst
View File

@ -4,10 +4,21 @@
Bare Metal API Bare Metal API
================ ================
This documentation describes the REST API for the Ironic service, beginning with the
5.1.0 (Mitaka) release.
Version negotiation is implemented in the server. When the negotiated version
is not the current maximum version, both request and response may not match what
is presented in this document. Significant changes may be noted inline.
.. rest_expand_all:: .. rest_expand_all::
.. include:: baremetal-api-v1-chassis.inc .. include:: baremetal-api-versions.inc
.. include:: baremetal-api-v1-drivers.inc
.. include:: baremetal-api-v1-nodes.inc .. include:: baremetal-api-v1-nodes.inc
.. include:: baremetal-api-v1-node-management.inc
.. include:: baremetal-api-v1-node-passthru.inc
.. include:: baremetal-api-v1-ports.inc .. include:: baremetal-api-v1-ports.inc
.. include:: baremetal-api-v1-drivers.inc
.. include:: baremetal-api-v1-chassis.inc

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

@ -1,17 +1,54 @@
# variables in header # variables in header
x-openstack-request-id: header_version:
description: |
Specific API microversion used to generate this response.
in: header
required: true
type: string
openstack-request-id:
description: > description: >
foo A unique ID for tracking the request. The request ID associated with the request
appears in the log lines for that request. By default, the middleware configuration
ensures that the request ID appears in the log files.
in: header in: header
required: false required: false
type: string type: string
x-openstack-ironic-api-max-version:
description: |
Maximum API microversion supported by this endpoint, eg. "1.16"
in: header
required: true
type: string
x-openstack-ironic-api-min-version:
description: |
Minimum API microversion supported by this endpoint, eg. "1.1"
in: header
required: true
type: string
x-openstack-ironic-api-version:
description: >
A request SHOULD include this header to indicate to the Ironic API service what
version the client supports. The server will transform the response object into
compliance with the requested version, if it is supported, or return a
406 Not Supported error.
If this header is not supplied, the server will default to ``min_version``
in all responses.
in: header
required: true
type: string
# variables in path # variables in path
driver_name: chassis_ident:
description: |
The UUID of the chassis.
in: path
required: true
type: string
driver_ident:
description: | description: |
The name of the driver. The name of the driver.
in: path in: path
required: false required: true
type: string type: string
node_id: node_id:
description: | description: |
@ -19,24 +56,31 @@ node_id:
in: path in: path
required: false required: false
type: string type: string
port_id: node_ident:
description: |
The UUID or Name of the node.
in: path
required: true
type: string
port_ident:
description: | description: |
The UUID of the port. The UUID of the port.
in: path in: path
required: false required: true
type: string type: string
# variables in query
# variables common to all query strings
fields: fields:
description: | description: |
One or more chassis fields to be returned in the response. One or more fields to be returned in the response.
For example, the following request returns only the ``description`` For example, the following request returns only the ``uuid``
field for each chassis: and ``name`` fields for each node:
:: ::
GET /v1/chassis?fields=description GET /v1/nodes?fields=uuid,name
in: query in: query
required: false required: false
type: array type: array
@ -59,6 +103,51 @@ marker:
in: query in: query
required: false required: false
type: string type: string
# variables in the vendor_passthru query string
method_name:
description: |
Driver specific method name.
in: query
required: true
type: string
# variables in the node query string
r_associated:
description: |
Filter the list of returned nodes and only return which are, or are not,
associated with an ``instance_uuid``.
in: query
required: false
type: boolean
r_driver:
description: |
Filter the list of returned nodes, and only return those with the specified
``driver``.
in: query
required: false
type: string
r_instance_uuid:
description: |
Filter the list of returned nodes, and only return the node with this
specific instance UUID, or an empty set if not found.
in: query
required: false
type: string
r_maintenance:
description: |
Filter the list of returned nodes and only return those with
``maintenance`` set to ``True`` or ``False``.
in: query
required: false
type: boolean
r_provision_state:
description: |
Filter the list of returned nodes, and only return those with the specified
``provision_state``.
in: query
required: false
type: string
sort_dir: sort_dir:
description: | description: |
Sorts the response by the requested sort Sorts the response by the requested sort
@ -82,19 +171,55 @@ sort_key:
required: false required: false
type: string type: string
# variables in body
# variables in API response body
boot_device:
description: |
The boot device for a Node, eg. "pxe" or "disk".
in: body
required: true
type: string
chassis: chassis:
description: | description: |
A ``chassis`` object. A ``chassis`` object.
in: body in: body
required: true required: true
type: array type: array
chassis_1: chassis_uuid:
description: | description: |
A list of chassis objects. UUID of the chassis associated with this Node. May be empty or None.
in: body in: body
required: true required: true
type: string
clean_step:
description: |
The current clean step. Introduced with the cleaning feature.
in: body
required: false
type: string
clean_steps:
description: |
An ordered list of cleaning steps that will be performed on the node. A
cleaning step is a dictionary with required keys ‘interface’ and ‘step’, and
optional key ‘args’. If specified, the value for ‘args’ is a keyword variable
argument dictionary that is passed to the cleaning step method.
in: body
required: false
type: array type: array
configdrive:
description: |
A gzip'ed and base-64 encoded config drive, to be written to a partition
on the Node's boot disk. This parameter is only accepted when setting the
state to "active".
in: body
required: false
type: string or gzip+b64 blob
console_enabled:
description: |
Indicates whether console access is enabled or disabled on this node.
in: body
required: true
type: boolean
created_at: created_at:
description: | description: |
The date and time when the resource was created. The date and time when the resource was created.
@ -115,13 +240,26 @@ created_at:
type: string type: string
description: description:
description: | description: |
A description for the chassis. Descriptive text about the Ironic service.
in: body
required: true
type: string
driver_info:
description: |
All the metadata required by the driver to manage this Node. List of fields
varies between drivers, and can be retrieved from the ``/v1/drivers/<DRIVER_NAME>/properties`` resource.
in: body
required: true
type: JSON
driver_internal_info:
description: |
Internal metadata set and stored by the Node's driver. This field is read-only.
in: body in: body
required: false required: false
type: string type: JSON
description_1: driver_name:
description: | description: |
A description for the chassis. The name of the driver.
in: body in: body
required: true required: true
type: string type: string
@ -134,43 +272,120 @@ drivers:
extra: extra:
description: | description: |
A set of one or more arbitrary metadata key and A set of one or more arbitrary metadata key and
value pairs for the chassis. value pairs.
in: body in: body
required: false required: false
type: object type: object
extra_1:
description: |
A set of zero or more arbitrary metadata key and
value pairs for the chassis.
in: body
required: true
type: object
hosts: hosts:
description: | description: |
A list of active hosts that support this driver. A list of active hosts that support this driver.
in: body in: body
required: true required: true
type: array type: array
links: id:
description: | description: |
A list that contains a self link and associated Major API version, eg, "v1"
chassis links.
in: body in: body
required: true required: true
type: array type: string
links_1: inspection_finished_at:
description: |
The date and time when the inspection process started.
May be "null"
in: body
required: true
type: string
inspection_started_at:
description: |
The date and time when the inspection process started.
May be "null"
in: body
required: true
type: string
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: true
type: JSON
instance_uuid:
description: |
UUID of the Nova instance associated with this Node.
in: body
required: true
type: string
last_error:
description: |
Any error from the most recent (last) transaction that started but failed to finish.
in: body
required: true
type: string
links:
description: | description: |
A list of relative links. Includes the self and A list of relative links. Includes the self and
bookmark links. bookmark links.
in: body in: body
required: true required: true
type: array type: array
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: true
type: boolean
maintenance_reason:
description: |
User-settable description of the reason why this Node was placed into
maintenance mode
in: body
required: false
type: string
n_ports:
description: |
Links to the collection of ports on this node
in: body
required: true
type: array
n_properties:
description: |
Physical characteristics of this Node. Populated by ironic-inspector during
inspection. May be edited via the REST API at any time.
in: body
required: true
type: JSON
n_states:
description: |
Links to the collection of states. Note that this resource is also used to
request state transitions.
in: body
required: true
type: array
name: name:
description: | description: |
The name of the driver. The name of the driver.
in: body in: body
required: true required: true
type: string type: string
node_name:
description: |
Human-readable identifier for the Node resource. May be undefined. Certain
words are reserved. Added in API microversion 1.5
in: body
required: false
type: string
node_uuid:
description: |
UUID of the Node resource.
in: body
required: true
type: string
nodes: nodes:
description: | description: |
Links to the collection of nodes contained in Links to the collection of nodes contained in
@ -178,12 +393,103 @@ nodes:
in: body in: body
required: true required: true
type: array type: array
persistent:
description: |
Whether the boot device should be set only for the next reboot, or
persistently.
in: body
required: true
type: boolean
power_state:
description: |
The current power state of this Node. Usually, "power on" or "power off", but may be "None"
if Ironic is unable to determine the power state (eg, due to hardware failure).
in: body
required: true
type: string
properties: properties:
description: | description: |
A list of links to driver properties. A list of links to driver properties.
in: body in: body
required: true required: true
type: array type: array
provision_state:
description: |
The current provisioning state of this Node.
in: body
required: true
type: string
provision_updated_at:
description: |
The date and time when the provision_state last changed.
``null`` if the node is not being provisioned.
in: body
required: true
type: string
r_driver_name:
description: |
The name of the driver used to manage this Node.
in: body
required: true
type: string
raid_config:
description: |
Represents the current RAID configuration of the node. Introduced with
the cleaning feature.
in: body
required: false
type: JSON
reason:
description: |
Specify the reason for setting the Node into maintenance mode.
in: body
required: false
type: string
requested_provision_state:
description: |
One of the provisioning verbs: manage, provide, inspect, clean, active,
rebuild, delete (deleted), abort.
in: body
required: true
type: string
reservation:
description: |
The ``name`` of an Ironic Conductor host which is holding a lock on this node,
if a lock is held. Usually "null", but this field can be useful for debugging.
in: body
required: true
type: string
supported_boot_devices:
description: |
List of boot devices which this Node's driver supports.
in: body
required: true
type: array
target_power_state:
description: |
If a power state transition has been requested, this field represents the
requested (ie, "target") state.
in: body
required: true
type: string
target_provision_state:
description: |
If a provisioning action has been requested, this field represents the
requested (ie, "target") state. Note that a Node may go through several
states during its transition to this target state. For instance, when requesting
an instance be deployed to an AVAILABLE Node, the Node may go through the following
state change progression: AVAILABLE -> DEPLOYING -> DEPLOYWAIT -> DEPLOYING -> ACTIVE
in: body
required: true
type: string
target_raid_config:
description: |
Represents the requested RAID configuration of the node, which will be
applied when the Node next transitions through the CLEANING state. Introduced
with the cleaning feature.
in: body
required: true
type: JSON
updated_at: updated_at:
description: | description: |
The date and time when the resource was updated. The date and time when the resource was updated.
@ -207,8 +513,64 @@ updated_at:
type: string type: string
uuid: uuid:
description: | description: |
The UUID for the chassis. The UUID for the resource.
in: body in: body
required: true required: true
type: string type: string
# variables returned from node-validate
v_boot:
description: |
Status of the "boot" interface
in: body
required: true
type: object
v_console:
description: |
Status of the "console" interface
in: body
required: true
type: object
v_deploy:
description: |
Status of the "deploy" interface
in: body
required: true
type: object
v_inspect:
description: |
Status of the "inspect" interface
in: body
required: true
type: object
v_management:
description: |
Status of the "management" interface
in: body
required: true
type: object
v_power:
description: |
Status of the "power" interface
in: body
required: true
type: object
v_raid:
description: |
Status of the "raid" interface
in: body
required: true
type: object
version:
description: |
Versioning of this API response, eg. "1.16".
in: body
required: true
type: string
versions:
description: |
Array of information about currently supported versions.
in: body
required: true
type: array

30
api-ref/source/samples/api-root-response.json Normal file
View File

@ -0,0 +1,30 @@
{
"name" : "OpenStack Ironic API",
"description" : "Ironic is an OpenStack project which aims to provision baremetal machines.",
"default_version" : {
"status" : "CURRENT",
"version" : "1.16",
"links" : [
{
"rel" : "self",
"href" : "http://127.0.0.1:6385/v1/"
}
],
"id" : "v1",
"min_version" : "1.1"
},
"versions" : [
{
"status" : "CURRENT",
"links" : [
{
"href" : "http://127.0.0.1:6385/v1/",
"rel" : "self"
}
],
"id" : "v1",
"version" : "1.16",
"min_version" : "1.1"
}
]
}

60
api-ref/source/samples/api-v1-root-response.json Normal file
View File

@ -0,0 +1,60 @@
{
"chassis" : [
{
"rel" : "self",
"href" : "http://127.0.0.1:6385/v1/chassis/"
},
{
"href" : "http://127.0.0.1:6385/chassis/",
"rel" : "bookmark"
}
],
"links" : [
{
"href" : "http://127.0.0.1:6385/v1/",
"rel" : "self"
},
{
"rel" : "describedby",
"type" : "text/html",
"href" : "http://docs.openstack.org/developer/ironic/dev/api-spec-v1.html"
}
],
"nodes" : [
{
"rel" : "self",
"href" : "http://127.0.0.1:6385/v1/nodes/"
},
{
"rel" : "bookmark",
"href" : "http://127.0.0.1:6385/nodes/"
}
],
"ports" : [
{
"href" : "http://127.0.0.1:6385/v1/ports/",
"rel" : "self"
},
{
"rel" : "bookmark",
"href" : "http://127.0.0.1:6385/ports/"
}
],
"media_types" : [
{
"type" : "application/vnd.openstack.ironic.v1+json",
"base" : "application/json"
}
],
"drivers" : [
{
"rel" : "self",
"href" : "http://127.0.0.1:6385/v1/drivers/"
},
{
"href" : "http://127.0.0.1:6385/drivers/",
"rel" : "bookmark"
}
],
"id" : "v1"
}

30
api-ref/source/samples/driver-get-response.json
View File

@ -1,6 +1,30 @@
{ {
"hosts": [ "drivers": [
"fake-host" {
"properties": [
{
"href": "http://127.0.0.1:6385/v1/drivers/agent_ipmitool/properties",
"rel": "self"
},
{
"href": "http://127.0.0.1:6385/drivers/agent_ipmitool/properties",
"rel": "bookmark"
}
], ],
"name": "sample-driver" "hosts": [
"localhost"
],
"name": "agent_ipmitool",
"links": [
{
"rel": "self",
"href": "http://127.0.0.1:6385/v1/drivers/agent_ipmitool"
},
{
"rel": "bookmark",
"href": "http://127.0.0.1:6385/drivers/agent_ipmitool"
}
]
}
]
} }

4
api-ref/source/samples/node-create-request.json Normal file
View File

@ -0,0 +1,4 @@
{
"driver": "agent_ipmitool",
"name": "test_node"
}

58
api-ref/source/samples/node-create-response.json Normal file
View File

@ -0,0 +1,58 @@
{
"last_error" : null,
"extra" : {},
"reservation" : null,
"driver" : "agent_ipmitool",
"instance_info" : {},
"created_at" : "2016-05-04T22:59:49.300836+00:00",
"raid_config" : {},
"uuid" : "14deb747-127c-4fe4-be9d-906c43006cd4",
"maintenance_reason" : null,
"target_provision_state" : null,
"ports" : [
{
"rel" : "self",
"href" : "http://127.0.0.1:6385/v1/nodes/14deb747-127c-4fe4-be9d-906c43006cd4/ports"
},
{
"rel" : "bookmark",
"href" : "http://127.0.0.1:6385/nodes/14deb747-127c-4fe4-be9d-906c43006cd4/ports"
}
],
"power_state" : null,
"instance_uuid" : null,
"name" : "test_node_",
"properties" : {},
"clean_step" : {},
"console_enabled" : false,
"driver_internal_info" : {},
"target_power_state" : null,
"inspection_started_at" : null,
"provision_state" : "enroll",
"provision_updated_at" : null,
"driver_info" : {},
"inspection_finished_at" : null,
"updated_at" : null,
"links" : [
{
"rel" : "self",
"href" : "http://127.0.0.1:6385/v1/nodes/14deb747-127c-4fe4-be9d-906c43006cd4"
},
{
"href" : "http://127.0.0.1:6385/nodes/14deb747-127c-4fe4-be9d-906c43006cd4",
"rel" : "bookmark"
}
],
"target_raid_config" : {},
"maintenance" : false,
"states" : [
{
"href" : "http://127.0.0.1:6385/v1/nodes/14deb747-127c-4fe4-be9d-906c43006cd4/states",
"rel" : "self"
},
{
"href" : "http://127.0.0.1:6385/nodes/14deb747-127c-4fe4-be9d-906c43006cd4/states",
"rel" : "bookmark"
}
]
}

4
api-ref/source/samples/node-get-or-set-boot-device.json Normal file
View File

@ -0,0 +1,4 @@
{
"boot_device": "pxe",
"persistent": false
}

11
api-ref/source/samples/node-get-state-response.json Normal file
View File

@ -0,0 +1,11 @@
{
"last_error" : "",
"target_raid_config" : {},
"target_power_state" : null,
"console_enabled" : false,
"target_provision_state" : null,
"provision_updated_at" : null,
"power_state" : "power off",
"raid_config" : {},
"provision_state" : "available"
}

9
api-ref/source/samples/node-get-supported-boot-devices-response.json Normal file
View File

@ -0,0 +1,9 @@
{
"supported_boot_devices" : [
"pxe",
"disk",
"cdrom",
"bios",
"safe"
]
}

3
api-ref/source/samples/node-maintenance-request.json Normal file
View File

@ -0,0 +1,3 @@
{
"reason": "Replacing the hard drive"
}

4
api-ref/source/samples/node-set-active-state.json Normal file
View File

@ -0,0 +1,4 @@
{
"target": "active",
"configdrive": "http://127.0.0.1/images/test-node-config-drive.iso.gz"
}

12
api-ref/source/samples/node-set-clean-state.json Normal file
View File

@ -0,0 +1,12 @@
{
"target": "clean",
"clean_steps": [
{
'interface': 'deploy',
'step': 'upgrade_firmware',
'args': {
'force': True
}
}
]
}

3
api-ref/source/samples/node-set-power-off.json Normal file
View File

@ -0,0 +1,3 @@
{
"target": "power off"
}

3
api-ref/source/samples/node-set-power-state.json Normal file
View File

@ -0,0 +1,3 @@
{
"target": "power on"
}

9
api-ref/source/samples/node-set-raid-request.json Normal file
View File

@ -0,0 +1,9 @@
{
"logical_disks" : [
{
"size_gb" : 100,
"is_root_volume" : true,
"raid_level" : "1"
}
]
}

100
api-ref/source/samples/node-show-response.json
View File

@ -1,63 +1,71 @@
{ {
"chassis_uuid": "edcad704-b2da-41d5-96d9-afd580ecfa12", "target_provision_state" : null,
"clean_step": {}, "instance_info" : {},
"console_enabled": false, "updated_at" : "2016-05-05T00:28:40+00:00",
"created_at": "2000-01-01T12:00:00", "maintenance_reason" : null,
"driver": "fake", "inspection_started_at" : null,
"driver_info": {}, "target_power_state" : null,
"driver_internal_info": {}, "ports" : [
"extra": {},
"inspection_finished_at": null,
"inspection_started_at": "2000-01-01T12:00:00",
"instance_info": {},
"instance_uuid": "dcf1fbc5-93fc-4596-9395-b80572f6267b",
"last_error": null,
"links": [
{ {
"href": "http://localhost:6385/v1/nodes/1be26c0b-03f2-4d2e-ae87-c02d7f33c123", "rel" : "self",
"rel": "self" "href" : "http://127.0.0.1:6385/v1/nodes/ecddf26d-8c9c-4ddf-8f45-fd57e09ccddb/ports"
}, },
{ {
"href": "http://localhost:6385/nodes/1be26c0b-03f2-4d2e-ae87-c02d7f33c123", "href" : "http://127.0.0.1:6385/nodes/ecddf26d-8c9c-4ddf-8f45-fd57e09ccddb/ports",
"rel": "bookmark" "rel" : "bookmark"
} }
], ],
"maintenance": false, "maintenance" : false,
"maintenance_reason": null, "driver" : "fake",
"name": "database16-dc02", "provision_state" : "available",
"ports": [ "reservation" : null,
"uuid" : "ecddf26d-8c9c-4ddf-8f45-fd57e09ccddb",
"extra" : {
"foo" : "bar"
},
"driver_internal_info" : {},
"states" : [
{ {
"href": "http://localhost:6385/v1/nodes/1be26c0b-03f2-4d2e-ae87-c02d7f33c123/ports", "href" : "http://127.0.0.1:6385/v1/nodes/ecddf26d-8c9c-4ddf-8f45-fd57e09ccddb/states",
"rel": "self" "rel" : "self"
}, },
{ {
"href": "http://localhost:6385/nodes/1be26c0b-03f2-4d2e-ae87-c02d7f33c123/ports", "rel" : "bookmark",
"rel": "bookmark" "href" : "http://127.0.0.1:6385/nodes/ecddf26d-8c9c-4ddf-8f45-fd57e09ccddb/states"
} }
], ],
"power_state": "power on", "target_raid_config" : {},
"properties": { "console_enabled" : false,
"cpus": "1", "clean_step" : {},
"local_gb": "10", "last_error" : null,
"memory_mb": "1024" "links" : [
},
"provision_state": "active",
"provision_updated_at": "2000-01-01T12:00:00",
"raid_config": null,
"reservation": null,
"states": [
{ {
"href": "http://localhost:6385/v1/nodes/1be26c0b-03f2-4d2e-ae87-c02d7f33c123/states", "rel" : "self",
"rel": "self" "href" : "http://127.0.0.1:6385/v1/nodes/ecddf26d-8c9c-4ddf-8f45-fd57e09ccddb"
}, },
{ {
"href": "http://localhost:6385/nodes/1be26c0b-03f2-4d2e-ae87-c02d7f33c123/states", "rel" : "bookmark",
"rel": "bookmark" "href" : "http://127.0.0.1:6385/nodes/ecddf26d-8c9c-4ddf-8f45-fd57e09ccddb"
} }
], ],
"target_power_state": null, "provision_updated_at" : null,
"target_provision_state": null, "name" : "test_node",
"target_raid_config": null, "properties" : {
"updated_at": "2000-01-01T12:00:00", "local_gb" : 10,
"uuid": "1be26c0b-03f2-4d2e-ae87-c02d7f33c123" "cpu_arch" : "x86_64",
"cpus" : 1,
"memory_mb" : 1024
},
"power_state" : "power off",
"created_at" : "2016-04-20T16:51:03+00:00",
"instance_uuid" : null,
"raid_config" : {},
"driver_info" : {
"ipmi_password" : "***",
"ipmi_username" : "ADMIN",
"ipmi_address" : "1.2.3.4",
"deploy_kernel" : "http://127.0.0.1/images/kernel",
"deploy_ramdisk" : "http://127.0.0.1/images/ramdisk"
},
"inspection_finished_at" : null
} }

12
api-ref/source/samples/node-update-driver-info-request.json Normal file
View File

@ -0,0 +1,12 @@
[
{
"op" : "replace",
"path" : "/driver_info/ipmi_username",
"value" : "OPERATOR"
},
{
"value" : "10.0.0.123",
"op" : "replace",
"path" : "/driver_info/ipmi_address"
}
]

71
api-ref/source/samples/node-update-driver-info-response.json Normal file
View File

@ -0,0 +1,71 @@
{
"properties" : {
"memory_mb" : 1024,
"cpus" : 1,
"local_gb" : 10,
"cpu_arch" : "x86_64"
},
"maintenance_reason" : null,
"instance_info" : {},
"states" : [
{
"rel" : "self",
"href" : "http://127.0.0.1:6385/v1/nodes/ecddf26d-8c9c-4ddf-8f45-fd57e09ccddb/states"
},
{
"href" : "http://127.0.0.1:6385/nodes/ecddf26d-8c9c-4ddf-8f45-fd57e09ccddb/states",
"rel" : "bookmark"
}
],
"driver_internal_info" : {},
"power_state" : "power off",
"console_enabled" : false,
"last_error" : null,
"target_raid_config" : {},
"maintenance" : false,
"provision_state" : "available",
"uuid" : "ecddf26d-8c9c-4ddf-8f45-fd57e09ccddb",
"links" : [
{
"rel" : "self",
"href" : "http://127.0.0.1:6385/v1/nodes/ecddf26d-8c9c-4ddf-8f45-fd57e09ccddb"
},
{
"href" : "http://127.0.0.1:6385/nodes/ecddf26d-8c9c-4ddf-8f45-fd57e09ccddb",
"rel" : "bookmark"
}
],
"clean_step" : {},
"created_at" : "2016-04-20T16:51:03+00:00",
"instance_uuid" : null,
"target_power_state" : null,
"driver_info" : {
"ipmi_address" : "10.0.0.123",
"deploy_ramdisk" : "http://127.0.0.1/images/ramdisk",
"deploy_kernel" : "http://127.0.0.1/images/kernel",
"ipmi_password" : "***",
"ipmi_username" : "OPERATOR"
},
"inspection_started_at" : null,
"raid_config" : {},
"inspection_finished_at" : null,
"reservation" : null,
"target_provision_state" : null,
"extra" : {
"foo" : "bar"
},
"driver" : "fake",
"name" : "test_node",
"updated_at" : "2016-05-05T18:43:41+00:00",
"ports" : [
{
"href" : "http://127.0.0.1:6385/v1/nodes/ecddf26d-8c9c-4ddf-8f45-fd57e09ccddb/ports",
"rel" : "self"
},
{
"rel" : "bookmark",
"href" : "http://127.0.0.1:6385/nodes/ecddf26d-8c9c-4ddf-8f45-fd57e09ccddb/ports"
}
],
"provision_updated_at" : null
}

27
api-ref/source/samples/node-validate-response.json Normal file
View File

@ -0,0 +1,27 @@
{
"management" : {
"result" : true
},
"inspect" : {
"result" : null,
"reason" : "not supported"
},
"power" : {
"result" : true
},
"raid" : {
"result" : true
},
"boot" : {
"result" : false,
"reason" : "Cannot validate image information for node ecddf26d-8c9c-4ddf-8f45-fd57e09ccddb because one or more parameters are missing from its instance_info.. Missing are: ['ramdisk', 'kernel', 'image_source']"
},
"console" : {
"result" : false,
"reason" : "Missing 'ipmi_terminal_port' parameter in node's driver_info."
},
"deploy" : {
"reason" : "Cannot validate image information for node ecddf26d-8c9c-4ddf-8f45-fd57e09ccddb because one or more parameters are missing from its instance_info.. Missing are: ['ramdisk', 'kernel', 'image_source']",
"result" : false
}
}

26
api-ref/source/samples/node-vendor-passthru-response.json Normal file
View File

@ -0,0 +1,26 @@
{
"bmc_reset" : {
"async" : true,
"description" : "",
"http_methods" : [
"POST"
],
"attach" : false
},
"send_raw" : {
"description" : "",
"attach" : false,
"http_methods" : [
"POST"
],
"async" : true
},
"heartbeat" : {
"async" : true,
"attach" : false,
"http_methods" : [
"POST"
],
"description" : ""
}
}

105
api-ref/source/samples/nodes-list-details-response.json
View File

@ -1,64 +1,75 @@
{ {
"nodes": [ "nodes" : [
{ {
"chassis_uuid": "633f9f21-5bd5-4166-b811-1eb01490c4ab", "reservation" : null,
"clean_step": {}, "driver" : "agent_ipmitool",
"console_enabled": false, "uuid" : "ecddf26d-8c9c-4ddf-8f45-fd57e09ccddb",
"created_at": "2016-04-23T10:52:43+00:00", "extra" : {
"driver": "pxe_ssh", "foo" : "bar"
"driver_info": {
"deploy_kernel": "aadebece-ce44-4cf6-a9e8-545f0e8ac9f3",
"deploy_ramdisk": "cfe6f9ce-b2e6-4a7a-9246-0cc7eeb89a71",
"ssh_address": "localhost",
"ssh_key_filename": "/opt/stack/data/ironic/ssh_keys/ironic_key",
"ssh_port": 22,
"ssh_username": "ubuntu",
"ssh_virt_type": "virsh"
}, },
"driver_internal_info": {}, "provision_updated_at" : null,
"extra": {}, "provision_state" : "available",
"inspection_finished_at": null, "clean_step" : {},
"inspection_started_at": null, "maintenance" : false,
"instance_info": {}, "driver_internal_info" : {},
"instance_uuid": null, "console_enabled" : false,
"last_error": null, "raid_config" : {},
"links": [ "target_raid_config" : {},
"inspection_started_at" : null,
"instance_info" : {},
"states" : [
{ {
"href": "http://localhost:6385/v1/nodes/277c9fe9-a385-4e45-9399-660f3287e48c", "rel" : "self",
"rel": "self" "href" : "http://127.0.0.1:6385/v1/nodes/ecddf26d-8c9c-4ddf-8f45-fd57e09ccddb/states"
}, },
{ {
"href": "http://localhost:6385/nodes/277c9fe9-a385-4e45-9399-660f3287e48c", "href" : "http://127.0.0.1:6385/nodes/ecddf26d-8c9c-4ddf-8f45-fd57e09ccddb/states",
"rel": "bookmark" "rel" : "bookmark"
} }
], ],
"maintenance": false, "last_error" : null,
"maintenance_reason": null, "properties" : {
"name": "node-0", "cpus" : 1,
"ports": [ "memory_mb" : 1024,
"local_gb" : 10,
"cpu_arch" : "x86_64"
},
"links" : [
{ {
"href": "http://localhost:6385/v1/nodes/277c9fe9-a385-4e45-9399-660f3287e48c/ports", "rel" : "self",
"rel": "self" "href" : "http://127.0.0.1:6385/v1/nodes/ecddf26d-8c9c-4ddf-8f45-fd57e09ccddb"
}, },
{ {
"href": "http://localhost:6385/nodes/277c9fe9-a385-4e45-9399-660f3287e48c/ports", "rel" : "bookmark",
"rel": "bookmark" "href" : "http://127.0.0.1:6385/nodes/ecddf26d-8c9c-4ddf-8f45-fd57e09ccddb"
} }
], ],
"power_state": "power off", "name" : "test_node",
"properties": { "ports" : [
"cpu_arch": "x86_64", {
"cpus": 1, "rel" : "self",
"local_gb": 10, "href" : "http://127.0.0.1:6385/v1/nodes/ecddf26d-8c9c-4ddf-8f45-fd57e09ccddb/ports"
"memory_mb": 1024
}, },
"provision_state": "available", {
"provision_updated_at": null, "rel" : "bookmark",
"reservation": null, "href" : "http://127.0.0.1:6385/nodes/ecddf26d-8c9c-4ddf-8f45-fd57e09ccddb/ports"
"target_power_state": null, }
"target_provision_state": null, ],
"updated_at": "2016-04-23T10:53:37+00:00", "created_at" : "2016-04-20T16:51:03+00:00",
"uuid": "277c9fe9-a385-4e45-9399-660f3287e48c" "updated_at" : "2016-05-04T23:24:20+00:00",
"maintenance_reason" : null,
"inspection_finished_at" : null,
"driver_info" : {
"deploy_kernel" : "http://127.0.0.1/images/kernel",
"ipmi_address" : "1.2.3.4",
"deploy_ramdisk" : "http://127.0.0.1/images/ramdisk",
"ipmi_password" : "******",
"ipmi_username" : "ADMIN",
},
"instance_uuid" : null,
"power_state" : "power off",
"target_power_state" : null,
"target_provision_state" : null
} }
] ]
} }

24
api-ref/source/samples/nodes-list-response.json
View File

@ -1,22 +1,22 @@
{ {
"nodes": [ "nodes" : [
{ {
"instance_uuid": "dcf1fbc5-93fc-4596-9395-b80572f6267b", "provision_state" : "available",
"links": [ "name" : "test_node",
"maintenance" : false,
"uuid" : "ecddf26d-8c9c-4ddf-8f45-fd57e09ccddb",
"links" : [
{ {
"href": "http://localhost:6385/v1/nodes/1be26c0b-03f2-4d2e-ae87-c02d7f33c123", "href" : "http://127.0.0.1:6385/v1/nodes/ecddf26d-8c9c-4ddf-8f45-fd57e09ccddb",
"rel": "self" "rel" : "self"
}, },
{ {
"href": "http://localhost:6385/nodes/1be26c0b-03f2-4d2e-ae87-c02d7f33c123", "href" : "http://127.0.0.1:6385/nodes/ecddf26d-8c9c-4ddf-8f45-fd57e09ccddb",
"rel": "bookmark" "rel" : "bookmark"
} }
], ],
"maintenance": false, "instance_uuid" : null,
"name": "database16-dc02", "power_state" : "power off"
"power_state": "power on",
"provision_state": "active",
"uuid": "1be26c0b-03f2-4d2e-ae87-c02d7f33c123"
} }
] ]
} }

4
tox.ini
View File

@ -72,10 +72,6 @@ commands =
# NOTE(sdague): this target does not use constraints because # NOTE(sdague): this target does not use constraints because
# upstream infra does not yet support it. Once that's fixed, we can # upstream infra does not yet support it. Once that's fixed, we can
# drop the install_command. # drop the install_command.
#
# we do not used -W here because we are doing some slightly tricky
# things to build a single page document, and as such, we are ok
# ignoring the duplicate stanzas warning.
whitelist_externals = bash whitelist_externals = bash
install_command = pip install -U --force-reinstall {opts} {packages} install_command = pip install -U --force-reinstall {opts} {packages}
commands = commands =