Helm Charts Tutorial: Complete Guide to Kubernetes Testing Deployment

May 15, 2025
read
Cortney Nickerson
Developer Advocate
Testkube
Read more from
Cortney Nickerson

Table of Contents

Start your free trial.

May 15, 2025
read
Cortney Nickerson
Developer Advocate
Testkube
Read more from
Cortney Nickerson
Cortney Nickerson
Developer Advocate
Testkube
Master Helm charts creation with our comprehensive tutorial. Learn Kubernetes deployment, templating, and cloud-native testing. Complete guide with code examples and best practices.

Table of Contents

Executive Summary

In the vast oceans of cloud-native application delivery, where microservices, containers, and Kubernetes-native architectures reign, navigating the turbulent waters of continuous testing can be a daunting task. Enter Helm, the swiss-army knife of Kubernetes, here to guide teams through the complex archipelago of deploying, managing, and scaling testing workloads. Helm charts, akin to the treasured maps of old, offer a structured pathway to deploy test suites directly on Kubernetes, making your continuous testing journey smoother and less error-prone.

Whether you're just docking your ship in the harbor of Kubernetes testing or have sailed these cloud-native seas many times before, understanding how to create Helm charts is essential for building a robust testing platform. These charts encapsulate testing configurations, making Kubernetes deployments a breeze while maintaining the control and flexibility that modern DevOps teams demand. In this Helm chart tutorial, we'll embark on a step-by-step expedition, crafting our very own custom Helm chart for testing workloads, ensuring that by journey's end, you'll have a treasured map that supports AI-driven development velocity. So hoist the anchor and set sail across the world of Helm charts with Testkube as your compass!

What Are Helm Charts?

Before diving into our Helm chart creation guide, it's important to understand that Helm charts are packages of pre-configured Kubernetes resources. They simplify Kubernetes application deployment by bundling YAML files, templates, and configuration values into a single, reusable package. Think of Helm charts as recipes for deploying applications consistently across different environments.

Prerequisites for Creating Helm Charts

1. Setup Environment

  • Ensure you have Helm CLI installed on your system (version 3+)
  • Ensure you have access to a Kubernetes cluster (version 1.21+, e.g., Minikube, EKS, GKE, or AKS)
  • Consider having Testkube installed to manage your testing workloads at scale
  • Basic understanding of Kubernetes YAML manifests
  • (RECOMMENDED) cert-manager (version 1.11+) for TLS certificate management
  • (RECOMMENDED) NGINX Ingress Controller (version v1.8+) for ingress configuration

⚠️ Important: Use kubernetes/ingress-nginx not nginx/nginx-ingress to avoid routing conflicts.

Step-by-Step Helm Chart Creation Tutorial

2. Create a New Helm Chart

helm create mychart

This Helm create command generates a directory called mychart with the basic Helm chart structure inside.

3. Understanding Helm Chart Directory Structure

Here's a breakdown of the generated Helm chart directory:

  • Chart.yaml: The metadata file containing Helm chart information
  • values.yaml: The default configuration values for the Helm chart templates
  • templates/: The directory containing Kubernetes template files
  • templates/NOTES.txt: A plain text file with Helm chart usage notes

This standard Helm chart structure ensures consistency across all Kubernetes Helm deployments.

Helm chart directory structure created by helm create: Chart.yaml, values.yaml, templates/ and _helpers.tpl

4. Configuring Chart.yaml Metadata

Open Chart.yaml and update the Helm chart metadata including name, version, description, and appVersion. This file is crucial for Helm chart management and repository organization.

apiVersion: v2
name: mychart
description: A Helm chart for Kubernetes testing
type: application
version: 0.1.0
appVersion: "1.16.0"

5. Working with Helm Templates

Helm templates use a combination of the Go programming language's templating system and Sprig functions. The templates/ directory contains files that are converted to Kubernetes manifest files when the Helm chart is installed.

Modify the YAML template files in the templates/ directory to represent the Kubernetes objects you need for your testing infrastructure. This is where the power of Helm templating really shines.

6. Helm Values and Template Variables

In the values.yaml file, you can define Helm chart variables. These variables enable dynamic Kubernetes deployments through your templates. For instance, in values.yaml:

image:
  repository: nginx
  tag: latest
replicaCount: 2

# Testing configuration
testkube:
  enabled: false
  namespace: testkube

# Security settings
secrets:
  autoGenerate: true

Can be referenced in a Helm template as:

image: {{ .Values.image.repository }}:{{ .Values.image.tag }}
replicas: {{ .Values.replicaCount }}
{{- if .Values.testkube.enabled }}
namespace: {{ .Values.testkube.namespace }}
{{- end }}

This Helm values system makes your charts flexible and reusable across different environments.

7. Installing Your Custom Helm Chart

Test your custom Helm chart by installing it:

helm install my-release-name ./mychart

