Skip to content

Commit 34d6912

Browse files
feat(version): warn when project charts drift from the talm binary version
talm vendors its preset and library charts into the project at `talm init` time; render commands (template/apply/upgrade) read that local copy, never the binary's embedded charts. Upgrading the talm binary therefore leaves charts/talm/ frozen at the version that last ran init, and the drift was invisible — operators had to eyeball `talm version` against Chart.yaml. Compare the binary version against the `version:` stamped in the project's Chart.yaml on every config-loading command. On mismatch, warn on stderr by default (output and exit code unchanged) and point at `talm init --update`. Teams can opt into enforcement via `strictVersion: true` in Chart.yaml or the `--strict-version` flag, turning drift into a hard error. The check stays silent for dev builds, the 0.1.0 dev sentinel, empty or unparseable versions, and matching versions, so it never raises a false alarm. The strictVersion field is optional; absent means today's behavior. Documents the vendoring model in the README and extends manual-test-plan B5. Co-Authored-By: Claude Opus 4.8 <[email protected]> Signed-off-by: Myasnikov Daniil <[email protected]>
1 parent 62f344c commit 34d6912

6 files changed

Lines changed: 262 additions & 1 deletion

File tree

‎README.md‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -226,6 +226,47 @@ talm template -f nodes/node1.yaml -I
226226
>
227227
> `talm template -f node.yaml` (with or without `-I`) does **not** apply the same overlay: its output is the rendered template plus the modeline and the auto-generated warning, byte-identical to what the template alone would produce. Routing it through the patcher would drop every YAML comment (including the modeline) and re-sort keys, breaking downstream commands that read the file back. Use `apply --dry-run` if you want to preview the exact bytes that will be sent to the node.
228228

229+
## How talm vendors charts (keeping a project in sync)
230+
231+
The talm binary **embeds** its preset charts (`generic`, `cozystack`) and the `talm` library chart at build time. When you run `talm init`, talm does not keep referring back to the binary — it **vendors a copy** of those charts into your project directory:
232+
233+
```
234+
your-project/
235+
Chart.yaml # preset config; its `version:` is stamped with the talm version that ran init
236+
values.yaml
237+
templates/ # preset templates
238+
charts/talm/ # the library chart — where the real rendering logic lives (vendored copy)
239+
```
240+
241+
From then on, `talm template`, `talm apply`, and `talm upgrade` render from the **local copy in your project**, never from the binary's embedded charts. This is what makes a project self-contained and GitOps-friendly: the chart logic is committed alongside your node configs.
242+
243+
The consequence: **upgrading the talm binary does not change your project's `charts/talm/`.** The vendored library chart stays frozen at whatever version last ran `talm init`. A newer binary's chart fixes are not picked up until you explicitly re-vendor:
244+
245+
```bash
246+
talm init --update -p <preset>
247+
```
248+
249+
`init --update` overwrites `charts/talm/` (no prompt — it is library code) and refreshes the preset templates (with a confirmation diff per file), then re-stamps the `version:` fields with the current binary version.
250+
251+
### Drift warning
252+
253+
To make this visible, talm compares the running binary version against the `version:` stamped in your project's `Chart.yaml` on every command that loads the project. When they differ you get a non-fatal warning on stderr (rendered output and exit code are unchanged):
254+
255+
```
256+
WARN: talm binary is 0.30.0 but this project's charts were vendored by talm 0.27.0;
257+
run `talm init --update` to sync charts/talm/ (or ignore if this is intentional)
258+
```
259+
260+
The check stays silent for source builds (`version: dev`), projects that were never stamped by a release, and matching versions — so it never raises a false alarm.
261+
262+
Teams that want this enforced rather than advisory can opt in. Add to `Chart.yaml`:
263+
264+
```yaml
265+
strictVersion: true
266+
```
267+
268+
With `strictVersion: true` (committed, so the whole team and CI inherit it) a version mismatch becomes a hard error (exit 1) instead of a warning, refusing to render or apply until the project is synced. The `--strict-version` flag forces the same behavior ad-hoc for a single invocation without editing `Chart.yaml`.
269+
229270
## Apply with side-patches
230271

