Config Merging

The final configuration of a kapp is the result of merging multiple config fragments from different places. Imagine that each config fragment is like a photographic slide - multiple slides can be laid on top of each other, and the final image is the result of shining light through all of them. It’s similar with a kapp’s config, the only difference being that YAML keys in upper slides will overwrite those lower down.

Creating a kapp’s configuration by merging fragments together provides a lot of flexibility. The kapp’s own sugarkube.yaml file can contain defaults which can be overridden in manifest or stack files to maximise reuse. For example the same kapp could be used multiple times in the a manifest (or in different ones) and parameterised differently in each one (here’s an example with the Wordpress kapp). Or they could be parameterised differently per stack. A concrete example of this would be to create a kapp that creates a Kubernetes NGINX ingress controller and an Elastic Load Balancer. This kapp could be run twice with different parameters – once to create an internal load balancer for routing internal traffic, and once to create a single shared load balancer for externally accessible services.

Precedence

Config fragments for a kapp will be loaded from the following places and merged together (in order of lowest to highest precedence):

  • The project’s sugarkube-conf.yaml - fragments here are organised by the programs a kapp requires and are typically used to define run units. A sample config file is available that contains run units for Helm & Terraform and configures dynamically searching for values/.tfvars files. Kapps can opt-out of these defaults by setting ignore_global_defaults: true.
  • A kapp’s sugarkube.yaml file - should contain default variables for the kapp, define programs it requires, actions, outputs and templates.
  • Manifest files. This is typically the place to declare dependencies between kapps and to pass outputs into kapps. Each kapp in a manifest will use the value of the manifest’s defaults block if one has been defined, making it simple to set shared values (e.g. the name of a namespace to be used across all kapps in the manifest). Config defined where a kapp is declared in a manifest has higher precedence than any defaults block in the manifest.
  • A defaults block defined in a stack file.
  • The overrides block for a manifest in a stack file.

Viewing a Kapp’s config

While config merging provides flexibility it might make it a bit less clear what the final config for a kapp will be. To help with that Sugarkube has a kapp vars command that will print out the merged config of a kapp so you can inspect it. It displays all the variables that can be used in the kapp’s config, and it also shows the final kapp config with all variables interpolated. It also has various options for suppressing or selecting output to make it easier to see only what you’re interested in.