Advanced: How the build-system works

Note

This section is not necessary for building, deploying or interacting with the platform. It provides a technical explanation of the steps performed by the build script.
For building the platform, refer to Build Kaapana.

Assuming the kaapana repository was cloned into the kaapana/ directory the build process is usually started by executing

kaapana-build -u <registriy_username> -p <registry_password>

inside kaapana/.

Important

This document expects a basic knowledge of the following technologies
- Docker
- Kubernetes
- Helm

Configuration steps

First the path to the kaapana repository is determined by walking up from the installed CLI to the nearest directory containing a .git folder. This can be overridden with the flag -kd, --kaapana-dir <path> or the KAAPANA_DIR environment variable.

The build is configured entirely through command-line flags and environment variables; there is no YAML config file. Every flag has a matching environment variable (for example --default-registry / DEFAULT_REGISTRY), and a .env file placed in the current working directory is loaded automatically. Options that are not set fall back to built-in defaults. All resolved settings are merged and validated into a single BuildConfig object that is shared across the whole build. For the full list of options run kaapana-build --help.

Directories for external sources are then checked for availability. They can be specified with the flag -es, --external-source-dirs <dir> (repeatable) or via the EXTERNAL_SOURCE_DIRS environment variable.

Collecting available images and charts

Before the build process is initiated all available Dockerfiles are recursively collected from the kaapana repository directory and all directories specified as external sources. For each found Dockerfile an instance of the helper class Container is initialized. This step also checks if all required local images are present in the collection of images.

Hint

Local images

Not all images are pushed to the registry. If the Dockerfile contains the line LABEL REGISTRY="local-only" the image is build but not pushed to the specified registry. It is tagged as local-only/<image-name>:<version>.

In a similar manner the kaapana directory and all external source directories are scanned for Chart.yaml files. For each found file an instance of HelmChart is initialized and if existing the .tgz file is removed.

Generating deployment scripts

Attention

Generated deployment scripts have been removed The build no longer generates deployment scripts. They were deprecated since Kaapana 0.6.0 and are replaced by kaapanactl — use kaapanactl to deploy a platform.

Hint

Platform charts

Currently there are two platforms build by default i.e. the admin-platform and the kaapana-platform. Each platform is entirely packaged as a single helm chart i.e. the kaapana-admin-chart and the kaapana-platform-chart. Platform charts are specified by the key-value pair kaapana_type: "platform" in the Chart.yaml file.

A filter can be applied in order to build only a subset of platform-charts e.g. only the kaapana-platform-chart. To do so use the command line flag -pf, --platform-filter <platform-chart-name> or set the PLATFORM_FILTER environment variable.

The actual build-proccess

The actual build-proccess consists of updating dependencies for helm charts, packaging and pushing helm charts and of tagging, building and pushing images. For each platform-chart that should be build the following steps are proccessed:

  1. A dependecy tree of helm charts is generated

  2. All helm charts in this tree are recursively packaged and the dependencies are updated, images associated with a chart are tagged in a uniform pattern

  3. The platform-chart is packaged and pushed.

  4. A list of images is generated in an order that allows to build them successively

  5. All images in the list generated in step 4 are build and all non-local images are pushed to the registry

Hint

Recursively proccessing charts

The basic component of step 2 is the static method build_platform(chart) of the HelmChart class. The method is first called for the platform-chart and then recursively for each chart it depends on. This way all charts of the dependency tree are proccessed in a depth-first approach. It updates dependencies, packages charts and tags images. (For special charts specified as collections also an image is build and pushed by this method.)

Hint

Collections

A collection can be identified with an image and a helm chart. In the scope of the build script a collection contains several charts as dependencies. The build scripts processes a collection by updating the dependencies for all charts and packaging all charts it depends on.

Hint

Caching

All packaged charts and all information regarding the build process like the log file or the dependecy trees are stored in kaapana/build/.