Skip to content

Commit 6e0913c

Browse files
committed
feat(commands): retire talm dmesg ahead of upstream, redirect operators to logs kernel
Upstream Talos signaled retirement of the `dmesg` command in siderolabs/talos#13333 ("Kernel logs are available with `talosctl logs kernel` which supports `--tail=N`, we will probably retire `dmesg` command"). The current wrapper-side cushion for the `--tail=N` ParseBool footgun points operators at a pipe workaround that becomes obsolete the moment upstream removes the surface — and `logs kernel --tail=N` is the better target right now anyway, because it matches the line-count semantics operators reach for. Removes `talm dmesg` proactively: - Adds `dmesg` to `excludedCommands` in the talosctl-wrapper init so the upstream `dmesg` command is no longer imported. - Replaces the cushion in `pkg/commands/dmesg_handler.go` with a hidden migration stub. Every `talm dmesg ...` invocation errors with "talm dmesg has been removed" plus a hint pointing at `talm logs kernel --tail=N --nodes <node>` and a reference to siderolabs/talos#13333. - `DisableFlagParsing` on the stub lets operator-supplied flags pass through to RunE so the hint surfaces regardless of what arguments accompanied the call. - Adds `dmesg` to `skipConfigCommands` in main.go so the migration hint fires even when the operator runs the command outside a talm project (mirrors the init / completion treatment). The stub is `Hidden: true` so operators reading `talm --help` don't see a retired command as available. Existing scripts that call `talm dmesg <flags>` get an immediate, actionable migration nudge instead of a silent break on the next Talos bump. Contract pins (TestDmesgRemoved_StubSurfacesMigrationHint, TestDmesgExcludedFromTalosctlWrap): - exactly one `dmesg` entry registered (the stub, not the upstream wrap), - stub is hidden + always-erroring, - error names the migration target (logs kernel + --tail). Test plan (docs/manual-test-plan.md): - I0-1 read-only command sweep: `dmesg --tail` replaced with `logs kernel --tail 3` so the bake hits the new supported path. - I0-1a new entry pinning the migration-stub UX (both bare-invocation and `--tail` invocations error with the hint; stub is hidden from --help; cwd-independent). - H2b regression anchor for reset: `dmesg | grep ephemeral` swapped for `logs kernel | grep ephemeral`. Assisted-By: Claude <[email protected]> Signed-off-by: Aleksei Sviridkin <[email protected]>
1 parent 31a27cd commit 6e0913c

6 files changed

Lines changed: 171 additions & 97 deletions

File tree

‎docs/manual-test-plan.md‎

Lines changed: 14 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -545,7 +545,7 @@ Regression anchor: when EITHER of these commands is run the wrapper MUST NOT sil
545545

546546
Expected: only STATE wiped, EPHEMERAL kept (containerd image cache survives the reset), node returns. The operator's explicit narrower list must be honored byte-for-byte; the wrapper MUST NOT silently expand to `STATE,EPHEMERAL`.
547547

548-
Regression anchor: after the node returns, `talm dmesg --nodes $NODE | grep -i ephemeral` should show no fresh-format markers for the EPHEMERAL partition. If the wrapper silently expanded the operator's list, EPHEMERAL would have been wiped too.
548+
Regression anchor: after the node returns, `talm logs kernel --nodes $NODE | grep -i ephemeral` should show no fresh-format markers for the EPHEMERAL partition. If the wrapper silently expanded the operator's list, EPHEMERAL would have been wiped too.
549549

550550
### H2c. Reset with `--graceful=false` (ungraceful, preserves safe default)
551551

