proposal(chart): migrate talm options out of Chart.yaml top-level into a Helm-compliant location

[lexfrei]

Problem

talm projects ship a Chart.yaml that mixes Helm chart metadata with talm-specific configuration at the top level:

apiVersion: v2
name: cozystack
type: application
version: 0.1.0
globalOptions:
  talosconfig: "talosconfig"
templateOptions:
  offline: false
  talosVersion: "v1.12"
  withSecrets: "secrets.yaml"
  kubernetesVersion: "v1.34.3"
  ...
applyOptions:
  preserve: false
  timeout: "1m"
  ...
upgradeOptions:
  preserve: false
  ...

Per the Helm chart specification (Chart.yaml), the top-level keys allowed in Chart.yaml are a fixed set: apiVersion, name, version, kubeVersion, description, type, keywords, home, sources, dependencies, maintainers, icon, appVersion, deprecated, annotations. talm's globalOptions / templateOptions / applyOptions / upgradeOptions are not in that set.

Helm's loader is permissive about unknown keys, so the current shape works at runtime — but it breaks tooling that validates against the schema:

• helm lint does not flag these today (it is itself permissive), but tooling that wraps the Helm JSON Schema (IDE plugins, schema-driven editors, security scanners, registry validators) sees them as schema violations.
• chart packagers and registries that round-trip Chart.yaml through a typed Helm SDK can drop the unknown fields silently — meaning a chart pushed through helm push and pulled back from a non-trivial registry may lose its talm config.
• a future Helm release that tightens loader strictness (already discussed upstream around chart provenance signing) would break talm projects across the board.

Proposed migration

A soft, two-phase migration that preserves backward compatibility:

Phase 1 (this release): keep accepting the existing top-level keys, AND introduce a Helm-compliant location to read the same configuration from. Print a WARNING: to stderr when a project still uses the legacy top-level shape, naming the new location and a future release in which the legacy form will be removed. Both talm init and the embedded preset chart should write to the new location only.

Phase 2 (future major release, e.g. v1): drop legacy-key support; load configuration from the new location only.

Open questions for discussion:

1. Target location. Two reasonable candidates:

   • annotations in Chart.yaml under a stable prefix, e.g. cozystack.io/talm-config: |. Stays inside Chart.yaml, no new file. Helm-compliant. Slightly awkward to edit because the value is a YAML string-of-YAML.
   • A dedicated config file alongside Chart.yaml, e.g. talm.yaml or .talm/config.yaml. Cleaner separation between Helm chart metadata and talm operational config. Adds a file to the project layout.

   I lean toward the dedicated file — it scales better as more options accumulate, and editing remains plain YAML.

2. Deprecation horizon. v1 is the obvious target if a major bump is planned. Otherwise: at least one minor release of overlap with warnings before dropping.

3. Migration helper. talm init could detect a legacy-shape Chart.yaml and offer to rewrite it on-the-fly, so users on existing projects do not have to hand-edit. Optional but reduces friction.

Acceptance criteria

• New location reads correctly when present.
• Legacy top-level keys still load, with a WARNING: printed to stderr naming the new location and the deprecation target release.
• Both shapes covered by tests, including the warning path.
• README and talm init template document the new location as canonical.