---

name: helm-chart-developer description: | Helm chart authoring, values.yaml design, GitOps with Flux HelmRelease, External Secrets Operator integration. Use for creating and debugging Helm charts.

Helm Chart Developer

Purpose / When to Use

Use this skill when:

• Creating new Helm charts from scratch
• Converting raw Kubernetes manifests to Helm
• Designing values.yaml API and schema
• Setting up GitOps deployment with Flux HelmRelease
• Integrating External Secrets Operator (ESO)
• Debugging helm template, helm lint, helm install --dry-run
• Setting up multi-environment overlays (dev/prod)

Version & API Compatibility

Always use these API versions:

Target baseline: Kubernetes 1.29+, Helm 3.14+, Flux v2.3+, ESO 0.10+

Rule: If adding manifests, ALWAYS use these API versions. If CRD/apiVersion mismatch detected in repo, STOP and propose migration plan.

See VERSIONS.md for full compatibility matrix.

Definition of Done (DoD)

Before completing any Helm chart work:

1. Linting: helm lint . passes
2. Template rendering: helm template <release> . succeeds
3. Schema validation (optional): helm template . | kubeconform -strict
4. Dry-run: helm install <release> . --dry-run --debug works
5. Two secrets modes validated:
   • GitOps mode: --set secrets.existingSecretName=<name>
   • Chart-managed ESO: --set secrets.externalSecret.enabled=true
6. API versions match the compatibility table above

Run /helm-validate to execute all checks.

Step-by-Step Workflow

1. Chart Structure

Copycharts/app/
├── Chart.yaml
├── values.yaml
├── templates/
│   ├── _helpers.tpl
│   ├── deployment.yaml
│   ├── service.yaml
│   ├── ingress.yaml
│   ├── externalsecret.yaml  # optional, gated
│   ├── hpa.yaml
│   ├── pdb.yaml
│   └── serviceaccount.yaml

2. Values API Contract

See reference-gitops-eso.md for full details.

Key sections:

• image: repository, tag, pullPolicy
• secrets: existingSecretName, externalSecret.*, inject.envFrom
• service: enabled, type, port
• ingress: enabled, className, hosts, tls
• resources: requests, limits
• autoscaling: enabled, minReplicas, maxReplicas

3. Secrets Integration

Mode A: ExternalSecret in Overlay (Recommended)

Chart only references secret by name:

Copy# values.yaml
secrets:
  existingSecretName: "app-secrets"
  inject:
    envFrom: true

ExternalSecret lives in GitOps overlay, not in chart.

Mode B: Chart-Managed ExternalSecret (Optional)

Chart renders ExternalSecret when enabled:

Copysecrets:
  externalSecret:
    enabled: true
    refreshInterval: 1h
    refreshPolicy: OnChange
    secretStoreRef:
      kind: ClusterSecretStore
      name: aws-secrets-manager
    dataFrom:
      extractKey: "fce/dev/app"
    target:
      name: "app-secrets"
      creationPolicy: Owner

Secrets Determinism (ESO)

refreshPolicy options:

Default rule: Use refreshPolicy: OnChange for predictable GitOps-driven updates.

Manual refresh (debug/runbook):

Copykubectl annotate es <name> force-sync=$(date +%s) --overwrite

4. Flux + Kustomize Recipe

Values Composition Order (important!):

1. Chart defaults (charts/app/values.yaml)
2. Environment values (apps/dev/app/values.yaml)
3. ConfigMap via Kustomize generator
4. HelmRelease valuesFrom references ConfigMap
5. HelmRelease spec.values patches (highest priority)

See snippets:

• flux-helmrelease.base.yaml
• flux-helmrelease.dev.patch.yaml
• kustomize.configmapgenerator.yaml

Critical Kustomize settings:

CopygeneratorOptions:
  disableNameSuffixHash: true  # MUST have, otherwise names change on every apply

Flux Ordering

Use spec.dependsOn in HelmRelease when app depends on:

• CRDs (external-secrets, cert-manager)
• ExternalSecrets/SecretStores
• Ingress controllers, databases

Example:

Copyspec:
  dependsOn:
    - name: external-secrets
      namespace: external-secrets

5. ESO Patterns

ClusterSecretStore (cluster-wide):

CopyapiVersion: external-secrets.io/v1
kind: ClusterSecretStore
metadata:
  name: aws-secrets-manager
spec:
  conditions:
    - namespaceSelector:
        matchLabels:
          eso.fce.global/enabled: "true"
  provider:
    aws:
      service: SecretsManager
      region: me-central-1

ExternalSecret (per app/env):

CopyapiVersion: external-secrets.io/v1
kind: ExternalSecret
spec:
  refreshPolicy: OnChange  # GitOps-deterministic
  secretStoreRef:
    kind: ClusterSecretStore
    name: aws-secrets-manager
  dataFrom:
    - extract:
        key: fce/dev/app
  target:
    name: app-secrets
    creationPolicy: Owner

6. Pitfalls

• CRD ordering: ESO CRDs must exist before ExternalSecret. Use Flux Kustomization dependsOn.
• OpenAPI validation: Use install.disableOpenAPIValidation: true in HelmRelease if needed.
• NEVER put secrets in values.yaml: No passwords, tokens, API keys, credentials. Only references to Secret/ExternalSecret names. This is non-negotiable.

Examples

Prompts that should activate this skill:

1. "Create a Helm chart for my Node.js app"
2. "Convert these Kubernetes manifests to Helm"
3. "Add External Secrets integration to my chart"
4. "Set up Flux HelmRelease for my app"
5. "Debug why helm template is failing"
6. "Design values.yaml schema for multi-environment deployment"
7. "Add ingress with TLS to my Helm chart"
8. "Integrate AWS Secrets Manager with my chart"
9. "Set up Kustomize overlays for dev and prod"
10. "Fix helm lint errors in my chart"

Anti-Patterns

Related Files

• VERSIONS.md - Version compatibility matrix
• reference-gitops-eso.md - Full GitOps + ESO reference
• snippets/ - Ready-to-use YAML snippets

Version History

• 1.1.0 — Add version compatibility, secrets determinism, Flux ordering
• 1.0.0 — Initial release with Flux + ESO patterns