Helm Chart Scaffolding

Helm Chart Scaffolding

Comprehensive guidance for creating, organizing, and managing Helm charts for packaging and deploying Kubernetes applications.

Purpose

This skill provides step-by-step instructions for building production-ready Helm charts, including chart structure, templating patterns, values management, and validation strategies.

When to Use This Skill

Use this skill when you need to:

• Create new Helm charts from scratch
• Package Kubernetes applications for distribution
• Manage multi-environment deployments with Helm
• Implement templating for reusable Kubernetes manifests
• Set up Helm chart repositories
• Follow Helm best practices and conventions

Chart Complexity Classification

Before starting, classify your chart to determine the appropriate approach:

Quick Decision:

• Needs database/search/messaging at runtime? → Complex (exclude from install tests)
• Has admin port separate from main port? → Check assets/patterns/multi-port-service.yaml
• JVM application? → Check assets/patterns/jvm-application.yaml

Details: See references/chart-complexity.md for full classification guide and CI configuration.

Research Strategy

Before creating a chart, research the application:

1. Check for official chart - Many projects maintain their own Helm charts
2. Review Docker documentation - Container entrypoint, environment variables, ports
3. Identify external dependencies - What services does the app need?

If documentation scraping fails, use alternative methods:

• Search GitHub for existing implementations
• Check Docker Hub for environment variable documentation
• Review Kubernetes deployment examples in project repos

Details: See references/research-strategy.md for complete fallback strategies and information gathering checklist.

Structured Development Workflow

For complex charts or when contributing to existing projects, use a structured approach:

Workflow Selection

Research Phase

Systematically investigate the application before creating templates:

1. Check for existing charts (official, community)
2. Gather configuration details (image, ports, env vars)
3. Document findings in structured format
4. Get approval for complex applications

Details: See references/research-phase-workflow.md

Planning Phase

Translate research into actionable implementation plan:

1. Create high-level plan with target features
2. Break down into atomic components (phases)
3. Draft phase plans for each component
4. Get sequential approvals
5. Map plans to GitHub issues (optional)

Details: See references/planning-phase-workflow.md

Implementation Phase

Execute with quality gates and review checkpoints:

1. Create worktree and draft PR immediately
2. Implement following phase plan
3. Run sanity checks (lint, template, security)
4. Pause for external review when needed
5. Submit PR when complete, clean up worktree

Details: See references/implementation-workflow.md

Extending Existing Charts

When an official chart exists but needs improvements:

1. Decide: fork repo vs copy locally
2. Review upstream patterns and values schema
3. Maintain compatibility for contribution
4. Document differences and improvements
5. Prepare upstream contribution (PR or patch)

Details: See references/extend-contribute-strategy.md

Helm Overview

Helm is the package manager for Kubernetes that:

• Templates Kubernetes manifests for reusability
• Manages application releases and rollbacks
• Handles dependencies between charts
• Provides version control for deployments
• Simplifies configuration management across environments

Step-by-Step Workflow

1. Initialize Chart Structure

Create new chart:

helm create my-app

Standard chart structure:

my-app/
├── Chart.yaml           # Chart metadata
├── values.yaml          # Default configuration values
├── charts/              # Chart dependencies
├── templates/           # Kubernetes manifest templates
│   ├── NOTES.txt       # Post-install notes
│   ├── _helpers.tpl    # Template helpers
│   ├── deployment.yaml
│   ├── service.yaml
│   ├── ingress.yaml
│   ├── serviceaccount.yaml
│   ├── hpa.yaml
│   └── tests/
│       └── test-connection.yaml
└── .helmignore         # Files to ignore

2. Configure Chart.yaml

Chart metadata defines the package:

apiVersion: v2
name: my-app
description: A Helm chart for My Application
type: application
version: 1.0.0      # Chart version
appVersion: "2.1.0" # Application version

# Keywords for chart discovery
keywords:
  - web
  - api
  - backend

# Maintainer information
maintainers:
  - name: DevOps Team
    email: devops@example.com
    url: https://github.com/example/my-app

# Source code repository
sources:
  - https://github.com/example/my-app

# Homepage
home: https://example.com

# Chart icon
icon: https://example.com/icon.png

# Dependencies
dependencies:
  - name: postgresql
    version: "12.0.0"
    repository: "https://charts.bitnami.com/bitnami"
    condition: postgresql.enabled
  - name: redis
    version: "17.0.0"
    repository: "https://charts.bitnami.com/bitnami"
    condition: redis.enabled

Reference: See assets/Chart.yaml.template for complete example

3. Design values.yaml Structure

Organize values hierarchically:

# Image configuration
image:
  repository: myapp
  tag: "1.0.0"
  pullPolicy: IfNotPresent

# Number of replicas
replicaCount: 3

# Service configuration
service:
  type: ClusterIP
  port: 80
  targetPort: 8080

# Ingress configuration
ingress:
  enabled: false
  className: nginx
  hosts:
    - host: app.example.com
      paths:
        - path: /
          pathType: Prefix