231272
`talm apply -f` accepts a chain of files. The FIRST `-f` is the **anchor** — it must carry a `# talm: nodes=[…], templates=[…]` modeline and live under a `talm init`'d project (Chart.yaml + secrets.yaml). Any subsequent `-f` files are **side-patches**: they are merged in order on top of the anchor's rendered config, and a single `ApplyConfiguration` is issued per node carrying the composed result.

‎docs/manual-test-plan.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -226,6 +226,16 @@ Regression anchor: write `nodes/node0.yaml` as `# Operator note A\n# Operator no
226226

227227
When the local `charts/talm/` is older than the talm binary's embedded preset, `talm template` succeeds against the local preset — it does NOT auto-bump. The operator must run `init --update`. Confirm by inspecting `talm version` against `Chart.yaml`.
228228

229+
**Drift warning.** With a release binary (`talm version` is a real `vX.Y.Z`, not `dev`) and a project `Chart.yaml` whose `version:` is a *different* release, any config-loading command (e.g. `talm template`, `talm get`, `talm apply`) prints to **stderr**:
230+
231+
```
232+
WARN: talm binary is <bin> but this project's charts were vendored by talm <chart>; run `talm init --update` to sync charts/talm/ (or ignore if this is intentional)
233+
```
234+
235+
Expected: warning on stderr only (piped stdout unchanged), exit code unchanged (0 on an otherwise-successful render). The warning must NOT fire when (a) the binary is a `dev` build, (b) `Chart.yaml` `version:` is `0.1.0` or empty, or (c) the two versions match — confirm each stays silent.
236+
237+
**Strict mode.** Set `strictVersion: true` at the top level of `Chart.yaml` (or pass `--strict-version`). Re-run any config-loading command against the same mismatched project. Expected: hard error, exit 1, the same message plus `hint: run \`talm init --update\`, or remove strictVersion / drop --strict-version to downgrade this to a warning`. Removing the field (and not passing the flag) returns to warning behavior.
238+
229239
**Regression anchor**: `template -I` is rewrite, not merge — verify by adding a `# my comment` line above the modeline in `nodes/node0.yaml`, running B4, and confirming the comment is GONE in the new body. If the comment survives, a behaviour change shipped (could be either an intentional new `--preserve-comments` flag or an undocumented merge mode — neither should appear silently).
230240

231241
### B6. Scope-filter symmetry across v1.11 and v1.12 renders

‎main.go‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -51,6 +51,14 @@ const cmdNameTalm = "talm"
5151
//nolint:gochecknoglobals // ldflags-injected build version, idiomatic for go release tooling.
5252
var Version = "dev"
5353