@@ -604,14 +604,25 @@ NODE=$NODE
604604
for cmd in version "get machineconfig -o yaml" containers processes \
605605
"health --server=false" "interfaces" "disks" "etcd members" \
606606
"list /system/state" memory mounts stats service cgroups \
607-
"dmesg --tail" netstat routes "usage /var/log" \
607+
"logs kernel --tail 3" netstat routes "usage /var/log" \
608608
"logs kubelet" "logs etcd" "events --tail=3" \
609609
"image list" "etcd status" "etcd alarm list"; do
610610
timeout 8 /tmp/talm-safety $cmd --nodes $NODE --endpoints $NODE 2>&1 | head -1
611611
done
612612
```
613613

614-
Expected: every command prints either a header row (table) or an error from the node side. None should hang past the timeout.
614+
Expected: every command prints either a header row (table) or an error from the node side. None should hang past the timeout. The `logs kernel` entry replaces the retired `dmesg` command; `logs kernel --tail=N` is the supported way to read the last N kernel-log lines.
615+
616+
### I0-1a. `talm dmesg` is retired — migration stub surfaces a hint
617+
618+
```bash
619+
/tmp/talm-safety dmesg --tail 3
620+
/tmp/talm-safety dmesg --nodes $NODE
621+
```
622+
623+
Expected: both invocations exit non-zero with `talm dmesg has been removed` and a hint pointing at `talm logs kernel --tail=N --nodes <node>`. The stub is hidden from `talm --help` (operators don't see a retired command as available). The migration hint surfaces regardless of cwd (the stub skips Chart.yaml loading, mirroring `init` and `completion`).
624+
625+
Regression anchor: a regression that re-enables the upstream `dmesg` wrap (removing it from `excludedCommands` in `pkg/commands/talosctl_wrapper.go`) would either collide with the talm-owned stub at cobra registration, or — if the stub is also dropped — leave operators with the original cryptic `strconv.ParseBool` failure on `--tail=N`. Both shapes are documented elsewhere; this anchor pins the proactive removal + migration-hint contract.
615626

616627
### I0-2. Concurrent dry-run apply
617628

‎main.go‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,12 @@ const (
3232
// appears both in skipConfigCommands and in cobra's exported
3333
// API.
3434
completionInternal = "__complete"
35+
// dmesgSubcommandName labels the hidden migration stub for the
36+
// retired `talm dmesg` command. The stub errors with a hint
37+
// pointing at `talm logs kernel --tail=N`; it must skip
38+
// Chart.yaml loading so the migration hint surfaces even when
39+
// the operator runs it outside a talm project.
40+
dmesgSubcommandName = "dmesg"
3541
)
3642

3743
// cmdNameTalm is the binary name used both as the cobra root
@@ -49,9 +55,10 @@ var Version = "dev"
4955
// - init: creates the config, so it doesn't exist yet
5056
// - completion: generates shell completion scripts
5157
// - __complete: cobra's internal command for shell autocompletion (Tab key).
58+
// - dmesg: retired migration stub; must error with the hint regardless of cwd.
5259
//
5360
//nolint:gochecknoglobals // immutable lookup table consulted by isCommandOrParent during PersistentPreRunE; init-time literal.
54-
var skipConfigCommands = []string{initSubcommandName, completionSubcommand, completionInternal}
61+
var skipConfigCommands = []string{initSubcommandName, completionSubcommand, completionInternal, dmesgSubcommandName}
5562

5663
// rootCmd represents the base command when called without any subcommands.
5764
//

‎main_test.go‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -248,6 +248,17 @@ func TestSkipConfigCommands(t *testing.T) {
248248
cmdPath: []string{"talm", "init"},
249249
expected: true,
250250
},
251+
{
252+
// dmesg is the retired migration stub — must skip
253+
// Chart.yaml loading so the "talm dmesg has been
254+
// removed" hint surfaces even outside a project
255+
// root. Without this membership the operator would
256+
// see an "error reading configuration file" instead
257+
// of the migration hint.
258+
name: "dmesg (retired migration stub)",
259+
cmdPath: []string{"talm", "dmesg"},
260+
expected: true,
261+
},
251262
{
252263
name: "apply command should load config",
253264
cmdPath: []string{"talm", "apply"},

‎pkg/commands/dmesg_handler.go‎

Lines changed: 46 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -15,54 +15,59 @@
1515
package commands
1616

1717
import (
18-
"strings"
19-
2018
"github.com/cockroachdb/errors"
2119
"github.com/spf13/cobra"
2220
)
2321

24-
// dmesgCmdName labels the wrapped dmesg subcommand in the dispatch.
25-
// Hoisted so a future rename touches one site.
22+
// dmesgCmdName labels the talm stub that replaces the wrapped
23+
// upstream dmesg command. Hoisted so a future rename touches one
24+
// site.
2625
const dmesgCmdName = "dmesg"
2726

28-
// wrapDmesgCommand installs a FlagErrorFunc that rewrites the
29-
// cryptic ParseBool error from a numeric --tail value into an
30-
// operator-friendly hint.
27+
// dmesgCmd is a hidden migration stub for the retired `talm dmesg`
28+
// surface.
29+
//
30+
// Upstream Talos is retiring the `dmesg` command in favor of
31+
// `talm logs kernel`, which supports `--tail=N` as a line count
32+
// directly (the semantics operators reach for; the original
33+
// `dmesg --tail` was a boolean toggle for tail-mode under
34+
// --follow, a frequent source of `strconv.ParseBool` confusion).
35+
// The upstream maintainer's response on siderolabs/talos#13333
36+
// pointed at `logs kernel` as the replacement.
3137
//
32-
// Upstream talosctl registers --tail as a BoolVarP toggling
33-
// tail-mode for --follow (`Dmesg(ctx, follow, tail bool)` on the
34-
// wire). Operators' first instinct is `tail(1)`-style line count;
35-
// `talm dmesg --tail=3` then surfaces
36-
// `strconv.ParseBool: parsing "3": invalid syntax` with no hint
37-
// at the actual contract.
38+
// Removing the command proactively (rather than waiting for
39+
// upstream's removal) means operators with scripts that call
40+
// `talm dmesg ...` get an immediate, actionable migration hint
41+
// instead of a silently-deprecated command that may disappear
42+
// on the next Talos bump. The stub is hidden from `talm --help`
43+
// so the command does not surface to new operators.
44+
// DisableFlagParsing lets operator-supplied flags pass through
45+
// to RunE without pflag erroring first — the migration hint
46+
// runs regardless of what arguments accompanied the call.
3847
//
39-
// The original ParseBool error is wrapped (not replaced) so it
40-
// stays reachable via errors.Unwrap and verbose fmt.Sprintf("%+v",
41-
// err) rendering — debugging the underlying pflag failure remains
42-
// possible while the operator-facing top line describes what --tail
43-
// actually does and what to do instead.
44-
func wrapDmesgCommand(wrappedCmd *cobra.Command) {
45-
wrappedCmd.SetFlagErrorFunc(func(_ *cobra.Command, err error) error {
46-
// Substring detection on pflag's error format. Two tokens
47-
// — `--tail` plus `ParseBool` — together are specific
48-
// enough to avoid false positives (pflag only emits
49-
// ParseBool errors for bool flags). Matching on `--tail`
50-
// without surrounding quotes is durable to pflag's
51-
// rendering difference between shorthand-present and
52-
// shorthand-absent flags: today's `BoolVarP(..., "tail",
53-
// "", ...)` emits `"--tail"`, but a future upstream that
54-
// adds a shorthand would emit `-T, --tail` and would
55-
// otherwise silently bypass the cushion. pflag does not
56-
// export a typed error for invalid-argument failures, so
57-
// substring is the only available detection path.
58-
msg := err.Error()
59-
if strings.Contains(msg, "--tail") && strings.Contains(msg, "ParseBool") {
60-
return errors.WithHint(
61-
errors.Wrap(err, "talm dmesg --tail is a boolean toggle (tail-mode for --follow), not a line count"),
62-
"for the last N lines, pipe to tail(1): `talm dmesg --nodes <node> | tail -n N`; to stream only new messages, use `--follow --tail`",
63-
)
64-
}
48+
// Side effect of DisableFlagParsing: cobra does NOT intercept
49+
// `--help` either — `talm dmesg --help` reaches RunE and
50+
// surfaces the same migration hint instead of cobra's help
51+
// renderer. Intentional: every invocation of the retired
52+
// command should reach the same nudge. A future maintainer
53+
// who flips DisableFlagParsing to false would silently
54+
// re-introduce the original pflag failure shape on `--tail=N`
55+
// for any operator who didn't migrate yet.
56+
//
57+
//nolint:gochecknoglobals // cobra command registration requires a package-level value
58+
var dmesgCmd = &cobra.Command{
59+
Use: dmesgCmdName,
60+
Short: "[removed] use `talm logs kernel` instead",
61+
Hidden: true,
62+
DisableFlagParsing: true,
63+
RunE: func(_ *cobra.Command, _ []string) error {
64+
return errors.WithHint(
65+
errors.New("talm dmesg has been removed"),
66+
"use `talm logs kernel --tail=N --nodes <node>` for the last N kernel-log lines, or `talm logs kernel --follow --nodes <node>` to stream new messages. Upstream Talos is retiring the `dmesg` command (see siderolabs/talos#13333) and talm drops it ahead of time to avoid a silent break on the next Talos bump.",
67+
)
68+
},
69+
}
6570

66-
return err
67-
})
71+
func init() {
72+
addCommand(dmesgCmd)
6873
}

