Skip to content

Commit 06642ce

Browse files
committed
fix(apply): refuse a node file that restores superseded fields
The render is checked for v1alpha1 fields the contract moved into typed documents, but apply then lays the node file over it. A node file rendered before the project moved to v1.14 still carries machine.kubelet, cluster.clusterName and the rest, so the merged config mixed both shapes and only the node rejected it, without talm's hint. The merged config now goes through the same check before it is sent, with a hint to re-render the node file with `talm template -I`. The render-time hint names the way out that actually applies there. A render never reads the node file's body, so re-rendering one fixes nothing: unpinned, the charts write v1alpha1 on every contract and only a pin helps; pinned at v1.14 or newer, the project's vendored templates predate the typed documents and `talm init --update` re-syncs them. Assisted-by: LLM Signed-off-by: Aleksei Sviridkin <[email protected]>
1 parent 901ace7 commit 06642ce

6 files changed

Lines changed: 147 additions & 20 deletions

File tree

‎docs/configuration/talos-versions.md‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -12,12 +12,14 @@ Rather than emit that config, the render stops. With both keys empty the Kuberne
1212

1313
```text
1414
rendered config mixes v1alpha1 fields with the documents that superseded them: ...
15-
hint: templateOptions.talosVersion is unset, so the render targets the Talos version talm was built from.
16-
Pin it to v1.13 or lower in Chart.yaml; above that contract Talos keeps these settings in documents of their own,
17-
which the charts do not emit.
15+
hint: templateOptions.talosVersion is unset, so the render targets the Talos version talm was built from; above v1.13
16+
Talos keeps these settings in documents of their own, and the charts emit them only for a pinned version. Pin it
17+
in Chart.yaml to the Talos version the nodes run, or to v1.13 or lower to keep the v1alpha1 shape.
1818
```
1919

20-
A chart can also fail earlier than either guard: the cozystack preset deletes a default node label with `$patch: delete`, and on a contract where `machine.nodeLabels` has moved into `KubeNodeConfig` that path no longer exists, so patching stops with `failed to delete path ...: lookup failed` before any version check runs. The preset happens to pin `v1.12`, which predates that move and sidesteps it.
20+
A project pinned at v1.14 or newer can hit the same error from its own templates: templates vendored by an earlier talm still write the v1alpha1 fields. The hint then points at `talm init --update --preset <preset>`, which re-syncs them; it also offers `Chart.yaml` and `values.yaml`, so review those changes before accepting them (see [Keeping charts in sync](../operations/upgrading.md)).
21+
22+
`talm apply` reports the conflict for a node file rendered before the project moved to v1.14, with a hint of its own: the file still carries `machine.kubelet`, `cluster.clusterName` and the rest, and laid over the v1.14 render they would reach the node as the mix it refuses. `talm template` alone does not catch it, because it renders from the templates and does not read the node file's body. `talm template -I` rewrites the file from the templates and keeps only its leading comments, so save any hand-written body first (per-node `LinkConfig` overlays, pinned settings), re-render, then put the saved settings back, moving v1alpha1 Kubernetes fields into the matching document.
2123

