Documentation
Explanation
Helm

Helm

Overview

Helm is a package manager for Kubernetes, providing a simple and efficient way to manage Kubernetes applications. It allows users to define, install, and upgrade even the most complex Kubernetes applications. Helm uses a packaging format called charts, which are collections of files that describe a related set of Kubernetes resources.

Prerequisites

Before installing Helm, ensure you have the following:

  • Kubernetes cluster (v1.16+)
  • kubectl installed and configured
  • Helm client (v3+)

Installation

Install Helm on Windows

  1. Download Helm:

    choco install kubernetes-helm

  2. Verify the Installation:

    helm version

Install Helm on macOS

  1. Download Helm using Homebrew:

    brew install helm

  2. Verify the Installation:

    helm version

Install Helm on Linux

  1. Download the Helm binary through the distro’s package manager

    curl https://baltocdn.com/helm/signing.asc | gpg --dearmor | sudo tee /usr/share/keyrings/helm.gpg > /dev/null
sudo apt-get install apt-transport-https --yes
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/helm.gpg] https://baltocdn.com/helm/stable/debian/ all main" | sudo tee /etc/apt/sources.list.d/helm-stable-debian.list
sudo apt-get update
sudo apt-get install helm

Note

Alternatively download it from GitHub https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3

  1. Verify the Installation:

    helm version

Using Helm

Adding a Repository

  1. Add the Stable Helm Repository:

    helm repo add stable https://charts.helm.sh/stable

  2. Update Your Repository:

    helm repo update

Searching for Charts

  1. Search for a Chart:

    helm search repo <chart-name>

Installing a Chart

  1. Install a Chart:

    helm install <release-name> <chart-name>

    Example:

    helm install my-release stable/mysql

Upgrading a Release

  1. Upgrade a Release:

    helm upgrade <release-name> <chart-name>

    Example:

    helm upgrade my-release stable/mysql

Rolling back a Release

  1. Rolling back a Release:

    helm rollback <release-name> <revision>

    Example:

    helm rollback my-release 2

Uninstalling a Release

  1. Uninstall a Release:

    helm uninstall <release-name>

    Example:

    helm uninstall my-release

Listing Releases

  1. List All Releases:

    helm list

Interacting with Helm

Helm Commands

  • Install a Chart:

    helm install <release-name> <chart-name> --values <values.yaml>

  • Get Release Information:

    helm status <release-name>

  • Rollback a Release:

    helm rollback <release-name> <revision>

  • Show the Values File for a Chart:

    helm show values <chart-name>

Helm Configuration

  • Override Default Values: You can create a values.yaml file to override default values:

    replicaCount: 2
image:
  repository: myrepo/myimage
  tag: latest

  • Install with Custom Values:

    helm install <release-name> <chart-name> -f <path-to-values-file>

Working with Helm Hooks

Helm hooks allow you to intervene at certain points in a release lifecycle, such as before installing or after upgrading. For more details, refer to the Helm Hooks documentation.

Troubleshooting

Common Issues

  • Failed to install chart: Ensure the chart name and repository are correct and updated:

    helm repo update
helm search repo <chart-name>

  • Release is in a failed state: Check the release status and logs for more information:

    helm status <release-name>
kubectl logs <pod-name>

Debugging Tips

  • Verbose Output: Use the --debug flag with Helm commands to get detailed output:

    helm install <release-name> <chart-name> --debug

Writing Helm charts

Writing Helm charts involves creating a directory structure with the necessary files to define the Kubernetes resources. For more information on how the directory structure should look like, refer to the Helm Chart documentation.

We recommend initializing a new charts using the helm create command:

helm create my-awesome-chart

This command creates a new directory called my-awesome-chart with the following structure:

my-awesome-chart/
├── Chart.yaml
├── charts/
├── templates/
│   ├── NOTES.txt
│   ├── _helpers.tpl
│   └── <resources>.yaml
├── values.yaml
├── .helmignore
├── .gitignore
├── README.md
└── LICENSE

The best practice for writing Helm charts is to follow the Helm Best Practices. Kubernetes resources should be in separate .yaml files, but logical bundling of resources is welcome: Eg: All services in one file, all deployments in another file ,etc. Resources must be split by the --- delimiter. .

