Workspaces are local checkouts of kapps that you can work on while you develop and that Sugarkube will use when installing kapps into a cluster. They literally contain the Helm chart/Terraform code/scripts/whatever that will be executed to install or delete each kapp into a cluster. Workspaces are created by running the workspace create command. Multiple workspaces can be created for different stacks or clusters, which makes it easy to context switch.

Complex environments (especially in enterprises) may have multiple live environments or need to respect change windows, etc. A team responsible for providing a Kubernetes platform for the rest of the organisation may need to treat a dev cluster like a prod cluster since if it goes down it’d block the rest of the organisation’s developers from working. Therefore the safest way of determining which version of which kapp should be installed into which cluster is to update a config file to explicitly select the appropriate version for each stack. This is how Sugarkube solves this challenge. Practically speaking this means using versions block for a manifest in a stack config file or directly in manifest files.

Version matrix

We could list the versions of each kapp to install into some clusters in a matrix:

dev1 staging prod1 prod2
ingress 1.1.0 1.1.0 1.0.0 1.0.0
memcached 2.4.3 2.4.3 2.4.3 2.4.2
wordpress br-new 3.2.1 3.2.0 3.2.0

The above shows 2 prod clusters running different versions of memcached – imagine the team have to wait for an upcoming change window before pushing the updated memcached to prod2. Staging has some changes to both Wordpress and the ingress controller being tested, while in dev1 a new branch of Wordpress is being worked on.

By explicitly choosing the version of each kapp to install into each cluster you can control exactly when it gets deployed. There’s no continuous deployment magic. And by versioning your configs you also gain the ability to recreate the state of a cluster (excluding data) by checking out an earlier version installing the kapps it defines.

Creating a workspace

Before you can run any commands on kapps you need to create a workspace. This will checkout all sources for a kapp and group all kapps in each manifest together. Creating a workspace can be done by using the workspace create command. Running workspace create on an existing workspace will update it.

Sugarkube will clone git repos in parallel as far as possible to speed up creating a workspace. It will also perform sparse checkouts to reduce the amount of data retrieved. Sugarkube will propagate any errors from git to prevent you losing uncommitted work (e.g. if running workspace create again to update your workspace).

If you browse the workspace that’s created you’ll see how kapps are grouped by manifest and how symlinks are created between each source in a kapp.


Imagine you needed to add a new feature to Wordpress from the above matrix. You’d create a workspace for the dev1 cluster, go to the Wordpress kapp and create a new branch (br-new), then develop and commit to your branch as usual.

Suppose that while you’re doing this you get asked to urgently fix a bug in prod. You could create another workspace for prod, hotfix the affected application in a new dev cluster and merge and tag the fix when you’re happy. Then you could update the staging stack’s config to test your new kapp, and if you were happy update the prod one to release it.

After this interruption you could go back to working in the dev1 workspace. You could update your configs to pull your fixed kapp, run workspace create again to pull in those changes, and pick up where you left off.