2224
Pin `templateOptions.talosVersion` in `Chart.yaml`, and keep it no newer than the Talos running on the node (see [Version compatibility](#version-compatibility)). Projects created from the shipped presets already carry a pin.
2325

‎docs/manual-test-plan.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -746,9 +746,11 @@ OIDC on cozystack: set `oidcIssuerUrl: https://issuer.example.com` and re-render
746746

747747
Refused flags, either preset: set `extraApiServerArgs: { oidc-issuer-url: x }` and re-render. Expected: the render fails naming `extraApiServerArgs.oidc-issuer-url` and pointing at `KubeAuthenticationConfig` or a pin at v1.13 or lower. The same key renders on a project pinned at v1.13.
748748

749+
Node files from an earlier contract, on a node running Talos v1.14: in a project pinned at `v1.13`, run `talm template -I --file nodes/<node>.yaml`, then set `talosVersion: "v1.14"` and `kubernetesVersion` to what the cluster runs, and run `talm apply --dry-run -f nodes/<node>.yaml`. Expected: the apply stops before contacting the node's apply API with `rendered config mixes v1alpha1 fields with the documents that superseded them`, naming the node file, and a hint to re-render with `talm template -I`. `talm template --file nodes/<node>.yaml` without `-I` succeeds at this point, since it does not read the node file's body. Run `talm template -I --file nodes/<node>.yaml`: the node file is rewritten in the v1.14 shape and the dry-run passes.
750+
749751
On a node running Talos v1.14 (any preset): `talm apply --dry-run -f nodes/<node>.yaml`, then apply. Expected: the drift preview lists `Kube*` documents rather than `cluster.*` fields, the node accepts the config, and `talm get kubeletconfig` / `talm get staticpods` show the kubelet and control-plane args from values. On cozystack, `kubectl get ds --namespace kube-system` lists neither `kube-flannel` nor `kube-proxy`, and control-plane nodes carry no `node-role.kubernetes.io/control-plane:NoSchedule` taint.
750752

751-
Regression anchor: `TestContract_ShippedChartsRenderValidConfig` loads both presets through the engine on v1.12, v1.13 and v1.14, at defaults and with every Kubernetes knob set, and validates the full render and the applied node file in machinery; `TestContract_ApiServerAuthFlagsRefusedFromV114` pins the refused flags; `TestContract_ChartKubeDocumentMergesIntoBundle`, `TestContract_ChartDeleteSelectorRemovesBundleDocument` and `TestContract_NonFullRenderKeepsChartKubeDocumentsVerbatim` pin the merge.
753+
Regression anchor: `TestContract_ShippedChartsRenderValidConfig` loads both presets through the engine on v1.12, v1.13 and v1.14, at defaults and with every Kubernetes knob set, and validates the full render and the applied node file in machinery; `TestContract_ApiServerAuthFlagsRefusedFromV114` pins the refused flags; `TestApplyTemplatesPerNode_RefusesNodeFileWithSupersededFields` pins the apply-time check on an old node file; `TestContract_ChartKubeDocumentMergesIntoBundle`, `TestContract_ChartDeleteSelectorRemovesBundleDocument` and `TestContract_NonFullRenderKeepsChartKubeDocumentsVerbatim` pin the merge.
752754

753755
## C. Apply (auth path)
754756

‎pkg/commands/apply.go‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1061,6 +1061,23 @@ func renderMergeAndApply(ctx context.Context, c *client.Client, opts engine.Opti
10611061
}
10621062
}
10631063

1064+
// The render was checked on its own; a node file written on an older
1065+
// contract can still bring back the v1alpha1 fields it superseded. The
1066+
// engine's hints are about the render, which passed, so they are dropped.
1067+
if err := engine.CheckSupersededFields(merged, opts.TalosVersion); err != nil {
1068+
files := strings.Join(append([]string{configFile}, sidePatches...), ", ")
1069+
1070+
//nolint:wrapcheck // cockroachdb/errors.WithHint at boundary.
1071+
return errors.WithHintf(
1072+
errors.Newf("laying %s over the rendered config: %s", files, err.Error()),
1073+
"one of these files sets a v1alpha1 field next to the document that replaced it. A node file "+
1074+
"rendered on an earlier Talos contract does: save its hand-written body, re-render it with "+
1075+
"`talm template -I --file %s` and put the body back. "+
1076+
"Otherwise move the reported field out of v1alpha1 into that document.",
1077+
configFile,
1078+
)
1079+
}
1080+
10641081
return apply(ctx, c, merged)
10651082
}
10661083

‎pkg/commands/apply_test.go‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -392,6 +392,75 @@ func TestApplyTemplatesPerNode_LoopsOncePerNodeWithSingleNodeContext(t *testing.
392392
}
393393
}
394394

395+
// A node file rendered on a contract that kept the Kubernetes settings in
396+
// v1alpha1 still carries them after the project moves to v1.14. Laid over the
397+
// v1.14 render, it produces the mix Talos refuses; the apply has to stop with
398+
// talm's hint instead of sending it to the node.
399+
func TestApplyTemplatesPerNode_RefusesNodeFileWithSupersededFields(t *testing.T) {
400+
dir := t.TempDir()
401+
configFile := filepath.Join(dir, "node.yaml")
402+
403+
body := "# talm: nodes=[\"a\"], templates=[\"templates/worker.yaml\"]\nmachine:\n kubelet:\n extraArgs:\n rotate-server-certificates: \"true\"\n"
404+
if err := os.WriteFile(configFile, []byte(body), 0o644); err != nil {
405+
t.Fatalf("write configFile: %v", err)
406+
}
407+
408+
render := func(context.Context, *client.Client, engine.Options) ([]byte, error) {
409+
return []byte("version: v1alpha1\nmachine:\n type: worker\n---\napiVersion: v1alpha1\nkind: KubeletConfig\nimage: ghcr.io/siderolabs/kubelet:v1.37.0\n"), nil
410+
}
411+
apply := func(context.Context, *client.Client, []byte) error {
412+
t.Error("a config mixing v1alpha1 kubelet with KubeletConfig was sent to the node")
413+
414+
return nil
415+
}
416+
417+
err := applyTemplatesPerNode(engine.Options{TalosVersion: "v1.14"}, configFile, nil, []string{testNodeAddrA}, fakeAuthOpenClient(context.Background()), render, apply)
418+
if err == nil {
419+
t.Fatal("expected the apply to stop on the superseded kubelet field")
420+
}
421+
422+
if !strings.Contains(err.Error(), "mixes v1alpha1 fields") {
423+
t.Errorf("error does not report the conflict: %v", err)
424+
}
425+
426+
// The templates rendered cleanly; the node file is what needs re-rendering.
427+
hints := strings.Join(errors.GetAllHints(err), "\n")
428+
if !strings.Contains(hints, "talm template -I") || strings.Contains(hints, "init --update") {
429+
t.Errorf("hint does not point at re-rendering the node file:\n%s", hints)
430+
}
431+
}
432+
433+
// A node file already in the v1.14 shape restates the typed documents and
434+
// carries no v1alpha1 Kubernetes field, so the check lets the apply through.
435+
func TestApplyTemplatesPerNode_AcceptsNodeFileInTypedShape(t *testing.T) {
436+
dir := t.TempDir()
437+
configFile := filepath.Join(dir, "node.yaml")
438+
439+
body := "# talm: nodes=[\"a\"], templates=[\"templates/worker.yaml\"]\nmachine:\n type: worker\n---\napiVersion: v1alpha1\nkind: KubeletConfig\nextraArgs:\n rotate-server-certificates: \"true\"\n"
440+
if err := os.WriteFile(configFile, []byte(body), 0o644); err != nil {
441+
t.Fatalf("write configFile: %v", err)
442+
}
443+
444+
render := func(context.Context, *client.Client, engine.Options) ([]byte, error) {
445+
return []byte("version: v1alpha1\nmachine:\n type: worker\n---\napiVersion: v1alpha1\nkind: KubeletConfig\nimage: ghcr.io/siderolabs/kubelet:v1.37.0\n"), nil
446+
}
447+
448+
applied := false
449+
apply := func(context.Context, *client.Client, []byte) error {
450+
applied = true
451+
452+
return nil
453+
}
454+
455+
if err := applyTemplatesPerNode(engine.Options{TalosVersion: "v1.14"}, configFile, nil, []string{testNodeAddrA}, fakeAuthOpenClient(context.Background()), render, apply); err != nil {
456+
t.Fatalf("applyTemplatesPerNode: %v", err)
457+
}
458+
459+
if !applied {
460+
t.Error("a node file in the typed shape was not applied")
461+
}
462+
}
463+
395464
// TestApplyTemplatesPerNode_NeverBatchesNodes guarantees no future tweak
396465
// can revert applyTemplatesPerNode to batching all nodes into a single
397466
// render call. Phrased against this helper directly, not against

