alivirgo Helm Chart Packaging AI Skill Guide
Overview & Engine Architecture
Helm packages Kubernetes manifests as charts: templates plus a values.yaml configuration surface. Releases track what was installed; upgrades render a new revision and apply the diff. Agents write maintainable templates, keep secrets out of committed values, and always render locally before touching a cluster.
Chart.yaml + values.yaml + templates/
|
v
helm template / lint
|
v
helm upgrade --install -> Kubernetes API
|
v
release history (rollback)
When to use this skill
- Packaging repeated Kubernetes YAML into a chart
- Promoting the same chart across dev/stage/prod with value files
- Debugging failed hooks or bad template rendering
- Vendoring chart dependencies
Operational directives
- Run
helm lintandhelm templatebefore every install/upgrade. - Treat
values.yamlas public defaults; inject secrets via--set-file, sealed secrets, or external secret stores. - Pin dependency chart versions in
Chart.yaml/Chart.lock. - Prefer
upgrade --installwith an explicit--namespaceand--create-namespacewhen intentional. - Keep templates readable: named helpers in
_helpers.tpl, no copy-paste label blocks.
Chart layout
mychart/
Chart.yaml
values.yaml
values.schema.json # optional but valuable
templates/
_helpers.tpl
deployment.yaml
service.yaml
ingress.yaml
charts/ # vendored deps
Chart.lock
Chart.yaml sketch:
apiVersion: v2
name: mychart
description: Example API chart
type: application
version: 0.3.0
appVersion: "1.4.2"
dependencies:
- name: redis
version: 19.0.0
repository: https://charts.bitnami.com/bitnami
condition: redis.enabled
Command loop
helm create mychart
helm dependency update ./mychart
helm lint ./mychart
helm template mychart ./mychart -f values.prod.yaml > /tmp/render.yaml
helm upgrade --install mychart ./mychart -n apps --create-namespace -f values.prod.yaml
helm history mychart -n apps
helm rollback mychart 2 -n apps
Common failure modes
| Problem | Cause | Fix |
|---|---|---|
| YAML parse error after render | Bad indentation in template | helm template and read line |
| Hooks never complete | Job hook fails / wrong weight | kubectl logs on hook pods |
| Values ignored | Wrong -f file or nested key typo |
helm get values |
| Subchart not present | Missing dependency update |
helm dependency build |
Best practices
- Provide a
values.schema.jsonfor required keys when teams are large. - Document every non-obvious value in comments or a VALUES.md.
- Use
lookupsparingly - it makes charts cluster-dependent and harder to test. - Separate cluster-wide operators from app charts.
Limitations
- CRDs and operator installs often need special ordering beyond a single chart.
- Helm is not a secret manager; do not encode production passwords in Git values.
- Library charts and OCI registries add auth steps specific to the org.
Related skills
@kubernetes- raw manifests and debugging@argocd- GitOps delivery of Helm releases@docker- images referenced by charts