[docs] talm: encrypted user values and dry-run secret redaction by lexfrei · Pull Request #590 · cozystack/website

Aleksei Sviridkin (lexfrei) · 2026-06-24T12:48:32Z

What

Adds a 2.4 Encrypted user values and secret redaction section to the next talm install guide.

Why

The talm encrypted-user-values feature — encrypted values-secret.yaml decrypted in memory, honored at both talm template and talm apply, with secrets kept out of committed node files and CI logs — had no user-facing documentation. The new section covers the full workflow (create → encrypt → reference in templateOptions.valueFiles → use in templates) and how secrets are redacted across talm template, talm template -i, and talm apply --dry-run, including --show-secrets / --show-secrets-in-drift and the value-based-matching sharp edge.

Notes

Lands in next only — the feature ships in talm v0.32.0; not backported to v1.0–v1.4 (older talm).
Documents the operator-facing side of feat: first-class encrypted user values, honored at template and apply talm#222 (merged).

Summary by CodeRabbit

Documentation
- Added guidance for encrypting user-supplied values and keeping secrets redacted in Talm v0.32+.
- Documented the recommended workflow for creating, encrypting, and referencing secret values during templating and apply operations.
- Clarified how secrets are shown or hidden in command output, including dry runs and optional secret-display flags.
- Added warnings about a common usage pitfall where encrypted values may be omitted in later apply steps.

netlify · 2026-06-24T12:48:38Z

❌ Deploy Preview for cozystack failed.

Name	Link
🔨 Latest commit	`c1235ab`
🔍 Latest deploy log	https://app.netlify.com/projects/cozystack/deploys/6a4dff0b9d7452000889f2af

coderabbitai · 2026-06-24T12:48:42Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: d0655ff0-a6b2-4577-96fd-ab8212431e02

📥 Commits

Reviewing files that changed from the base of the PR and between 94b299f and c1235ab.

📒 Files selected for processing (1)

content/en/docs/next/install/kubernetes/talm.md

📝 Walkthrough

Walkthrough

Adds a new documentation subsection to talm.md describing encrypted operator-supplied secret values for Talm v0.32+, covering encryption via talm.key, Chart.yaml wiring, and secret redaction behavior across talm template, node-file rendering, and dry-run apply.

Changes

Talm documentation update

Layer / File(s)	Summary
Encrypted values and secret redaction section `content/en/docs/next/install/kubernetes/talm.md`	Documents creating `values-secret.yaml`, encrypting it with `talm.key` via `talm init --encrypt`, referencing it from `Chart.yaml` under `templateOptions.valueFiles`, and redaction behavior across `talm template`, node-file rendering (`-I`), and `talm apply --dry-run`, including `--show-secrets`/`--show-secrets-in-drift` flags and a value-collision caveat.

Estimated code review effort: 1 (Trivial) | ~5 minutes

Possibly related PRs

cozystack/website#537: Both PRs update the same talm.md section around encrypted artifacts and the talm.key/talm init --encrypt workflow.

Suggested reviewers: kvaps, lllamnyp

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the added documentation about encrypted user values and secret redaction.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch docs/talm-encrypted-user-values

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands.}

gemini-code-assist

Code Review

This pull request adds a new section to the Talm documentation explaining how to handle encrypted user values and secret redaction. The feedback suggests formatting the YAML configuration using block style instead of flow style, maintaining American English spelling consistency (e.g., changing 'Behaviour' to 'Behavior' and 'honours' to 'honors'), and correcting a minor grammatical issue.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

gemini-code-assist · 2026-06-24T12:49:29Z

