airship/shipyard
Code Issues Proposed changes
shipyard/docs/API.md
Bryan Strassner 59fabf8cac Updated the API documentation for shipyard: 
Incorporated feedback from reviews

Added steps to the action commands document

Added renderedconfigdocs resource for rendered representations of
documents

Updated POST configdocs to be collection based

Added append and force parameter behaviors for POST configdocs

Updated verbiage for the document staging API to be collection
based

Update GET behaviors for configdocs to clarify when collections
are removed vs. not represented.

Remove the secrets API, as it will be handled by the configdocs

change to have document versions referenced by verion=rollback|staged
instead of lastDeployed=true|false.
Updated to make clearer when documents move from staged to rollback

reformatted for 80 cols

removed extraneous trailing whitespace

Change-Id: I59ceb8643d7da5ef335b746ea98053a8338207be
2017-08-24 09:55:47 -05:00

9.3 KiB
Raw Blame History

Shipyard API

Logically, the API has three parts to handle the three areas of functionality in Shipyard.

  1. Document Staging
  2. Action Handling
  3. Airflow Monitoring

Standards used by the API

See UCP API conventions

Document Staging API

Shipyard will serve as the entrypoint for documents (designs, secrets, configurations, etc...) into a site. Documents are posted to Shipyard in collections, rather than individually. At any point in time, there will be two represented versions of documents in a site that are accessible via this API:

  • The "Committed Documents" version, which represents the last version of documents that were successfully commited with a commit_configdocs action.
  • The "Shipyard Buffer" version, which represents the collection of documents that have been ingested by this API since the last commited version. Note that only one set of documents maybe posted to the buffer at a time by default. (This behavior can be overridden by query parameters issued by the user of Shipyard)

All versions of documents rely upon Deckhand for storage. Shipyard uses the tagging features of Deckhand of to find the appropriate Committed Documents and Shipyard Buffer version.

/v1.0/configdocs/{collection_id}

Represents the site configuration documents

Payload Structure

The documents as noted above (commonly yaml), in a format understood by Deckhand

POST

Ingests a collection of documents. Synchronous. POSTing an empty body indicates that the specified collection should be deleted if the Shipyard Buffer is committed.

Query Parameters
  • bufferMode=append|replace|rejectOnContents
    Indicates how the existing Shipyard Buffer should be handled. By default, Shipyard will reject the POST if contents already exist in the Shipyard Buffer.
    • append: Add the collection to the Shipyard Buffer, only if that collection doesn't already exist in the Shipyard Buffer. If the collection is already present, the request will be rejected and a 409 Conflict will be returned.
    • replace: Clear the Shipyard Buffer before adding the specified collection.
Responses

  • 201 Created
    If the documents are successfully ingested, even with validation failures. Response message includes:

    • a list of validation results
    • The response headers will include a Location indicating the GET endpoint to retrieve the configDocs

  • 409 Conflict

    • If a commit_configdocs action is in progress.
    • If any collections exist in the Shipyard Buffer unless bufferMode=replace or bufferMode=append.
    • If bufferMode=append, and the collection being posted is already in the Shipyard Buffer

GET

Returns the source documents for a collection of documents

Query Parameters
  • version=committed|buffer
    Return the documents for the version specified - buffer by default.
Responses
  • 200 OK
    If documents can be retrieved.
    • If the response is 200 with an empty response body, this indicates that the buffer version is attempting to 'delete' the collection when it is committed. An empty response body will only be possible for version=buffer.
  • 404 Not Found
    If the collection is not represented
    • When version=buffer, this indicates that no representations of this collection have been POSTed since the last committed version.
    • When version=committed, this indicates that either the collection has never existed or has been deleted by a prior commit

/v1.0/renderedconfigdocs

Represents the site configuration documents, as a whole set - does not consider collections in any way.

GET

Returns the full set of configdocs in their rendered form.

Query Parameters
  • version=committed|buffer
    Return the documents for the version specified - buffer by default.
Responses
  • 200 OK
    If documents can be retrieved.

/v1.0/validations

Represents the validation messages for the documents in deckhand

Payload Structure

The list of validations

[
  { TBD }
]

GET

Returns the validations

Query Parameters
  • version=committed|buffer
    returns the validations if any associated with the version specified.