‎pkg/engine/contract_validate_render_test.go‎

Lines changed: 19 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -480,27 +480,43 @@ kind: HostnameConfig
480480
hostname: node0
481481
`
482482

483+
// The way out depends on why the render mixed the shapes. Unpinned, the
484+
// charts render v1alpha1 whatever the contract, so only a pin helps.
485+
// Pinned above the boundary, the project's templates predate the typed
486+
// documents and need a re-sync. Re-rendering a node file fixes neither: the
487+
// render never reads its body.
483488
for _, tc := range []struct {
484489
name string
485490
talosVersion string
486491
wantPinLower bool
492+
wantInHint string
487493
}{
488-
{name: "above the boundary", talosVersion: "v1.14", wantPinLower: true},
494+
{name: "unpinned", talosVersion: "", wantPinLower: true, wantInHint: "Pin it in Chart.yaml"},
495+
{name: "above the boundary", talosVersion: "v1.14", wantPinLower: true, wantInHint: "talm init --update"},
489496
{name: "at the boundary", talosVersion: "v1.13", wantPinLower: false},
490497
{name: "below the boundary", talosVersion: "v1.12", wantPinLower: false},
491498
} {
492499
t.Run(tc.name, func(t *testing.T) {
493-
err := checkSupersededFields([]byte(rendered), tc.talosVersion)
500+
err := CheckSupersededFields([]byte(rendered), tc.talosVersion)
494501
if err == nil {
495502
t.Fatalf("talosVersion=%s: expected a conflict", tc.talosVersion)
496503
}
497504

498505
hints := strings.Join(errors.GetAllHints(err), "\n")
499506

500-
if got := strings.Contains(hints, "Pin it to"); got != tc.wantPinLower {
507+
if got := strings.Contains(hints, "v1.13 or lower"); got != tc.wantPinLower {
501508
t.Errorf("talosVersion=%s: hint offers a lower pin = %v, want %v:\n%s",
502509
tc.talosVersion, got, tc.wantPinLower, hints)
503510
}
511+
512+
if tc.wantInHint != "" && !strings.Contains(hints, tc.wantInHint) {
513+
t.Errorf("talosVersion=%s: hint does not say %q:\n%s", tc.talosVersion, tc.wantInHint, hints)
514+
}
515+
516+
if strings.Contains(hints, "template -I") {
517+
t.Errorf("talosVersion=%s: hint sends the operator to re-render a node file the render never reads:\n%s",
518+
tc.talosVersion, hints)
519+
}
504520
})
505521
}
506522
}

‎pkg/engine/engine.go‎

Lines changed: 33 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -293,7 +293,7 @@ func SerializeConfiguration(configBundle *bundle.Bundle, machineType machine.Typ
293293
return nil, err
294294
}
295295

296-
if err := checkSupersededFields(serialized, talosVersion); err != nil {
296+
if err := CheckSupersededFields(serialized, talosVersion); err != nil {
297297
return nil, err
298298
}
299299

@@ -2109,7 +2109,7 @@ func applyPatchesAndRenderConfig(opts Options, configPatches []string) ([]byte,
21092109
return nil, err
21102110
}
21112111

2112-
if err := checkSupersededFields(assembled.Bytes(), opts.TalosVersion); err != nil {
2112+
if err := CheckSupersededFields(assembled.Bytes(), opts.TalosVersion); err != nil {
21132113
return nil, err
21142114
}
21152115

@@ -2134,7 +2134,7 @@ func applyPatchesAndRenderConfig(opts Options, configPatches []string) ([]byte,
21342134
return buf.Bytes(), nil
21352135
}
21362136

2137-
// checkSupersededFields fails the render when the config sets a v1alpha1 field
2137+
// CheckSupersededFields fails the render when the config sets a v1alpha1 field
21382138
// that the targeted contract has moved into a document of its own. Talos rejects
21392139
// such a config outright, so catching it here turns an apply-time rejection into
21402140
// a render-time error naming the way out.
@@ -2147,7 +2147,7 @@ func applyPatchesAndRenderConfig(opts Options, configPatches []string) ([]byte,
21472147
//
21482148
// Only that class is reported: a render is legitimately incomplete in other ways
21492149
// (no install disk yet, no endpoint), and those are the operator's to fill in.
2150-
func checkSupersededFields(rendered []byte, talosVersion string) error {
2150+
func CheckSupersededFields(rendered []byte, talosVersion string) error {
21512151
cfg, err := configloader.NewFromBytes(rendered)
21522152
if err != nil {
21532153
// Not this check's job to decide the config is unloadable; the render
@@ -2183,16 +2183,20 @@ func checkSupersededFields(rendered []byte, talosVersion string) error {
21832183
return nil
21842184
}
21852185

2186+
return withSupersededFieldsHint(errors.Wrap(
2187+
errors.Join(conflicts...),
2188+
"rendered config mixes v1alpha1 fields with the documents that superseded them",
2189+
), talosVersion)
2190+
}
2191+
2192+
// withSupersededFieldsHint attaches the way out of a v1alpha1/typed-document
2193+
// mix, which depends on the contract and on whether the version is pinned.
2194+
func withSupersededFieldsHint(conflict error, talosVersion string) error {
21862195
pinned := talosVersion
21872196
if pinned == "" {
21882197
pinned = "unset, so the render targets the Talos version talm was built from"
21892198
}
21902199

2191-
conflict := errors.Wrap(
2192-
errors.Join(conflicts...),
2193-
"rendered config mixes v1alpha1 fields with the documents that superseded them",
2194-
)
2195-
21962200
// Above the boundary the contract is what moved the settings, so lowering it
21972201
// resolves the conflict. At or below it the contract is innocent: something
21982202
// in the charts or the patches wrote both shapes, and telling the operator
@@ -2209,13 +2213,30 @@ func checkSupersededFields(rendered []byte, talosVersion string) error {
22092213
)
22102214
}
22112215

2216+
// The charts pick the shape from the pinned version, so unpinned they write
2217+
// v1alpha1 on every contract and only a pin helps.
2218+
if talosVersion == "" {
2219+
//nolint:wrapcheck // cockroachdb/errors.WithHint at boundary.
2220+
return errors.WithHintf(
2221+
conflict,
2222+
"templateOptions.talosVersion is %s; above %s Talos keeps these settings in documents of their own, "+
2223+
"and the charts emit them only for a pinned version. Pin it in Chart.yaml to the Talos version "+
2224+
"the nodes run, or to %s or lower to keep the v1alpha1 shape.",
2225+
pinned,
2226+
config.TalosVersion1_13,
2227+
config.TalosVersion1_13,
2228+
)
2229+
}
2230+
22122231
//nolint:wrapcheck // cockroachdb/errors.WithHint at boundary.
22132232
return errors.WithHintf(
22142233
conflict,
22152234
"templateOptions.talosVersion is %s; above %s Talos keeps these settings in documents of their own. "+
2216-
"Re-render the node files with `talm template` (the charts emit those documents when talosVersion is pinned) "+
2217-
"and move the reported fields out of v1alpha1 in your own patches. Pin it to %s or lower in Chart.yaml "+
2218-
"to keep the v1alpha1 shape.",
2235+
"Templates vendored by an earlier talm still write them in v1alpha1: re-sync them with "+
2236+
"`talm init --update --preset <preset>`, accepting the templates but reviewing the Chart.yaml and "+
2237+
"values.yaml changes it also offers (they move the version pins and the install image), "+
2238+
"and move the reported fields out of v1alpha1 in your own "+
2239+
"templates and patches. Pin it to %s or lower in Chart.yaml to keep the v1alpha1 shape.",
22192240
pinned,
22202241
config.TalosVersion1_13,
22212242
config.TalosVersion1_13,

0 commit comments

Comments
 (0)