app-build-suite

A tool to build apps (Helm Charts) for Giant Swarm App Platform.

This tool is a Helm charts development and CI/CD tool that allows you to:

do some simple variable replacements before building the chart
lint chart's source code
run Helm chart code analysis tools
generate actual chart archive
generate App Platform specific metadata

In short, it runs an opinionated Helm chart build process as a single configurable build step (one step build`).

It has a companion tool called app-test-suite for running dynamic (run-time) tests on charts built.

Big fat warning This tool is available as a development version!

Index

How to use app-build-suite
Tuning app-build-suite execution and running parts of the build process
- Configuring app-build-suite
Execution steps details and configuration
How to contribute

How to use app-build-suite

Installation

IMPORTANT NOTE: we are planning to sunset dabs.sh, we recommend running locally as pure python.

First, you need pipenv to manage the virtual environment for ABS.

# Set up the virtual environment based on `Pipfile.lock`
pipenv install

# Activate the virtual environment for the current shell
pipenv shell

# Then simply run ABS commands with:
python -m app_build_suite --help

# Example to run Helm Chart validations on a repository
python -m app_build_suite --step validate -c PATH_TO_HELM_CHART_ROOT

All the examples below and under `docs` using `dabs.sh ...` can run with `python -m app_build_suite ...` too.

abs is distributed as a docker image, so the easiest way to install and use it is to get our dabs.sh script from releases. dabs.sh is a wrapper script that launches for you abs inside a docker container and provides all the necessary docker options required to make it work (check te script for details, it's short).

Alternatively, you can just check out this repository and build the docker image yourself by running:

make docker-build

Tutorial

If you prefer to learn by example, building a simple project step-by-step, please start with tutorial.

Quick start

Executing dabs.sh is the most straight forward way to run app-build-suite. As an example, we have included a chart in this repository in examples/apps/hello-world-app. It's configuration file for abs is in the .abs/main.yaml file. To build the chart using dabs.sh and the provided config file, run:

dabs.sh -c examples/apps/hello-world-app

GitHub Action

We have created a GitHub Action called push-to-app-catalog for publishing apps to an app catalog served with GitHub Pages. See its docs for how to configure it.

A command wrapper on steroids

abs is not much more than a wrapper around a set of well-known open source tools. It orchestrates these tools into an opinionated build process and adds some additional features, like generating metadata for the Giant Swarm App Platform.

To better explain it, see what really happens when you call

dabs.sh -c examples/apps/hello-world-app --destination build

The list bellow is a set of commands executed for you by abs:

# app and chart versions in the Chart.yaml file are set using git changes (if configured)
ct lint --validate-maintainers=false --charts=examples/apps/hello-world-app --chart-yaml-schema=/abs/workdir/app_build_suite/build_steps/../../resources/ct_schemas/gs_metadata_chart_schema.yaml
kube-linter lint . --config .kube-linter.yaml
helm package examples/apps/hello-world-app --destination build
# now metadata is generated from the data collected during the build (if configured)

Full usage help

To get an overview of available options, please run:

dabs.sh -h

To learn what the configuration options mean and how to use them, please follow to execution steps and their config options.

Tuning app-build-suite execution and running parts of the build process

This tool works by executing a series of so called Build Steps. In general, one BuildSteps is about a single step in the Chart build process, like running a single external tool. Most of the build steps are configurable (run ./dabs.sh -h to check available options and go to steps details and configuration for detailed description).

The important property in app-build-suite is that you can execute a subset of all the build steps. This idea should be useful for integrating abs with other workflows, like CI/CD systems or for running parts of the build process on your local machine during development. You can either run only a selected set of steps using --steps option or you can run all of them excluding some steps using --skip-steps. Check dabs.sh -h output for step names available to --steps and --skip-steps flags.

To skip or include multiple step names, separate them with space, like in this example:

dabs.sh -c examples/apps/hello-world-app --skip-steps validate static_check

Configuring app-build-suite

Every configuration option in abs can be configured in 3 ways. Starting from the highest to the lowest priority, these are:

command line arguments,
environment variables,
config file (abs tries first to load the config file from the chart's directory .abs/main.yaml file; if it doesn't exist, then it tries to load the default config file from the current working directory's .abs.main.yaml).

When you run dabs.sh -h it shows you command line options and the relevant environment variables names. Options for a config file are the same as for command line, just with truncated leading --. You can check this example.

The configuration is made this way, so you can put your defaults into the config file, yet override them with env variables or command line when needed. This way you can easily override configs for stuff like CI/CD builds.

Tools included in app-build-suite can have their own, tool-specific config files. Refer to build pipeline steps to learn more.

Execution steps details and configuration

When abs runs, it executes all the steps from the build pipeline. Config options can be used to disable/enable any specific build steps. Please check below for available steps and their config options.

Currently, only one build pipeline is supported. It is based on helm. Please check this doc for detailed description of steps and available config options.

How to contribute

Check out the contribution guidelines.

giantswarm/app-build-suite