+**Step 3 — reference the encrypted file** from `Chart.yaml` by adding it to `templateOptions.valueFiles`, so both `talm template` and `talm apply` read it:
+
+```yaml
+templateOptions: { valueFiles: ["values-secret.encrypted.yaml"] }


Using block style for YAML is generally preferred over flow style (JSON-like) in Kubernetes and Helm documentation as it is more readable and consistent with the rest of the examples in this guide.

Suggested change

templateOptions: { valueFiles: ["values-secret.encrypted.yaml"] }

templateOptions:

valueFiles:

- values-secret.encrypted.yaml

Switched to block style in edff884 — agreed, it reads better and matches the other examples in this guide.

gemini-code-assist · 2026-06-24T12:49:29Z

+
+How secrets are handled across commands:
+
+| Command | Behaviour |


The rest of the documentation primarily uses American English spelling (e.g., optimized, customizable, customization). Consider changing Behaviour to Behavior to maintain spelling consistency across the document.

Fixed in edff884 (Behaviour → Behavior).

gemini-code-assist · 2026-06-24T12:49:29Z

+| `talm template -i` (node file) | secret values are omitted entirely from the committed node file — the real value is re-rendered in memory only at apply, so no plaintext (or ciphertext) ever lands in `nodes/*.yaml`. |
+| `talm apply --dry-run` | both diffs redact secrets: talm's structured drift preview AND the server-returned `Config diff:` block. `--show-secrets-in-drift` reveals them. |
+
+The `--show-secrets-in-drift` flag governs every secret-bearing surface of the apply dry-run, covering both these user values and the Talos bootstrap material (`cluster.ca.key`, `machine.token`, encryption secrets, Wireguard keys, etc.). By default a dry-run never prints a CA private key or a user secret in cleartext.


Add a comma after By default to improve readability and grammatical correctness.

Added the comma in edff884.

gemini-code-assist · 2026-06-24T12:49:29Z

+
+The `--show-secrets-in-drift` flag governs every secret-bearing surface of the apply dry-run, covering both these user values and the Talos bootstrap material (`cluster.ca.key`, `machine.token`, encryption secrets, Wireguard keys, etc.). By default a dry-run never prints a CA private key or a user secret in cleartext.
+
+`talm apply` honours the full set of value sources, matching `talm template`: `--values`, `--set`, `--set-string`, `--set-file`, `--set-json`, `--set-literal`, merged on top of the `templateOptions.*` defaults from `Chart.yaml`. This keeps `template` and `apply` rendering identically.


Consider changing honours to honors to remain consistent with the American English spelling used throughout the rest of the documentation.

Fixed in edff884 (honours → honors).

Add a talm.md section covering the encrypted-user-values workflow (values-secret.yaml -> talm.key encryption -> templateOptions.valueFiles -> in-template use) and how secrets are redacted across talm template, talm template -i, and talm apply --dry-run. Documents --show-secrets / --show-secrets-in-drift, the apply value-source flags, and the value-based-matching sharp edge. Signed-off-by: Aleksei Sviridkin <f@lex.la>

- block-style YAML for the templateOptions.valueFiles example - American English spelling (Behavior, honors) - comma after "By default" for readability Signed-off-by: Aleksei Sviridkin <f@lex.la>

IvanHunters

One blocking fix before merge; everything else is verified correct against talm v0.32.0 source.

Blocking:

The behavior table lists talm template -i for the in-place node-file row, but -i is --insecure (template via the maintenance service). The in-place flag is -I / --in-place. This is worth fixing carefully: suggesting -i in a secret-handling context is misleading — the --show-secrets help itself notes it "never affects -I, which always omits them". Please change -i to -I.

Everything else checks out against the source: talm init --encrypt/-e, the --values unpersisted-secret warning, the stdout *** redaction vs --show-secrets, --dry-run redaction of both structured drift and the server Config diff: block, --show-secrets-in-drift, and the value-based exact-match redaction caveat.

The secret-handling table referenced `talm template -i` for the in-place node-file case, but `-i` is `--insecure` (render via the maintenance service). In-place rendering into nodes/*.yaml uses `-I` / `--in-place`. Assisted-By: Claude <noreply@anthropic.com> Signed-off-by: Aleksei Sviridkin <f@lex.la>

IvanHunters

LGTM

The blocking -i → -I fix is in place (commit 1ac0301). Every talm flag/behavior
claim verified against talm source, twice:

-I/--in-place, -i/--insecure, -e/--encrypt semantics match
(pkg/commands/template.go:486-488,501, init.go:1592).
-I always omits secrets regardless of --show-secrets: sealRenderedSecrets
matches case inplace: first (value_secret.go:51-71), covered by the
inplace omits contract test.
dry-run redacts the server-side Config diff: block via printApplyResultsRedacted
(preflight_apply_safety_modedetails.go:169), covered by
contract_modedetails_redaction_test.go.

No claim tells the user a command is safe while it actually leaks secrets. markdownlint clean.

gemini-code-assist Bot reviewed Jun 24, 2026

View reviewed changes

Aleksei Sviridkin (lexfrei) marked this pull request as ready for review June 24, 2026 13:21

Aleksei Sviridkin (lexfrei) requested review from Andrei Kvapil (kvaps) and Timofei Larkin (lllamnyp) as code owners June 24, 2026 13:21

Aleksei Sviridkin (lexfrei) marked this pull request as draft June 24, 2026 13:23

Aleksei Sviridkin (lexfrei) marked this pull request as ready for review June 24, 2026 13:30

Aleksei Sviridkin (lexfrei) self-assigned this Jun 25, 2026

Aleksei Sviridkin (lexfrei) added 2 commits July 1, 2026 13:45

[docs] talm: address review feedback on encrypted-values section

9884e5e

- block-style YAML for the templateOptions.valueFiles example - American English spelling (Behavior, honors) - comma after "By default" for readability Signed-off-by: Aleksei Sviridkin <f@lex.la>

Aleksei Sviridkin (lexfrei) force-pushed the docs/talm-encrypted-user-values branch from edff884 to 9884e5e Compare July 1, 2026 10:46

IvanHunters requested changes Jul 2, 2026

View reviewed changes

IvanHunters approved these changes Jul 8, 2026

View reviewed changes

Merge branch 'main' into docs/talm-encrypted-user-values

c1235ab

Aleksei Sviridkin (lexfrei) merged commit 4921068 into main Jul 8, 2026
2 of 6 checks passed

Aleksei Sviridkin (lexfrei) deleted the docs/talm-encrypted-user-values branch July 8, 2026 07:57


		How secrets are handled across commands:

		\| Command \| Behaviour \|


		The `--show-secrets-in-drift` flag governs every secret-bearing surface of the apply dry-run, covering both these user values and the Talos bootstrap material (`cluster.ca.key`, `machine.token`, encryption secrets, Wireguard keys, etc.). By default a dry-run never prints a CA private key or a user secret in cleartext.

		`talm apply` honours the full set of value sources, matching `talm template`: `--values`, `--set`, `--set-string`, `--set-file`, `--set-json`, `--set-literal`, merged on top of the `templateOptions.*` defaults from `Chart.yaml`. This keeps `template` and `apply` rendering identically.

Uh oh!

Conversation

Aleksei Sviridkin (lexfrei) commented Jun 24, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What

Why

Notes

Summary by CodeRabbit

Uh oh!

netlify Bot commented Jun 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

❌ Deploy Preview for cozystack failed.

Uh oh!

coderabbitai Bot commented Jun 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

gemini-code-assist Bot Jun 24, 2026

Choose a reason for hiding this comment

Uh oh!

Aleksei Sviridkin (lexfrei) Jun 24, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot Jun 24, 2026

Choose a reason for hiding this comment

Uh oh!

Aleksei Sviridkin (lexfrei) Jun 24, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot Jun 24, 2026

Choose a reason for hiding this comment

Uh oh!

Aleksei Sviridkin (lexfrei) Jun 24, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot Jun 24, 2026

Choose a reason for hiding this comment

Uh oh!

Aleksei Sviridkin (lexfrei) Jun 24, 2026

Choose a reason for hiding this comment

Uh oh!

IvanHunters left a comment

Choose a reason for hiding this comment

Uh oh!

IvanHunters left a comment

Choose a reason for hiding this comment

LGTM

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Aleksei Sviridkin (lexfrei) commented Jun 24, 2026 •

edited by coderabbitai Bot

Loading

netlify Bot commented Jun 24, 2026 •

edited

Loading

coderabbitai Bot commented Jun 24, 2026 •

edited

Loading