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 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
@ -14,11 +20,9 @@ List chassis with details
Lists all chassis with details.
Normal response codes: 200
Error response codes:413,405,404,403,401,400,503,
Request
-------
@ -29,7 +33,6 @@ Request
- sort_dir: sort_dir
- sort_key: sort_key
Response Parameters
-------------------
@ -40,8 +43,6 @@ Response Parameters
- description: description
- extra: extra
Response Example
----------------
@ -49,15 +50,6 @@ Response Example
:language: javascript
Show chassis details
====================
@ -65,11 +57,9 @@ Show chassis details
Shows details for a chassis.
Normal response codes: 200
Error response codes:413,405,404,403,401,400,503,
Request
-------
@ -77,7 +67,6 @@ Request
- fields: fields
Response Parameters
-------------------
@ -88,24 +77,12 @@ Response Parameters
- description: description
- extra: extra
Response Example
----------------
.. literalinclude:: samples/chassis-show-response.json
:language: javascript
Update chassis
==============
@ -113,11 +90,9 @@ Update chassis
Updates a chassis.
Normal response codes: 200
Error response codes:413,415,405,404,403,401,400,503,409,
Request
-------
@ -133,8 +108,6 @@ Request Example
.. literalinclude:: samples/chassis-update-request.json
:language: javascript
Response Parameters
-------------------
@ -149,8 +122,6 @@ Response Parameters
- nodes: nodes
- uuid: uuid
Response Example
----------------
@ -158,17 +129,6 @@ Response Example
:language: javascript
Delete chassis
==============
@ -178,25 +138,9 @@ Deletes a chassis.
Error response codes:204,413,415,405,404,403,401,400,503,409,
Request
-------
Create chassis
==============
@ -206,7 +150,6 @@ Creates a chassis.
Error response codes:201,413,415,405,404,403,401,400,503,409,
Request
-------
@ -222,8 +165,6 @@ Request Example
.. literalinclude:: samples/chassis-create-request.json
:language: javascript
Response Parameters
-------------------
@ -237,19 +178,6 @@ Response Parameters
- nodes: nodes
- uuid: uuid
List chassis
============
@ -257,11 +185,9 @@ List chassis
Lists all chassis.
Normal response codes: 200
Error response codes:413,405,404,403,401,400,503,
Request
-------
@ -273,7 +199,6 @@ Request
- sort_key: sort_key
- fields: fields
Response Parameters
-------------------
@ -284,20 +209,8 @@ Response Parameters
- description: description
- extra: extra
Response Example
----------------
.. literalinclude:: samples/chassis-list-response.json
: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)
=============
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}
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
Create Node
===========
.. 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
-------
.. 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
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
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
- 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
: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
- port_id: port_id
- port_id: uuid
- fields: fields
@ -61,7 +61,7 @@ Request
.. rest_parameters:: parameters.yaml
- port_id: port_id
- port_id: uuid
@ -97,7 +97,7 @@ Request
.. 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
================
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::
.. include:: baremetal-api-v1-chassis.inc
.. include:: baremetal-api-v1-drivers.inc
.. include:: baremetal-api-versions.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-drivers.inc
.. include:: baremetal-api-v1-chassis.inc

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

@ -1,17 +1,54 @@
# 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: >
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
required: false
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
driver_name:
chassis_ident:
description: |
The UUID of the chassis.
in: path
required: true
type: string
driver_ident:
description: |
The name of the driver.
in: path
required: false
required: true
type: string
node_id:
description: |
@ -19,24 +56,31 @@ node_id:
in: path
required: false
type: string
port_id:
node_ident:
description: |
The UUID or Name of the node.
in: path
required: true
type: string
port_ident:
description: |
The UUID of the port.
in: path
required: false
required: true
type: string
# variables in query
# variables common to all query strings
fields:
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``
field for each chassis:
For example, the following request returns only the ``uuid``
and ``name`` fields for each node:
::
GET /v1/chassis?fields=description
GET /v1/nodes?fields=uuid,name
in: query
required: false
type: array
@ -59,6 +103,51 @@ marker:
in: query
required: false
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: