helm-generator

# Helm Chart Generator

## Overview

Generate production-ready Helm charts with best practices built-in. Create complete charts or individual resources with standard helpers, proper templating, and automatic validation.

**Official Documentation:**
- [Helm Docs](https://helm.sh/docs/) | [Chart Best Practices](https://helm.sh/docs/chart_best_practices/) | [Template Functions](https://helm.sh/docs/chart_template_guide/function_list/) | [Sprig Functions](http://masterminds.github.io/sprig/)

## When to Use This Skill

Use for creating/generating Helm charts and templates. For validation/linting of existing charts use **devops-skills:helm-validator**; for raw K8s YAML (no Helm) use **k8s-generator**.

## Chart Generation Workflow

### Stage 1: Understand Requirements

**REQUIRED: Use `AskUserQuestion`** if any of these are missing or ambiguous:

| Missing Information | Question to Ask |
|---------------------|-----------------|
| Image repository/tag | "What container image should be used? (e.g., nginx:1.25)" |
| Service port | "What port does the application listen on?" |
| Resource limits | "What CPU/memory limits should be set? (e.g., 500m CPU, 512Mi memory)" |
| Probe endpoints | "What health check endpoints does the app expose? (e.g., /health, /ready)" |
| Scaling requirements | "Should autoscaling be enabled? If yes, min/max replicas and target CPU%?" |
| Workload type | "What workload type: Deployment, StatefulSet, or DaemonSet?" |
| Storage requirements | "Does the application need persistent storage? Size and access mode?" |

**Do NOT assume values** for critical settings. Ask first, then proceed.

### Stage 2: CRD Documentation Lookup

If custom resources are needed:

1. **Try context7 MCP first:**
   ```
   mcp__context7__resolve-library-id with operator name
   mcp__context7__get-library-docs with topic for CRD kind
   ```

2. **Fallback to WebSearch:**
   ```
   "<operator>" "<CRD-kind>" "<version>" kubernetes documentation spec
   ```

See `references/crd_patterns.md` for common CRD examples.

### Stage 3: Create Chart Structure

Use the scaffolding script:
```bash
bash scripts/generate_chart_structure.sh <chart-name> <output-directory> [options]
```

**Script options:**
- `--image <repo>` - Image repository (default: nginx). **Note:** Pass only the repository name without tag (e.g., `redis` not `redis:7-alpine`)
- `--port <number>` - Service port (default: 80)
- `--type <type>` - Workload type: deployment, statefulset, daemonset (default: deployment)
- `--with-templates` - Generate resource templates (deployment.yaml, service.yaml, etc.)
- `--with-ingress` - Include ingress template
- `--with-hpa` - Include HPA template
- `--force` - Overwrite existing chart without prompting

**Important customization notes:**
- The script uses `http` as the default port name in templates. **Customize port names** for non-HTTP services (e.g., `redis`, `mysql`, `grpc`)
- Templates include checksum annotations for ConfigMap/Secret changes (conditionally enabled via `.Values.configMap.enabled` and `.Values.secret.enabled`)

### Stage 4: Generate Standard Helpers

Use the helpers script or `assets/_helpers-template.tpl`:
```bash
bash scripts/generate_standard_helpers.sh <chart-name> <chart-directory>
```

### Stage 5: Generate Templates

> **⚠️ CRITICAL REQUIREMENT: Read Reference Files NOW**
>
> You **MUST** use the `Read` tool to load these reference files **at this stage**, even if you read them earlier in the conversation:
>
> ```
> 1. Read references/resource_templates.md - for the specific resource type patterns
> 2. Read references/helm_template_functions.md - for template function usage
> 3. Read references/crd_patterns.md - if generating CRD resources (ServiceMonitor, Certificate, etc.)
> ```
>
> **Why:** Prior context may be incomplete or summarized. Reading reference files at generation time guarantees all patterns, functions, and examples are available for accurate template creation.
>
> **Do NOT skip this step.** Template quality depends on having current reference patterns loaded.

Reference templates for all resource types in `references/resource_templates.md`:
- Workloads: Deployment, StatefulSet, DaemonSet, Job, CronJob
- Services: Service, Ingress
- Config: ConfigMap, Secret
- RBAC: ServiceAccount, Role, RoleBinding, ClusterRole, ClusterRoleBinding
- Network: NetworkPolicy
- Autoscaling: HPA, PodDisruptionBudget

**Key patterns (MUST include in all templates):**
```yaml
# Use helpers for names and labels
metadata:
  name: {{ include "mychart.fullname" . }}
  labels: {{- include "mychart.labels" . | nindent 4 }}

# Conditional sections with 'with'
{{- with .Values.nodeSelector }}
nodeSelector: {{- toYaml . | nindent 2 }}
{{- end }}

# Checksum annotation (REQUIRED for Deployments/StatefulSets/DaemonSets to trigger restarts on config changes)
annotations:
  checksum/config: {{ include (print $.Template.BasePath "/configmap.yaml") . | sha256sum }}
```

### Stage 6: Create values.yaml

**Structure guidelines:**
- Group related settings logically
- Document every value with `# --` comments
- Provide sensible defaults
- Include security contexts, resource limits, probes

See `assets/values-schema-template.json` for JSON Schema validation.

### Stage 7: Validate

Run validation using **devops-skills:helm-validator** skill (helm lint, template render, schema checks, dry-run).

## Template Functions Quick Reference

See `references/helm_template_functions.md` for complete guide.

| Function | Purpose | Example |
|----------|---------|---------|
| `required` | Enforce required values | `{{ required "msg" .Values.x }}` |
| `default` | Fallback value | `{{ .Values.x \| default 1 }}` |
| `quote` | Quote strings | `{{ .Values.x \| quote }}` |
| `include` | Use helpers | `{{ include "name" . \| nindent 4 }}` |
| `toYaml` | Convert to YAML | `{{ toYaml .Values.x \| nindent 2 }}` |
| `tpl` | Render as template | `{{ tpl .Values.config . }}` |
| `nindent` | Newline + indent | `{{- include "x" . \| nindent 4 }}` |

## Working with CRDs

See `references/crd_patterns.md` for complete examples. Ship CRDs in `crds/` directory (not templated); template CR instances in `templates/`.

## Converting Manifests to Helm

1. Parameterize names (use helpers) and extract values
2. Apply label/conditional patterns, use `toYaml` for complex objects
3. Create `_helpers.tpl` with standard helpers
4. Validate with **devops-skills:helm-validator**

## Error Handling

| Issue | Solution |
|-------|----------|
| Template syntax errors | Check `{{-` / `-}}` matching, use `helm template --debug` |
| Undefined values | Use `default` or `required` functions |
| Indentation issues | Use `nindent` consistently |
| CRD validation fails | Verify apiVersion, check docs for required fields |

## Post-Generation Validation

After generating charts, invoke **devops-skills:helm-validator** to ensure quality.

## Anti-Patterns

### NEVER hardcode image tags in `values.yaml`

- **WHY**: Pinning to `:latest` or a hard-coded version in the chart prevents version overrides at deploy time.
- **BAD**: `image: repository: myapp tag: latest`
- **GOOD**: `image: repository: myapp tag: ""` with `appVersion` as the default, overridden via `--set image.tag=v1.2.3`.

### NEVER omit `resources:` limits and requests on containers

- **WHY**: Containers without resource constraints are evicted unpredictably under node pressure and cannot be scheduled by the Kubernetes cluster autoscaler.
- **BAD**: No `resources:` block in the container spec template.
- **GOOD**: Set both `requests` and `limits` for CPU and memory, with documented tuning guidance in `values.yaml`.

### NEVER use `helm upgrade --install` without `--atomic` in CI/CD

- **WHY**: Without `--atomic`, a failed upgrade leaves the release in a broken state that blocks future upgrades and requires manual `helm rollback`.
- **BAD**: `helm upgrade --install myapp ./chart`
- **GOOD**: `helm upgrade --install --atomic --timeout 5m myapp ./chart`

### NEVER place environment-specific values inside the chart's default `values.yaml`

- **WHY**: Mixing production values into the chart couples the chart to one environment.
- **BAD**: Production database URLs in `values.yaml`.
- **GOOD**: Use a layered values approach: `values.yaml` for defaults, `values-prod.yaml` for overrides, `-f values-prod.yaml` at deploy time.

### NEVER skip `helm template` + `kubeval`/`kubeconform` validation

- **WHY**: A chart that renders without error can still produce invalid Kubernetes manifests.
- **BAD**: Only run `helm lint` before deploying.
- **GOOD**: `helm template . | kubeval --strict --ignore-missing-schemas` to validate rendered manifests against the Kubernetes API schema.

## References

### Scripts

| Script | Usage |
|--------|-------|
| `scripts/generate_chart_structure.sh` | `bash <script> <chart-name> <output-dir>` |
| `scripts/generate_standard_helpers.sh` | `bash <script> <chart-name> <chart-dir>` |

### References

| File | Content |
|------|---------|
| `references/helm_template_functions.md` | Complete template function guide |
| `references/resource_templates.md` | All K8s resource templates |
| `references/crd_patterns.md` | CRD patterns (cert-manager, Prometheus, Istio, ArgoCD) |

### Assets

| File | Purpose |
|------|---------|
| `assets/_helpers-template.tpl` | Standard helpers template |
| `assets/values-schema-template.json` | JSON Schema for values validation |