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

Abierto
  • ¿Algo no está bien?
#134 0 comentarios 0 reacciones 0 asignados Ver en GitHub

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
5/5
Tiempo estimado
Más de una semana
Aptitud para principiantes
45/100
Tipo de issue
Nueva funcionalidad
Claridad
Bastante claro
Estado de actividad
Tranquilo
Stack tecnológico
go, helm, yaml
Área
cli

Línea de trabajo

Start by reading the chart configuration loading code, talm init, the embedded preset chart, and their existing tests; the issue does not name specific files. Decide how configuration is read from the new location while retaining legacy support, then test both shapes and the stderr warning. Done also includes documenting the canonical location in the README and talm init template.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

area/chart kind/api-change kind/feature priority/important-longterm triage/accepted

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.
Lenguaje dominante
Go
Estrellas
493
Forks
23
Merge medio
5 d 19 h
PR fusionados (30 d)
5

Preparar el entorno

Este proyecto no incluye contenedor de desarrollo, Dockerfile ni guía de contribución, así que la configuración corre por tu cuenta: empieza por su README y consulta nuestra guía para la primera contribución para los pasos generales.

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de cozystack/talm

Todos los issues de cozystack/talm

Issues similares

Más issues de Go

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.