Developer guide

Here we will walk through how to compile the Tarmak CLI and documentation from source.

Building Tarmak


Building Tarmak binary

First we will clone the Tarmak repository and build the tarmak binary. Make sure you have your $GOPATH set correctly. The last line may change depending on your architecture.

mkdir -p $GOPATH/src/
cd $GOPATH/src/
git clone
cd tarmak
make build
ln -s $PWD/tarmak_$(uname -s | tr '[:upper:]' '[:lower:]')_amd64 /usr/local/bin/tarmak

You should now be able to run tarmak to view the available commands.

$ tarmak
Tarmak is a toolkit for provisioning and managing Kubernetes clusters.

  tarmak [command]

Available Commands:
  clusters     Operations on clusters
  environments Operations on environments
  help         Help about any command
  init         Initialize a cluster
  kubectl      Run kubectl on the current cluster
  providers    Operations on providers
  version      Print the version number of tarmak

  -c, --config-directory string   config directory for tarmak's configuration (default "~/.tarmak")
  -h, --help                      help for tarmak
  -v, --verbose                   enable verbose logging

Use "tarmak [command] --help" for more information about a command.

Building Tarmak documentation

To build the documentation run the following.

cd $GOPATH/src/
make html

Or using docker:

cd $GOPATH/src/
make docker_html

You can now open _build/html/index.html in a browser or serve the site with a web server of your choice.

Updating puppet subtrees

Puppet modules are maintained as separate repositories, which get bundled into tarmak using git subtree. To pull the latest changes from the upstream repositories, run make subtrees.

Release Checklist

This is a list to collect manual tasks/checks necessary for cutting a release of Tarmak:

  • Ensure release references are updated (don’t forget to commit)
make release VERSION=x.y.x
  • Tag release commit with x.y.z and push to GitLab and GitHub
  • Update the CHANGELOG using the release notes
# relnotes is the golang tool from
relnotes -repo tarmak -owner jetstack -doc-url= -htmlize-md -markdown-file x.y(-1).z-1..x.y.z
  • Branch out minor releases into release-x.y

After release job has run:

  • Make sure we update the generated releases page

Setting up a Puppet Development Environment

In order to develop the Puppet modules for configuring Tarmak instances we need to set up our environment properly. The following instructions will walk through the process on a fresh Ubuntu 16.04 LTS instance.

Install Ruby development tools (

sudo apt-get install build-essential patch ruby-dev zlib1g-dev liblzma-dev
sudo gem install bundler

To test your environment, verify a module:

cd puppet/modules/kubernetes
make verify

Install the latest version of vagrant:

sudo dpkg -i vagrant_2.1.1_x86_64.deb

Install vagrant-libvirt ( You should now be able to run acceptance tests:

make acceptance

To keep any VMs around for debugging purposes, use the following commands instead of the acceptance target:

BEAKER_provision=yes BEAKER_destroy=no bundle exec rake beaker
bundle exec rake beaker:ssh