docs(talm): expand init reference with flag matrix + update + encrypt/decrypt#537
docs(talm): expand init reference with flag matrix + update + encrypt/decrypt#537lexfrei wants to merge 2 commits into
Conversation
…/decrypt
The talm.md install guide had a single quick-start example for
'talm init' and no flag reference. Operators following the guide
landed on the support channel asking which flags are available,
how '--update' interacts with their customisations, and how the
'--encrypt' / '--decrypt' round-trip works — answers that are not
discoverable from the page today.
Expand section 2.1 with:
- Project layout: call out 'secrets.encrypted.yaml',
'talosconfig.encrypted', and 'talm.key' (the previous list
only mentioned 'secrets.yaml').
- Available presets: name the two embedded presets ('cozystack',
'talm') so operators stop guessing the --preset argument.
- Flag reference grouped by mode (new project / update / encrypt
/ decrypt) with the exact short and long forms, defaults, and
interactions between flags (--force semantics differ between
new-project and --update).
- Updating-to-a-newer-talm-release subsection covering the two
common --update invocations (interactive vs --force CI).
- Encrypt / decrypt round-trip with a sentence about backing up
'talm.key' out-of-band.
Applied to both /docs/v1.3 (current stable) and /docs/next
(unreleased), mirroring the existing cross-version structure.
Signed-off-by: Aleksei Sviridkin <f@lex.la>
✅ Deploy Preview for cozystack ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (2)
✅ Files skipped from review due to trivial changes (1)
🚧 Files skipped from review as they are similar to previous changes (1)
📝 WalkthroughWalkthroughThis PR expands Talm initialization documentation in both the ChangesTalm Init Documentation Expansion
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
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. Comment |
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?s=60&v=4){kind=small}
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request updates the talm documentation for both the next and v1.3 versions, adding detailed sections for available presets, a talm init flag reference, and instructions for updating releases and managing encrypted secrets. The review feedback suggests improving consistency by including kubeconfig.encrypted in the project layout and command examples, and standardizing the spelling of 'customizations' to US English.
| - `Chart.yaml` - a file containing the common information about your project; the name of the chart is used as the name for the newly created cluster. | ||
| - `templates` - a directory used to describe templates for the configuration generation. | ||
| - `secrets.yaml` - a file containing secrets for your cluster. | ||
| - `secrets.encrypted.yaml`, `talosconfig.encrypted` - encrypted counterparts produced from `talm.key` (commit these to git instead of the plaintext files). |
There was a problem hiding this comment.
The list of encrypted files is missing kubeconfig.encrypted, which is mentioned later in the flag reference (line 131). Including it here ensures the project layout description is complete and consistent.
| - `secrets.encrypted.yaml`, `talosconfig.encrypted` - encrypted counterparts produced from `talm.key` (commit these to git instead of the plaintext files). | |
| - `secrets.encrypted.yaml`, `talosconfig.encrypted`, `kubeconfig.encrypted` - encrypted counterparts produced from `talm.key` (commit these to git instead of the plaintext files). |
| - `-u, --update` - re-extract `charts/talm/` and other preset-shipped files from the talm binary. `--preset` is required; `--name` is not. | ||
| - `--force` - auto-accept every preset-template diff (skip the interactive prompt; safe to use in CI). | ||
|
|
||
| `--update` rewrites preset-shipped files only; your `values.yaml`, `secrets.yaml`, `templates/`, and `nodes/` customisations are preserved. |
There was a problem hiding this comment.
The document uses US English spelling (e.g., 'optimized', 'customizable', 'initialize'). 'customisations' should be updated to 'customizations' for consistency.
| `--update` rewrites preset-shipped files only; your `values.yaml`, `secrets.yaml`, `templates/`, and `nodes/` customisations are preserved. | |
| `--update` rewrites preset-shipped files only; your `values.yaml`, `secrets.yaml`, `templates/`, and `nodes/` customizations are preserved. |
| The encrypted copies are what you commit to git; the plaintext copies are what `talm` reads. Use these to round-trip between the two: | ||
|
|
||
| ```bash | ||
| talm init --encrypt # secrets.yaml -> secrets.encrypted.yaml; talosconfig -> talosconfig.encrypted |
There was a problem hiding this comment.
The comment for the encrypt command is missing the kubeconfig mapping, which is described as being handled by the --encrypt flag on line 131.
| talm init --encrypt # secrets.yaml -> secrets.encrypted.yaml; talosconfig -> talosconfig.encrypted | |
| talm init --encrypt # secrets.yaml -> secrets.encrypted.yaml; talosconfig -> talosconfig.encrypted; kubeconfig -> kubeconfig.encrypted |
| - `Chart.yaml` - a file containing the common information about your project; the name of the chart is used as the name for the newly created cluster. | ||
| - `templates` - a directory used to describe templates for the configuration generation. | ||
| - `secrets.yaml` - a file containing secrets for your cluster. | ||
| - `secrets.encrypted.yaml`, `talosconfig.encrypted` - encrypted counterparts produced from `talm.key` (commit these to git instead of the plaintext files). |
There was a problem hiding this comment.
The list of encrypted files is missing kubeconfig.encrypted, which is mentioned later in the flag reference (line 131). Including it here ensures the project layout description is complete and consistent.
| - `secrets.encrypted.yaml`, `talosconfig.encrypted` - encrypted counterparts produced from `talm.key` (commit these to git instead of the plaintext files). | |
| - `secrets.encrypted.yaml`, `talosconfig.encrypted`, `kubeconfig.encrypted` - encrypted counterparts produced from `talm.key` (commit these to git instead of the plaintext files). |
| - `-u, --update` - re-extract `charts/talm/` and other preset-shipped files from the talm binary. `--preset` is required; `--name` is not. | ||
| - `--force` - auto-accept every preset-template diff (skip the interactive prompt; safe to use in CI). | ||
|
|
||
| `--update` rewrites preset-shipped files only; your `values.yaml`, `secrets.yaml`, `templates/`, and `nodes/` customisations are preserved. |
There was a problem hiding this comment.
The document uses US English spelling (e.g., 'optimized', 'customizable', 'initialize'). 'customisations' should be updated to 'customizations' for consistency.
| `--update` rewrites preset-shipped files only; your `values.yaml`, `secrets.yaml`, `templates/`, and `nodes/` customisations are preserved. | |
| `--update` rewrites preset-shipped files only; your `values.yaml`, `secrets.yaml`, `templates/`, and `nodes/` customizations are preserved. |
| The encrypted copies are what you commit to git; the plaintext copies are what `talm` reads. Use these to round-trip between the two: | ||
|
|
||
| ```bash | ||
| talm init --encrypt # secrets.yaml -> secrets.encrypted.yaml; talosconfig -> talosconfig.encrypted |
There was a problem hiding this comment.
The comment for the encrypt command is missing the kubeconfig mapping, which is described as being handled by the --encrypt flag on line 131.
| talm init --encrypt # secrets.yaml -> secrets.encrypted.yaml; talosconfig -> talosconfig.encrypted | |
| talm init --encrypt # secrets.yaml -> secrets.encrypted.yaml; talosconfig -> talosconfig.encrypted; kubeconfig -> kubeconfig.encrypted |
The talm template example invoked the shorthand -n IP, which is no longer registered as of cozystack/talm v0.28.0 (PR cozystack#197). Without this fix the documented bootstrap golden path errors out at parse time with 'flag -n not defined'. Long form --nodes IP is the permanent replacement. Assisted-By: Claude <noreply@anthropic.com> Signed-off-by: Aleksei Sviridkin <f@lex.la>
1 participant
What
Expand section 2.1 "Initialize Configuration" of the talm install guide (
/docs/v1.3and/docs/next) with the missing operator-facing detail that has been driving questions on the support channel:secrets.encrypted.yaml,talosconfig.encrypted, andtalm.key(the previous list mentioned onlysecrets.yaml, leaving operators unsure why the project also ships encrypted counterparts and a key file).cozystack,talm) so operators stop guessing the--presetargument.--force(CI) invocations oftalm init --update.talm.keyout-of-band.Why
The current section is a single quick-start example and a directory listing. Operators reading the guide do not know which flags
talm initsupports beyond--preset/--name, how--updateinteracts with their customisations, or how the encrypt / decrypt round-trip works.talm init -hlists the flags but doesn't explain semantics or which preset names are valid.Source-of-truth for flags:
cozystack/talmpkg/commands/init.goonmain. Preset list:cozystack/talmpkg/generated/embed.go.Where
content/en/docs/v1.3/install/kubernetes/talm.md(current stable)content/en/docs/next/install/kubernetes/talm.md(unreleased)Older versions (
v0/v1.0/v1.1/v1.2) are historical snapshots and intentionally left untouched.Summary by CodeRabbit