Mastering Helm: The Essential Guide to Kubernetes Package Management

Revision	Date	Description
`1.0`	24.07.2024	Init Changelog

Introduction to Helm

Helm is a package manager for Kubernetes, an open-source system for automating the deployment, scaling, and management of containerized applications. Helm streamlines the process of managing complex applications and services on Kubernetes by using “charts”, which are pre-configured packages of Kubernetes resources.

By using Helm, administrators and developers can easily deploy, upgrade, and manage applications on Kubernetes clusters, ensuring consistent and reproducible deployments.

Here you have some useful informations about Helm:

Benefits of using Helm in Kubernetes environments

Simplified Deployments
Helm abstracts the complexity of Kubernetes resource management, making it easier to deploy and manage applications.
Version Control
Helm charts and releases are versioned, providing a clear history of changes and the ability to roll back to previous versions.
Reusability and Shareability
Helm charts can be shared and reused across different projects and teams, promoting consistency and efficiency.
Customizability
Users can override chart values to customize deployments, making Helm suitable for a wide range of environments and requirements.

Use Cases

Application Deployment
Simplifies deploying complex applications with multiple Kubernetes resources.
Configuration Management
Allows easy management of configuration changes and rollbacks.
CI/CD Integration
Integrates with CI/CD pipelines to automate deployments and updates.

Key Concepts and Terminology

Here are some key features and components of Helm.

Charts

Charts are Helm's packaging format, consisting of a collection of files that describe Kubernetes resources. Each chart can define:

Deployments
Services
ConfigMaps
Ingress rules
Any other Kubernetes object

Repositories

Charts are stored in repositories, which are locations where packaged charts can be shared and versioned. Public repositories, like the Artifact Hub, offer a wide variety of pre-packaged charts for common applications, while private repositories can be used for proprietary or custom charts.

Releases

When you deploy a chart using Helm, it creates a “release”, which is a specific instance of a chart running in a Kubernetes cluster. Each release can be managed independently, allowing for versioned updates and rollbacks.

Templates

Helm charts use templates to generate Kubernetes manifests dynamically. This allows users to customize their deployments by supplying configuration values, enabling the same chart to be reused across different environments and use cases.

Helm CLI

The Helm command-line interface (CLI) provides commands to manage charts and releases. Common commands include:

helm install: Deploys a chart to the cluster.
helm template: Outputs YAML manifests based on templates.
helm upgrade: Updates a release to a new chart version or configuration.
helm rollback: Rolls back a release to a previous version.
helm list: Lists all releases in the cluster.
helm repo add/update: Manages chart repositories.

Setting up Helm

Prerequisites

To effectively use Helm, you should have:

basic understanding of Kubernetes architecture (Pods, Deployments, Services, etc.) and concepts (rolling updates, scaling, storage).
installed Kubernetes cluster and kubectl.

Installing Helm

The Helm project provides two ways to fetch and install Helm. These are the official methods to get Helm releases. In addition to that, the Helm community provides methods to install Helm through different package managers. Installation through those methods can be found below the official methods.

From the Binary Releases

Every release of Helm provides binary releases for a variety of OSes. These binary versions can be manually downloaded and installed.

Download your desired version
Unpack it (tar -zxvf helm-v3.0.0-linux-amd64.tar.gz)
Find the helm binary in the unpacked directory, and move it to its desired destination (mv linux-amd64/helm /usr/local/bin/helm)

From there, you should be able to run the client and add the stable repo: helm help.

From Script

Helm now has an installer script that will automatically grab the latest version of Helm and install it locally.

You can fetch that script, and then execute it locally. It's well documented so that you can read through it and understand what it is doing before you run it.

curl -fsSL -o get_helm.sh https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3
chmod 700 get_helm.sh
./get_helm.sh

Yes, you can curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash if you want to live on the edge.

Through Package Managers

The Helm community provides the ability to install Helm through operating system package managers. These are not supported by the Helm project and are not considered trusted 3rd parties.

From Homebrew (macOS)

Members of the Helm community have contributed a Helm formula build to Homebrew. This formula is generally up to date.

brew install helm

From Chocolatey (Windows)

Members of the Helm community have contributed a Helm package build to Chocolatey. This package is generally up to date.

choco install kubernetes-helm

From Scoop (Windows)

Members of the Helm community have contributed a Helm package build to Scoop. This package is generally up to date.

scoop install helm

From Winget (Windows)

Members of the Helm community have contributed a Helm package build to Winget. This package is generally up to date.

winget install Helm.Helm

From Apt (Debian/Ubuntu)

Members of the Helm community have contributed a Helm package for Apt. This package is generally up to date.

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

From dnf/yum (fedora)