# Resources
resources:
  requests:
    memory: "256Mi"
    cpu: "250m"
  limits:
    memory: "512Mi"
    cpu: "500m"

# Autoscaling
autoscaling:
  enabled: false
  minReplicas: 2
  maxReplicas: 10
  targetCPUUtilizationPercentage: 80

# Environment variables
env:
  - name: LOG_LEVEL
    value: "info"

# ConfigMap data
configMap:
  data:
    APP_MODE: production

# Dependencies
postgresql:
  enabled: true
  auth:
    database: myapp
    username: myapp

redis:
  enabled: false

Reference: See assets/values.yaml.template for complete structure

4. Create Template Files

Use Go templating with Helm functions:

templates/deployment.yaml:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: {{ include "my-app.fullname" . }}
  labels:
    {{- include "my-app.labels" . | nindent 4 }}
spec:
  {{- if not .Values.autoscaling.enabled }}
  replicas: {{ .Values.replicaCount }}
  {{- end }}
  selector:
    matchLabels:
      {{- include "my-app.selectorLabels" . | nindent 6 }}
  template:
    metadata:
      labels:
        {{- include "my-app.selectorLabels" . | nindent 8 }}
    spec:
      containers:
      - name: {{ .Chart.Name }}
        image: "{{ .Values.image.repository }}:{{ .Values.image.tag | default .Chart.AppVersion }}"
        imagePullPolicy: {{ .Values.image.pullPolicy }}
        ports:
        - name: http
          containerPort: {{ .Values.service.targetPort }}
        resources:
          {{- toYaml .Values.resources | nindent 12 }}
        env:
          {{- toYaml .Values.env | nindent 12 }}

5. Create Template Helpers

templates/_helpers.tpl:

{{/*
Expand the name of the chart.
*/}}
{{- define "my-app.name" -}}
{{- default .Chart.Name .Values.nameOverride | trunc 63 | trimSuffix "-" }}
{{- end }}

{{/*
Create a default fully qualified app name.
*/}}
{{- define "my-app.fullname" -}}
{{- if .Values.fullnameOverride }}
{{- .Values.fullnameOverride | trunc 63 | trimSuffix "-" }}
{{- else }}
{{- $name := default .Chart.Name .Values.nameOverride }}
{{- if contains $name .Release.Name }}
{{- .Release.Name | trunc 63 | trimSuffix "-" }}
{{- else }}
{{- printf "%s-%s" .Release.Name $name | trunc 63 | trimSuffix "-" }}
{{- end }}
{{- end }}
{{- end }}

{{/*
Common labels
*/}}
{{- define "my-app.labels" -}}
helm.sh/chart: {{ include "my-app.chart" . }}
{{ include "my-app.selectorLabels" . }}
{{- if .Chart.AppVersion }}
app.kubernetes.io/version: {{ .Chart.AppVersion | quote }}
{{- end }}
app.kubernetes.io/managed-by: {{ .Release.Service }}
{{- end }}

{{/*
Selector labels
*/}}
{{- define "my-app.selectorLabels" -}}
app.kubernetes.io/name: {{ include "my-app.name" . }}
app.kubernetes.io/instance: {{ .Release.Name }}
{{- end }}

6. Manage Dependencies

Add dependencies in Chart.yaml:

dependencies:
  - name: postgresql
    version: "12.0.0"
    repository: "https://charts.bitnami.com/bitnami"
    condition: postgresql.enabled

Update dependencies:

helm dependency update
helm dependency build

Override dependency values:

# values.yaml
postgresql:
  enabled: true
  auth:
    database: myapp
    username: myapp
    password: changeme
  primary:
    persistence:
      enabled: true
      size: 10Gi

7. Test and Validate

Validation commands:

# Lint the chart
helm lint my-app/

# Dry-run installation
helm install my-app ./my-app --dry-run --debug

# Template rendering
helm template my-app ./my-app

# Template with values
helm template my-app ./my-app -f values-prod.yaml

# Show computed values
helm show values ./my-app

Validation script:

#!/bin/bash
set -e

echo "Linting chart..."
helm lint .

echo "Testing template rendering..."
helm template test-release . --dry-run

echo "Checking for required values..."
helm template test-release . --validate

echo "All validations passed!"

Reference: See scripts/validate-chart.sh

8. Package and Distribute

Package the chart:

helm package my-app/
# Creates: my-app-1.0.0.tgz

Create chart repository:

# Create index
helm repo index .

# Upload to repository
# AWS S3 example
aws s3 sync . s3://my-helm-charts/ --exclude "*" --include "*.tgz" --include "index.yaml"

Use the chart:

helm repo add my-repo https://charts.example.com
helm repo update
helm install my-app my-repo/my-app

9. Multi-Environment Configuration

Environment-specific values files:

my-app/
├── values.yaml          # Defaults
├── values-dev.yaml      # Development
├── values-staging.yaml  # Staging
└── values-prod.yaml     # Production

