Part 11: "The Helm of the Ship" — Helm, Kustomize, and Templating

Alex stared at the sea of YAML files, a sprawling digital metropolis of configuration that had grown beyond control. What had started as a handful of simple deployment and service files for NovaCraft’s flagship application had ballooned into a complex web of over fifty YAMLs. Each new feature, every minor environment tweak, added another layer to the configuration labyrinth. Alex, a seasoned engineer with a decade of experience in the more predictable world of virtual machines, felt a familiar headache brewing. The promise of Kubernetes was scalability and resilience, but right now, it felt like a chaotic, unmanageable beast.

“There has to be a better way,” Alex muttered, scrolling endlessly through a terminal window. A simple change, like updating a container image tag across all environments, required a tedious and error-prone process of finding and replacing the value in dozens of files. The risk of a typo bringing down an entire environment was terrifyingly high. It was clear that managing raw Kubernetes YAML files wasn’t a sustainable solution for a fast-growing startup like NovaCraft. The team needed a way to tame the configuration chaos, a way to introduce order and reusability into their deployment process. The ship was sailing, but it was time to take the helm.

The YAML Tsunami and the Need for a Captain

Alex’s predicament is a common one in the Kubernetes world. The very flexibility that makes Kubernetes so powerful—its declarative, API-driven nature, expressed in YAML—can also be its Achilles’ heel. As applications grow in complexity, so does the number of YAML files required to describe them. This is what we call “YAML sprawl,” and it leads to a host of problems:

• Duplication: The same boilerplate configuration is repeated across multiple files and environments.
• Inconsistency: Manual changes across environments are prone to errors and inconsistencies.
• Lack of Reusability: Sharing and reusing application configurations becomes a copy-paste nightmare.
• Complexity: It’s difficult to see the big picture of an application’s configuration when it’s spread across dozens of files.

To navigate these treacherous waters, the Kubernetes community has developed powerful tools to manage and template configurations. Two of the most popular are Helm and Kustomize. Think of them as the captain and first mate of your Kubernetes ship, each with a distinct but complementary role in steering your application deployments.

Helm: The Package Manager for Kubernetes

Imagine you’re building a complex piece of furniture, like a large bookshelf. You could buy all the individual screws, planks, and brackets yourself, and follow a long, complicated set of instructions. Or, you could buy a flat-pack kit from IKEA. The kit comes with everything you need, neatly packaged, with a clear set of instructions and a simple way to customize it (e.g., choosing the color of the shelves).

Helm is the IKEA of Kubernetes. It’s a package manager that bundles all the necessary Kubernetes resources for an application into a single, reusable package called a chart. A Helm chart is like a blueprint for your application, containing templates for all the required YAML files (deployments, services, configmaps, etc.).

Here are the core concepts of Helm:

• Chart: A collection of files that describe a related set of Kubernetes resources. It’s a package of pre-configured Kubernetes resources that can be managed as a single unit.
• Values: A set of customizable parameters that allow you to tailor a chart to your specific needs. This is how you can use the same chart to deploy an application to different environments (development, staging, production) with different configurations (e.g., different database URLs, replica counts, or resource limits).
• Release: An instance of a chart deployed to a Kubernetes cluster. When you install a chart, Helm creates a release, which is a record of that specific deployment. This allows you to track, upgrade, and roll back your application deployments with ease.

Kustomize: The kubectl-Native Approach

If Helm is the all-in-one package deal, Kustomize is the master craftsman’s toolkit. It’s a tool for customizing Kubernetes resources that is built directly into kubectl, the Kubernetes command-line interface. Kustomize takes a different approach to configuration management: instead of using templates, it uses a declarative, patch-based system.

Imagine you have a master blueprint for a house. You want to build two versions of the house: a standard model and a deluxe model with an extra bedroom and a larger kitchen. With Kustomize, you would start with the base blueprint and then create separate “patches” for the deluxe model. The patches would describe the differences between the standard and deluxe models, rather than redefining the entire house.

Here’s how Kustomize works:

• Base: A set of standard, off-the-shelf Kubernetes resources (YAML files).
• Overlays: A collection of patches and customizations that are applied to the base. Each overlay is specific to an environment (e.g., development, production).
• kustomization.yaml: A file that defines the resources to be included and the customizations to be applied.

Kustomize is powerful because it allows you to manage your configurations in a way that is both declarative and composable. You can start with a common base and then layer on environment-specific customizations, without duplicating code or using a complex templating language.

Under the Hood: How They Work

Let’s dive deeper into the technical workings of Helm and Kustomize to understand how they perform their magic.

Helm’s Architecture: Templates and a Tiller (in the old days)

Helm’s power lies in its templating engine, which is based on Go templates. When you install a chart, Helm’s templating engine reads the values.yaml file and uses it to generate the final Kubernetes YAML manifests. These manifests are then sent to the Kubernetes API server to create or update the resources.

A typical Helm chart has the following structure:

my-chart/
  Chart.yaml        # Metadata about the chart
  values.yaml       # Default configuration values
  templates/        # A directory of templates that, when combined with values, will generate valid Kubernetes manifest files.
    deployment.yaml
    service.yaml
    _helpers.tpl    # A place to put template helpers that you can re-use throughout your chart
  charts/           # A directory containing any charts upon which this chart depends.

The templates/ directory is the heart of the chart. It contains YAML files with embedded Go template directives. For example, a deployment.yaml template might look like this:

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

When you install this chart with helm install my-release ./my-chart --set replicaCount=3, Helm will replace {{ .Values.replicaCount }} with 3, {{ .Values.image.repository }} with the value from values.yaml, and so on, to generate the final YAML that is applied to the cluster.

It’s worth noting that older versions of Helm (Helm 2) used a server-side component called Tiller, which ran in your cluster. Helm 3, the current version, is Tiller-less, which simplifies the architecture and improves security by removing the need for a privileged component in the cluster.

Kustomize’s Architecture: Declarative Patches

Kustomize’s approach is fundamentally different. It doesn’t use a templating language. Instead, it works by applying declarative patches to a base set of YAML files. This makes it a “template-free” way to customize your application configuration.

The core of Kustomize is the kustomization.yaml file. This file tells Kustomize where to find the base resources and what patches to apply. A typical Kustomize project structure looks like this:

my-app/
  base/
    deployment.yaml
    service.yaml
    kustomization.yaml
  overlays/
    development/
      deployment-patch.yaml
      kustomization.yaml
    production/
      deployment-patch.yaml
      kustomization.yaml

The base/kustomization.yaml might look like this:

resources:
- deployment.yaml
- service.yaml

The overlays/production/kustomization.yaml would then reference the base and apply a patch:

bases:
- ../../base

patchesStrategicMerge:
- deployment-patch.yaml

And the deployment-patch.yaml would contain only the changes for the production environment:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
spec:
  replicas: 10

When you run kubectl apply -k overlays/production, kustomize will first load the base resources, then merge the patch to change the replica count to 10, and finally apply the resulting YAML to the cluster. This approach keeps the environment-specific configuration separate and concise, making it easier to manage and review.

Helm vs. Kustomize: The Grand Debate

So, which tool should you use? The answer, as is often the case in engineering, is “it depends.” Here’s a breakdown of their strengths and weaknesses to help you decide:

When to use Helm:

• You need to package and distribute your application for others to use. Helm is the de facto standard for this.
• You want to install complex, third-party applications like Prometheus, Grafana, or Jenkins. Most of these are available as pre-built Helm charts.
• You have a lot of configuration options and need the power of a full-fledged templating language.

When to use Kustomize:

• You want a simpler, template-free way to manage your application’s configuration.
• You prefer a kubectl-native workflow.
• Your configuration differences between environments are relatively small and can be expressed as patches.
• You want to keep your configuration in a Git repository and use a GitOps workflow.

Many teams find that Helm and Kustomize can be used together. For example, you might use Helm to install a third-party application and then use Kustomize to apply your own customizations on top of it. The key is to understand the strengths of each tool and choose the right one for the job.