Since Fedora 35, helm is available on the official repository. You can install helm with invoking:

sudo dnf install helm

From Snap

The Snapcrafters community maintains the Snap version of the Helm package:

sudo snap install helm --classic

From pkg (FreeBSD)

Members of the FreeBSD community have contributed a Helm package build to the FreeBSD Ports Collection. This package is generally up to date.

pkg install helm

Understanding Helm Charts

A Helm chart is a package of pre-configured Kubernetes resources. It allows users to define, install, and manage applications on Kubernetes. Helm charts simplify the deployment and management of applications by bundling multiple Kubernetes manifests into a single cohesive package.

Structure of a Helm Chart

A Helm chart has a specific directory structure that organizes its components and makes it easy to manage and understand. Here is a typical directory layout of a Helm chart:

my-chart/
├── Chart.yaml
├── README.md
├── charts
├── templates
│ ├── NOTES.txt
│ ├── _helpers.tpl
│ ├── deployment.yaml
│ ├── hpa.yaml
│ ├── ingress.yaml
│ ├── service.yaml
│ ├── serviceaccount.yaml
│ └── tests
│     └── test-connection.yaml
└── values.yaml

Detailed description:

Chart.yaml
- This is the main descriptor file for the Helm chart. It contains metadata about the chart, such as its name, version, description, and maintainers.
- Example content od Chart.yaml:
apiVersion: v2 name: my-chart description: A Helm chart for Kubernetes version: 0.1.0 appVersion: 1.16.0
README.md
- This file provides documentation about the chart. It typically includes instructions on how to install, configure, and use the chart, along with any other relevant information.
charts/ (optional)
- This directory is used to store chart dependencies. If your chart depends on other charts, you can place those charts here.
- Alternatively, dependencies can be specified in the Chart.yaml.
templates/
- This directory contains Kubernetes manifest templates. These templates are written in YAML and utilize the Go templating language to generate Kubernetes resource definitions dynamically.
- Common files in the templates/ directory (all files are optional, but you should create some Kubernetes resources for your chart):
  - *.yaml: Defines the Kubernetes resource.
  - _*.tpl: Contains helper template functions that can be used throughout other template files.
  - NOTES.txt: Provides post-installation information or instructions to the user.
  - tests/: Contains YAML manifests (templated) for resources used by Helm to verify that the chart has been deployed correctly.
values.yaml
- This file contains the default configuration values for the chart. Users can override these values during installation to customize the deployment.
- Example content of values.yaml:
replicaCount: 3 image: repository: nginx tag: stable pullPolicy: IfNotPresent service: type: ClusterIP port: 80

This directory layout helps you organize your Kubernetes resources in a way that makes them reusable, configurable, and easier to manage.

Creating Your First Helm Chart

Creating a simple Helm chart involves several steps, from setting up the chart structure to defining the necessary Kubernetes resources. Here’s a step-by-step guide to help you create a basic Helm chart.

Step 1: Create a New Helm Chart

Use the helm create command to scaffold a new Helm chart. This command generates a basic directory structure with some default files.

helm create my-chart

This will create a directory named my-chart with the following structure:

my-chart/
├── Chart.yaml
├── README.md
├── charts
├── templates
│   ├── NOTES.txt
│   ├── _helpers.tpl
│   ├── deployment.yaml
│   ├── hpa.yaml
│   ├── ingress.yaml
│   ├── service.yaml
│   ├── serviceaccount.yaml
│   └── tests
│       └── test-connection.yaml
└── values.yaml

Step 2: Customize Chart Metadata

Open Chart.yaml and update the metadata to match your application:

apiVersion: v2
name: my-chart
description: A Helm chart for simple Kubernetes application
version: 0.1.0
appVersion: 1.0.0

Step 3: Define Your Application’s Values

Edit values.yaml to set the default values for your application. These values can be overridden during installation:

replicaCount: 2

image:
  repository: nginx
  tag: stable
  pullPolicy: IfNotPresent
  
service:
  type: ClusterIP
  port: 80

ingress:
  enabled: false
  className: ""
  annotations: {}
  hosts:
    - host: chart-example.local
      paths:
        - path: /
          pathType: ImplementationSpecific
  tls: []

resources: {}

nodeSelector: {}

tolerations: []

affinity: {}

Step 4: Customize Kubernetes Manifests

Open and edit the templates in the templates/ directory to define your Kubernetes resources. For simple example, we’ll focus on deployment.yaml and service.yaml.

templates/deployment.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: {{ .Release.Name }}-deployment
spec:
  replicas: {{ .Values.replicaCount }}
  selector:
    matchLabels:
      app: {{ .Release.Name }}
  template:
    metadata:
      labels:
        app: {{ .Release.Name }}
    spec:
      containers:
        - name: {{ .Chart.Name }}
          image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"
          imagePullPolicy: {{ .Values.image.pullPolicy }}
          ports:
            - containerPort: {{ .Values.service.port }}

