Developers Guide

This guide explains how to set up your environment for developing onHelm and Tiller.

Prerequisites

  • The latest version of Go
  • The latest version of Glide
  • A Kubernetes cluster w/ kubectl (optional)
  • The gRPC toolchain
  • Git

Building Helm/Tiller

We use Make to build our programs. The simplest way to get started is:

  1. $ make bootstrap build

NOTE: This will fail if not running from the path $GOPATH/src/k8s.io/helm. Thedirectory k8s.io should not be a symlink or build will not find the relevantpackages.

This will build both Helm and Tiller. make bootstrap will attempt toinstall certain tools if they are missing.

To run all the tests (without running the tests for vendor/), runmake test. To run all tests in a containerized environment, run make docker-test.

To run Helm and Tiller locally, you can run bin/helm or bin/tiller.

  • Helm and Tiller are known to run on macOS and most Linux distributions, includingAlpine.
  • Tiller must have access to a Kubernetes cluster. It learns about thecluster by examining the Kube config files that kubectl uses.

Man pages

Man pages and Markdown documentation are already pre-built in docs/. You mayregenerate documentation using make docs.

To expose the Helm man pages to your man client, you can put the files in your$MANPATH:

  1. $ export MANPATH=$GOPATH/src/k8s.io/helm/docs/man:$MANPATH
  2. $ man helm

gRPC and Protobuf

Helm and Tiller communicate using gRPC. To get started with gRPC, you will need to…

  • Install protoc for compiling protobuf files. Releases arehere
  • Run Helm's make bootstrap to generate the protoc-gen-go plugin andplace it in bin/.Note that you need to be on protobuf 3.2.0 (protoc —version). Theversion of protoc-gen-go is tied to the version of gRPC used inKubernetes. So the plugin is maintained locally.

While the gRPC and ProtoBuf specs remain silent on indentation, werequire that the indentation style matches the Go format specification.Namely, protocol buffers should use tab-based indentation and rpcdeclarations should follow the style of Go function declarations.

The Helm API (HAPI)

We use gRPC as an API layer. See pkg/proto/hapi for the generated Go code,and _proto for the protocol buffer definitions.

To regenerate the Go files from the protobuf source, make protoc.

Docker Images

To build Docker images, use make docker-build.

Pre-build images are already available in the official Kubernetes HelmGCR registry.

Running a Local Cluster

For development, we highly recommend using theKubernetes Minikubedeveloper-oriented distribution. Once this is installed, you can usehelm init to install into the cluster. Note that version of tiller you're using fordevelopment may not be available in Google Cloud Container Registry. If you're gettingimage pull errors, you can override the version of Tiller. Example:

  1. helm init --tiller-image=gcr.io/kubernetes-helm/tiller:2.7.2

Or use the latest version:

  1. helm init --canary-image

For developing on Tiller, it is sometimes more expedient to run Tiller locallyinstead of packaging it into an image and running it in-cluster. You can dothis by telling the Helm client to use a local instance.

  1. $ make build
  2. $ bin/tiller

And to configure the Helm client, use the —host flag or export the HELM_HOSTenvironment variable:

  1. $ export HELM_HOST=localhost:44134
  2. $ helm install foo

(Note that you do not need to use helm init when you are running Tiller directly)

Tiller should run on any >= 1.3 Kubernetes cluster.

Contribution Guidelines

We welcome contributions. This project has set up some guidelines inorder to ensure that (a) code quality remains high, (b) the projectremains consistent, and (c) contributions follow the open source legalrequirements. Our intent is not to burden contributors, but to buildelegant and high-quality open source code so that our users will benefit.

Make sure you have read and understood the main CONTRIBUTING guide:

https://github.com/helm/helm/blob/master/CONTRIBUTING.md

Structure of the Code

The code for the Helm project is organized as follows:

  • The individual programs are located in cmd/. Code inside of cmd/is not designed for library re-use.
  • Shared libraries are stored in pkg/.
  • The raw ProtoBuf files are stored in _proto/hapi (where hapi stands forthe Helm Application Programming Interface).
  • The Go files generated from the proto definitions are stored in pkg/proto.
  • The scripts/ directory contains a number of utility scripts. Most of theseare used by the CI/CD pipeline.
  • The rootfs/ folder is used for Docker-specific files.
  • The docs/ folder is used for documentation and examples.Go dependencies are managed withGlide and stored in thevendor/ directory.

Git Conventions

We use Git for our version control system. The master branch is thehome of the current development candidate. Releases are tagged.

We accept changes to the code via GitHub Pull Requests (PRs). Oneworkflow for doing this is as follows:

  • Go to your $GOPATH/src/k8s.io directory and git clone thegithub.com/helm/helm repository.
  • Fork that repository into your GitHub account
  • Add your repository as a remote for $GOPATH/src/k8s.io/helm
  • Create a new working branch (git checkout -b feat/my-feature) anddo your work on that branch.
  • When you are ready for us to review, sign your commit, push your branch to GitHub, andthen open a new pull request with us.For Git commit messages, we follow the Semantic Commit Messages:
  1. fix(helm): add --foo flag to 'helm install'
  3. When 'helm install --foo bar' is run, this will print "foo" in the
  4. output regardless of the outcome of the installation.
  6. Closes #1234

Common commit types:

  • fix: Fix a bug or error
  • feat: Add a new feature
  • docs: Change documentation
  • test: Improve testing

  • ref: refactor existing codeCommon scopes:

  • helm: The Helm CLI

  • tiller: The Tiller server
  • proto: Protobuf definitions
  • pkg/lint: The lint package. Follow a similar convention for anypackage

  • *: two or more scopesRead more:

  • The Deis Guidelineswere the inspiration for this section.

  • Karma Runner defines the semantic commit message idea.

Go Conventions

We follow the Go coding style standards very closely. Typically, runninggo fmt will make your code beautiful for you.

We also typically follow the conventions recommended by go lint andgometalinter. Run make test-style to test the style conformance.If you do not want to install all the linters from gometalinter into yourglobal Go environment, you can run make docker-test-style which willrun the same tests, but isolated within a docker container.

Read more:

Protobuf Conventions

Because this project is largely Go code, we format our Protobuf files asclosely to Go as possible. There are currently no real formatting rulesor guidelines for Protobuf, but as they emerge, we may opt to followthose instead.

Standards:

  • Tabs for indentation, not spaces.

  • Spacing rules follow Go conventions (curly braces at line end, spacesaround operators).Conventions:

  • Files should specify their package with option go_package = "…";

  • Comments should translate into good Go code comments (since protoccopies comments into the destination source code file).
  • RPC functions are defined in the same file as their request/responsemessages.
  • Deprecated RPCs, messages, and fields are marked deprecated in the comments (// UpdateFoo DEPRECATED updates a foo.).