app_build_suite 1.8.0

An app build suite for GiantSwarm app platform

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
  • Installation
  • Tutorial
  • Quick start
  • GitHub Action
  • A command wrapper on steroids
  • Full usage help
• 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

With uv

You install app-build-suite as a command line tool called with abs command. In this case, you're responsible for installing all the binary dependencies that abs needs to work.

This mode doesn't need docker, so it's a good match for all the systems with isolation and sandboxing in mind, like CI/CD or AI agents running in isolated jails/sandboxes.

The main tool you need is uv. Please refer to the uv installation documentation for instructions on how to install it.

You also need to have the following binaries installed:

• helm
• chart testing
• kube-linter

Then, to install abs, just run:

uv tool install app-build-suite

Check the installation:

abs --version

To upgrade:

uv tool upgrade app-build-suite

With docker

[!IMPORTANT] We are planning to sunset dabs.sh, we recommend running locally as a python app.

abs is also distributed as a docker image, so the easiest way to install it and all of the dependencies 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 the script for details, it's short). Unfortunately, this means you need to be able to access docker socket, which is not always available. In that case, it's probably easier to run as python app.

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.