helm-conventions

Files (1)

• SKILL.md

SKILL.md (first lines)

# Helm chart conventions

**Always:**

- Expose `extraEnv`, `extraVolumes`, and `extraVolumeMounts` in `values.yaml`
  with empty defaults (`[]`) and wire them into every relevant workload
  template (Deployment, StatefulSet, Job, etc.).
- Define pod and container security context in `values.yaml`, defaulting to
  a **restricted** profile aligned with Kubernetes Pod Security Standards:
  ```yaml
  podSecurityContext:
    runAsNonRoot: true
    runAsUser: 65532
    runAsGroup: 65532
    fsGroup: 65532
    seccompProfile:
      type: RuntimeDefault
  securityContext:
    allowPrivilegeEscalation: false
    readOnlyRootFilesystem: true
    capabilities:
      drop:
        - ALL
  ```
  The IDs must be **> 10000** (Trivy `KSV-0020` / `KSV-0021`: a low container
  UID collides with the host's user table). 65532 is the `nonroot` UID used
  by distroless and Chainguard images — keep it in sync with the `USER` baked
  into the image (see `docker-conventions`), otherwise a
  `readOnlyRootFilesystem` pod hits permission errors on its own state
  directory.
- Lay out `templates/` with **one Kubernetes object per file**, and
  derive every filename from the object's `kind` in kebab-case (split
  CamelCase on word boundaries, replace spaces with hyphens, lowercase —
  e.g. `ClusterRoleBinding` → `cluster-role-binding.yaml`,
  `MutatingWebhookConfiguration` → `mutating-webhook-configuration.yaml`).
  How files are grouped depends on how many objects a component renders:
  - A component that renders **two or more** objects gets its own
    directory `templates/<component>/` (matching its `values.yaml`
    block), with one kind-named file per object — e.g.
    `templates/api/deployment.yaml`, `templates/api/service.yaml`.
  - When a component renders **two or more objects of the same Kind**,
    nest those in a per-kind subdirectory
    `templates/<component>/<kind>/<qualifier>.yaml`. The directory carries
    the Kind, so each file is named by its distinguishing qualifier only —
    e.g. four Secrets become `templates/api/secret/database.yaml`,
    `.../jwt.yaml`, `.../oidc.yaml`, `.../bootstrap-admin.yaml`. This is
    Kind-agnostic: it applies equally to multiple Services
    (`templates/api/service/grpc.yaml`, `.../http.yaml`), ConfigMaps,
    `Job`s, etc. A Kind with a single instance in that component stays flat
    as `templates/<component>/<kind>.yaml` (one Service → `service.yaml`,
    not `service/http.yaml`).
  - A component that renders a **single** object — typically shared
    infrastructure such as an `Ingress`, a Gateway route, or a database
    `Cluster` — gets **no directory**: put the file at the root,
    `templates/<kind>.yaml` (e.g. `templates/ingress.yaml`,
    `templates/http-route.yaml`, `templates/cnpg-cluster.yaml`). Qualify
    the bare Kind with the component name when the Kind alone would be
    ambiguous (the generic `Cluster` → `cnpg-cluster.yaml`).
  Never place one component's template under another component's directory.
- Give **each component its own `ServiceAccount`** (and its own
  `ClusterRole` + `ClusterRoleBinding`, in separate files, when it needs
  cluster RBAC) so components stay least-privilege and independent.
- When a chart attaches a route to shared gateway infrastructure, create
  **only the route resource** and attach it to a **pre-existing** gateway
  referenced by name (and namespace) via `values.yaml`. This applies to
  Gateway API and Envoy (AI) Gateway: create the `MCPRoute` / `HTTPRoute` /
  `GRPCRoute`, but **never** the `Gateway` or `GatewayClass`. Make the
  gateway name **required** (`required` in the template / helper) so the
  chart fails fast when it is missing, and default the gateway namespace to
  the release namespace. The `Gateway` and `GatewayClass` are
  cluster-shared infrastructure owned outside the app chart.
- Structure `values.yaml` as exactly two kinds of top-level blocks: a
  `global:` block holding values shared by more than one component, plus
  one `<component>:` block per app/component holding that component's
  own values. As soon as a knob is needed by **two or more components**,
  it must live in `global:` at the top level — never duplicated across
  the component blocks, and never moved into one component's block
  "because that's where it's mostly used". Conversely, values used by a
  single component live only in that component's block. Every `global.*`
  key must be **overridable per component** by setting the same key in
  that component's block (resolve via a deep-merge helper:
  `mergeOverwrite (deepCopy global) (pick component …)`), so a component
  can deviate from a shared default without forcing the value to move
  out of `global`.
- **Group values by domain into a nested object as soon as two or more
  keys concern the same concern.** Within any block (`global:` or a
  component), when more than one key relates to the same domain
  (database, OIDC, TLS, signing keys, a sidecar, …), nest them under a
  single object named for that domain instead of leaving a flat run of
  prefixed scalars. Drop the now-redundant prefix from each sub-key —
  the object name carries it. For example, prefer
  ```yaml
  database:
    # -- (string) Connection string. Unset → built from the managed cluster.
    url: ~
    existingSecret:
      # -- (string) Name of a pre-existing Secret holding the connection string. Set → takes precedence over the generated one.
      name: ~
      # -- Key in that Secret holding the connection string.
      key: DATABASE_URL
    # -- Maximum size of the connection pool.
    maxConns: 25
    # -- Minimum number of idle pooled connections.
    minConns: 5
  ```
  over the flat `databaseUrl` / `databaseUrlSecret` / `dbMaxConns` /
  `dbMinConns`. A lone key for a domain stays flat — only group once the
  second related key appears (the rule of two for grouping). The object's
  shape still maps cleanly onto its env vars / flags at the template
  boundary (e.g. `database.maxConns` → `DATABASE_MAX_CONNS`); grouping is a
  `values.yaml` ergonomics rule, it does not change the wire/env contract.
- **An `existingSecret` value is always an object `{ name, key }`, never a
  bare string.** Whenever a chart lets the user point at a pre-existing
  Secret instead of generating one, model it as a nested object: `name`
  (default `~` — unset means "generate the Secret from the inline value")
  and `key` (the entry to read, defaulting to the same key the generated
  Secret would use, e.g. `DATABASE_URL` / `UPSTREAM_HEADERS`). A bare
  `existingSecret: ~` string hardcodes the key and cannot consume a Secret
  whose entry is named differently — which is exactly the case

From leroyguillaume/claude, MIT.

More from leroyguillaume/claude