54+
// strictVersionFlag is bound to the --strict-version persistent flag. When set
55+
// (or when Chart.yaml carries strictVersion: true), a mismatch between the talm
56+
// binary version and the project's vendored chart version becomes a hard error
57+
// instead of a warning.
58+
//
59+
//nolint:gochecknoglobals // cobra persistent flag binds to package-level state, consistent with the rest of this file.
60+
var strictVersionFlag bool
61+
5462
// skipConfigCommands lists commands that should not load Chart.yaml config.
5563
// - init: creates the config, so it doesn't exist yet
5664
// - completion: generates shell completion scripts
@@ -121,6 +129,7 @@ func registerRootFlags(cmd *cobra.Command) {
121129
cmd.PersistentFlags().StringVar(&commands.GlobalArgs.Cluster, "cluster", "", "Cluster to connect to if a proxy endpoint is used.")
122130
cmd.PersistentFlags().BoolVar(&commands.GlobalArgs.SkipVerify, "skip-verify", false, "skip TLS certificate verification (keeps client authentication)")
123131
cmd.PersistentFlags().Bool("version", false, "Print the version number of the application")
132+
cmd.PersistentFlags().BoolVar(&strictVersionFlag, "strict-version", false, "fail if the talm binary version differs from the project's vendored chart version (run `talm init --update` to sync)")
124133

125134
// Shell completion for root persistent flags. --nodes /
126135
// --endpoints draw from the in-scope talosconfig contexts.
@@ -185,6 +194,22 @@ func init() {
185194
if err != nil {
186195
return errors.Wrap(err, "error loading configuration")
187196
}
197+
198+
// Surface vendored-chart drift: the project's charts/talm/ is a
199+
// frozen copy from init time, so upgrading the talm binary without
200+
// re-running `talm init --update` silently renders with stale chart
201+
// logic. Warn by default; hard-fail when the project (or the
202+
// operator via --strict-version) opted into strict matching.
203+
if mismatch, msg := commands.CheckChartVersion(Version, commands.Config.ChartVersion); mismatch {
204+
if commands.Config.StrictVersion || strictVersionFlag {
205+
return errors.WithHint(
206+
errors.New(msg),
207+
"run `talm init --update`, or remove strictVersion / drop --strict-version to downgrade this to a warning",
208+
)
209+
}
210+
211+
fmt.Fprintf(os.Stderr, "WARN: %s\n", msg)
212+
}
188213
}
189214

190215
// Ensure talosconfig path is set to project root if not explicitly set via flag

‎pkg/commands/root.go‎

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -42,7 +42,16 @@ var GlobalArgs global.Args
4242
var Config struct {
4343
RootDir string
4444
RootDirExplicit bool // true if --root was explicitly set
45-
GlobalOptions struct {
45+
// ChartVersion is the project Chart.yaml `version:` field, stamped with
46+
// the talm binary version at `talm init` / `talm init --update` time. It
47+
// is compared against the running binary version to surface vendored-chart
48+
// drift (see CheckChartVersion).
49+
ChartVersion string `yaml:"version"`
50+
// StrictVersion turns vendored-chart drift into a hard error instead of a
51+
// warning. Opt-in per project via Chart.yaml; absent means false (the
52+
// historical behavior). The --strict-version flag can also force it on.
53+
StrictVersion bool `yaml:"strictVersion"`
54+
GlobalOptions struct {
4655
Talosconfig string `yaml:"talosconfig"`
4756
Kubeconfig string `yaml:"kubeconfig"`
4857
} `yaml:"globalOptions"`

‎pkg/commands/version_check.go‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
// Copyright Cozystack Authors
2+
//
3+
// Licensed under the Apache License, Version 2.0 (the "License");
4+
// you may not use this file except in compliance with the License.
5+
// You may obtain a copy of the License at
6+
//
7+
// http://www.apache.org/licenses/LICENSE-2.0
8+
//
9+
// Unless required by applicable law or agreed to in writing, software
10+
// distributed under the License is distributed on an "AS IS" BASIS,
11+
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
// See the License for the specific language governing permissions and
13+
// limitations under the License.
14+
15+
package commands
16+
17+
import (
18+
"fmt"
19+
"strings"
20+
21+
"github.com/Masterminds/semver/v3"
22+
)
23+
24+
// devVersionStamp is the placeholder version written into a project's
25+
// Chart.yaml when it is generated by a non-release (dev) talm build. It
26+
// mirrors the sentinel used in main.go's initConfig. A project carrying
27+
// this value was never stamped by a real release, so there is nothing
28+
// meaningful to compare against.
29+
const devVersionStamp = "0.1.0"
30+
31+
// CheckChartVersion compares the talm binary version against the version
32+
// stamped into the project's Chart.yaml at `talm init` / `talm init --update`
33+
// time.
34+
//
35+
// talm vendors its preset and library charts into the project directory at
36+
// init time; rendering (template/apply/upgrade) then reads that local copy,
37+
// never the binary's embedded charts. So upgrading the talm binary does not
38+
// touch the vendored charts/talm/ — they stay frozen at the version that last
39+
// ran init. This function surfaces that drift.
40+
//
41+
// binaryVersion is main.Version (e.g. "v0.30.0", or "dev" for source builds).
42+
// chartVersion is the project Chart.yaml `version:` field (e.g. "0.27.0").
43+
//
44+
// It returns (true, message) only when both versions are real, parseable
45+
// releases that differ. It returns (false, "") — i.e. stays silent — when
46+
// either side is a dev build, the sentinel, empty, or unparseable, so it
47+
// never raises a false alarm against source builds or unstamped projects.
48+
func CheckChartVersion(binaryVersion, chartVersion string) (bool, string) {
49+
bin, err := semver.NewVersion(strings.TrimPrefix(binaryVersion, "v"))
50+
if err != nil {
51+
// dev / unparseable binary — nothing meaningful to compare.
52+
return false, ""
53+
}
54+
55+
normalizedChart := strings.TrimPrefix(chartVersion, "v")
56+
if normalizedChart == "" || normalizedChart == devVersionStamp {
57+
// project was never stamped by a release build.
58+
return false, ""
59+
}
60+
61+
chart, err := semver.NewVersion(normalizedChart)
62+
if err != nil {
63+
return false, ""
64+
}
65+
66+
if bin.Equal(chart) {
67+
return false, ""
68+
}
69+
70+
return true, fmt.Sprintf(
71+
"talm binary is %s but this project's charts were vendored by talm %s; "+
72+
"run `talm init --update` to sync charts/talm/ (or ignore if this is intentional)",
73+
bin.String(), chart.String(),
74+
)
75+
}

‎pkg/commands/version_check_test.go‎

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
// Copyright Cozystack Authors
2+
//
3+
// Licensed under the Apache License, Version 2.0 (the "License");
4+
// you may not use this file except in compliance with the License.
5+
// You may obtain a copy of the License at
6+
//
7+
// http://www.apache.org/licenses/LICENSE-2.0
8+
//
9+
// Unless required by applicable law or agreed to in writing, software
10+
// distributed under the License is distributed on an "AS IS" BASIS,
11+
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
// See the License for the specific language governing permissions and
13+
// limitations under the License.
14+
15+
package commands
16+
17+
import "testing"
18+
19+
func TestCheckChartVersion(t *testing.T) {
20+
tests := []struct {
21+
name string
22+
binary string
23+
chart string
24+
wantMismatch bool
25+
}{
26+
{
27+
name: "equal release versions stay silent",
28+
binary: "v0.30.0",
29+
chart: "0.30.0",
30+
wantMismatch: false,
31+
},
32+
{
33+
name: "binary newer than vendored chart warns",
34+
binary: "v0.30.0",
35+
chart: "0.27.0",
36+
wantMismatch: true,
37+
},
38+
{
39+
name: "binary older than vendored chart warns",
40+
binary: "v0.27.0",
41+
chart: "0.30.0",
42+
wantMismatch: true,
43+
},
44+
{
45+
name: "v prefix on chart version is normalized",
46+
binary: "v0.30.0",
47+
chart: "v0.30.0",
48+
wantMismatch: false,
49+
},
50+
{
51+
name: "dev binary build is skipped",
52+
binary: "dev",
53+
chart: "0.27.0",
54+
wantMismatch: false,
55+
},
56+
{
57+
name: "chart stamped by dev build (0.1.0 sentinel) is skipped",
58+
binary: "v0.30.0",
59+
chart: "0.1.0",
60+
wantMismatch: false,
61+
},
62+
{
63+
name: "empty chart version is skipped",
64+
binary: "v0.30.0",
65+
chart: "",
66+
wantMismatch: false,
67+
},
68+
{
69+
name: "unparseable chart version is skipped",
70+
binary: "v0.30.0",
71+
chart: "not-a-version",
72+
wantMismatch: false,
73+
},
74+
{
75+
name: "unparseable binary version is skipped",
76+
binary: "garbage",
77+
chart: "0.27.0",
78+
wantMismatch: false,
79+
},
80+
}
81+
82+
for _, tt := range tests {
83+
t.Run(tt.name, func(t *testing.T) {
84+
gotMismatch, gotMsg := CheckChartVersion(tt.binary, tt.chart)
85+
if gotMismatch != tt.wantMismatch {
86+
t.Errorf("CheckChartVersion(%q, %q) mismatch = %v, want %v",
87+
tt.binary, tt.chart, gotMismatch, tt.wantMismatch)
88+
}
89+
90+
if gotMismatch && gotMsg == "" {
91+
t.Errorf("CheckChartVersion(%q, %q) reported a mismatch but returned an empty message",
92+
tt.binary, tt.chart)
93+
}
94+
95+
if !gotMismatch && gotMsg != "" {
96+
t.Errorf("CheckChartVersion(%q, %q) returned no mismatch but a non-empty message %q",
97+
tt.binary, tt.chart, gotMsg)
98+
}
99+
})
100+
}
101+
}

0 commit comments

Comments
 (0)