Developer Overview of Deckhand

The core objective of Deckhand is to provide storage, rendering, validation and version control for declarative YAML documents. Deckhand ingests raw, Airship-formatted documents and outputs fully rendered documents to other Airship components.

Architecture

From a high-level perspective, Deckhand consists of a RESTful API, a document rendering engine, and a PostgreSQL relational database for document storage. Deckhand ingests Airship-formatted documents, validates them, and stores them in its database for future processing. On demand, Deckhand will fully render the documents, after which they can be consumed by the other Airship components.

Deckhand uses Barbican to securely storage sensitive document data.

Pegleg in effect provides Deckhand with a CLI, which facilitates communication with Deckhand.

Components

control

The control module is simply the RESTful API. It is based on the Falcon Framework and utilizes oslo.policy for RBAC enforcement of the API endpoints. The normal deployment of Deckhand uses uWSGI and PasteDeploy to build a pipeline that includes Keystone Middleware for authentication and role decoration of the request.

The control module is also responsible for communicating with Barbican, which it uses to store and retrieve document secrets, which it passes to the engine module for Document Rendering.

engine

The engine module is the interface responsible for all Document Rendering. Rendering consists of applying a series of algorithms to the documents, including: topological sorting, Document Layering, Document Substitution, and Document Replacement. This module also realizes revision-diffing and revision-deepdiffing functionality.

db

The db module is responsible for implementing the database tables needed to store all Airship documents. This module also realizes version control.

client

The API client library provides an interface for other services to communicate with Deckhand’s API. Requires Keystone authentication to use.

Developer Workflow

Because Airship is a container-centric platform, the developer workflow heavily utilizes containers for testing and publishing. It also requires Deckhand to produce multiple artifacts that are related, but separate: the Python package, the Docker image and the Helm chart. The code is published via the Docker image artifact.

Deckhand strives to conform to the Airship coding conventions.

Python

The Deckhand code base lives under /deckhand. Deckhand supports py36 through py37 versions of interpreters.

See Deckhand Coding Guide for more information on contribution guidelines.

Docker

The distribution specific Deckhand Dockerfile.{DISTRO} is located in /images/deckhand along with any artifacts built specifically to enable the container image. Make targets are used for generating and testing the artifacts.

• make images - Build the Deckhand Docker image.

Helm

The Deckhand Helm chart is located in /charts/deckhand. Local testing currently only supports linting and previewing the rendered artifacts. Richer functional chart testing is a TODO.

• make charts - Pull down dependencies for the Deckhand charts and package everything into a .tgz file.
• make helm_lint - Lint the Helm charts.
• make dry-run - Render the chart and output the Kubernetes manifest YAML documents.

Testing

All Deckhand tests are nested under /deckhand/tests.

Deckhand comes equipped with a number of tox targets for running unit and functional tests. See Development Utilities for a list of commands.

See Testing for more information on testing guidelines.