drydock/docs/source/API.rst
Scott Hussey 9a52dca199 Bootaction cleanup
- Clean up the docs and code around bootactions to support the
  baclient work

- Update the Jinja2 environment in the bootaction rendering
- Refactor authentication of bootaction signal API calls

Change-Id: Ic64f0c7ee09a487be750188953013f1ed3cd99cb
2018-09-06 16:33:11 -05:00

3.7 KiB

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

The Tasks API is used for creating and listing asynchronous tasks to be executed by the Drydock orchestrator. See 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

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

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 validatedesign for more details on validating documents.