Stacks represent clusters, whether Kubernetes clusters or otherwise. They allow configuring broad settings that are more specific to clusters rather than to individual kapps.

Stacks refer to configurations for clusters. A cluster is an instance of a stack and multiple clusters may use the same stack config but perhaps change minor details. This is analogous to how a class in an object-orientated language is used to create instances of objects.

Several settings are available to help you namespace resources so you can run multiple stacks and clusters in the same cloud account. E.g. if you need a hosted zone, name it something like {{cluster_name}}.{{profile}}.{{region}} The same goes for other resources you create (e.g. load balancer names, S3 buckets, etc.). This is important to ensure each cluster’s resources are isolated from each other. See the sample project and notice how every resource uses variables to avoid naming conflicts between clusters.


Here are the available settings for a stack (all settings are required except defaults):

  • name - allows you to refer to a particular stack when there are multiple stacks defined in a stack YAML file.
  • provider - the provider to use to load configs from disk
  • provisioner - the provisioner to use to create a cluster. Use none if you’ve got an existing cluster or don’t want Sugarkube to create clusters
  • account - the human-readable name of the account to run under, e.g. dev, prod, etc. This should be used to namespace your resources
  • region - cloud provider region, e.g. eu-west-1. Not required when using the local provisioner
  • profile - name of the profile to use. Profiles allow you to broadly configure different categories of clusters in a single cloud account. E.g. you may have a single account for testing, and want to use one profile with smaller instances for normal user acceptance testing, and larger instances for various different staging/performance testing clusters.
  • cluster - name of the cluster. This should also be used to namespace your resources to avoid conflicts between multiple clusters running in the same cloud account.
  • provider_vars_dirs - A list of directories that providers should search for config files
  • kapp_vars_dirs - A list of directories that should be searched for kapp variables
  • manifests - A list of manifest locations containing the manifests that should be applied to the stack.
  • template_dirs - A list of directories to search for templates in if they aren’t in a kapp
  • defaults (optional) - set default values for kapps in the whole stack

Manifests locations are defined as a list of:

  • uri (required) - path to the local manifest file. Can be relative to the stack config file (i.e. the YAML file that defines your stack), or absolute.
  • id - optional. If not set, the basename of the manifest file (i.e. the name without .yaml) will be used
  • overrides - Allows overriding values in manifests from stack configs. See below for more information.
  • versions - Allows changing the git branch to use for a particular kapp. This allows you to easily control which versions of each kapp are deployed in each stack. The syntax is ‘/’. If no source ID is explicitly defined it defaults to the last component of the URI’s path. E.g. for the uri the source ID would default to site1-data. So you could specify the version with the key wordpress/site1-data.

An example stack config is:

defaults: &defaults
    - ../providers/  
    - ../kapp-vars/  
    - ../templates/

local-web:        # a local stack for web development
  <<: *defaults   # inherit the defaults above
  cluster: standard
  provider: local
  provisioner: minikube
  profile: minikube
    - uri: ../manifests/web/bootstrap.yaml
    - uri: ../manifests/web/wordpress-sites.yaml
        site1/wordpress: master      # for this stack override the branch
          - false             # explicitly disable this site


It’s possible to override values for manifests in stack configs. This allows you to reuse the same set of manifests across multiple different stacks but to parameterise them differently at the stack level. You can override all config values for kapps, as well as overriding the URIs to their sources. This is one way of selecting which release/tag of a kapp to deploy into each stack.

In the above example stack config, a condition is used to stop site2 from being installed/deleted in the local-web stack.