EN-11919: add chart lint, values schema, and CI tooling (1 of 2)

[thefirstofthe300]

Adds automated linting and values-schema validation to both charts, plus the scaffolding the docs generation in PR 2 builds on. Follows the pattern already used in helm-platform — adapted rather than copied, since that repo's charts sit two directory levels deep, it has no make setup, and it enforces sync through pre-commit alone with no CI job.

PR 1 of 2. This lands tooling and schemas; #2 lands the generated README values tables. The split falls here on purpose: the ~40 hand-written schema lines below carry the entire consumer-facing regression risk, and reviewing them alongside ~1,550 lines of mechanical description comments would mean reviewing both at the same attention level.

What changes for chart consumers

Both charts now ship a values.schema.json, so Helm validates values at lint/template/install and rejects a malformed value with its path named, instead of failing deep inside template rendering or producing an invalid object that only fails at apply.

That is a real behavior change for people outside this repo, so the schemas are deliberately permissive: additionalProperties: false and required are not emitted at either schema root. Thirteen inline @schema annotations correct types the generator cannot infer — blank sentinels that would otherwise be typed null-only and reject any real value, and both maxUnavailable fields, which Kubernetes treats as IntOrString but which infer from whichever literal each workload happens to default to.

Without those annotations a naively generated schema rejects seven configurations this chart's own README documents as valid, including --set-file ssl.certFile and the BottleRocket seLinuxOptions example.

Why CI runs two Helm versions

lint and schema are matrixed over Helm 3.17.0 and 4.3.0 with fail-fast: false, because the two validate schemas with different JSON Schema dialects. Helm 3 follows draft-07, where keywords sitting beside a $ref are ignored; Helm 4 applies them.

gremlin.podSecurity.seLinuxOptions has no live default keys to infer a shape from, so it references a hand-written fragment. Measured across both majors:

Form	Helm 4	Helm 3.17
nullable fragment + sibling type — what this ships	ok	ok
sibling type only	breaks the documented BottleRocket config	ok
empty sibling type: []	chart uninstallable under any values	ok
non-nullable fragment	ok	breaks a stock default install

Each wrong variant is fully green on the major it does not break. That is why the matrix is required rather than nice to have, and why hooks/assert-helm-version.sh fails loudly when a Helm binary is missing rather than silently testing one major twice — a half-running matrix is worse than none, because it manufactures the appearance of coverage.

helm plugin install is also not portable: Helm 4 refuses an unverifiable source without --verify=false, and Helm 3.17 has no such flag. hooks/install-schema-plugin.sh probes --help for the flag rather than parsing a version, which degrades sanely on a future major in either direction.

Local workflow

make setup installs any missing tooling at its pinned version, and never replaces or upgrades a tool you already have, at any version. It warns instead — naming the tool, the version found and the version expected — so a later drift failure is debuggable rather than mysterious. The pre-commit hooks warn on the same mismatch rather than failing, since a hard failure there would block commits for exactly the contributor that tolerance exists for.

make lint / schema / docs / check / test all run the same scripts CI runs, so local and CI cannot drift apart by construction.

Two Helm behaviors worth knowing

• helm lint --strict does not propagate a chart's fail() call — it logs it and reports success. It is therefore not a backstop for the mutual-exclusion checks in _helpers.tpl; only helm template, install or unittest surface those.
• helm-docs with no README.md.gotmpl present does not no-op — it falls back to its own default template and overwrites hand-written READMEs wholesale. hooks/helm-docs.sh generates only for charts that have a template, which is what lets this PR ship the tooling without touching either README.

Verification

• helm unittest: 253/253 across both charts. The two terminationGracePeriodSeconds cases asserting that a string renders literally are superseded — the schema rejects that input before rendering — and now assert the rejection, alongside the existing cases proving a valid integer is accepted, so the field is covered on both sides of the schema boundary. They match on the value path only, since Helm 3 and 4 word the rejection differently.
• The documented-configuration corpus — stock defaults for both charts, the READMEs' own helm install examples, and all thirteen annotated paths — renders under both Helm majors, positively and negatively.
• helm lint --strict passes on both charts, with and without the ci/linting/*.yaml overrides, on both majors.

tests/contract/ holds executable checks for the above, runnable directly. They need a Helm 3 and a Helm 4 binary and will refuse to run with only one rather than silently testing a single major.

For whoever merges

The six matrix-expanded checks need adding to the master branch protection rule, and marking only the v3.17.0 legs required would silently void the point — the 4.3 leg would run, go red, and merge anyway. Check names embed the matrix values, so bumping a pin renames a required check and the rule must be updated in the same change. This is a configuration step invisible in the diff, which makes it the easiest thing here to get wrong.

The cert/key values in ci/linting/*.yaml are deliberately not real PEM — the chart base64-encodes that material without parsing it, so a placeholder exercises the same render path without putting a private key in a public repository.

🤖 Generated with Claude Code

https://claude.ai/code/session_01L3TrXY8bWRGNv3aRFZZwGZ