Hands-On: Packaging the NovaCraft App with Helm

Now it’s time to put theory into practice. We’re going to take a simple version of the NovaCraft application, package it as a Helm chart, and deploy it to our local Kubernetes cluster with different configurations for development and production.

Prerequisites

Before we begin, make sure you have the following tools installed on your macOS machine:

• Docker Desktop: This will provide you with a local Kubernetes cluster and the docker and kubectl CLIs. Make sure to enable Kubernetes in the Docker Desktop settings.
• Helm: You can install Helm with Homebrew: brew install helm

Step 1: The NovaCraft Application

For this tutorial, our “NovaCraft” application will be a simple Python web server that displays a message. Let’s create a directory for our project:

mkdir novacraft-app
cd novacraft-app

Now, create a file named app.py with the following content:

from flask import Flask
import os

app = Flask(__name__)

@app.route('/')
def hello():
    env = os.environ.get('ENVIRONMENT', 'development')
    return f"<h1>Hello from NovaCraft!</h1><p>Environment: {env}</p>"

if __name__ == '__main__':
    app.run(host='0.0.0.0', port=80)

This is a simple Flask application that will display a message indicating the environment it’s running in. We’ll control this with an environment variable.

Next, create a requirements.txt file:

Flask==2.2.2

Step 2: Dockerizing the Application

Now, let’s create a Dockerfile to containerize our application:

FROM python:3.9-slim

WORKDIR /app

COPY requirements.txt .
RUN pip install -r requirements.txt

COPY . .

CMD ["python", "app.py"]

This Dockerfile creates a Python 3.9 image, installs the dependencies, copies the application code, and sets the command to run the Flask app.

Let’s build the Docker image and push it to Docker Hub. Replace your-dockerhub-username with your actual Docker Hub username.

docker build -t your-dockerhub-username/novacraft-app:1.0.0 .
docker push your-dockerhub-username/novacraft-app:1.0.0

If you don’t have a Docker Hub account, you can also use the local Docker registry that comes with Docker Desktop. In that case, you can skip the docker push command and use the image name novacraft-app:1.0.0 in the following steps.

Step 3: Creating the Helm Chart

Now for the main event: creating our Helm chart. Helm provides a handy command to scaffold a new chart.

helm create novacraft-chart

This will create a new directory named novacraft-chart with the standard Helm chart structure. Let’s take a look at the most important files:

• novacraft-chart/Chart.yaml: Contains metadata about the chart.
• novacraft-chart/values.yaml: The default values for the chart.
• novacraft-chart/templates/: The directory containing the templates for our Kubernetes resources.

Let’s customize the values.yaml file. Open novacraft-chart/values.yaml and replace the content with the following:

replicaCount: 1

image:
  repository: your-dockerhub-username/novacraft-app
  pullPolicy: IfNotPresent
  tag: "1.0.0"

environment: development

service:
  type: ClusterIP
  port: 80

ingress:
  enabled: false

Make sure to replace your-dockerhub-username with your Docker Hub username.

Now, let’s modify the deployment.yaml template to use our environment value. Open novacraft-chart/templates/deployment.yaml and add the following env section to the container spec:

          env:
            - name: ENVIRONMENT
              value: {{ .Values.environment | quote }}

The full deployment.yaml should look something like this:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: {{ include "novacraft-chart.fullname" . }}
  labels:
    {{- include "novacraft-chart.labels" . | nindent 4 }}
spec:
  replicas: {{ .Values.replicaCount }}
  selector:
    matchLabels:
      {{- include "novacraft-chart.selectorLabels" . | nindent 6 }}
  template:
    metadata:
      labels:
        {{- include "novacraft-chart.selectorLabels" . | nindent 8 }}
    spec:
      containers:
        - name: {{ .Chart.Name }}
          image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"
          imagePullPolicy: {{ .Values.image.pullPolicy }}
          env:
            - name: ENVIRONMENT
              value: {{ .Values.environment | quote }}
          ports:
            - name: http
              containerPort: 80
              protocol: TCP
          livenessProbe:
            httpGet:
              path: /
              port: http
          readinessProbe:
            httpGet:
              path: /
              port: http
          resources:
            {{- toYaml .Values.resources | nindent 12 }}

