helm
Package Kubernetes applications as Helm charts, configure values and dependencies, and inspect release upgrades or rollbacks.
SKILL.mdskills/helm/SKILL.md
GitHubHelm Chart Packaging AI Skill Guide (Claude)
Overview & Engine Architecture
Helm packages Kubernetes manifests as charts: Chart.yaml, values.yaml, and Go templates in templates/. A release is an installed instance with revision history; helm upgrade --install renders templates and applies via the Kubernetes API. Agents enforce local render before cluster, secrets outside values.yaml, and understanding Helm’s render-time lookup semantics— a common production footgun.
┌─────────────────────────────────────────────────────────────┐
│ Helm release lifecycle │
│ │
│ Chart + values (+ values.prod.yaml) │
│ ↓ helm lint / template / schema │
│ Rendered manifest batch → API server │
│ Hooks (pre/post install/upgrade) run weighted jobs │
│ Revision N stored → rollback to N-1 │
└─────────────────────────────────────────────────────────────┘
When to use / when not to
Use when
- Templating repeated K8s YAML; promoting same chart across envs with value files.
- Debugging failed hooks, schema validation, or subchart dependency drift.
- Publishing charts to OCI registries or vendoring dependencies.
Do not use when
- GitOps sync semantics and drift—pair with
@argocd(Helm is render engine, not policy loop). - Secret management—use External Secrets / Vault (
@vault), not committed prod passwords invalues.yaml.
Operational Capabilities & Agent Directives
helm lint+helm templateon every change before install/upgrade; pipe tokubeconformin CI.- Pin dependency versions in
Chart.yaml; commitChart.lock; runhelm dependency buildin CI. - Secrets:
--set-file, SOPS, or external operators—defaults invalues.yamlare public. lookupcaution: all templates render before anything is applied—lookupcannot see resources created earlier in the same chart on fresh install; conditional templates vanish on upgrade → Helm deletes resources. Split charts or use operators/CRDs instead of install-time lookup gates.- Hooks: set weights; debug with hook pod logs; understand
helm.sh/hook-delete-policy. - Idempotent upgrades: explicit
--namespace;--atomicfor auto-rollback on failure when appropriate. - Post-renderers: must fail closed (
set -euo pipefail)—empty stdout deletes resources (known incident class).
Production Example: chart layout + command loop
api/
Chart.yaml
values.yaml
values.schema.json
templates/
_helpers.tpl
deployment.yaml
service.yaml
ingress.yaml
charts/
Chart.lock
Chart.yaml dependencies:
apiVersion: v2
name: api
version: 0.4.0
appVersion: "1.5.0"
dependencies:
- name: redis
version: 19.0.2
repository: oci://registry.example.com/charts
condition: redis.enabled
helm dependency update ./api
helm lint ./api
helm template api ./api -f values.prod.yaml > /tmp/render.yaml
helm upgrade --install api ./api -n apps --create-namespace -f values.prod.yaml --atomic --timeout 10m
helm history api -n apps
helm rollback api 3 -n apps
Deployment template excerpt (labels/helpers):
metadata:
labels:
{{- include "api.labels" . | nindent 4 }}
spec:
replicas: {{ .Values.replicaCount }}
template:
spec:
containers:
- name: api
image: "{{ .Values.image.repository }}:{{ .Values.image.tag | default .Chart.AppVersion }}"
Technical Troubleshooting Matrix
| Symptom | Likely cause | Fix |
|---|---|---|
| YAML parse error at line N | Template indent | helm template and inspect line |
| Hook job never completes | Failed migration job | kubectl logs hook pod; fix command |
| Values “ignored” | Wrong -f or typo in key |
helm get values; schema validate |
| Subchart missing | Skipped dependency build |
CI must run helm dependency build |
| Resources deleted on upgrade | lookup conditional dropped manifest |
Remove lookup pattern; split chart |
| All resources deleted | Post-renderer returned empty | set -euo pipefail in renderer |
upgrade --install hook on first install |
Misread .Release.IsUpgrade |
Test revision; upgrade Helm if bug on old patch |
Best Practices
values.schema.jsonfor required keys in large teams.- Library charts for shared labels (
_helpers.tpl)—no copy-paste label blocks. - Keep CRD/operator installs as separate release when ordering matters.
- Document non-obvious values in comments or VALUES.md.
- OCI: pin chart version digest in GitOps repo consumed by
@argocd.
Limitations
- Helm does not build container images—CI updates tags/digests in values.
lookupmakes charts cluster-dependent and hard to test offline.- Stop and ask if target cluster version, namespace policy, or CRD ownership is unclear.
Related Skills
@kubernetes— raw manifests and pod debugging@argocd— GitOps delivery of Helm releases@docker— image build and digest promotion@github-actions— lint/template in CI
Agent Operational Directive
MANDATORY: Never ship chart changes without
helm lintandhelm templateoutput reviewed. Do not uselookupto conditionally omit resources unless ownership and upgrade behavior are explicitly designed—prefer two-chart sequential install. Keep production secrets out of Git values. Fail CI if post-render scripts can emit empty manifests.