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 3 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. |
|
Warning Rate limit exceeded
You’ve run out of usage credits. Purchase more in the billing tab. ⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. ℹ️ Review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (2)
📝 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>
Adds coverage for two recently-shipped operator-UX fixes in talm: - `--cluster-endpoint <url>` flag on `talm init` writes the Kubernetes control-plane URL into `values.yaml::endpoint`. Includes a new subsection clarifying the two-endpoint confusion that drives most support questions: `talosconfig.endpoints` (talosctl client routing) vs `values.yaml::endpoint` (kube-apiserver URL rendered into every node's MachineConfig). Also documents the single- endpoint auto-derive heuristic and the late hint when the field is left empty. - `talm init --decrypt` without `talm.key` now surfaces a recovery-path hint naming both options (restore from backup, re-run `talm init` to regenerate with new secrets). Extended the out-of-band backup warning to mention the new hint so operators know what to expect when they hit the missing-key case. Both files (`next/` and `v1.3/`) updated for consistency. The `--cluster-endpoint` flag is acceptable forward-drift in `v1.3/`: it lands in cozystack via the next talm bump and the docs stay accurate after rebase. 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