161326fe06
Readthedocs failed to render Drydock exceptions with error: > WARNING: autodoc: failed to import exception xxx from module > 'drydock_provisioner'; the following exception was raised: No module > named 'drydock_provisioner' Trying to add Drydock requirements to the installed requirements list, so that Readthedocs has all modules, including those needed for the Drydock itself. Unify docs building by utilizing Zuul docs-on-readthedocs template job. Cosmetic readability changes: 1. combined all Makefile .PHONY targets into one 2. merged multiple LABEL instructions in Dockerfile into one Change-Id: I6a9b47cffc66d739968fa886c51e25b1e09ef124
123 lines
3.7 KiB
ReStructuredText
123 lines
3.7 KiB
ReStructuredText
.. _api:
|
|
|
|
===========
|
|
Drydock API
|
|
===========
|
|
|
|
The Drydock API is a RESTful interface used for accessing the services provided by Drydock.
|
|
All endpoints are located under ``/api/<version>/``.
|
|
|
|
Secured endpoints require Keystone authentication and proper role assignment for authorization
|
|
|
|
v1.0
|
|
====
|
|
|
|
.. _tasks-api:
|
|
|
|
tasks API
|
|
---------
|
|
|
|
The Tasks API is used for creating and listing asynchronous tasks to be executed by the
|
|
Drydock orchestrator. See :ref:`task` for details on creating tasks and field information.
|
|
|
|
nodes API
|
|
---------
|
|
|
|
GET nodes
|
|
^^^^^^^^^
|
|
|
|
The Nodes API will provide a report of current nodes as known by the node provisioner
|
|
and their status with a few hardware details.
|
|
|
|
GET nodes/hostname/builddata
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
Get all the build data record for node ``hostname``. The response will be a list of
|
|
objects in the below form.::
|
|
|
|
{
|
|
"node_name": "hostname",
|
|
"generator": "description of how data was generated",
|
|
"collected_date": ios8601 UTC datestamp,
|
|
"task_id": "UUID of task initiating collection",
|
|
"data_format": "MIME-type of data_element",
|
|
"data_element": "Collected data"
|
|
}
|
|
|
|
If the query parameter ``latest`` is passed with a value of ``true``, then only
|
|
the most recently collected data for each ``generator`` will be included in the
|
|
response.
|
|
|
|
nodefilter API
|
|
--------------
|
|
|
|
POST nodefilter
|
|
^^^^^^^^^^^^^^^
|
|
|
|
The Nodes API will provide a list of node names based on design_ref. This API
|
|
requires design_ref in the POST body with an optional node_filter to return the node
|
|
names.
|
|
|
|
bootdata API
|
|
------------
|
|
|
|
The boot data API is used by deploying nodes to load the appropriate boot actions to be
|
|
instantiated on the node. It uses alternative authentication and is not accessible with
|
|
Keystone.
|
|
|
|
GET bootdata/hostname/files
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
Returns a gzipped tar file containing all the file-type boot action data assets for
|
|
the node ``hostname`` with appropriate permissions set in the tar-file.
|
|
|
|
GET bootdata/hostname/units
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
Returns a gzipped tar file containing all the unit-type boot action data assets for
|
|
the node ``hostname`` with appropriate permissions set in the tar-file.
|
|
|
|
.. _bootaction-api:
|
|
|
|
bootaction API
|
|
--------------
|
|
|
|
The boot action API is used by deploying nodes to report status and results of running
|
|
boot actions. It expects a JSON-formatted body with the top-level entity of an object.
|
|
The status of the boot action and any detail status messages for it will be added to the
|
|
DeployNode task that prompted the node deployment the boot action is associated with.
|
|
|
|
POST bootaction/bootaction-id
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
Example::
|
|
|
|
{
|
|
"status": "Failure"|"Success",
|
|
"details": [
|
|
{
|
|
"message": "Boot action status message",
|
|
"error": true|false,
|
|
...
|
|
},
|
|
...
|
|
]
|
|
}
|
|
|
|
POSTs to this endpoint can be made repeatedly omitting the ``status`` field and simply
|
|
adding one or more detail status messages. The ``message`` and ``error`` fields are required and
|
|
the ``context``, ``context_type`` and ``ts`` fields are reserved. Otherwise the message
|
|
object in details can be extended with additional fields as needed.
|
|
|
|
Once a POST containing the ``status`` field is made to a bootaction-id, that bootaction-id can no
|
|
longer be updated with status changes nor additional detailed status messages.
|
|
|
|
Each request made must contain the ``X-Bootaction-Key`` header with the correct hex
|
|
key for ``bootaction-id``.
|
|
|
|
validatedesign API
|
|
------------------
|
|
|
|
The Validatedesign API is used for validating documents before they will be used by Drydock. See
|
|
:ref:`validatedesign` for more details on validating documents.
|