Helm bjw-s Chart Generator

Published as helm-chart-generator until v2.x. Update anything still pointing at the old name.

Library version matrix

Everything documented here works on common 5.x by default. When a pattern is not available on 4.x it's tagged `(5.x only)` so agents pinned to the legacy track can skip it. See references/migration-4-to-5.md for the full 4 → 5 upgrade procedure.

New in common 5.3

5.3.0 (2026-10-10) is drop-in over 5.2.x: no values change is required to upgrade, and the Kubernetes and Helm minimums are unchanged.

1. `namespace.create: true` renders a v1/Namespace named after the

release namespace, before every other resource. namespace.labels and namespace.annotations are optional (keys and values are templated).

   namespace:
     create: true
     labels:
       pod-security.kubernetes.io/enforce: restricted

1. `controllers.<id>.extraSelectorLabels` adds labels that identify the

controller's pods. They land in the pod labels and in every generated selector (workload matchLabels, Services, native and Cilium policies, PodMonitor, PodDisruptionBudget, default topologySpreadConstraints).

   controllers:
     main:
       extraSelectorLabels:
         app.kubernetes.io/component: backend

Workload selectors are immutable: adding or changing this on a live Deployment or StatefulSet means deleting and recreating the workload. The resource-level extraSelectorLabels (Service, NetworkPolicy, ...) still only affect that resource's own selector.

1. Native `COMMAND` probes. probes.<n>.command (array of strings)

renders exec.command, and type gains COMMAND. The type defaults to COMMAND when command is set and type is absent or AUTO. No port is emitted. type: COMMAND without command fails the render. The old custom: true plus raw spec.exec workaround is no longer needed.

   probes:
     liveness:
       enabled: true
       command: ["/usr/bin/healthcheck", "--timeout=3"]

1. Templated keys. The keys of annotations, labels and

extraSelectorLabels maps go through tpl too, not only the values.

1. `global.templateEvaluation` controls multi-pass templating.

passes (integer >= 1, default 1) re-evaluates a string when a templated value itself produces {{ }}, and stops early once a pass changes nothing. excludePaths lists paths (each a list of map keys or array indexes, as strings) that are left untouched with their descendants, for values that must keep a literal {{ }}.

   global:
     templateEvaluation:
       passes: 2
       excludePaths:
         - [controllers, main, containers, main, env, VPN_PORT_FORWARDING_UP_COMMAND]

1. Controller references in network policies. On

networkpolicies.<id> (all three types), controllers: [<id or regex>] targets several controllers. Entries are exact identifiers or regular expressions anchored as ^(<expr>)$. It is mutually exclusive with controller, podSelector and endpointSelector. A reference that matches no enabled controller fails the render and lists the available identifiers.

• Native rules: a peer in rules.ingress[].from[] or