This Helm install command deploys the mychart directory as a release named my-release-name to your Kubernetes cluster.

For production installations with custom values:

helm upgrade --install \
  --create-namespace \
  --namespace testkube \
  -f values.yaml \
  my-release-name ./mychart

8. Validating Helm Chart Deployment

After installing the Helm chart, verify that all Kubernetes resources have been created successfully:

kubectl get pods
kubectl get services
kubectl get deployments
kubectl get ingress

This step is crucial for Kubernetes deployment troubleshooting and ensuring your Helm chart works correctly.

9. Helm Chart Testing and Debugging

Before deploying to production, test your Helm templates:

# Render templates without installing
helm template my-release-name ./mychart --debug

# Validate chart syntax
helm lint ./mychart

# Dry run installation
helm install my-release-name ./mychart --dry-run --debug

These Helm debugging commands help catch template errors early in the development process.

Helm chart deployment workflow in five steps: create, configure, validate, install and package a Helm chart

10. Helm Chart Packaging

Once you're satisfied with your Helm chart, package it for distribution:

helm package mychart

This Helm package command produces a .tgz file that can be shared or uploaded to a Helm chart repository.

11. Helm Chart Distribution and Repository Management

You can push your packaged Helm chart to a Helm chart repository or share the .tgz file with your team to maintain consistency across testing environments. This enables Helm chart reusability and standardized Kubernetes deployments.

12. Helm Chart Cleanup and Uninstallation

If you need to remove the deployed release:

helm uninstall my-release-name

This Helm uninstall command removes all Kubernetes resources created by your Helm chart deployment.

Real-World Example: Deploying Testkube with Helm Charts

Adding Testkube to Your Helm Chart

Once you've mastered basic Helm chart creation, you can integrate Testkube for comprehensive Kubernetes testing:

# In your values.yaml
global:
  domain: "your-domain.com"
  enterpriseLicenseKey: "XXXXXX-XXXXXX-XXXXXX-XXXXXX-XXXXXX-V3"
  ingress:
    enabled: true

testkube:
  enabled: true
  namespace: testkube
  
# Authentication configuration
dex:
  configTemplate:
    additionalConfig: |
      connectors:
        - type: oidc
          id: google
          name: Google
          config:
            issuer: https://accounts.google.com
            clientID: $GOOGLE_CLIENT_ID
            clientSecret: $GOOGLE_CLIENT_SECRET

Installing Testkube via Helm

helm upgrade --install \
  --create-namespace \
  --namespace testkube \
  -f values.yaml \
  testkube oci://registry-1.docker.io/kubeshop/testkube-enterprise --version <version>

This demonstrates how enterprise Helm charts handle complex multi-service deployments with proper secret management and ingress configuration.

Production Helm Chart Patterns

Secret Management Best Practices

Learn from Testkube's approach to handling sensitive data in production Helm charts:

# Auto-generate secrets when not provided
secrets:
  testkube-license:
    autoGenerate: true
  testkube-default-agent-token:
    autoGenerate: true
  testkube-minio-credentials:
    autoGenerate: true

# Reference secrets via secretKeyRef
envVars:
  - name: GOOGLE_CLIENT_ID
    valueFrom:
      secretKeyRef:
        name: oidc-credentials-secret
        key: client-id

Multi-Service Architecture

Complex applications like Testkube show how to structure Helm charts with:

  • Multiple ingress endpoints (API, Dashboard, WebSockets)
  • Service-specific subdomains
  • Conditional resource creation based on values
# Service exposure configuration
services:
  dashboard: "dashboard.{{ .Values.global.domain }}"
  api: "api.{{ .Values.global.domain }}"
  grpc: "agent.{{ .Values.global.domain }}"
  websockets: "websockets.{{ .Values.global.domain }}"

Prometheus Metrics Integration

Enable observability in your Helm charts:

prometheus:
  enabled: true
  serviceMonitor:
    enabled: true
    path: /metrics

Common Helm Chart Troubleshooting

Ingress Controller Conflicts

⚠️ Critical: Always verify your ingress controller choice:

  • ✅ Use: kubernetes/ingress-nginx
  • ❌ Avoid: nginx/nginx-ingress (causes Dex and API ingress conflicts)

Template Validation Issues

Debug Helm template problems systematically:

# Check template rendering
helm template my-release ./mychart --debug

# Validate chart structure
helm lint ./mychart

# Test with different values
helm template my-release ./mychart -f custom-values.yaml

TLS and HTTP/2 Requirements

