6c45569ecd
This patchset adds developer overview documentation for providing a high-level introduction to Deckhand, including its architecture, modules, test utilities, Helm utilities, and other errata. This work is based off this Drydock patchset: https://review.openstack.org/#/c/571298/ Change-Id: Ic3382d4e04edf02a65184651d272fe9cd1db56a4
4.9 KiB
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 <encryption>,
which it passes to the engine module for rendering.
engine
The engine module is the interface responsible for all
rendering. Rendering
consists of applying a series of algorithms to the documents, including:
topological sorting, layering, substitution, and replacement.
db
The db module is responsible for implementing the
database tables needed to store all Airship documents. The module also
realizes version control and revision-diffing functionality.
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 py27 and py35 interpreters. Once OpenStack deprecates usage of
py27, Deckhand will as well.
See coding-guide for
more information on contribution guidelines.
Docker
The Deckhand Dockerfile 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.tgzfile.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.