templates/service.yaml

apiVersion: v1
kind: Service
metadata:
name: {{ .Release.Name }}-service
spec:
type: {{ .Values.service.type }}
ports:
- port: {{ .Values.service.port }}
  targetPort: {{ .Values.service.port }}
  selector:
  app: {{ .Release.Name }}

Step 5: Package and Deploy the Chart

Use helm package command to package your chart into a .tgz file.

helm package my-chart

This will create a file like my-chart-0.1.0.tgz.

Next, use the helm install command to deploy your chart to a Kubernetes cluster.

helm install my-release my-chart/

Replace my-relese with desired release name.

Step 6: Verify the Deployment

Check the status of your deployment using kubectl:

kubectl get deployments
kubectl get pods
kubectl get services

You should see the resources defined in your Helm chart running in your cluster.

Step 7: Customize and Upgrade

To update your deployment, modify the chart files as needed and then use helm upgrade command:

helm upgrade my-release my-chart/

Step 8: Clean Up

To delete the deployed resources, use the helm uninstall command:

helm uninstall my-release

Using Pre-existing Charts

Using pre-existing Helm charts is a common and efficient way to deploy applications to Kubernetes without having to write all the manifests yourself. Many popular tool providers offer their own Helm charts to simplify the deployment of their applications on Kubernetes. These Helm charts are maintained either by the providers themselves or by the community.

Manage local repositories

Adding a Helm Repository

To use a Helm chart, you first need to add the repository where the chart is hosted. Here's how you do it:

Find the URL of the Helm repository you want to add.
Use helm repo add command to add the repository to your local Helm setup. The command format is:

helm repo add <repo-name> <repo-url>

For example, to add the Bitnami repository:

helm repo add bitnami https://charts.bitnami.com/bitnami

Updating Helm Repositories

After adding repositories, it’s important to update your local cache to get the latest list of charts and versions available in those repositories.

Use the helm repo update command to refresh the information from all added repositories:

helm repo update

This command fetches the latest information from each repository and updates your local Helm client.

Listing Added Repositories

You can list all the repositories you have added with:

helm repo list

This command displays a table with the repository names and their URLs.

Searching for Charts

You can search for charts within the added repositories to see what’s available:

helm search repo <keyword>

For example, to search for all charts related to Grafana:

helm search repo grafana

This command lists all charts related to Grafana from the added repositories.

Using Charts from Added Repositories

After adding and updating repositories, you can install charts from them. For example, to install Grafana:

helm install my-grafana grafana/grafana

Or to install a Bitnami Redis chart:

helm install my-redis bitnami/redis

Finding and using charts from the Artifact Hub

Artifact Hub is a web-based application that helps users find, install, and publish packages and configurations for various tools and projects, including Helm charts. Here's a step-by-step guide on how to find and use Helm charts from Artifact Hub:

Open your web browser and go to Artifact Hub.
Use the search bar at top of the page to enter keywords related to the Helm chart you are looking for (e.g., “Grafana”, “Redis”, “PostgreSQL”).
Browse the search results to find the Helm chart that best fits your needs.
Click on the Helm chart you are interested in to view its details page.
On the details page you will find information such as:
- Overview of the chart
- Installation instructions
- Available versions
- Values you can configure
- Maintainers and source code links
To use this Helm chart, follow the installation instructions.

Customizing Helm CHarts

Customizing Helm charts allows you to tailor the deployment of applications to fit your specific requirements.

Values

There are several ways to customize Helm charts, primarily through the use of values.yaml files and the --set command-line option.

When you pass custom values into a Helm chart, Helm merges these custom values with the default values provided by the chart. This merging process follows a specific order and set of rules to ensure that your custom configurations override the defaults appropriately.

Using `values.yaml` File

Every Helm chart comes with a default values.yaml file that contains default configurations for the chart. You can create your own values.yaml file to override these defaults.

Example `values.yaml`

For instance, consider a custom values.yaml for a MySQL chart:

mysqlRootPassword: "rootpassword"
mysqlUser: "myuser"
mysqlPassword: "userpassword"
mysqlDatabase: "mydatabase"
replicaCount: 2

Installing with Custom `values.yaml`

You can then use this values.yaml during installation:

helm install my-mysql -f custom-values.yaml bitnami/mysql

This command tells Helm to use your custom values.yaml instead of the default values provided by the chart.

Using `--set` Command-Line Option

For smaller changes or quick adjustments, you can override values directly from the command line using the --set flag.