For gRPC endpoints (like Testkube's agent communication):

  • Ensure your gateway supports HTTP/2
  • Use Application Gateway for Containers in Azure environments
  • Terminate TLS at application level for better gRPC performance

Advanced Helm Chart Best Practices

Here are the comprehensive basics of creating production-ready Helm charts! Keep in mind, Helm charts can range from simple configurations like we covered above, to complex enterprise Kubernetes deployments with multiple services, ingress rules, and authentication providers.

When you encounter complexities with testing workloads that need to scale across multiple environments or integrate with CI/CD pipelines, remember that there are advanced Helm chart patterns and comprehensive documentation for more in-depth scenarios.

Cloud-native testing platforms like Testkube demonstrate how to orchestrate complex testing scenarios while maintaining the Kubernetes-native approach that gives you full control over your testing infrastructure. This combination of sophisticated Helm charts and specialized testing tools creates a powerful foundation for scalable Kubernetes testing that keeps pace with AI-driven development velocity.

Conclusion: Mastering Helm Charts for Kubernetes

Helm charts are essential tools for modern Kubernetes application deployment and management. By following this comprehensive Helm tutorial, you now have the foundation to create, deploy, and manage custom Helm charts for your testing and application workloads.

Whether you're building simple deployments or complex cloud-native testing platforms like Testkube, Helm charts provide the flexibility, security, and control needed for successful Kubernetes operations. The patterns and practices demonstrated here, from basic chart creation to enterprise-grade secret management and multi-service architectures, will serve as your compass for navigating the waters of production Kubernetes deployments.

Frequently Asked Questions

What are Helm charts and why should I use them?

Helm charts are packages of pre-configured Kubernetes resources that simplify application deployment. They bundle YAML files, templates, and configuration values into reusable packages, making Kubernetes deployments consistent and manageable across different environments.

How do I debug Helm chart template errors?

Run helm template my-release ./mychart --debug to render templates locally, helm lint ./mychart to validate chart syntax, and helm install my-release ./mychart --dry-run --debug to simulate the install without changing the cluster.

What's the difference between Helm 2 and Helm 3?

Helm 3 removed Tiller (the server-side component), improved security, and introduced better Kubernetes RBAC integration. Always use Helm 3 for new projects, as it's more secure and doesn't require cluster-wide permissions.

Can I use Helm charts with different Kubernetes clusters?

Yes. Helm charts are designed for portability. Use a different values.yaml file for each environment (development, staging, production) to customize deployments while keeping the same chart structure.

How do I manage secrets in Helm charts?

Use secretKeyRef to reference existing Kubernetes secrets, enable auto-generation for non-sensitive secrets, and store sensitive data in an external secret management system. Never hardcode secrets in templates or values files.

What's the recommended way to structure large Helm charts?

For complex applications like Testkube, use separate templates for each service, conditional resource creation with {{- if .Values.service.enabled }}, shared configuration in _helpers.tpl, and multiple values files for different environments.

How do I handle Helm chart dependencies?

Declare them in the dependencies section of Chart.yaml with a name, version, repository, and optional condition (for example, a postgresql chart from the Bitnami repository enabled by postgresql.enabled). Then run helm dependency update to download them.

Why am I getting ingress controller conflicts?

This usually means the wrong NGINX ingress controller is installed. Use kubernetes/ingress-nginx and avoid nginx/nginx-ingress, which causes routing conflicts when multiple services share the same hostname.

How do I upgrade Helm chart releases safely?

Run helm upgrade my-release ./mychart --atomic --timeout 10m. The --atomic flag rolls the release back automatically if the upgrade fails.

Can Helm charts work with GitOps workflows?

Yes. Helm charts integrate with GitOps tools like Argo CD and Flux. Store your charts in Git repositories and let the GitOps operator manage deployments declaratively.

How do I test Helm charts in CI/CD pipelines?

Lint charts with helm lint ./mychart, validate templates with helm template test-release ./mychart --debug, and run integration tests against the deployed release with a testing platform like Testkube.

What are Helm chart hooks and when should I use them?

Helm hooks run at specific points in the release lifecycle, such as pre-install, post-install, and pre-delete. Use them for database migrations, pre-deployment validation, cleanup tasks, and triggering tests on platforms like Testkube.

How do I handle different environments with Helm charts?

Create environment-specific values files and pass the right one at install time, for example helm install my-app ./mychart -f values-dev.yaml for development and -f values-prod.yaml for production.

Can I use Helm charts for stateful applications?

Yes, with extra care. Use StatefulSets instead of Deployments, configure persistent volumes properly, handle initialization and scaling carefully, and consider operators for complex stateful applications.

How do I monitor Helm chart deployments?

Build observability into your charts: expose Prometheus metrics endpoints, configure ServiceMonitor resources, add logging and alerting, and use a tool like Testkube for continuous testing of the deployed release.

{{banner-get-started}}

Cortney Nickerson
Developer Advocate
Testkube
Read more from
Cortney Nickerson

About Testkube

Testkube is the open testing platform for AI-driven engineering teams. It runs tests directly in your Kubernetes clusters, works with any CI/CD system, and supports every testing tool your team uses. By removing CI/CD bottlenecks, Testkube helps teams ship faster with confidence.
Get Started with a trial to see Testkube in action.