‎pkg/commands/talosctl_wrapper.go‎

Lines changed: 1 addition & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -301,13 +301,6 @@ func wrapTalosCommand(cmd *cobra.Command, cmdName string) *cobra.Command {
301301
wrapCrashdumpCommand(wrappedCmd)
302302
}
303303

304-
// Special handling for dmesg: rewrite the cryptic ParseBool
305-
// error from a numeric --tail value into a hint that describes
306-
// upstream's actual --tail contract.
307-
if baseCmdName == dmesgCmdName {
308-
wrapDmesgCommand(wrappedCmd)
309-
}
310-
311304
// Special handling for the interactive-only commands
312305
// (dashboard, edit): refuse non-tty stdin up front so the
313306
// operator gets a clear hint instead of a no-output failure.
@@ -344,6 +337,7 @@ func init() {
344337
"config": true, // talm manages config differently
345338
"patch": true, // not needed in talm
346339
"upgrade-k8s": true, // not needed in talm
340+
dmesgCmdName: true, // retired upstream (siderolabs/talos#13333); talm registers a hidden migration stub pointing at `talm logs kernel --tail=N`
347341
talosconfigName: true, // talm has its own talosconfig command
348342
}
349343

‎pkg/commands/talosctl_wrapper_test.go‎

Lines changed: 91 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -332,71 +332,117 @@ func TestWrapKubeconfigCommand_PositionalPathErrorMessageMatchesContract(t *test
332332
}
333333
}
334334