Example Usage

helm install my-mysql bitnami/mysql --set mysqlRootPassword=rootpassword,mysqlUser=myuser,mysqlPassword=userpassword,mysqlDatabase=mydatabase,replicaCount=2

This command sets the same values as the custom values.yaml file before, but does so directly from the command line.

Customizing Nested Values

For charts with nested values, you can override specific nested keys using the dot notation in the --set flag. For example:

helm install my-application bitnami/application --set service.type=LoadBalancer --set resources.limits.cpu=200m

Combining Multiple Methods

You can combine multiple customization methods. For example, use a values.yaml file for most configurations and the --set flag for specific overrides:

helm install my-mysql -f custom-values.yaml --set mysqlRootPassword=anotherpassword bitnami/mysql

Values Merging Process

Helm merges your custom values with the default values.
If custom value is provided for a key that exists in the default values, the custom value overrides the default.
If a custom value is provided for a key that exists in the default values, the custom value overrides the default.
If custom value is provided for a key that does not exist in default values, it is added to the final configuration.

Order of Precedence

The precedence of values is as follows, from lowest to highest:

Chart’s values.yaml: Default values specified in the chart.
Values specified with -f or --values: Custom values provided via one or more files.
Values specified with --set: Custom values provided directly via the command line.

Viewing Effective Configuration

To see what the final configuration will look like after all customizations, you can use the helm get values command on an installed release:

helm get values my-mysql

To see all values, including default values, use:

helm get values my-mysql --all

Updating a Release with New Values

To update an existing release with new values, use the helm upgrade command with the new values.yaml or --set options.

Exammple

helm upgrade my-webapp -f new-values.yaml bitnami/webapp

helm upgrade my-webapp bitnami/webapp --set replicaCount=4

Template Functions and Helpers

Writing and using templates in Helm charts is a powerful way to define, deploy, and manage Kubernetes resources. Helm uses Go templates to dynamically generate Kubernetes manifest files. Here’s a comprehensive guide on how to write and use templates in Helm charts.

Basic Template Syntax

Helm template use Go templating language. Here are some basic templating constructs:

Variable: Defined using {{ .VariableName }}.
Conditional Statements: Using {{ if }}, {{ else }}, and {{ end }}.
Loops: Using {{ range }} and {{ end }}.
Functions: Using built-in and custom functions.

Scopes

In Helm charts, scopes define the context in which templates and values are rendered and accessed. Understanding scopes helps you manage how data is passed and used within templates. Here’s a detailed overview of the different scopes and their usage in Helm charts.

Global scope

The global scope is accessible throughout the entire chart, including subcharts. Values defined under the global key in values.yaml can be shared across different parts of the chart and its dependencies.

Example `values.yaml`

global:
  image:
    repository: myrepo/nginx
    tag: 1.17.1

Accessing Global Values

# templates/deployment.yaml
spec:
  containers:
    - name: nginx
      image: "{{ .Values.global.image.repository }}:{{ .Values.global.image.tag }}"

Local scope

Local scope refers to values and variables that are accessible only within a specific context, such as a template or a loop within a template.

Example with Local scope

# templates/deployment.yaml
{{- range $index, $container := .Values.containers }}
- name: {{ $container.name }}
  image: {{ $container.image }}
{{- end }}

Here, $index and $container are locally scoped variables available only within the range loop.

Template scope

Templates defined in _helpers.tpl or other template files can have their own scope, which can be customized using the define keyword.

Example `_helpers.tpl`

{{- define "mychart.fullname" -}}
{{- printf "%s-%s" .Release.Name .Chart.Name | trunc 63 | trimSuffix "-" -}}
{{- end -}}

You cat then use this helper in other templates, passing the current scope (.) to id:

metadata:
  name: {{ include "mychart.fullname" . }}

Subchart scope

Subcharts have their own scope and values but can access global values from the parent chart. Subcharts are defined in the charts/ directory.

Example of a Subchart Values

Parent values.yaml

global:
  database:
    user: admin
    password: secret

mysql:
  rootPassword: rootpassword

Subchart values.yaml (e.g., charts/mysql/values.yaml):

image:
  repository: mysql
  tag: 5.7

The subchart can access the global scope:

# charts/mysql/templates/deployment.yaml
env:
  - name: MYSQL_ROOT_PASSWORD
    value: "{{ .Values.rootPassword }}"
  - name: DATABASE_USER
    value: "{{ .Values.global.database.user }}"
  - name: DATABASE_PASSWORD
    value: "{{ .Values.global.database.password }}"

Built-in Objects

Helm provides several built-in objects that are available in the scope of templates:

Release: Information about the release (e.g., Release.Name, Release.Namespace).
Values: The values passed into the chart.
Chart: Metadata about the chart (e.g., Chart.Name, Chart.Version).
Files: Access to non-template files in the chart (e.g., Files.Get to get file contents).
Capabilities: Information about the Kubernetes cluster’s capabilities.
Template: Information about the current template being rendered.

Example of Using Built-in Objects

# templates/deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: {{ .Release.Name }}-{{ .Chart.Name }}
  labels:
    app: {{ .Release.Name }}
spec:
  replicas: {{ .Values.replicaCount }}
  selector:
    matchLabels:
      app: {{ .Release.Name }}
  template:
    metadata:
      labels:
        app: {{ .Release.Name }}
    spec:
      containers:
        - name: {{ .Chart.Name }}
          image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"
          ports:
            - containerPort: {{ .Values.service.port }}
          env:
            - name: RELEASE_NAME
              value: {{ .Release.Name }}
            - name: NAMESPACE
              value: {{ .Release.Namespace }}

Conditional Logic and Loops

Example with Conditionals

{{- if .Values.service.enabled }}
apiVersion: v1
kind: Service
metadata:
  name: {{ .Release.Name }}-{{ .Chart.Name }}
  labels:
    app: {{ .Release.Name }}
spec:
  type: {{ .Values.service.type }}
  ports:
    - port: {{ .Values.service.port }}
      targetPort: {{ .Values.service.port }}
  selector:
    app: {{ .Release.Name }}
{{- end }}

Example with Loops

spec:
  containers:
    {{- range .Values.containers }}
    - name: {{ .name }}
      image: {{ .image }}
      ports:
        - containerPort: {{ .port }}
    {{- end }}

Debbuging Templates

To debug templates, you can render them locally without deploying using helm template command:

helm template my-release ./my-chart

This command shows the rendered Kubernetes manifests using your chart templates and values.

Helm Best Practices

Helm is a powerful tool for managing Kubernetes applications, but to use it effectively, it’s essential to follow best practices. Here are some Helm best practices to ensure smooth deployments, maintainable charts, and efficient management of your Kubernetes resources:

Organize Your Helm Chart Structure

Follow Helm’s Standard Directory Structure
Adhere to Helm’s recommended directory structure to keep your charts organized and easily understandable by others.
Separate Chart Logic
Divide your chart into smaller templates and use separate files for different Kubernetes resources like deployments, services, and ingresses.

Define Clear Chart Metadata

Chart.yaml
Provide clear and descriptive metadata in your Chart.yaml file, including the chart name, version, description, and maintainers.

Use `values.yaml` for Configurations

Separate Configuration from Code
Store configurable values in values.yaml to separate configuration from chart logic, making it easier to manage and customize deployments.
Document Values
Document the purpose and usage of each value in values.yaml to provide guidance for users and maintainers.

Provide Useful README Documentation

README.md
Include comprehensive documentation in your README.md file, covering installation instructions, configuration options, and troubleshooting tips.

Use Version Control

Git Repositories
Store your Helm charts in version-controlled Git repositories to track changes, collaborate within others, and facilitate code reviews.

Version Your Charts

Semantic Versioning
Follow semantic versioning principles for your charts to communicate compatibility and changes effectively.
Release Notes
Document significant changes and enhancements in your chart’s release notes to keep users informed about updates.

Validate Chart Syntax

Lint Charts
Use Helm’s built-in linter (helm lint) to validate your chart syntax and catch errors before deploying to Kubernetes.

Use Dependencies Wisely

Subcharts
Use subcharts and dependencies to modularize your charts and manage complex application stacks effectively.
Dependency Management
Keep dependencies up-to-date and avoid using deprecated or unmaintained charts.

Security

Image Security
Use trusted container images from reputable sources and regularly scan images for vulnerabilities.
Secret Management
Store sensitive information like passwords and API keys securely using Kubernetes secrets.

Test Your Charts

Unit Tests
Write unit tests for your Helm charts to validate template syntax, configuration values, and resource generation.
Integration Tests
Test your charts in a real Kubernetes environment to ensure proper functionality and compatibility.

Continous Integration/Continous Deployment (CI/CD)

Automate Deployment Pipelines
Implement CI/CD pipelines to automat chart testing, linting, packaging, and deployment processes.

Monitor and Maintain Charts

Monitor CHart Health
Regularly monitor your Helm charts for vulnerabilities, performance issues, and compatibility with Kubernetes updates.
Community Involvement
Participate in the Helm community, share best practices, contribute to open-source projects, and seek assistance when needed.

Debbuging Charts

Debugging Helm charts is essential for identifying and resolving issues during chart development and deployment. Here are some strategies and tools for debugging Helm charts effectively:

Verify Chart Syntax

