Kapps are the release artefacts in Sugarkube. They’re bundles of versioned applications and infrastructure code and are simply git repos where different directories contain a sugarkube.yaml config file containing various settings. Git repos containing kapps should be tagged so they can be checked out at different versions.

It might be easier to understand kapps by using them. If you haven’t already, you can try our tutorials for a hands-on introduction.

If you decide to install your applications into a Kubernetes cluster as a Helm chart and manage your infrastructure using Terraform you can take advantage of our default run units that should cover 80-90% of use-cases. There’ll probably be almost a 1:1 mapping between Helm charts and kapps. However, you have complete freedom to define exactly what series of commands is executed to install or delete a kapp. They could instead contain things like scripts or terraform configs and can also execute commands before or after installing Helm charts/applying Terraform configs.

Kapps are organised into manifests which are further grouped into stacks that represent your actual clusters.


To give you some context, here’s a sample sugarkube.yaml file from our Jenkins kapp:

  hostname: "{{ .kapp.vars.release }}.localhost"
  prometheus_hostname: "{{ .kapp.vars.release }}-prometheus.localhost"
  prometheus_enabled: true     # using a variable here allows prometheus to be easily 
                               # (dis)abled for different stacks
  ingress_class: nginx
  dns_record_name: "{{ .kapp.id }}"
  prometheus_dns_record_name: "{{ if .kapp.vars.prometheus_enabled }}{{ .kapp.id }}-prometheus{{ end }}"
#  cert_manager_issuer_kind:    # set these in a manifest
#  cert_manager_issuer_name:
# hosted_zone         # hosted zone to create a CNAME DNS record under (AWS only)
# cname_hostname      # target of the CNAME record (AWS only)

  - helm
  - terraform

    source: kapp-templates/values.tpl.yaml
    dest: _generated_values.yaml
    source: kapp-templates/vars-aws.tpl.tfvars
    dest: "{{ .kapp.vars.terraform_dir }}/_generated_vars.tfvars"
      - "{{ eq .stack.provider \"aws\" }}"        # only template this file when running in AWS

This file documents some variables and sets default values for some as well. It declares that it uses Helm and Terraform which correspond to entries in the project’s config file. It also declares some files that need templating. sugarkube.yaml files can also define things like outputs that should be made available to other kapps, dependencies on other kapps, and exactly which commands should be run to install or delete them.

We have other sample sugarkube.yaml files that you can browse.

Dealing with shared infrastructure

One important thing to point out is that kapps must only create infrastructure that is solely used by the application in the kapp. Any infrastructure that’s shared between multiple applications/kapps must be created by another kapp (i.e. so you’d have one or several kapps dedicated to creating shared infrastructure like databases, hosted zone records, etc.). These ‘shared infrastructure’ kapps therefore form the foundation for running certain groups of applications. So for example, you could create a shared infrastructure kapp to create your databases and hosted zone records, and configure it to be executed before executing kapps to install your web applications, etc. that use them.


The settings below can be used to configure kapps everywhere it’s possible to configure them but some only make sense in certain places. Sugarkube strictly validates the structure of sugarkube.yaml files and will abort with an error if any extra keys exist. The metadata key can be used to add arbitrary extra data.

  • id (required) - a string identifier for the kapp.
  • sources (required) - a list of sources.
  • conditions - a list of entries that must all evaluate to true for the kapp to be installed/deleted.
  • depends_on - a list of kapps that must be installed before this kapp is installed, or deleted after this kapp is deleted. Kapps within the same manifest can be referred to directly by ID, while those in different manifests must be referred to by their fully-qualified ID (of the format <manifest ID>:<kapp ID>). Wildcards can be used to select all kapps in a manifest with <manifest ID>:*.
  • ignore_global_defaults - don’t merge values from the project config file for this kapp
  • metadata - a freeform field for additional values you wish to associate with a kapp. Sugarkube ignores this field entirely (but it’s a valid key in a sugarkube.yaml file).
  • outputs - a list of outputs.
  • post_install_actions - a list of actions
  • post_delete_actions - a list of actions
  • pre_install_actions - a list of actions
  • pre_delete_actions - a list of actions
  • requires - a list of program names that the kapp uses. These may correspond to keys under the programs key in the project config file and are a way of easily sharing run units and configuration between similar kapps.
  • run_units - a list of run units which define exactly which commands to execute for the kapp
  • templates - a list of outputs.
  • vars - a map of key/value variables for the kapp.

The canonical list of available settings is in the code.