write-helm-chart

# Write Helm Chart Create production-ready Helm charts for deploying applications to Kubernetes. ## When to Use - Need to package Kubernetes application for repeatable deployments - Want to parameterize manifests for different environments (dev/staging/prod) - Managing complex multi-component applications with dependencies - Sharing reusable deployment patterns across teams or organizations - Implementing versioned application releases with rollback capability - Need template-based configuration management for Kubernetes resources - Want to standardize deployment practices across projects ## Inputs - **Required**: Kubernetes manifests for your application (deployment, service, etc.) - **Required**: Application name and version - **Required**: List of configurable parameters (image tag, replicas, resources, etc.) - **Optional**: Dependencies on other Helm charts (databases, message queues) - **Optional**: Pre/post-install hooks for migrations or setup - **Optional**: Chart repository URL for publishing - **Optional**: Values for different environments ## Procedure > See [Extended Examples](references/EXAMPLES.md) for complete template files, values structures, and hooks. ### Step 1: Initialize Chart Structure and Metadata Create the Helm chart directory structure and define chart metadata. **Install Helm:** ```bash # Linux curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash # macOS brew install helm # Windows (Chocolatey) choco install kubernetes-helm # Verify installation helm version ``` **Create chart structure:** ```bash # Create new chart helm create my-app # Chart structure created: # my-app/ # Chart.yaml # Chart metadata # values.yaml # Default configuration values # charts/ # Chart dependencies # templates/ # Template files # deployment.yaml # service.yaml # ingress.yaml # _helpers.tpl # Template helpers # NOTES.txt # Post-install notes # .helmignore # Files to ignore # Or create from scratch mkdir -p my-app/{templates,charts} cd my-app ``` **Define Chart.yaml:** ```yaml # Chart.yaml (excerpt - see EXAMPLES.md for complete file) apiVersion: v2 name: my-app description: A Helm chart for deploying my-app to Kubernetes version: 0.1.0 appVersion: "1.0.0" maintainers: - name: Platform Team email: platform@example.com # ... (keywords, dependencies, kubeVersion - see EXAMPLES.md) ``` **Create .helmignore:** ```text # .helmignore # Patterns to ignore when packaging chart .git/ .gitignore .bzr/ .bzrignore .hg/ .hgignore .svn/ *.swp *.bak *.tmp *.orig *~ .DS_Store .project .idea/ *.tmproj .vscode/ ``` **Expected:** Chart directory structure created with all required files. Chart.yaml contains complete metadata. Dependencies listed if applicable. Chart validates: `helm lint my-app`. **On failure:** - Check YAML syntax in Chart.yaml: `helm lint my-app` - Verify apiVersion is v2 (v1 deprecated) - Ensure version follows SemVer (x.y.z) - Check dependency repository URLs are reachable - Use `helm show chart <chart>` to inspect existing charts for examples ### Step 2: Design values.yaml Structure Create well-organized values.yaml with sensible defaults and documentation. **Create comprehensive values.yaml:** ```yaml # values.yaml (excerpt - see EXAMPLES.md for complete structure) global: imageRegistry: "" image: registry: docker.io repository: mycompany/my-app tag: "" replicaCount: 3 service: type: ClusterIP port: 80 resources: limits: {cpu: 1000m, memory: 512Mi} requests: {cpu: 100m, memory: 128Mi} # ... (ingress, autoscaling, probes, persistence - see EXAMPLES.md) ``` See [EXAMPLES.md](references/EXAMPLES.md#step-2-valuesyaml--complete-structure) for the complete values.yaml structure and values.schema.json **Expected:** values.yaml organized logically with sections. All values documented with comments. Sensible defaults that work out-of-box. Schema validates value types. No hardcoded environment-specific values. **On failure:** - Validate YAML syntax: `yamllint values.yaml` - Check schema validation: `helm lint my-app` - Review against Helm best practices: `helm lint --strict my-app` - Ensure all template references have corresponding values - Test with minimal values: `helm template my-app --set image.repository=test` ### Step 3: Create Template Files with Go Templating Write Kubernetes resource templates using Go template syntax and Helm functions. **Create deployment template:** ```yaml # templates/deployment.yaml (excerpt) 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 }} template: spec: containers: - name: {{ .Chart.Name }} image: "{{ .Values.image.registry }}/{{ .Values.image.repository }}:{{ .Values.image.tag | default .Chart.AppVersion }}" # ... (see EXAMPLES.md for complete template with probes, volumes, etc.) ``` See [EXAMPLES.md](references/EXAMPLES.md#step-3-deploymentyaml--complete-template) for the complete deployment template **Create helper template file:** ```yaml # templates/_helpers.tpl (excerpt) {{- define "my-app.name" -}} {{- default .Chart.Name .Values.nameOverride | trunc 63 | trimSuffix "-" }} {{- end }} {{- define "my-app.fullname" -}} {{- if .Values.fullnameOverride }} {{- .Values.fullnameOverride | trunc 63 | trimSuffix "-" }} {{- else }} {{- printf "%s-%s" .Release.Name .Chart.Name | trunc 63 | trimSuffix "-" }} {{- end }} {{- end }} # ... (labels, serviceAccountName, hpa.apiVersion - see EXAMPLES.md) ``` **Create conditional templates:** ```yaml # templates/ingress.yaml (excerpt) {{- if .Values.ingress.enabled -}} apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: {{ include "my-app.fullname" . }} # ... (see EXAMPLES.md for complete ingress and HPA templates) ``` See [EXAMPLES.md](references/EXAMPLES.md#step-3-helperstpl--complete-helper-functions) for complete _helpers.tpl and conditional templates **Expected:** Templates generate valid Kubernetes YAML. Conditionals work correctly (if/with). Helper functions produce expected output. Resources properly labeled and named. No hardcoded values in templates. **On failure:** - Test template rendering: `helm template my-app` - Check for template syntax errors: `helm lint my-app` - Validate Go template syntax carefully (dashes, spaces matter) - Use `helm template --debug` for detailed error messages - Test with different values files: `helm template my-app -f values-prod.yaml` - Verify output is valid Kubernetes YAML: `helm template my-app | kubectl apply --dry-run=client -f -` ### Step 4: Add Hooks for Pre/Post-Install Actions Create hooks for database migrations, setup tasks, or cleanup. **Create pre-install hook for migrations:** ```yaml # templates/hooks/pre-install-migration.yaml (excerpt) apiVersion: batch/v1 kind: Job metadata: name: {{ include "my-app.fullname" . }}-migration annotations: "helm.sh/hook": pre-install,pre-upgrade "helm.sh/hook-weight": "-5" spec: template: spec: containers: - name: migration image: "{{ .Values.image.registry }}/{{ .Values.image.repository }}:{{ .Values.image.tag | default .Chart.AppVersion }}" command: ["/app/migrate"] # ... (see EXAMPLES.md for test hook, pre-delete backup, NOTES.txt) ``` See [EXAMPLES.md](references/EXAMPLES.md#step-4-helm-hooks) for complete hook templates and NOTES.txt **Expected:** Hooks execute in correct order (weights determine sequence). Pre-install migration completes before deployment. Test hook validates deployment. Pre-delete hook runs cleanup. NOTES.txt provides helpful post-install information. **On failure:** - Check hook annotations syntax exactly matches Helm spec - Verify hook jobs have `restartPolicy: Never` - Review hook execution: `kubectl get jobs -n <namespace>` - Check hook logs: `kubectl logs job/<job-name> -n <namespace>` - Ensure hook-delete-policy appropriate (before-hook-creation, hook-succeeded, hook-failed) - Test hooks independently: `helm install --dry-run --debug my-app` ### Step 5: Test and Package Chart Validate chart, run tests, and package for distribution. **Lint and validate chart:** ```bash # Basic linting helm lint my-app # Strict linting helm lint --strict my-app # Test template rendering helm template my-app # Test with custom values helm template my-app -f values-prod.yaml # Validate against Kubernetes cluster (dry-run) helm install my-app my-app --dry-run --debug # Check for deprecated API versions helm install my-app my-app --dry-run | kubectl apply --dry-run=server -f - ``` **Create chart tests:** ```bash # Run Helm tests helm install my-app my-app -n test --create-namespace helm test my-app -n test kubectl logs -n test -l "helm.sh/hook=test" --tail=-1 # See EXAMPLES.md for complete test script (test-chart.sh) ``` **Package chart:** ```bash # Update dependencies first helm dependency update my-app # Package chart helm package my-app # Creates: my-app-0.1.0.tgz # Verify package helm verify my-app-0.1.0.tgz # Generate index for repository helm repo index . --url https://charts.example.com/ # Creates: index.yaml ``` **Create different values files for environments:** ```yaml # values-dev.yaml (excerpt) replicaCount: 1 resources: limits: {cpu: 500m, memory: 256Mi} ingress: enabled: true hosts: - host: my-app-dev.example.com paths: - path: / pathType: Prefix --- # values-prod.yaml (excerpt) replicaCount: 5 autoscaling: {enabled: true, minReplicas: 3, maxReplicas: 10} ingress: enabled: true hosts: - host: my-app.example.com paths: - path: / pathType: Prefix tls: - secretName: my-app-tls hosts: - my-app.example.com podDisruptionBudget: enabled: true minAvailable: 2 postgresql: enabled: true primary: persistence: size: 50Gi resources: limits: cpu: 4000m memory: 8Gi ``` Two shapes in that block are easy to get backwards. `ingress.hosts` is a list of **mappings** — the template renders `.host` and iterates `.paths` — while `tls[].hosts` is a list of **strings**, ranged as scalars. And `enabled: true` is required in each environment file because the base `values.yaml` ships `ingress.enabled: false` and the whole template is wrapped in that guard; omit it and the ingress renders nothing at all, silently. `replicaCount: 5` in the production file is not the production replica count. The Deployment renders `replicas:` only under `{{- if not .Values.autoscaling.enabled }}`, so with the autoscaler enabled the field is never emitted, the Deployment is created at the API server's default of **one** replica, and the HPA raises it to `minReplicas: 3` on its first reconcile — a brief window of under-provisioning worth knowing about on a cold install. The value is kept deliberately: it is what applies the moment autoscaling is switched off. Reading it as a live production setting is the mistake, and it is why the guard belongs in the deployment excerpt above rather than only in the complete template. See [EXAMPLES.md](references/EXAMPLES.md#step-5-environment-specific-values) for the complete values-dev.yaml and values-prod.yaml **Test with different environments:** ```bash # Test development values helm install my-app-dev my-app -f values-dev.yaml --dry-run --debug # Test production values helm install my-app-prod my-app -f values-prod.yaml --dry-run --debug # Install to dev namespace helm install my-app my-app -f values-dev.yaml -n development --create-namespace # Install to prod namespace helm install my-app my-app -f values-prod.yaml -n production --create-namespace ``` **Expected:** Chart passes all lint checks. Template rendering produces valid Kubernetes YAML. Tests pass successfully. Chart packages without errors. Different values files work for each environment. Installation succeeds without warnings. **On failure:** - Review lint output for specific issues - Check template syntax errors with `--debug` flag - Verify all required values are set: `helm get values <release>` - Test dependency resolution: `helm dependency list my-app` - Validate packaged chart: `tar -tzf my-app-0.1.0.tgz` - Check for missing files in package ### Step 6: Publish to Chart Repository Set up chart repository and publish versioned releases. **Options for publishing:** ```bash # GitHub Pages git checkout -b gh-pages && mkdir charts cp my-app-0.1.0.tgz charts/ helm repo index charts/ --url https://username.github.io/repo/charts # OCI registry (Helm 3.8+) helm registry login registry.example.com -u $USER -p $PASS helm push my-app-0.1.0.tgz oci://registry.example.com/charts # Install from repo helm repo add myrepo https://charts.example.com helm install my-app myrepo/my-app -f custom-values.yaml ``` See [Extended Examples](references/EXAMPLES.md) for ChartMuseum setup, release automation, and complete README template. **Expected:** Chart published to repository successfully. Chart discoverable via `helm search`. Installation works from repository. Versioning follows SemVer. **On failure:** - Verify repository URL accessible - Check index.yaml generated: `helm repo index --help` - For OCI registries, ensure authentication working - Test repository addition: `helm repo add test <url>` ## Validation - [ ] `helm lint --strict my-app` reports no errors and no warnings - [ ] `helm template my-app | kubectl apply --dry-run=client -f -` accepts every rendered resource - [ ] Rendered output contains no hardcoded namespace, hostname, or environment value - [ ] Each environment values file renders: `helm install --dry-run --debug my-app my-app -f values-<env>.yaml`