Responses
  • 200 OK
    If the validations can be retrieved.

Action API

The Shipyard Action API is a resource that allows for creation, control and investigation of triggered workflows. These actions encapsulate a command interface for the Undercloud Platform. See Action Commands for supported actions

/v1.0/actions

Payload Structure

A list of actions that have been executed through shipyard's action API.

[
  { Action objects summarized, TBD },
  ...
]

GET

Returns the list of actions in the system that have been posted, and are accessible to the current user.

Responses
  • 200 OK
    If the actions can be retrieved.

POST

Creates an action in the system. This will cause some action to start. The input body to this post will represent an action object that has at least these fields:

  • name
    The name of the action to invoke, as noted in Action Commands
  • parameters
    A dictionary of parameters to use for the trigger invocation. The supported parameters will vary for the action invoked.
{
  "name" : "action name",
  "parameters" : { varies by action }
}

The POST will synchrounously create the action (a shell object that represents a DAG invocation), perform any checks to validate the preconditions to run the DAG, and trigger the invocation of the DAG. The DAG will run asynchronously in airflow.

Responses
  • 201 Created
    If the action is created successfully, and all preconditions to run the DAG are successful. The response body is the action entity created.
  • 400 Bad Request
    If the action name doesn't exist, or the payload is otherwise malformed.
  • 409 Conflict
    For any failed pre-run validations. The response body is the action entity created, with the failed validations. The DAG will not begin execution in this case.

/v1.0/actions/{action_id}

Each action will be assigned an unique id that can be used to get details for the action, including the execution status.

Payload Structure

All actions will include fields that indicate the following data:

  • id (assigned during POST)
  • name - the name of the action - likely to be the DAG Names, but may be mapped for "nicer" values.
  • parameters - a dictionary of the parameters configuring the action.
  • tracking info - (user, time, etc)
  • action_lifecycle value:
    • Pending
    • Validation Failed
    • Processing
    • Complete
    • Failed
  • DAG_status - representing the status that airflow provides for an executing DAG
  • validations - a list of validations that have been done, including any status information for those validations. During the lifecycle of the DAG, this list of validations may continue to grow.
  • steps - the list of steps for this action, including the status for that step.
{ TBD }

GET

Returns the action entity for the specified id.

Responses
  • 200 OK

/v1.0/actions/{action_id}/validationdetails/{validation_id}

Allows for drilldown to validation detailed info.

Payload Structure

The detailed information for a validation

{ TBD }

GET

Returns the validation detail by Id for the supplied action Id.

Responses
  • 200 OK

/v1.0/actions/{action_id}/steps/{step_id}

Allow for drilldown to step information. The step information includes details of the steps excution, successful or not, and enough to facilitate troubleshooting in as easy a fashion as possible.

Payload Structure

The detailed information representing a single step of execution as part of an action.

{ TBD }

GET

Returns the details for a step by id for the given action by Id.

Responses
  • 200 OK

/v1.0/actions/{action_id}/{control_verb}

Allows for issuing DAG controls against an action.

Payload Structure

None, there is no associated body for this resource

POST

Trigger a control action against an activity.- this includes: pause, unpause

Responses
  • 202 Accepted

Airflow Monitoring API

Airflow has a primary function of scheduling DAGs, as opposed to Shipyard's primary case of triggering DAGs.
Shipyard provides functionality to allow for an operator to monitor and review these scheduled workflows (DAGs) in addition to the ones triggered by Shipyard. This API will allow for accessing Airflow DAGs of any type -- providing a peek into the totality of what is happening in Airflow.

/v1.0/workflows

The resource that represents DAGs (workflows) in airflow

Payload Structure

A list of objects representing the DAGs that have run in airflow.

[
  {TBD},
  ...
]

GET

Queries airflow for DAGs that are running or have run (successfully or unsuccessfully) and provides a summary of those things.

Query parameters
  • since={iso8601 date (past) or duration}
    optional, a boundary in the past within which to retrieve results. Default is 30 days in the past.
Responses
  • 200 OK

/v1.0/workflows/{id}

Payload Structure

An object representing the information available from airflow regarding a DAG's execution

{ TBD }

GET

Further details of a particular scheduled DAG's output

Responses
  • 200 OK