Skip to content

Commit a337835

Browse files
committed
docs(test-plan): extend manual-test-plan with C5-C7/D3/E3/M6-M7 (#189+#190+#191+#192)
Forward-looking regression anchors for the four apply-safety follow-ups: - C5: drift preview redacts secret-bearing fields by default. Regression anchor: rotating any allowlisted path produces ***redacted (len=N)***; leaking the value to stderr is a security-class bug, verify with grep -F. - C6: --show-secrets-in-drift flag bypasses redaction (operator opt-in for debugging). - C7: Phase 1 walker now blocks malformed StaticHostConfig.address / NetworkRuleConfig.matchSourceAddress[] / WireguardConfig.peers[].endpoint before the apply RPC. Listener-shape (empty endpoint, missing address) intentionally passes. - D3: per-node prefix on the maintenance-connection warning for multi-node insecure apply; single-node case must keep the bare line (no 'node : ' garbage prefix). - E3: --post-upgrade-reconcile-window flag (default 90s, operator-tunable). Hint must not hardcode '90s' literal. - M6: secret-redaction false-positive guard — path-segment-aware matcher must not redact cluster.tokenExtras / siblings. - M7: net-addr walker boundary cases (IPv6, listener-shape, bracketed IPv6:port, mixed CIDR, hostname-as-endpoint). Signed-off-by: Aleksei Sviridkin <[email protected]>
1 parent 24f8007 commit a337835

1 file changed

Lines changed: 93 additions & 0 deletions

File tree

‎docs/manual-test-plan.md‎

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -184,6 +184,39 @@ Expected: each node renders / diffs independently; per-node gate output sections
184184

185185
Expected: Phase 2B auto-skipped (staged config doesn't change ActiveID); output ends with `Staged configuration to be applied after the next reboot`.
186186

187+
### C5. Drift preview redacts secret-bearing fields by default
188+
189+
```bash
190+
# Rotate machine.token by editing secrets.yaml (or any allowlisted path) then:
191+
/tmp/talm-safety apply --dry-run -f nodes/node0.yaml
192+
```
193+
194+
Expected: the drift preview line for `machine.token` reads `machine.token: ***redacted (len=N)*** -> ***redacted (len=M)***`. The literal `old-token-value` / `new-token-value` strings MUST NOT appear in stderr. Non-secret paths (e.g. `machine.network.hostname` if it changed) render verbatim.
195+
196+
Regression anchor: rotating any field in the allowlist (`cluster.{secret,token,aescbcEncryptionSecret,secretboxEncryptionSecret}`, `cluster.{ca,aggregatorCA,serviceAccount,etcd.ca}.key`, `cluster.acceptedCAs[].key`, `machine.{token,ca.key}`, `machine.acceptedCAs[].key`) MUST redact. A regression that silently leaks a secret value into stderr is a security-class bug — verify the substring with `grep -F` against the captured output.
197+
198+
### C6. Drift preview shows secrets with explicit opt-in
199+
200+
```bash
201+
/tmp/talm-safety apply --dry-run --show-secrets-in-drift -f nodes/node0.yaml
202+
```
203+
204+
Expected: same drift preview as C5, but the secret paths render verbatim — no `***redacted***` sentinel. Operator-explicit bypass for debugging.
205+
206+
Regression anchor: `--show-secrets-in-drift` is operator opt-in, never default. Verify by running `talm apply --help` and confirming the flag default is `false`.
207+
208+
### C7. Phase 1 walker rejects malformed net-addr fields before the RPC
209+
210+
When a rendered MachineConfig carries a malformed value in any of the new walker-covered fields, Phase 1 must block before the apply RPC fires:
211+
212+
- `StaticHostConfig.address` not a parseable IP literal.
213+
- `NetworkRuleConfig.matchSourceAddress[i]` not a parseable CIDR.
214+
- `WireguardConfig.peers[i].endpoint` not a parseable host:port.
215+
216+
Hand-craft a chart that emits a bad value (e.g. `address: 999.999.0.1` or `endpoint: notavalid:endpoint`) and run `apply --dry-run`. Expected: Phase 1 emits a blocker citing the offending field path (`doc[N].address`, `doc[N].matchSourceAddress[i]`, `doc[N].peers[i].endpoint`); exit non-zero before any RPC. Valid values (IPv4, IPv6, IPv6:port via `[host]:port`) pass through.
217+
218+
Regression anchor: empty / omitted endpoint on a Wireguard peer is NOT a finding — peers without endpoints are listener-only remote peers. Verify a chart with `endpoint: ""` passes Phase 1.
219+
187220
## D. Apply (insecure / maintenance path)
188221

189222
### D1. Apply with chart that uses discovery
@@ -200,6 +233,21 @@ When a chart renders fully offline (no `lookup`), `talm apply -i` runs through t
200233

201234
**Regression anchor**: D2's offline-renderable behaviour is also covered by unit-level mocking — see `pkg/commands/preflight_apply_safety_test.go` for the in-process equivalent. Surface that file's tests in the manual suite when D2 is impractical to exercise live.
202235

236+
### D3. Per-node prefix on the maintenance-connection warning
237+
238+
On a multi-node insecure apply where every node hits the `ok=false` (maintenance) path, each per-node emission of the warning must carry the node identifier prefix so the operator can correlate which line came from which node:
239+
240+
```bash
241+
/tmp/talm-safety apply -i \
242+
--nodes 192.0.2.10,192.0.2.11,192.0.2.12 \
243+
--endpoints 192.0.2.10,192.0.2.11,192.0.2.12 \
244+
-f nodes/node0.yaml
245+
```
246+
247+
Expected (per node): `node 192.0.2.10: talm: drift verification unavailable on maintenance connection`. The single-node case (empty `nodeID`, the implicit path) MUST still emit the bare `talm: drift verification unavailable on maintenance connection` line — no `node : ` garbage prefix.
248+
249+
Regression anchor: a refactor that always-prefixes (`node : talm: ...` on single-node) is a UX regression. The `nodePrefix("")` helper must collapse to empty for the bare-line single-node case.
250+
203251
## E. Upgrade
204252

205253
### E1. Stage an upgrade to the same image
@@ -221,6 +269,26 @@ Expected: events stream from BOOTING through `post check passed`. Node returns t
221269

222270
Expected: `error validating installer image ... not found`. Talos itself catches this; talm passes through the error.
223271

272+
### E3. Configurable post-upgrade reconcile window
273+
274+
```bash
275+
# Help-text surface — confirms the flag is registered with the 90s default.
276+
/tmp/talm-safety upgrade --help | grep -A1 post-upgrade-reconcile-window
277+
278+
# Custom widened window (slow hardware / large image pulls).
279+
/tmp/talm-safety upgrade --post-upgrade-reconcile-window=180s \
280+
--image ghcr.io/siderolabs/installer:v1.13.0 \
281+
--stage -f nodes/node0.yaml
282+
283+
# Rejection of non-positive values.
284+
/tmp/talm-safety upgrade --post-upgrade-reconcile-window=0s \
285+
-f nodes/node0.yaml
286+
```
287+
288+
Expected for the help line: flag listed with `default 1m30s`. Expected for the 180s run: stderr emits `post-upgrade verify: waiting 3m0s for the node to finish booting...` (or `waiting 180s` depending on Go's Duration formatter — both are acceptable). Expected for the `0s` rejection: error with a hint mentioning "positive duration".
289+
290+
Regression anchor: the version-mismatch hint emitted on a Phase 2C blocker MUST NOT contain the literal string `90s` — operators passing a custom window would see contradictory advice. The hint should reference "the configured reconcile window (`--post-upgrade-reconcile-window`)" instead.
291+
224292
## F. CA rotation
225293

226294
### F1. Rotate CA dry-run
@@ -766,6 +834,31 @@ TALOSCONFIG=$PWD/talosconfig /tmp/talm-safety apply --dry-run \
766834

767835
Expected: same as native `--talosconfig $PWD/talosconfig`. Phase 2A drift preview runs normally.
768836

837+
### M6. Secret redaction false-positive guard (intentional rotation)
838+
839+
When an operator deliberately rotates a secret (e.g. `cluster.token` via `talm init --update`), the drift preview must render both sides as `***redacted (len=N)***` — same shape as C5. The control case lives here: confirm a "rotation" of a non-secret-shaped path adjacent to the allowlist (`cluster.tokenExtras`, `cluster.acceptedCAsExtras`, or a synthetic test path like `machine.network.hostname`) renders verbatim.
840+
841+
Expected: paths matching `cluster.token` → redacted; paths matching `cluster.tokenExtras` → verbatim. The path-segment-aware matcher must not false-positive on string-prefix overlap.
842+
843+
Regression anchor: a future regression to substring matching (`strings.HasPrefix(path, "cluster.token")`) would silently redact `cluster.tokenExtras` and other operator-visible fields that share a prefix. Verify by inspecting a chart with both shapes side-by-side.
844+
845+
### M7. Net-addr walker boundary cases
846+
847+
Walk the net-addr walker (C7) on the full boundary set:
848+
849+
- `StaticHostConfig.address: 2001:db8::1` — valid IPv6, passes.
850+
- `StaticHostConfig.address: 192.0.2.999` — IPv4 with octet >255, blocks.
851+
- `StaticHostConfig` with no `address` field — listener-shape, passes (Talos rejects at RPC with a clearer message).
852+
- `NetworkRuleConfig.matchSourceAddress: [192.0.2.0/24, 2001:db8::/32]` — mixed IPv4 + IPv6 CIDRs, both pass.
853+
- `NetworkRuleConfig.matchSourceAddress: [192.0.2.0/24, notacidr, 10.0.0.0/8]` — one blocker per malformed entry; the count must equal exactly one.
854+
- `WireguardConfig.peers[].endpoint: "[2001:db8::1]:51820"` — bracketed IPv6:port, passes.
855+
- `WireguardConfig.peers[].endpoint: ""` — listener-only peer, passes.
856+
- `WireguardConfig.peers[].endpoint: example.invalid:51820` — hostname:port, blocks (hostnames must already be resolved in the rendered config).
857+
858+
Expected: per-entry findings count exactly, valid forms produce zero findings, and the per-finding `Reason` cites the field path with the bracket-normalised index (`peers[1].endpoint`, not `peers[].endpoint`).
859+
860+
Regression anchor: the no-overlap unit test `TestMultidocNetAddrHandlers_NoOverlapWithRefHandlers` pins the dispatch-map disjointness contract. A future entry that lands in BOTH `multidocHandlers` and `multidocNetAddrHandlers` produces double findings — verify via the unit suite before manual smokes.
861+
769862
## Sanity-check block
770863

771864
Run after every destructive section (E, F, H, and anything that touches `--mode=reboot` / `--mode=staged` / `apply -I`):

0 commit comments

Comments
 (0)