Use the helm lint command to validate the syntax of your chart files and catch any errors or warnings.

helm lint my-chart

Dry Run installation

Perform a dry run installation (--dry-run) to simulate the installation process without actually deploying resources to the Kubernetes cluster. This helps identify potential issues before applying changes.

helm install my-release ./my-chart --dry-run

Generate Manifests

Use the helm template command to render Helm templates into Kubernetes manifests without deploying them. This allows you to inspect the generated YAML files for correctness.

helm template my-release ./my-chart

View Rendered Templates

Inspect the rendered templates to ensure that values are substituted correctly and that the resulting YAML files match your expectations.

helm get manifest my-release

Helm Debug Mode

Enable Helm's debug mode (--debug) during installation to print detailed debugging information, including the generated templates and rendered values.

helm install my-release ./my-chart --debug

Debugging Templates

Add debug statements within your template files ({{ printf "Debug: %s" .Values.someValue }}) to output specific values for debugging purposes.

Logging and Events

Check the Kubernetes events and logs for your Helm releases and pods to identify any issues or errors during deployment.

kubectl get events
kubectl logs <pod-name>

Use Helm Plugins

Consider using Helm plugins like helm-secrets for managing encrypted secrets or helm-diff for comparing release manifests before and after changes.

Community Support and Resources

Leverage online forums, community channels, and documentation to seek assistance and troubleshoot specific issues encountered during chart development and deployment.

Advanced Helm Features

Helm Hooks

Helm hooks provide a way to execute custom actions at various points in the release lifecycle of a Helm chart. These hooks allow you to run jobs or scripts before or after events like installation, upgrade, or deletion of Helm releases. This capability is useful for tasks such as data migrations, cleanup, or any custom initialization.

Helm Hook Points

Here are the common hook points where you can attach your hooks:

pre-install: Before any resources are installed.
post-install: After all resources are installed.
pre-delete: Before any resources are deleted.
post-delete: After all resources are deleted.
pre-upgrade: Before any resources are upgraded.
post-upgrade: After all resources are upgraded.
pre-rollback: Before any resources are rolled back.
post-rollback: After all resources are rolled back.
test: During helm test.

Defining Helm Hooks

Helm hooks are defined by adding annotations to your Kubernetes resource definitions in your Helm templates. The annotation key is helm.sh/hook and the value is one of the hook points.

Example of a Pre-Install Hook

Here is an example of a Kubernetes Job that runs before the Helm chart is installed:

apiVersion: batch/v1
kind: Job
metadata:
  name: "{{ .Release.Name }}-pre-install-job"
  annotations:
    "helm.sh/hook": pre-install
    "helm.sh/hook-delete-policy": hook-succeeded
spec:
  template:
    spec:
      containers:
      - name: pre-install-job
        image: busybox
        command: ['sh', '-c', 'echo Hello from the pre-install hook!']
      restartPolicy: Never

Hook Delete Policies

Hook delete policies determine when Helm should delete the hook resources. Here are the available policies:

hook-succeeded: Delete the resource if the hook is successful.
hook-failed: Delete the resource if the hook fails.
before-hook-creation: Delete the previous resource before creating a new one.
hook-succeeded,hook-failed: Delete the resource regardless of the outcome.

Example with Hook Delete Policy

metadata:
  annotations:
    "helm.sh/hook": pre-install
    "helm.sh/hook-delete-policy": before-hook-creation,hook-succeeded

Running Tests with Hooks

Helm Supports defining tests for your chart using the test hook. These tests are run using the helm tests command.

Example of a Test Hook

apiVersion: v1
kind: Pod
metadata:
  name: "{{ .Release.Name }}-test-connection"
  annotations:
    "helm.sh/hook": test
spec:
  containers:
  - name: test
    image: busybox
    command: ['sh', '-c', 'echo Testing connection...']
  restartPolicy: Never

Summary

Helm hooks are powerful tools for managing the lifecycle of your Helm releases. They enable you to perform custom tasks at various stages of the deployment process, such as running migrations, performing cleanup, or initializing resources. By leveraging hooks, you can ensure that your Helm-managed applications are set up correctly and maintain operational integrity throughout their lifecycle.

Helm Plugins

Helm plugins extend the functionality of Helm by adding new commands or enhancing existing ones. They are written in any language and can be distributed and installed via Git repositories or Helm plugin repositories.

Commonly Used Helm Plugins

Here are some popular Helm plugins that provide additional capabilities:

helm-diff

Purpose

Compares the difference between the current state of a release and a prospective revision.

Source

GitHub Repository

Installation

helm plugin install https://github.com/databus23/helm-diff

Usage

helm diff upgrade my-release ./my-chart

