Helm

This document introduces Helm, the Kubernetes package manager, and provides guidelines for writing Helm charts.

What Is Helm?

Helm makes Kubernetes applications easy to manage as packages. You can define compute resources such as Deployments and StatefulSets, and discovery or load-balancing resources such as Services and Ingresses, using templated YAML and then deploy them. A template engine avoids repeating API object definitions across deployment environments: you specify only environment-specific differences in separate YAML files that override the defaults. Helm also supports release versioning, making it easy to roll back through the CLI when a problem occurs.

At Buzzvil, however, we use only Helm’s template engine. Actual release management is handled by Spinnaker, our continuous delivery (CD) platform. Spinnaker renders the templates with Helm and applies them directly to the Kubernetes cluster.

Helm Components

• Client: The Helm CLI.
• Tiller: A component installed in the Kubernetes cluster. It communicates with the CLI and applies changes to the cluster.

Note: The upcoming Helm 3 release will switch to a client-only approach because the Tiller server component has excessive privileges.

Helm Charts

Helm uses a packaging format called a chart. A chart manages a collection of Kubernetes resources as templates. Complex workloads can be defined by including multiple subcharts within a chart. Charts can also include custom resource definitions (CRDs) beyond standard Kubernetes resources—for example, VirtualService and Gateway resources for a service mesh such as Istio, or Certificate resources managed by Cert Manager.

Charts for Buzzvil’s internal services are managed in the charts monorepo. Its structure is similar to the official Helm charts repository. When chart changes are merged into master, CI uploads them to the internal chart registry. See the README for setup and usage.

Creating a Chart

Manage charts for internal services in the charts monorepo, rather than in individual projects. A monorepo lets us handle linting, testing, and release CI in one place instead of configuring it separately for each project.

Start a chart from the CLI in Buzzvil’s Helm charts monorepo.

$ helm create PROJECT_NAME
> Creating PROJECT_NAME

A chart generally has the following structure.

buzzscreen
├── Chart.yaml
├── templates
│   ├── _helpers.tpl
│   ├── configmap.yaml
│   ├── deployment.yaml
│   ├── fluentd-configmap.yaml
│   ├── fluentd-file-configmap.yaml
│   ├── hpa.yaml
│   ├── pdb.yaml
│   ├── secret.yaml
│   ├── service.yaml
│   └── virtualservice.yaml
└── values.yaml

• Keep the chart name as close as possible to the project name, and add a suitable description to Chart.yaml.
• Remove NOTES.txt and the tests directory generated by helm create, as we do not use them.
• Use helpers to reduce repetition of expressions such as labels and matchLabels across templates. See the authsvc example.
• Define a VirtualService when the service is accessed directly through a gateway. Define an Ingress for cases that cannot use Istio’s Gateway. For services used only inside the cluster, define only a Service.
• Where possible, add a README to each chart explaining its values and deployment considerations. Refer to charts in the official Helm stable repository, such as the mysql example.
• The official Kubernetes extension for VS Code provides syntax highlighting, linting, completion, and template output testing when writing charts.
• Define a Pod Disruption Budget (PDB) and Horizontal Pod Autoscaler (HPA) in the chart to improve the stability of running services.

We also recommend The Chart Best Practices Guide in the official repository.

Environment-Specific Helm Values Files

Values supplied at release time can override each chart’s defaults in values.yaml. With the Helm CLI, specify a YAML file containing overrides or use the --set flag for individual values. Buzzvil deploys Helm charts through Spinnaker. We manage environment-specific overrides in a separate monorepo; at deployment time, Spinnaker reads the appropriate configuration file and renders the Helm templates. This makes it possible to deploy applications separately from their configuration.

Creating an HPA with Custom Metrics (Autoscaling v2)

TBD