rules.egress[].to[] may carry controllers: [...] (expands to that peer's podSelector, exclusive with podSelector and ipBlock; the singular controller is not valid inside a peer).

• Cilium and ciliumClusterwide rules: ingress[].fromControllers and

egress[].toControllers expand into fromEndpoints / toEndpoints.

   networkpolicies:
     api:
       controllers: ["api", "^worker-.*$"]
       policyTypes: [Ingress]
       rules:
         ingress:
           - from:
               - controllers: ["frontend"]
             ports:
               - port: 8080

Three fixes ride along. Global metadata is now the base and resource-level labels / annotations override it (the reverse on Services and several other resources). Pod labels and generated selectors share one helper, so selector labels are merged last and always win over user pod labels. clusterIP is now rendered for LoadBalancer and NodePort Services (still omitted for ExternalName).

Earlier 5.x additions

Worked examples for most of these live in references/patterns.md.

• 5.2.0 (2026-09-16): externalSecrets (with

defaultExternalSecretStoreRef) generates ExternalSecret resources; networkpolicies.<id>.type: cilium / ciliumClusterwide renders Cilium policies (native is the default); listenerSets adds initial Gateway API ListenerSet support; controllers get default topologySpreadConstraints selectors; persistence.<id>.type: projected is native; string fields are templated globally, so {{ }} works in more places. A bugfix made NetworkPolicy extraSelectorLabels take precedence over generated selector labels.

• 5.1.0: DaemonSets accept strategy / rollingUpdate (silently

ignored on 5.0.x); serviceAccount.<id>.automountServiceAccountToken sets the field on the SA itself; route.<id>.namespaceOverride deploys a Route into another namespace and emits the ReferenceGrant (route.<id>.referenceGrant.enabled: false turns that off); rollingUpdate takes the upstream maxSurge / maxUnavailable; StatefulSets gained rollingUpdate.maxUnavailable, which needs the MaxUnavailableStatefulSet feature gate (alpha, off by default up to Kubernetes 1.34, beta from 1.35). An invalid strategy is now rejected by the values schema, so helm lint catches it earlier.

Two behavioural notes still bite. The surge / unavailable shorthands are deprecated and removed in 6.0. The library always writes automountServiceAccountToken into the pod spec (default false) and the pod spec wins over the ServiceAccount key, so set both.

Migration 4.x → 5.x at a glance

Five things to know — full details in references/migration-4-to-5.md:

1. `automountServiceAccountToken: false` is now the default. Flip it

back to true per-pod if the workload needs to call the Kubernetes API.

1. A default unprivileged ServiceAccount is created for every release.

Opt out with global.createDefaultServiceAccount: false when you reference an externally-managed SA.

1. `rawResources` was restructured — manifest content moved out of

spec: into a manifest: wrapper, and labels/annotations now live under metadata:. Only relevant if you use rawResources (rare).

1. ServiceMonitor / PodMonitor `jobLabel` defaults to

app.kubernetes.io/name. Override if your Prometheus rules depended on the old metadata.name default.

1. Minimums bumped: Kubernetes ≥ 1.31, Helm ≥ 3.18.

Quick Start Workflow

1. Understand the app. Image, ports, environment, storage (config,

data, logs), ingress, and whether sidecars or init containers apply.

1. Generate the base from assets/templates/: Chart.yaml,

values.yaml, templates/common.yaml, templates/NOTES.txt.

1. Build `values.yaml` in order: controllers and containers, then

services, ingress, persistence, secrets and configMaps.

1. Validate: helm dependency update (writes Chart.lock), then

validate_chart.py, then helm lint and helm template.

Core Structure

my-app/
├── Chart.yaml           # Metadata and dependencies
├── values.yaml          # Configuration
└── templates/
    ├── common.yaml      # Includes the bjw-s library
    └── NOTES.txt        # Post-install instructions

templates/common.yaml is always exactly one line: {{- include "bjw-s.common.loader.all" . }}. NOTES.txt covers how to reach the app, default credentials if any, and the next configuration step.

Chart.yaml

apiVersion: v2
name: <app-name>
description: <brief description>
type: application
version: 1.0.0
appVersion: "<app version>"
dependencies:
  - name: common
    repository: https://bjw-s-labs.github.io/helm-charts
    version: 5.3.0  # Default. Pin to 4.6.2 for legacy clusters (K8s < 1.31 / Helm < 3.18).

values.yaml Structure

Follow this order for clarity:

# 1. Default Pod options (optional)
defaultPodOptions:
  # 5.x default is false; set to true only if the pod calls the K8s API.
  automountServiceAccountToken: false
  securityContext: {}
  annotations: {}

# 2. Controllers (required)
controllers:
  main:  # or custom name
    containers:
      main:  # or custom name
        image: {}
        env: {}
        probes: {}

# 3. Service (required if exposing)
service:
  main:
    controller: main
    ports: {}

# 4. Ingress (optional)
ingress:
  main:
    className: ""
    hosts: []

# 5. Persistence (optional)
persistence:
  config:
    type: persistentVolumeClaim
    # or: emptyDir, configMap, secret, nfs, hostPath, ephemeral

# 6. ConfigMaps/Secrets (optional)
configMaps: {}
secrets: {}

Common Patterns

The baseline, a single container with a service and a PVC:

controllers:
  main:
    containers:
      main:
        image:
          repository: nginx
          tag: "1.25-alpine"
          pullPolicy: IfNotPresent

service:
  main:
    controller: main
    ports:
      http:
        port: 80

persistence:
  config:
    type: persistentVolumeClaim
    accessMode: ReadWriteOnce
    size: 1Gi
    globalMounts:
      - path: /config

A sidecar is one more entry under containers: with dependsOn: <container> to order startup.

See references/patterns.md for worked examples:

• Multi-controller setups
• Init containers
• VPN sidecars (gluetun)
• Code-server sidecars
• Shared volumes between containers
• Private registries with imagePullSecrets
• StatefulSets with headless service

Plus one section per version-gated key listed below.

Version-gated features

These are ignored or rejected below the version in the Since column. Each has a worked example in references/patterns.md:

Best Practices

These shape every generated chart. The reasoning, and the long form, are in references/best-practices.md.

• Pin image tags, never :latest. Requests and limits on every

container. Liveness and readiness probes at minimum.

• Non-root securityContext. Secrets for sensitive data,

imagePullSecrets for private registries.

• Reference services by identifier, not by name.
• Name controllers and containers for what they do, not main; name

services after their controller or their purpose.

• Keep automountServiceAccountToken: false (the 5.x default). When the

workload genuinely calls the K8s API, pair it with an explicit ServiceAccount and RBAC rather than the auto-created default.

• globalMounts for simple cases, advancedMounts for multi-container,

existingClaim for pre-created PVCs, type: ephemeral for scratch space tied to the pod (5.x only).

Validation

After generating a chart:

# 1. Fetch dependencies (required before helm commands)
cd /path/to/chart
helm dependency update

# 2. Validate structure
uv run skills/helm-bjw-s-chart/scripts/validate_chart.py /path/to/chart
# Or with JSON output for CI:
uv run skills/helm-bjw-s-chart/scripts/validate_chart.py --json /path/to/chart

# 3. Helm validation
helm lint .
helm template . --debug

# 4. Dry-run installation
helm install --dry-run --debug my-release .

The validator warns when the chart still pins common 4.x, when rawResources uses the legacy spec: shape (removed in 5.x), when an external ServiceAccount is referenced without global.createDefaultServiceAccount: false, when Chart.lock is missing, or when a declared dependency has no vendored tarball under charts/.

Pre-Deploy Checklist

Before deploying to a cluster, verify:

• [ ] All image tags are pinned (no :latest)
• [ ] Resources (requests + memory limits) are set on every container
• [ ] Health probes configured (liveness + readiness minimum)
• [ ] securityContext set: non-root, readOnlyRootFilesystem, drop ALL capabilities
• [ ] automountServiceAccountToken: false unless explicitly needed
• [ ] If using an external ServiceAccount, global.createDefaultServiceAccount: false is set
• [ ] If rawResources is in play, manifest uses the 5.x manifest: wrapper (not legacy spec:)
• [ ] Secrets reference external sources, not hardcoded values
• [ ] helm dependency update run, with Chart.lock and the populated charts/ published (see Publishing the Chart)
• [ ] helm lint passes with no errors

Publishing the Chart

A published chart must be self-contained: both Chart.lock and a populated charts/ have to be present before helm package runs, or offline consumers cannot resolve the common library. Run helm dependency update first, then package. Either commit charts/ to git, or gitignore it and run helm dependency build in the pipeline.

Full rationale and the two strategies: references/best-practices.md, section "Publishing and Dependency Vendoring".

Common Issues

Services not found: Use identifier not name in ingress paths Mounts not working: Check globalMounts vs advancedMounts usage Names too long: Use nameOverride or fullnameOverride in global settings Controller not starting: Check dependsOn order for init/sidecar containers Unexpected ServiceAccount appears (5.x): Set global.createDefaultServiceAccount: false or define your own SA Pod can't talk to the K8s API (5.x): Set automountServiceAccountToken: true on the pod AND grant RBAC `strategy` rejected by `helm lint` (5.1+): It is a string, never a map, and the valid values depend on the controller type Cross-namespace Route can't reach the Service: The ReferenceGrant is only emitted from namespaceOverride, not from a hand-written backendRefs.namespace

References

• references/migration-4-to-5.md - Full 4 → 5 upgrade procedure
• references/patterns.md - Common deployment patterns, including Gateway API HTTPRoute
• references/best-practices.md - Kubernetes/Helm best practices
• references/values-schema.md - Complete values.yaml reference
• references/compose-mapping.md - Docker Compose → bjw-s values.yaml mapping
• assets/templates/ - Base templates for quick start