values-prod.yaml:

replicaCount: 5

image:
  tag: "2.1.0"

resources:
  requests:
    memory: "512Mi"
    cpu: "500m"
  limits:
    memory: "1Gi"
    cpu: "1000m"

autoscaling:
  enabled: true
  minReplicas: 3
  maxReplicas: 20

ingress:
  enabled: true
  hosts:
    - host: app.example.com
      paths:
        - path: /
          pathType: Prefix

postgresql:
  enabled: true
  primary:
    persistence:
      size: 100Gi

Install with environment:

helm install my-app ./my-app -f values-prod.yaml --namespace production

10. Implement Hooks and Tests

Pre-install hook:

# templates/pre-install-job.yaml
apiVersion: batch/v1
kind: Job
metadata:
  name: {{ include "my-app.fullname" . }}-db-setup
  annotations:
    "helm.sh/hook": pre-install
    "helm.sh/hook-weight": "-5"
    "helm.sh/hook-delete-policy": hook-succeeded
spec:
  template:
    spec:
      containers:
      - name: db-setup
        image: postgres:15
        command: ["psql", "-c", "CREATE DATABASE myapp"]
      restartPolicy: Never

Test connection:

# templates/tests/test-connection.yaml
apiVersion: v1
kind: Pod
metadata:
  name: "{{ include "my-app.fullname" . }}-test-connection"
  annotations:
    "helm.sh/hook": test
spec:
  containers:
  - name: wget
    image: busybox
    command: ['wget']
    args: ['{{ include "my-app.fullname" . }}:{{ .Values.service.port }}']
  restartPolicy: Never

Run tests:

helm test my-app

Common Patterns

Pattern 1: Conditional Resources

{{- if .Values.ingress.enabled }}
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: {{ include "my-app.fullname" . }}
spec:
  # ...
{{- end }}

Pattern 2: Iterating Over Lists

env:
{{- range .Values.env }}
- name: {{ .name }}
  value: {{ .value | quote }}
{{- end }}

Pattern 3: Including Files

data:
  config.yaml: |
    {{- .Files.Get "config/application.yaml" | nindent 4 }}

Pattern 4: Global Values

global:
  imageRegistry: docker.io
  imagePullSecrets:
    - name: regcred

# Use in templates:
image: {{ .Values.global.imageRegistry }}/{{ .Values.image.repository }}

Pattern Templates

Ready-to-use patterns for common scenarios. Copy values and template sections to your chart.

External Services

All patterns include:

• Values structure with existingSecret support
• Helper template functions
• Environment variable configuration
• Example configurations

Application Architecture

Quick Reference

For port numbers, environment variables, and connection strings:

• references/external-services.md - Common services reference table

Best Practices

1. Use semantic versioning for chart and app versions
2. Document all values in values.yaml with comments
3. Use template helpers for repeated logic
4. Validate charts before packaging
5. Pin dependency versions explicitly
6. Use conditions for optional resources
7. Follow naming conventions (lowercase, hyphens)
8. Include NOTES.txt with usage instructions
9. Add labels consistently using helpers
10. Test installations in all environments

Troubleshooting

Template rendering errors:

helm template my-app ./my-app --debug

Dependency issues:

helm dependency update
helm dependency list

Installation failures:

helm install my-app ./my-app --dry-run --debug
kubectl get events --sort-by='.lastTimestamp'

Reference Files

Chart Templates

• assets/Chart.yaml.template - Chart metadata template
• assets/values.yaml.template - Values structure template

Pattern Files

• assets/patterns/external-database.yaml - MySQL/PostgreSQL configuration
• assets/patterns/external-search.yaml - Elasticsearch/OpenSearch configuration
• assets/patterns/external-messaging.yaml - Airflow/Kafka/RabbitMQ/Redis configuration
• assets/patterns/multi-port-service.yaml - Multiple ports pattern
• assets/patterns/jvm-application.yaml - JVM heap/GC/JMX configuration
• assets/patterns/health-probes-multiport.yaml - Probes on different ports

Workflow Templates

• assets/templates/research-summary.md - Research findings documentation
• assets/templates/high-level-plan.md - High-level chart plan
• assets/templates/phase-plan.md - Per-phase implementation plan
• assets/templates/issue-structure.md - GitHub issue hierarchy

References

• references/chart-structure.md - Detailed chart organization
• references/chart-complexity.md - Chart complexity classification guide
• references/research-strategy.md - Documentation research and fallback strategies
• references/external-services.md - Common ports, env vars, connection strings
• references/extend-contribute-strategy.md - Extending and contributing to existing charts
• references/research-phase-workflow.md - Research phase structured workflow
• references/planning-phase-workflow.md - Planning phase structured workflow
• references/implementation-workflow.md - Implementation phase with checkpoints

Scripts

• scripts/validate-chart.sh - Validation script

Related Skills

• k8s-manifest-generator - For creating base Kubernetes manifests
• gitops-workflow - For automated Helm chart deployments