Handling CustomResourceDefinitions (CRDs)

For handling CustomResourceDefinitions (CRDs), there are two common approaches.

We recommend the first approach:

The first one is using a separate chart to manage them from the Helm Best Practices documentation. This approach has more overhead (installing 2 charts instead of 1), but gives more clarity and control over the CRDs installation and upgrade cycle.

The second one is to package the CRDs with the main chart. This approach is simpler and more straightforward, but it can lead to issues when upgrading the CRDs. For more information, refer to the Let Helm do it for you section (caveats explained).

Chart.yaml file

The Chart.yaml file contains metadata about the chart, such as the name, version, and description. A full example can be found here.

Many fields of the Chart.yaml file are optional, but our recommendation is to fill in at least the following optional fields:

  • kubeVersion: The Kubernetes version the chart is compatible with. Having this field helps users understand which Kubernetes versions the chart supports.
  • description: A short description of the chart. This field helps users understand what the chart does.
  • type: See Chart Types for more information.
  • home and sources: URLs to the project home and source code, respectively. These fields help users find more information about the chart.
  • dependencies: A list of charts this chart depends on. This field helps users understand what other charts are required to use this chart.
  • appVersion: The version of the app that this chart installs. This field tells us which version of the application the chart installs by default, if not specified in the values.yaml file.

Naming of Resources

Our recommendation for naming of resources in Helm charts is the following:

  • metadata.name: The name of the resource should be the same as the release name. This ensures that the resource name is unique and easy to identify.

In case of multiple of the same resource, a postfix should be added to the resource name. Eg: if you have multiple services, the name should be {{ .Release.Name }}-{{ .Values.serviceName }}. Eg: my-awesome-chart-api, my-awesome-chart-frontend.

Additional Labels & Annotations

Adding labels should be done through the values.yaml file. This allows users to add more labels as needed. For example:

additionalLabels:
  company: my-awesome-company
  additionalLabel: additionalValue

Including these labels in the resources is done by using the {{ .Values.labels }} template. For example:

metadata:
  labels:
    {{- include "my-awesome-chart.labels" . | nindent 4 }} # Include labels from helpers.tpl
    {{- toYaml .Values.additionalLabels | nindent 4 }} # Include additional labels from values.yaml

The same approach can be used for annotations.

Giving Options

Helm charts should be written in an environment agnostic way (To allow deployment on different cloud providers, on-prem, etc.). It is recommended to provide options in the values.yaml file and using Flow Control in the resources themselves. For example, exposing your application through a LoadBalancer service in a cloud provider, but using a NodePort service in an on-prem environment.

service:
  type: LoadBalancer # NodePort, LoadBalancer...
  port: 80
  targetPort: 80
  nodePort: null
apiVersion: v1
kind: Service
metadata:
  name: {{ include "my-awesome-chart.fullname" . }}
  ...
spec:
  type: {{ .Values.service.type }}
  ports:
    - port: {{ .Values.service.port }}
      targetPort: {{ .Values.service.targetPort }}
{{- if and (eq .Values.service.type "NodePort") (ne .Values.service.nodePort null) }}
      nodePort: {{ .Values.service.nodePort }}
{{- end }}
      protocol: TCP
  ...

Using helpers.tpl

helpers.tpl is a file that contains defined templates that are globally accessible in your chart. Our general recommendation is to not put too much logic in the helpers.tpl file, as it can make the chart harder to understand. Instead, the already generated templates in the helpers.tpl file should be used as much as possible.

Using NOTES.txt

We reccomend using the NOTES.txt file to provide information to the user after the chart is installed. This file should contain information about how to access the application, how to configure it, etc. A good example is auto-generated when using helm create.

NOTES.txt file is optional, but it is a good practice to include it in your chart.

Conclusion

Helm simplifies managing Kubernetes applications by providing powerful commands and an easy-to-use interface. By following this guide, you should be able to install, use, create Helm charts and interact with Helm efficiently. For more information and advanced usage, refer to the official Helm documentation.

Last updated on
Logging