Skip to content

Commit 3295889

Browse files
committed
chore: strip issue and ticket references from public artifacts
Per the project's "describe content, not the workflow that produced it" rule, code comments, help text, README, and test docstrings must not embed bug/ticket numbers — a reader of git log six months from now, with no access to GitHub, must understand what the code does without grepping issue trackers. The same rule applies to external-tracker references and Telegram message IDs. Sweeps every #NNN and similar reference out of: - Operator-facing surface: applyCmd Long, --file Usage, --skip-post-apply-verify and --skip-post-upgrade-verify Usage, templateCmd Long, README copy. These are visible in --help and the project README. - Source comments and test docstrings across pkg/commands/, pkg/modeline/, pkg/applycheck/, pkg/engine/, main.go. Each reference is rewritten to describe the contract, the behaviour, or the failure mode it captures, not the ticket that prompted the work. Assisted-By: Claude <[email protected]> Signed-off-by: Aleksei Sviridkin <[email protected]>
1 parent df0b433 commit 3295889

29 files changed

Lines changed: 180 additions & 176 deletions

‎README.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -176,9 +176,9 @@ cluster:
176176
>
177177
> 2. **Pre-apply drift preview** (`--skip-drift-preview` opt-out, default on). Reads the node's current MachineConfig via COSI and prints a `+`/`-`/`~`/`=` diff of what's about to change, keyed by `(kind, name)`. Informational only — never blocks. The `-` lines are the most useful: they surface stale documents from a previous apply that the new render no longer emits (e.g. an `eth1` LinkConfig lingering after a migration to `eth0`). Reading the current config requires the auth path — `MachineConfig` is a Sensitive COSI resource and is unreachable on the `--insecure` maintenance connection; the gate prints `drift verification unavailable on maintenance connection` (per-node-prefixed on multi-node insecure apply) and proceeds in that case. Secret-bearing field values (`cluster.token`, `cluster.{ca,aggregatorCA,serviceAccount,etcd.ca}.key`, `machine.token` / `machine.ca.key`, the `cluster.acceptedCAs` / `machine.acceptedCAs` slices, `WireguardConfig.privateKey`, the `peers` slice carrying `presharedKey`s) are redacted by default — both sides render as `***redacted (len=N)***` so a rotation surfaces as different-length sentinels without leaking the value. Pass `--show-secrets-in-drift` to see the raw values verbatim (debugging only — disables the redaction for the run). **`--dry-run` runs this gate** — the diff is read-only and "show me what would change" is exactly the dry-run contract.
178178
>
179-
> 3. **Post-apply state verification** (`--skip-post-apply-verify` opt-out, **default off** until the Talos-mutated-field allowlist lands — see [#172](https://github.com/cozystack/talm/issues/172)). After `ApplyConfiguration` returns success, re-reads the on-node MachineConfig and structurally compares it against the bytes that were sent. Divergence blocks the apply chain with a per-document diff, primarily catching silent doc drops (Talos parser ignored an unknown field) and controller reverts. Disabled by default because Talos mutates a handful of leaf fields post-apply (cert hashes, timestamps) that would surface as false-positive divergence without an allowlist. The verify runs only on `--mode=no-reboot`. `--mode=staged`, `--mode=try`, `--mode=reboot`, and `--mode=auto` all skip the gate — each for a documented reason: staged stores rather than activates; try auto-rolls back; reboot kills the COSI connection mid-verify; auto is promoted by Talos to REBOOT internally when the change requires it, so the verify would race the reboot. `--dry-run` skips it too.
179+
> 3. **Post-apply state verification** (`--skip-post-apply-verify` opt-out, **default off** pending a Talos-mutated-field allowlist). After `ApplyConfiguration` returns success, re-reads the on-node MachineConfig and structurally compares it against the bytes that were sent. Divergence blocks the apply chain with a per-document diff, primarily catching silent doc drops (Talos parser ignored an unknown field) and controller reverts. Disabled by default because Talos mutates a handful of leaf fields post-apply (cert hashes, timestamps) that would surface as false-positive divergence without an allowlist. The verify runs only on `--mode=no-reboot`. `--mode=staged`, `--mode=try`, `--mode=reboot`, and `--mode=auto` all skip the gate — each for a documented reason: staged stores rather than activates; try auto-rolls back; reboot kills the COSI connection mid-verify; auto is promoted by Talos to REBOOT internally when the change requires it, so the verify would race the reboot. `--dry-run` skips it too.
180180
>
181-
> 4. **Post-upgrade version verify** (`--skip-post-upgrade-verify` opt-out, default on — the gate runs). After `talm upgrade` reports success, waits the configured reconcile window (default 90s; tune via `--post-upgrade-reconcile-window` for slow hardware / large image pulls) for the node to finish booting, then reads `runtime.Version` COSI and compares the running version's `(Major, Minor)` contract against the contract parsed from the target image tag. Point releases share a minor contract; cross-minor mismatch surfaces as a hint-bearing blocker. Catches the silent A/B rollback case where the upgrade RPC acks success but Talos rolled back to the previous partition (cross-vendor image, missing extensions, failed boot readiness check, slow boot exceeding the configured window). Best-effort surrender on digest-pinned images and unparseable tags. See [#175](https://github.com/cozystack/talm/issues/175) for the reproduction.
181+
> 4. **Post-upgrade version verify** (`--skip-post-upgrade-verify` opt-out, default on — the gate runs). After `talm upgrade` reports success, waits the configured reconcile window (default 90s; tune via `--post-upgrade-reconcile-window` for slow hardware / large image pulls) for the node to finish booting, then reads `runtime.Version` COSI and compares the running version's `(Major, Minor)` contract against the contract parsed from the target image tag. Point releases share a minor contract; cross-minor mismatch surfaces as a hint-bearing blocker. Catches the silent A/B rollback case where the upgrade RPC acks success but Talos rolled back to the previous partition (cross-vendor image, missing extensions, failed boot readiness check, slow boot exceeding the configured window). Best-effort surrender on digest-pinned images and unparseable tags.
182182
>
183183
> The skip flags don't suppress each other — pass them independently. On the `--insecure` (maintenance) path the gates are functionally unreachable for charts that drive discovery via `lookup` — those COSI lookups require an authenticated connection and the render itself errors before any gate runs. Charts that render fully offline (no `lookup` calls) reach the gates on `--insecure` as well, with the Phase 2 hooks degrading gracefully because the `MachineConfig` resource is Sensitive.
184184

@@ -237,7 +237,7 @@ If you were relying on the previous "apply N independent node files" shape (`tal
237237
for n in nodes/*.yaml; do talm apply -f "$n"; done
238238
```
239239

240-
Without migrating, the previous shape would silently stack the later files as side-patches onto the first node's render — only the FIRST node would end up with the expected config; the others were never reached. The post-`#184` shape rejects this misuse: subsequent `-f` files merge into the anchor's bundle rather than triggering their own applies.
240+
Without migrating, the previous shape would silently stack the later files as side-patches onto the first node's render — only the FIRST node would end up with the expected config; the others were never reached. The current shape rejects this misuse: subsequent `-f` files merge into the anchor's bundle rather than triggering their own applies.
241241

242242
## Using talosctl commands
243243

‎main.go‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -136,8 +136,8 @@ func Execute() error {
136136
}
137137

138138
errorString := err.Error()
139-
//nolint:godox // tracked as #153-followup; cobra validation returns plain fmt.Errorf without a typed error, requires substring matching until cobra ships sentinel errors.
140-
// FIXME(#153-followup): cobra arg/flag validation returns plain
139+
//nolint:godox // cobra validation returns plain fmt.Errorf without a typed error; substring matching is the only way to distinguish those from talm's own errors until cobra ships sentinel errors.
140+
// FIXME: cobra arg/flag validation returns plain
141141
// fmt.Errorf without a typed error; substring-matching the
142142
// rendered message is the only way to distinguish those from
143143
// our own errors today. Track a refactor to wrap cobra

‎pkg/applycheck/diff.go‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -101,7 +101,7 @@ type Change struct {
101101
// with different key ordering or whitespace produces the same Diff
102102
// output. Talos-mutated leaf fields (cert hashes etc.) currently land
103103
// as OpUpdate entries with FieldChange path pinpointing what differs;
104-
// an allowlist will be layered on later (see open question in #172).
104+
// an allowlist for Talos-mutated leaf fields will be layered on later.
105105
func Diff(current, desired []byte) ([]Change, error) {
106106
currentDocs, err := parseDocs(current)
107107
if err != nil {

‎pkg/commands/apply.go‎

Lines changed: 42 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -77,9 +77,9 @@ var applyCmd = &cobra.Command{
7777
Short: "Apply config to a Talos node",
7878
Long: `Apply rendered configuration to a Talos node.
7979
80-
Multi-file invocation (anchor + side-patches, per #184): the FIRST -f file
81-
is the anchor — it must carry a "# talm: nodes=[…], templates=[…]" modeline
82-
and lives under a project root (Chart.yaml + secrets.yaml). Subsequent -f
80+
Multi-file invocation (anchor + side-patches): the FIRST -f file is the
81+
anchor — it must carry a "# talm: nodes=[…], templates=[…]" modeline and
82+
live under a project root (Chart.yaml + secrets.yaml). Subsequent -f
8383
files are side-patches stacked on top of the anchor's rendered config in
8484
the order they appear; each is merged via the same overlay mechanism the
8585
anchor's node body uses. A single ApplyConfiguration is issued per node
@@ -153,17 +153,15 @@ func apply() error {
153153
return err
154154
}
155155

156-
// Pre-#184: each -f file ran through applyOneFile in turn, with
157-
// each iteration producing its own ApplyConfiguration. For a
158-
// chain like `-f node.yaml -f side-patch.yaml` that meant the
159-
// second apply OVERWROTE the first — Talos replaces the whole
160-
// MachineConfig per call. Per #184 the first file anchors the
161-
// project root and any subsequent files are side-patches stacked
162-
// on top of the first file's rendered config; the result is a
163-
// single ApplyConfiguration per node carrying the composed
164-
// bundle. Multiple modelined node files (the historical "apply
165-
// to N nodes in one command" idiom) is still supported via the
166-
// first file's modeline carrying `nodes=[…]`.
156+
// Chain semantics: the first -f file anchors the project root
157+
// and any subsequent files are side-patches stacked on top of
158+
// the first file's rendered config; the result is a single
159+
// ApplyConfiguration per node carrying the composed bundle.
160+
// Talos replaces the whole MachineConfig per call, so per-file
161+
// independent applies (as an earlier design did) would have the
162+
// second apply overwrite everything the first wrote. Multiple
163+
// nodes are still targetable from one invocation via the first
164+
// file's modeline carrying `nodes=[…]`.
167165
if len(expandedFiles) == 0 {
168166
return nil
169167
}
@@ -209,13 +207,15 @@ func resetGlobalArgsBetweenFiles(nodesFromArgs, endpointsFromArgs bool) {
209207
// sidePatches are present — side-patches are stacked on top of the
210208
// rendered config, which requires the chart templates from the
211209
// anchor's modeline. Single-file invocations (no side-patches)
212-
// retain the pre-#184 dispatch: modelined → template path,
213-
// non-modelined → direct-patch path.
210+
// dispatch by file shape: modelined → template path, non-modelined
211+
// → direct-patch path.
214212
//
215-
// Stack semantics (#184): the anchor's chart + body + each
216-
// sidePatch in order produces ONE composed config per node; one
217-
// ApplyConfiguration call is issued. Pre-#184 looped each file
218-
// independently, so the second apply overwrote the first.
213+
// Stack semantics: the anchor's chart + body + each sidePatch in
214+
// order produces ONE composed config per node; a single
215+
// ApplyConfiguration call is issued per node. Any design that
216+
// iterated each file as an independent apply would have the second
217+
// apply overwrite everything the first wrote, since Talos replaces
218+
// the whole MachineConfig per call.
219219
func applyOneFile(configFile string, sidePatches []string) error {
220220
hasModeline, modelineErr := fileHasTalmModeline(configFile)
221221
// Malformed modeline (typo in keys, bad JSON value, non-comment
@@ -287,10 +287,11 @@ func applyOneFile(configFile string, sidePatches []string) error {
287287
// before the modeline). The caller surfaces err to the
288288
// operator so the real cause is visible.
289289
//
290-
// Pre-fix this returned a bare bool and swallowed all errors,
291-
// silently routing typoed modelines onto the direct-patch path
292-
// where the operator saw a misleading "no nodes" hint instead of
293-
// "parsing modeline: invalid JSON".
290+
// Distinguishing "no modeline" from "malformed modeline" is the
291+
// reason this helper exists. Returning a bare bool would conflate
292+
// the two, silently routing typoed modelines onto the direct-patch
293+
// path where the operator would see a misleading "no nodes" hint
294+
// instead of "parsing modeline: invalid JSON".
294295
func fileHasTalmModeline(configFile string) (bool, error) {
295296
_, _, err := modeline.FindAndParseModeline(configFile)
296297
if err == nil {
@@ -307,13 +308,14 @@ func fileHasTalmModeline(configFile string) (bool, error) {
307308
return false, err //nolint:wrapcheck // forwarded verbatim; caller wraps with configFile context
308309
}
309310

310-
// applyOneFileTemplateMode runs the template-rendering apply path for
311-
// a single rooted configFile and an optional chain of sidePatches
312-
// (#184). Per node: renders templates, overlays the node body, then
313-
// stacks every sidePatch in order via engine.MergeFileAsPatch — a
314-
// single ApplyConfiguration is issued per node with the final
315-
// composed config. Empty sidePatches reproduces the pre-#184 single-
316-
// file shape. See applyTemplatesPerNode for the per-node loop.
311+
// applyOneFileTemplateMode runs the template-rendering apply path
312+
// for a single rooted configFile and an optional chain of side
313+
// patches. Per node: renders templates, overlays the node body,
314+
// then stacks every sidePatch in order via engine.MergeFileAsPatch
315+
// — a single ApplyConfiguration is issued per node with the final
316+
// composed config. Empty sidePatches degrades to a single-file
317+
// shape (anchor only). See applyTemplatesPerNode for the per-node
318+
// loop.
317319
func applyOneFileTemplateMode(configFile string, sidePatches, modelineTemplates []string, withSecretsPath string) error {
318320
opts := buildApplyRenderOptions(modelineTemplates, withSecretsPath)
319321

@@ -591,9 +593,9 @@ func shouldRunPostApplyVerify(mode machineapi.ApplyConfigurationRequest_Mode, dr
591593
//
592594
// Cost: AUTO applies that DON'T require a reboot lose their
593595
// post-apply verify. Acceptable trade-off: the verify is
594-
// default-off until the Talos-mutated-field allowlist lands
595-
// (see #172), and an operator who needs verify-on-no-reboot
596-
// can pass --mode=no-reboot explicitly.
596+
// default-off pending a Talos-mutated-field allowlist, and
597+
// an operator who needs verify-on-no-reboot can pass
598+
// --mode=no-reboot explicitly.
597599
machineapi.ApplyConfigurationRequest_AUTO:
598600
return false
599601
case machineapi.ApplyConfigurationRequest_NO_REBOOT:
@@ -853,12 +855,12 @@ func resolveAuthTemplateNodes(cliNodes []string, c *client.Client) []string {
853855
return append([]string(nil), cfg.Nodes...)
854856
}
855857

856-
// renderMergeAndApply is the per-node body shared by every apply mode.
857-
// sidePatches is the chain of additional -f files stacked on top of
858-
// the rooted configFile (#184). Each is merged in order via
858+
// renderMergeAndApply is the per-node body shared by every apply
859+
// mode. sidePatches is the chain of additional -f files stacked on
860+
// top of the rooted configFile. Each is merged in order via
859861
// engine.MergeFileAsPatch; the result is a single composed config
860862
// applied with one ApplyConfiguration call per node. Empty slice
861-
// (single -f file) reproduces the pre-#184 single-merge shape.
863+
// (single -f file) is a single-merge shape.
862864
//
863865
//nolint:gocritic // opts taken by value to mirror applyTemplatesPerNode's test-injection signature
864866
func renderMergeAndApply(ctx context.Context, c *client.Client, opts engine.Options, configFile string, sidePatches []string, render renderFunc, apply applyFunc) error {
@@ -1019,7 +1021,7 @@ func resolveTemplatePaths(templates []string, rootDir string) []string {
10191021

10201022
func init() {
10211023
applyCmd.Flags().BoolVarP(&applyCmdFlags.insecure, "insecure", "i", false, "apply using the insecure (encrypted with no auth) maintenance service")
1022-
applyCmd.Flags().StringSliceVarP(&applyCmdFlags.configFiles, "file", "f", nil, "node config files / patches (`.yaml` / `.yml`; shell completion narrows to these extensions). First -f is the modelined anchor (must live under a `talm init`'d project root); subsequent -f files are side-patches stacked onto the anchor's rendered config and may live anywhere (#184).")
1024+
applyCmd.Flags().StringSliceVarP(&applyCmdFlags.configFiles, "file", "f", nil, "node config files / patches (`.yaml` / `.yml`; shell completion narrows to these extensions). First -f is the modelined anchor (must live under a `talm init`'d project root); subsequent -f files are side-patches stacked onto the anchor's rendered config and may live anywhere.")
10231025
applyCmd.Flags().StringVar(&applyCmdFlags.talosVersion, "talos-version", "", "the desired Talos version to generate config for (backwards compatibility, e.g. v0.8)")
10241026
applyCmd.Flags().StringVar(&applyCmdFlags.withSecrets, "with-secrets", "", "use a secrets file generated using 'gen secrets'")
10251027
applyCmd.Flags().StringVar(&applyCmdFlags.kubernetesVersion, "kubernetes-version", constants.DefaultKubernetesVersion, "desired kubernetes version to run")
@@ -1030,7 +1032,7 @@ func init() {
10301032
applyCmd.Flags().BoolVar(&applyCmdFlags.force, "force", false, "will overwrite existing files")
10311033
applyCmd.Flags().BoolVar(&applyCmdFlags.skipResourceValidation, "skip-resource-validation", false, "skip the pre-apply check that declared host resources (links, disks) exist on the target node")
10321034
applyCmd.Flags().BoolVar(&applyCmdFlags.skipDriftPreview, "skip-drift-preview", false, "skip the pre-apply diff of on-node vs rendered MachineConfig")
1033-
applyCmd.Flags().BoolVar(&applyCmdFlags.skipPostApplyVerify, "skip-post-apply-verify", true, "skip the post-apply structural verification of on-node vs sent MachineConfig (default skip until the Talos-mutated field allowlist lands; see #172)")
1035+
applyCmd.Flags().BoolVar(&applyCmdFlags.skipPostApplyVerify, "skip-post-apply-verify", true, "skip the post-apply structural verification of on-node vs sent MachineConfig (default skip until the Talos-mutated field allowlist lands)")
10341036
applyCmd.Flags().BoolVar(&applyCmdFlags.showSecretsInDrift, "show-secrets-in-drift", false, "show secret-bearing field values verbatim in drift preview / post-apply verify output (default: redacted; cluster.token, cluster.ca.key, machine.token, Wireguard private keys, etc.)")
10351037
helpers.AddModeFlags(&applyCmdFlags.Mode, applyCmd)
10361038

‎pkg/commands/completion.go‎

Lines changed: 11 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -120,14 +120,14 @@ func completeNodeFiles(_ *cobra.Command, _ []string, toComplete string) ([]strin
120120
continue
121121
}
122122

123-
// FindAndParseModeline accepts leading operator comments per
124-
// #178; using a strict first-line-only parser would hide
125-
// files that `talm template -I` just produced from
126-
// `talm apply <TAB>` / `talm upgrade <TAB>`. Both
127-
// ErrModelineNotFound and malformed-modeline parse errors
128-
// drop the candidate from the completion list — completion
129-
// must not block on individual-file parse failures, and a
130-
// malformed modeline is still not a useful tab target.
123+
// FindAndParseModeline accepts leading operator comments;
124+
// using a strict first-line-only parser would hide files
125+
// that `talm template -I` just produced from `talm apply
126+
// <TAB>` / `talm upgrade <TAB>`. Both ErrModelineNotFound
127+
// and malformed-modeline parse errors drop the candidate
128+
// from the completion list — completion must not block on
129+
// individual-file parse failures, and a malformed modeline
130+
// is still not a useful tab target.
131131
if _, _, err := modeline.FindAndParseModeline(filepath.Join(root, path)); err != nil {
132132
continue
133133
}
@@ -139,14 +139,14 @@ func completeNodeFiles(_ *cobra.Command, _ []string, toComplete string) ([]strin
139139
}
140140

141141
// CompleteTalosconfigNodes is the exported entry point for
142-
// completion of the root `--nodes` persistent flag (#170). main.go
143-
// wires it via cobra.RegisterFlagCompletionFunc.
142+
// completion of the root `--nodes` persistent flag. main.go wires
143+
// it via cobra.RegisterFlagCompletionFunc.
144144
//
145145
//nolint:gochecknoglobals // package-level var holding the closure produced by completeTalosconfigField; the alternative (per-call construction) re-allocates on every shell completion invocation.
146146
var CompleteTalosconfigNodes = completeTalosconfigField(flagNameNodes)
147147

148148
// CompleteTalosconfigEndpoints is the exported entry point for
149-
// completion of the root `--endpoints` persistent flag (#170).
149+
// completion of the root `--endpoints` persistent flag.
150150
//
151151
//nolint:gochecknoglobals // see CompleteTalosconfigNodes.
152152
var CompleteTalosconfigEndpoints = completeTalosconfigField(flagNameEndpoints)

0 commit comments

Comments
 (0)