Helm

• Structure charts with Chart.yaml (metadata), values.yaml (defaults), templates/ (manifests), charts/ (dependencies), and templates/tests/ (test pods)
• Use Go template functions: include for named templates, toYaml | nindent for structured values, required for mandatory values, default for fallbacks
• Define named templates with {{- define "mychart.labels" -}} and invoke with {{- include "mychart.labels" . | nindent 4 }}
• Use hooks with "helm.sh/hook": pre-install,pre-upgrade and "helm.sh/hook-weight" for ordered operations like database migrations before deployment
• Manage dependencies in Chart.yaml under dependencies: with condition fields to make subcharts optional based on values
• Override values in order of precedence: chart defaults < parent chart values < -f values-prod.yaml < --set key=value

Common Patterns

• Environment Overlays: Maintain values-dev.yaml, values-staging.yaml, values-prod.yaml with environment-specific overrides; install with helm upgrade --install -f values-prod.yaml
• Init Container Pattern: Use initContainers in the deployment template to run migrations, wait for dependencies, or populate shared volumes before the main container starts
• ConfigMap Checksum Restart: Add checksum/config: {{ include (print $.Template.BasePath "/configmap.yaml") . | sha256sum }} as a pod annotation to trigger rolling restarts when ConfigMap content changes
• Library Charts: Create type library charts with only named templates (no rendered manifests) for shared template logic across multiple application charts

Pitfalls to Avoid

• Do not hardcode namespaces in templates; use {{ .Release.Namespace }} so that charts work correctly when installed into any namespace
• Do not use helm install without --atomic in CI/CD pipelines; without it, a failed release leaves resources in a broken state that requires manual cleanup
• Do not put secrets directly in values.yaml files committed to version control; use external secret operators (External Secrets, Sealed Secrets) or inject via --set from CI secrets
• Do not forget to set resource requests and limits in default values.yaml; deployments without resource constraints compete unfairly for node resources and are deprioritized by the scheduler