feat(helm): global values, and the registry/repository image split

[jjamroga]

What this gives operators

This PR adds a global: block. Each install-wide setting becomes one value. Helm passes global.* into subcharts automatically. A parent chart that vendors kmcp (kagent does) sets each value once for its whole install.

• global.imageRegistry — for air-gapped and private-registry installs. Mirror the image, then set this one value. The chart pulls <your-registry>/kagent-dev/kmcp/controller. The image path is identical on every registry. A mirror copies the image where it already lives.
• global.imagePullSecrets — the pull secret that mirror needs. The chart merges it (union) into the pod's own list. A local secret is never removed.
• global.imagePullPolicy — one pull policy for the install. An explicitly set image.pullPolicy still wins.
• global.watchNamespaces — a namespace-scoped install in one value. A non-empty list renders Roles instead of ClusterRoles. The controller's --watch-namespaces derives from the same list. RBAC scope and watch scope cannot disagree.

The breaking change

image.repository was one string that carried its registry: ghcr.io/kagent-dev/kmcp/controller. It is now split. image.registry holds the registry host. image.repository holds the image path. The other kagent-family charts use this same shape. The shared shape is what makes one mirror value work across all of them.

Who this breaks: values files that relocated the image by overriding repository with a host-carrying string.

How the break stays safe: it cannot fail silently. A naive render would prepend the default registry onto the old-shape override. The doubled path would fail only at pod start, as ImagePullBackOff. Instead, the render fails at template time. The error names the fix:

image.repository ("my.registry.example/platform/kmcp-controller") carries a
registry host. It is now the image path only: move the host into
image.registry (or global.imageRegistry) and keep repository as the path,
e.g. registry: ghcr.io, repository: kagent-dev/kmcp/controller.

The operator sees one loud helm upgrade error. The message contains the migration. No pod fails to pull. Operators who do not override repository are untouched. A default render is byte-identical to main.

We considered a host-detection heuristic instead: use repository as-is when its first segment looks like a registry. That keeps old files rendering. It also embeds the heuristic in the default render path forever. It silently ignores image.registry whenever the old shape appears. That trades one loud migration for a permanent class of quiet misconfiguration. Loud and once won.

Other compatibility notes

• An explicit rbac.namespaces: [] opts out of the global. An empty list has always meant "create ClusterRoles". The global is only a fallback, so it must not override that choice. But Helm's coalesce cannot see the choice: it skips empty values, so [] and "not set" look the same. The chart therefore checks key presence instead. Example: a parent sets global.watchNamespaces: [team-a, team-b] to scope its other subcharts. A kmcp values file contains rbac.namespaces: []. That file keeps its ClusterRoles. Without the presence check, the same upgrade would silently replace them with Roles in team-a and team-b, and the controller would lose access everywhere else. One consequence: values.yaml no longer declares namespaces: [] as a default. A declared empty default would make every install look explicitly cluster-scoped, and the global fallback would never fire. The key now ships commented out, with this explanation next to it.
• A global that omits kmcp's namespace does not break the install. The chart needs a Role in its own namespace: the controller's leader election and its manager Role live there. A parent may set global.watchNamespaces for its other subcharts and forget kmcp's namespace. Failing the render for that would brick the whole umbrella install over a list that was never about kmcp. The operator would then have to add kmcp's namespace to a global list every other chart also reads. So on the global path, the chart auto-appends its install namespace to the resolved scope. The hard error remains for an explicit rbac.namespaces: there the operator is talking about this chart, and a list without the install namespace is a real mistake worth stopping.
• image.pullPolicy no longer declares IfNotPresent in values. The template's fallback chain ends at IfNotPresent instead. The rendered output is the same. The reason for the move: a declared default is always "set", so global.imagePullPolicy could never fire. With the default in the template, the global fallback is reachable.

Verification

A default render is byte-identical to main. Each behavior is verified by render: the mirror override, a local image.registry override, the old-shape failure message, the scope fallback, the install-namespace auto-append, the explicit-empty opt-out, local-wins precedence, the pull-secret merge, and the pull-policy chain.

🤖 Generated with Claude Code

[dhaifley]

The repository split changes the existing Helm fixtures from test-repo:v1.0.0 to ghcr.io/test-repo:v1.0.0, but this PR only migrates the Go e2e caller. helm unittest helm/kmcp passes all 48 tests on the merge base and fails 18 tests at this head, with 18 snapshot failures in the deployment and RBAC suites. Should we update those fixtures and their expected output, and add cases for the new registry/global behavior? Or, if a fixture is intended to keep an unqualified image, set image.registry: "" explicitly?

[jjamroga]

Yep, you're right. Updated the fixtures AND added a CI job to run helm unit tests, this would have been more visible had we been running these tests in CI.