helm-secrets

Purpose

Manages secrets securely using tools like Sops and GPG.

Source

GitHub Repository

Installation

helm plugin install https://github.com/jkroepke/helm-secrets

Usage

helm secrets enc values.yaml
helm secrets dec values.yaml
helm secrets install my-release ./my-chart

helm-unittest

Purpose

Adds unit testing capability for Helm charts.

Source

GitHub Repository

Installation

helm plugin install https://github.com/quintush/helm-unittest

Usage

helm unittest ./my-chart

Managing Helm Plugins

Installing a Plugin

To install a Helm plugin, use the helm plugin install command followed by the plugin repository URL.

helm plugin install <plugin-repo-url>

Listing Installed Plugins

To list all installed plugins, use the helm plugin list command.

helm plugin list

Update a Plugin

To update an installed plugin, use the helm plugin update command followed by the plugin name.

helm plugin update <plugin-name>

Removing a Plugin

To remove an installed plugin, use the helm plugin uninstall command followed by the plugin name.

helm plugin uninstall <plugin-name>

Developing Custom Helm Plugins

If you need functionality that isn’t provided by existing plugins, you can create your own Helm plugin.

Plugin Directory Structure

A typical Helm plugin directory structure looks like this:

my-plugin/
├── plugin.yaml
├── bin/
│   └── my-plugin
└── README.md

`plugin.yaml`

The plugin.yaml file defines the plugin’s metadata and commands.

name: "my-plugin"
version: "0.1.0"
usage: "A Helm plugin for ..."
description: "A detailed description of what the plugin does."
command: "$HELM_PLUGIN_DIR/bin/my-plugin"

Plugin Script

The script in the bin/ directory (e.g., my-plugin) contains the logic of your plugin. It can be a shell script, Go binary, Python script, etc.

Example (Bash script)

#!/bin/bash
echo "Hello from my Helm plugin!"

Installing a Custom Plugin

To install your custom plugin, navigate to the directory containing your plugin and use:

helm plugin install ./my-plugin

helm-docs

helm-docs is a standalone tool designed to automatically generate documentation for Helm charts. It helms ensure that the documentation for Helm charts is consistent, up-to-date, and easily maintainable. The generated documentation typically includes details about the chart’s configuration options, default values, and usage instructions.

Key Features of helm-docs

Automatic Documentation Generation: Generates README.md files for Helm charts based on the chart's metadata and configuration files.
Extracts Information: Pulls data from Chart.yaml, values.yaml, and other relevant files to create comprehensive documentation.
Customizable Templates: Allows the use of custom templates to format the generated documentation according to specific requirements.
Consistent Documentation: Ensures that the documentation format remains consistent across multiple charts.
Easy Integration: Can be integrated into CI/CD pipelines to automate the documentation process.

Installation

Via Homebrew (macOS and Linux)

If you're using macOS or Linux, you can install helm-docs using Homebrew:

brew install norwoodj/tap/helm-docs

Via Downloading Binaries

Go to the helm-docs releases page.
Download the appropriate binary for your operating system.
Extract the binary and move it to a directory in your PATH (e.g. /usr/local/bin).

For example, on a Unix-like system:

wget https://github.com/norwoodj/helm-docs/releases/download/v1.5.0/helm-docs_1.5.0_linux_amd64.tar.gz
tar -zxvf helm-docs_1.5.0_linux_amd64.tar.gz
sudo mv helm-docs /usr/local/bin/

Via Go

If you have Go installed, you can install helm-docs using the following command:

go install github.com/norwoodj/helm-docs/cmd/helm-docs@latest

Usage

Once helm-docs is installed, you can generate documentation for your Helm chart by navigating to the root directory of your chart and running:

helm-docs

This command will create or update the README.md file in the chart's directory with the relevant documentation.

Example of Generated Documentation

Here’s an example of what the generated README.md might look like:

# My Helm Chart
This is a Helm chart for deploying MyApp.
## Values
| Key          | Description                                | Default     |
|--------------|--------------------------------------------|-------------|
| replicaCount | Number of replicas for the deployment      | `1`         |
| image.tag    | The tag of the Docker image to deploy      | `latest`    |
| service.type | The type of the Kubernetes service to use  | `ClusterIP` |

Pre-commit

Pre-commit hooks are useful for automating checks and ensuring code quality before changes are committed to the repository. For Helm, you can set up pre-commit hooks to perform tasks such as linting Helm charts, validating YAML files, and generating documentation with helm-docs.

Step 1: Install Pre-commit

First, you need to install the pre-commit tool:

pip install pre-commit

brew install pre-commit

Step 2: Create a Pre-commit configuration file

Create a .pre-commit-config.yaml file in the root of your repository. This file will define the hooks that should run before each commit.