We’ve also simplified the template a bit for clarity.

Step 4: Deploying with Helm

Now we’re ready to deploy our application. First, let’s deploy it to our “development” environment using the default values.

helm install dev-release ./novacraft-chart

This will install the chart and create a release named dev-release. You can check the status of the release with helm list and the created resources with kubectl get all.

To access the application, we can use kubectl port-forward to forward a local port to the service:

kubectl port-forward service/dev-release-novacraft-chart 8080:80

Now, if you open your browser to http://localhost:8080, you should see the message: “Hello from NovaCraft! Environment: development”.

Step 5: Deploying to Production

Now, let’s deploy our application to a “production” environment. We’ll create a separate values file for our production configuration. Create a file named values-prod.yaml with the following content:

replicaCount: 3

environment: production

image:
  tag: "1.0.0"

service:
  type: LoadBalancer

This file overrides the default values with our production settings: 3 replicas, the environment set to “production”, and the service type set to LoadBalancer (which would provision an external load balancer in a real cloud environment).

Now, we can deploy our production release using this values file:

helm install prod-release ./novacraft-chart -f values-prod.yaml

This creates a new release named prod-release with the production configuration. You can check the status with helm list.

To access the production application, you can again use kubectl port-forward:

kubectl port-forward service/prod-release-novacraft-chart 8081:80

Now, if you open your browser to http://localhost:8081, you should see the message: “Hello from NovaCraft! Environment: production”.

And there you have it! We’ve successfully packaged our application as a Helm chart and deployed it with different configurations for development and production. This is the power of Helm: the ability to manage complex applications as a single, version-controlled unit, and to easily customize them for different environments.

Debugging and Troubleshooting

Even with powerful tools like Helm, things can go wrong. Here are a few common issues you might encounter and how to solve them:

• “Unable to connect to the server”: This usually means kubectl is not configured correctly to connect to your Kubernetes cluster. Make sure Docker Desktop is running and Kubernetes is enabled. You can test your connection with kubectl cluster-info.
• “ImagePullBackOff”: This error means Kubernetes can’t pull the Docker image for your container. Double-check that the image name and tag in your values.yaml are correct and that you have pushed the image to Docker Hub (or are using a local image that is available in your Docker Desktop environment).
• Helm template errors: If you have a syntax error in your Helm templates, helm install will fail with a parsing error. Helm provides a useful command to debug templates locally without actually installing the chart: helm template ./novacraft-chart. This will render the templates and print the resulting YAML to the console, so you can inspect it for errors.
• Upgrading a release fails: If you make a change to your chart and helm upgrade fails, you can use helm history <release-name> to see the history of the release and helm rollback <release-name> <revision> to roll back to a previous, working version.

Key Takeaways

• Managing raw Kubernetes YAML files becomes unmanageable as applications grow.
• Helm is a package manager for Kubernetes that bundles applications into reusable charts.
• Kustomize is a template-free tool for customizing Kubernetes resources using patches.
• Helm is great for packaging and distributing applications, while Kustomize is excellent for environment-specific configuration management.
• You can use Helm and Kustomize together to get the best of both worlds.

The Calm After the Storm

Alex leaned back, a sense of accomplishment washing over them. The chaotic sea of YAML files had been tamed. With the NovaCraft application neatly packaged as a Helm chart, deploying to different environments was no longer a hair-raising ordeal but a simple, repeatable command. The team could now focus on building features, confident that their deployment process was robust and scalable.

But as Alex looked at the monitoring dashboard, a new challenge began to emerge. The application was running smoothly, but how could they ensure it stayed that way? How could they automatically scale the application to meet fluctuating demand? And how could they gain deeper insights into the application’s performance and health? The journey into the heart of Kubernetes was far from over. The next leg of the odyssey would take them into the world of autoscaling and monitoring, where they would learn to build a truly self-healing and resilient system.