pegleg/doc/source/developer-overview.rst

Developer Overview of Pegleg

Pegleg's core mission is to, alongside Deckhand, facilitate document authoring strategies within Airship, by:

• aggregating documents across multiple revisioned repositories, each of which contains multiple documents defining sites' software and hardware stacks
• providing early linting of documents prior to their collection and eventual deployment
• including utility functions enabling operators and developers alike to list available sites, render individual manifests via Deckhand, bootstrap repositories with Pegleg-compliant directory layouts, to name a few

Architecture

Pegleg, as a CLI, has a rather simplistic architecture. It is meaningful to visualize Pegleg alongside Deckhand:

Components

cli

The Pegleg cli module implements the user-facing CLI. For more information about this module, reference the CLI documentation <pegleg-cli>.

engine

The engine module implements the following functionality:

• document linting
• document rendering via Deckhand
• document aggregation
• additional document utility functions

Developer Workflow

Because Airship is a container-centric platform, the developer workflow heavily utilizes containers for testing and publishing. It also requires Pegleg 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.

Pegleg strives to conform to the Airship coding conventions.

Python

The Pegleg code base lives under pegleg. Pegleg supports py36 interpreter.

Docker

The Pegleg Dockerfile is located in /images/pegleg 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 Pegleg Docker image.

Pegleg, as a containerized CLI, uses Docker via tools/pegleg.sh to execute CLI commands. Commands can also be executed using the Makefile target: run_pegleg.

Virtual Environment

Rather than, after each local code change, rebuilding the Pegleg image and overriding the IMAGE environment variable so tools/pegleg.sh uses the latest code changes, it is possible to use a virtual environment for much faster development.

This can achieved by issuing the following commands (from the root Pegleg directory):

# Quick way of building a venv and installing all required dependencies into
# it.
tox -e py36 --notest
source .tox/py36/bin/activate
pip install -e .

# Now is it possible to run the Pegleg CLI to test local changes:
pegleg <command> <options>

# Or run unit tests:
pytest -k <regex>

Note that after setting up the virtual environment, one only needs to source it in order to re-run unit tests or Pegleg CLI commands, to test local changes.

Testing

All Pegleg tests are nested under tests.

Pegleg comes equipped with a number of tox targets for running unit tests, as well as pep8 and Bandit checks.

Unit Tests

To run all unit tests, execute:

$ tox -epy36

To run unit tests using a regex, execute:

$ tox -epy36 -- <regex>