repos:
- repo: https://github.com/pre-commit/pre-commit-hooks
  rev: v4.3.0
  hooks:
  - id: check-yaml
  - id: end-of-file-fixer
  - id: trailing-whitespace
- repo: https://github.com/karancode/helm-pre-commit
  rev: v0.1.2
  hooks:
  - id: helm-lint
- repo: local
  hooks:
  - id: helm-docs
    name: helm-docs
    entry: helm-docs
    language: system
    files: ^charts/
    stages: [pre-commit, manual]

Step 3: Configure Hooks

In the .pre-commit-config.yaml file, configure the necessary hooks:

YAML validation hooks from pre-commit-hooks:
- check-yaml: Ensures YAML files are valid.
- end-of-file-fixer: Ensures files end with a newline.
- trailing-whitespace: Removes trailing whitespace.
Helm lint hook:
- From karancode/helm-pre-commit, this hook will lint your Helm charts using helm lint.
Helm-docs hook:
- A local hook to generate documentation using helm-docs.

Step 4: Install the Pre-commit Hooks

Run the following command to install the pre-commit hooks defined in your configuration file:

pre-commit install

Step 5: Running Pre-commit Hooks Manually

Manually run the pre-commit hooks on all files to allow it download all dependencies.

pre-commit run --all-files

CI/CD Integrations

Integrating Helm into your CI/CD pipeline can automate the process of deploying and managing applications on Kubernetes. Below are some examples of how to integrate Helm with Gitlab CI/CD.

Lint

.gitlab-ci.yml

stages:
- lint

lint:
  stage: lint
  image: alpine/helm:3.5.2
  script:
  - helm lint ./my-chart

Build

.gitlab-ci.yml

stages:
- build

build:
  stage: build
  image: alpine/helm:3.5.2
  variables:
  script:
  - helm package ./my-chart
  artifacts:
    paths:
    - $CI_COMMIT_TAG
    expire_in: 1 day

Upload to Gitlab Package Registry

.gitlab-ci.yml

stages:
- upload

upload:
  stage: upload
  image: curimages/curl:latest
  script:
  - 'curl --request POST --user gitlab-ci-token:$CI_JOB_TOKEN --form "chart=@${CI_COMMIT_TAG}.tgz" "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/helm/api/stable/charts"'

Last modified: 17 February 2025

Mastering Helm: The Essential Guide to Kubernetes Package Management

Introduction to Helm

Benefits of using Helm in Kubernetes environments

Use Cases

Key Concepts and Terminology

Charts

Repositories

Releases

Templates

Helm CLI

Setting up Helm

Prerequisites

Installing Helm

From the Binary Releases

From Script

Through Package Managers

From Homebrew (macOS)

From Chocolatey (Windows)

From Scoop (Windows)

From Winget (Windows)

From Apt (Debian/Ubuntu)

From dnf/yum (fedora)

From Snap

From pkg (FreeBSD)

Understanding Helm Charts

Structure of a Helm Chart

Creating Your First Helm Chart

Step 1: Create a New Helm Chart

Step 2: Customize Chart Metadata

Step 3: Define Your Application’s Values

Step 4: Customize Kubernetes Manifests

Step 5: Package and Deploy the Chart

Step 6: Verify the Deployment

Step 7: Customize and Upgrade

Step 8: Clean Up

Using Pre-existing Charts

Manage local repositories

Adding a Helm Repository

Updating Helm Repositories

Listing Added Repositories

Searching for Charts

Using Charts from Added Repositories

Finding and using charts from the Artifact Hub

Customizing Helm CHarts

Values

Using values.yaml File

Example values.yaml

Installing with Custom values.yaml

Using --set Command-Line Option

Example Usage

Customizing Nested Values

Combining Multiple Methods

Values Merging Process

Order of Precedence

Viewing Effective Configuration

Updating a Release with New Values

Exammple

Template Functions and Helpers

Basic Template Syntax

Scopes

Global scope

Example values.yaml

Accessing Global Values

Local scope

Example with Local scope

Template scope

Example _helpers.tpl

Subchart scope

Example of a Subchart Values

Built-in Objects

Example of Using Built-in Objects

Conditional Logic and Loops

Example with Conditionals

Example with Loops

Debbuging Templates

Helm Best Practices

Organize Your Helm Chart Structure

Define Clear Chart Metadata

Use values.yaml for Configurations

Provide Useful README Documentation

Using `values.yaml` File

Example `values.yaml`

Installing with Custom `values.yaml`

Using `--set` Command-Line Option

Example `values.yaml`

Example `_helpers.tpl`

Use `values.yaml` for Configurations

`plugin.yaml`