335-
// TestWrapDmesgCommand_TailEqualsNumeric_RewritesError pins the
336-
// FlagErrorFunc cushion for `--tail=<n>` typo. Upstream talosctl
337-
// registers --tail as a BoolVarP (toggling tail-mode for --follow), but
338-
// operators' first instinct is tail(1)-style line count. `--tail=3`
339-
// trips pflag's ParseBool and surfaces a cryptic
340-
// 'strconv.ParseBool: parsing "3": invalid syntax' error.
335+
// TestDmesgRemoved_StubSurfacesMigrationHint pins the proactive
336+
// removal of `talm dmesg`. Upstream Talos is retiring the `dmesg`
337+
// command in favor of `talm logs kernel`, which supports
338+
// `--tail=N` as a line count directly (the exact semantics
339+
// operators reach for). Per siderolabs/talos#13333 the upstream
340+
// maintainer pointed at `logs kernel` as the replacement.
341341
//
342-
// The wrapper installs a FlagErrorFunc that detects this specific
343-
// pattern and rewrites it with a hint pointing at the actual
344-
// upstream contract + a pipe-to-tail(1) suggestion for the
345-
// line-count case operators usually want.
346-
func TestWrapDmesgCommand_TailEqualsNumeric_RewritesError(t *testing.T) {
347-
var dmesgCmd *cobra.Command
348-
349-
for _, cmd := range taloscommands.Commands {
342+
// talm short-circuits any `talm dmesg ...` invocation with a
343+
// hidden stub command that always errors. The error names the
344+
// migration path so operators with scripts get an immediate
345+
// nudge to the right surface rather than a silent "unknown
346+
// command" or — worse — a working-but-deprecated command.
347+
//
348+
// Contract pins:
349+
//
350+
// - The stub exists at the `talm dmesg` command path.
351+
// - It is HIDDEN from `talm --help` (operators shouldn't see
352+
// dmesg as available).
353+
// - Any invocation (with or without flags) errors and the
354+
// error's hint names `logs kernel --tail=N` as the
355+
// replacement.
356+
// - The upstream taloscommands.Commands entry for `dmesg` is
357+
// NOT wrapped (the wrapper's excludedCommands map skips it).
358+
// Without this, the stub would collide with the wrapped
359+
// upstream command and cobra would error on duplicate.
360+
func TestDmesgRemoved_StubSurfacesMigrationHint(t *testing.T) {
361+
t.Parallel()
362+
363+
// Find the registered talm `dmesg` stub among package
364+
// commands. Iterate Commands rather than rootCmd.Commands
365+
// because rootCmd assembly happens in main.go's init, which
366+
// the test package doesn't drive.
367+
var stub *cobra.Command
368+
369+
for _, cmd := range Commands {
350370
if cmd.Name() == "dmesg" {
351-
dmesgCmd = cmd
371+
stub = cmd
352372

353373
break
354374
}
355375
}
356376

357-
if dmesgCmd == nil {
358-
t.Skip("upstream taloscommands.Commands has no 'dmesg' command — schema changed")
377+
if stub == nil {
378+
t.Fatal("talm must register a `dmesg` stub command so `talm dmesg ...` invocations surface a migration hint; got no command with that name in Commands")
359379
}
360380

361-
wrapped := wrapTalosCommand(dmesgCmd, "dmesg")
362-
363-
// FlagErrorFunc is invoked by cobra's Execute() lifecycle on a
364-
// ParseFlags failure. Reproduce that path by capturing the
365-
// ParseFlags error and feeding it through the registered hook —
366-
// this is exactly what cobra does internally in command.execute.
367-
rawErr := wrapped.ParseFlags([]string{"--tail=3"})
368-
if rawErr == nil {
369-
t.Fatal("--tail=3 must error from pflag (upstream --tail is bool); got nil")
381+
if !stub.Hidden {
382+
t.Error("dmesg stub must be hidden from --help so operators don't see a retired command as available")
370383
}
371384

372-
hook := wrapped.FlagErrorFunc()
373-
if hook == nil {
374-
t.Fatal("wrapped dmesg must register a FlagErrorFunc to rewrite ParseBool errors")
385+
// Invoke RunE to verify the migration error fires with the
386+
// hint pointing at `logs kernel`. RunE invocation skips
387+
// cobra's flag parsing layer; the stub uses
388+
// DisableFlagParsing so any operator-supplied flags pass
389+
// through and don't error before reaching RunE.
390+
if stub.RunE == nil {
391+
t.Fatal("stub must have a RunE that returns the migration error")
375392
}
376393

377-
err := hook(wrapped, rawErr)
394+
err := stub.RunE(stub, []string{"--nodes", "1.2.3.4"})
395+
if err == nil {
396+
t.Fatal("dmesg stub must error on every invocation")
397+
}
378398

379399
msg := err.Error()
400+
if !strings.Contains(msg, "dmesg") || !strings.Contains(strings.ToLower(msg), "removed") {
401+
t.Errorf("error must name the dmesg-removal explicitly; got: %q", msg)
402+
}
380403

381-
// Top-level message must describe the actual contract
382-
// (boolean toggle for --follow) so the operator sees it first
383-
// before any inherited ParseBool noise.
384-
if !strings.Contains(strings.ToLower(msg), "boolean") && !strings.Contains(strings.ToLower(msg), "follow") {
385-
t.Errorf("rewritten error must describe --tail's actual contract (boolean toggle for --follow); got: %q", msg)
404+
hints := strings.Join(errors.GetAllHints(err), "\n")
405+
// The hint must cover both operator use cases that the
406+
// retired dmesg surface served: --tail=N for the last N
407+
// lines (the line-count case operators reach for), AND
408+
// --follow for live streaming (the original valid usage of
409+
// `talm dmesg --follow` that wasn't a parse-error trap).
410+
// Operators with either pattern in scripts get a complete
411+
// migration target instead of a hint that only covers one.
412+
for _, want := range []string{"logs kernel", "--tail", "--follow"} {
413+
if !strings.Contains(hints, want) {
414+
t.Errorf("hint must point at `talm logs kernel` covering both `--tail=N` (last N lines) and `--follow` (stream); missing %q in hints:\n%s", want, hints)
415+
}
386416
}
417+
}
387418

388-
// Chain must preserve the original ParseBool error via
389-
// errors.Wrap so the underlying pflag failure remains
390-
// reachable for verbose debugging (errors.Unwrap,
391-
// fmt.Sprintf("%+v", err), etc.). Without wrap-not-replace,
392-
// downstream tooling that walks the chain or matches against
393-
// the upstream error type loses information.
394-
if !strings.Contains(msg, "ParseBool") {
395-
t.Errorf("rewritten error must wrap (not replace) the original ParseBool error so the chain stays inspectable; got: %q", msg)
419+
// TestDmesgExcludedFromTalosctlWrap pins the other half of the
420+
// removal contract: the upstream taloscommands.Commands entry
421+
// for `dmesg` MUST NOT be wrapped through wrapTalosCommand.
422+
// Without this guard the talm-owned stub and the wrapped
423+
// upstream command would collide on cobra registration. The
424+
// excludedCommands map in talosctl_wrapper.go's init is the
425+
// load-bearing piece; this test surfaces a regression that
426+
// removes "dmesg" from the map while leaving the stub.
427+
func TestDmesgExcludedFromTalosctlWrap(t *testing.T) {
428+
t.Parallel()
429+
430+
// The talm Commands slice is built from two sources:
431+
// upstream taloscommands.Commands (excluding the
432+
// excludedCommands map) and talm-native registrations
433+
// (apply, init, template, talosconfig, plus our new dmesg
434+
// stub). Exactly one entry named `dmesg` should exist (the
435+
// stub). If two are present, the exclusion failed.
436+
count := 0
437+
438+
for _, cmd := range Commands {
439+
if cmd.Name() == "dmesg" {
440+
count++
441+
}
396442
}
397443

398-
if unwrapped := errors.Unwrap(err); unwrapped == nil {
399-
t.Errorf("rewritten error must be unwrappable to the original; errors.Unwrap returned nil for %q", msg)
444+
if count != 1 {
445+
t.Errorf("Commands slice must contain exactly one entry named 'dmesg' (the talm stub); got %d — upstream taloscommands.Commands entry was not excluded", count)
400446
}
401447
}
402448

0 commit comments

Comments
 (0)