From db59d4ab50fac58c9287f7c7b95dae556aefb4fd Mon Sep 17 00:00:00 2001 From: Aleksei Sviridkin Date: Wed, 13 May 2026 12:21:07 +0300 Subject: [PATCH 1/4] docs(talm): expand init reference with flag matrix + update + encrypt/decrypt MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- .../en/docs/next/install/kubernetes/talm.md | 57 +++++++++++++++++++ .../en/docs/v1.3/install/kubernetes/talm.md | 57 +++++++++++++++++++ 2 files changed, 114 insertions(+) diff --git a/content/en/docs/next/install/kubernetes/talm.md b/content/en/docs/next/install/kubernetes/talm.md index e1cf66aa..c72c42f3 100644 --- a/content/en/docs/next/install/kubernetes/talm.md +++ b/content/en/docs/next/install/kubernetes/talm.md @@ -92,9 +92,66 @@ The structure of the project mostly mirrors an ordinary Helm chart: - `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). +- `talm.key` - the project-local age key used for encrypt / decrypt. Back this up; without it the encrypted files cannot be reopened. - `values.yaml` - a common values file used to provide parameters for the templating. - `nodes` - an optional directory used to describe and store generated configuration for nodes. +#### Available Presets + +`talm` ships two embedded presets: + +- `cozystack` - the production preset used by this guide. +- `talm` - a minimal library chart for advanced users who want to build their own preset on top of it. + +Pass the preset name via `-p` / `--preset`. + +#### `talm init` Flag Reference + +Run `talm init -h` for the canonical list. Grouped by mode: + +**Create a new project (default mode):** + +- `-p, --preset ` - preset for file generation. +- `-N, --name ` - cluster name. +- `--endpoints ` - Talos API endpoints (comma-separated). +- `--image ` - override the Talos installer image written to the preset's `values.yaml` (e.g. `factory.talos.dev/installer/:`). +- `--talos-version ` - desired Talos contract version for backwards-compatibility templating (e.g. `v1.12`). +- `--force` - overwrite existing files without prompt. + +**Update an existing project to the latest bundled library chart:** + +- `-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. + +**Manage encrypted secrets in-place:** + +- `-e, --encrypt` - encrypt `secrets.yaml` / `talosconfig` / `kubeconfig` into their `.encrypted` counterparts. Requires `talm.key`. +- `-d, --decrypt` - reverse the above. Does not require `--preset` or `--name`. + +#### Updating to a Newer Talm Release + +When a new talm version ships a newer bundled library chart, refresh your project in place: + +```bash +cd cozystack-cluster +talm init --update --preset cozystack # interactive: prompts for each preset-template diff +talm init --update --preset cozystack --force # non-interactive: auto-accept all diffs +``` + +#### Encrypt / Decrypt Round-Trip + +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 +talm init --decrypt # reverse — does not require --preset or --name +``` + +Lose the `talm.key` file and the encrypted counterparts become unreadable, so keep a backup of the key out-of-band. + ### 2.2. Edit Configuration Values and Templates diff --git a/content/en/docs/v1.3/install/kubernetes/talm.md b/content/en/docs/v1.3/install/kubernetes/talm.md index 8b3ab2d2..c1962e3c 100644 --- a/content/en/docs/v1.3/install/kubernetes/talm.md +++ b/content/en/docs/v1.3/install/kubernetes/talm.md @@ -92,9 +92,66 @@ The structure of the project mostly mirrors an ordinary Helm chart: - `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). +- `talm.key` - the project-local age key used for encrypt / decrypt. Back this up; without it the encrypted files cannot be reopened. - `values.yaml` - a common values file used to provide parameters for the templating. - `nodes` - an optional directory used to describe and store generated configuration for nodes. +#### Available Presets + +`talm` ships two embedded presets: + +- `cozystack` - the production preset used by this guide. +- `talm` - a minimal library chart for advanced users who want to build their own preset on top of it. + +Pass the preset name via `-p` / `--preset`. + +#### `talm init` Flag Reference + +Run `talm init -h` for the canonical list. Grouped by mode: + +**Create a new project (default mode):** + +- `-p, --preset ` - preset for file generation. +- `-N, --name ` - cluster name. +- `--endpoints ` - Talos API endpoints (comma-separated). +- `--image ` - override the Talos installer image written to the preset's `values.yaml` (e.g. `factory.talos.dev/installer/:`). +- `--talos-version ` - desired Talos contract version for backwards-compatibility templating (e.g. `v1.12`). +- `--force` - overwrite existing files without prompt. + +**Update an existing project to the latest bundled library chart:** + +- `-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. + +**Manage encrypted secrets in-place:** + +- `-e, --encrypt` - encrypt `secrets.yaml` / `talosconfig` / `kubeconfig` into their `.encrypted` counterparts. Requires `talm.key`. +- `-d, --decrypt` - reverse the above. Does not require `--preset` or `--name`. + +#### Updating to a Newer Talm Release + +When a new talm version ships a newer bundled library chart, refresh your project in place: + +```bash +cd cozystack-cluster +talm init --update --preset cozystack # interactive: prompts for each preset-template diff +talm init --update --preset cozystack --force # non-interactive: auto-accept all diffs +``` + +#### Encrypt / Decrypt Round-Trip + +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 +talm init --decrypt # reverse — does not require --preset or --name +``` + +Lose the `talm.key` file and the encrypted counterparts become unreadable, so keep a backup of the key out-of-band. + ### 2.2. Edit Configuration Values and Templates From eead9f488c05581fbb537ba2ed25af9c1649da97 Mon Sep 17 00:00:00 2001 From: Aleksei Sviridkin Date: Wed, 13 May 2026 16:16:54 +0300 Subject: [PATCH 2/4] docs(talm): use --nodes long form after -n shorthand drop in v0.28.0 The talm template example invoked the shorthand -n IP, which is no longer registered as of cozystack/talm v0.28.0 (PR #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 Signed-off-by: Aleksei Sviridkin --- content/en/docs/next/install/kubernetes/talm.md | 6 +++--- content/en/docs/v1.3/install/kubernetes/talm.md | 6 +++--- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/content/en/docs/next/install/kubernetes/talm.md b/content/en/docs/next/install/kubernetes/talm.md index c72c42f3..6e57c138 100644 --- a/content/en/docs/next/install/kubernetes/talm.md +++ b/content/en/docs/next/install/kubernetes/talm.md @@ -219,9 +219,9 @@ Create a `nodes` directory and collect the information from each node into a nod ```bash mkdir nodes -talm template -e 192.168.123.11 -n 192.168.123.11 -t templates/controlplane.yaml -i > nodes/node1.yaml -talm template -e 192.168.123.12 -n 192.168.123.12 -t templates/controlplane.yaml -i > nodes/node2.yaml -talm template -e 192.168.123.13 -n 192.168.123.13 -t templates/controlplane.yaml -i > nodes/node3.yaml +talm template -e 192.168.123.11 --nodes 192.168.123.11 -t templates/controlplane.yaml -i > nodes/node1.yaml +talm template -e 192.168.123.12 --nodes 192.168.123.12 -t templates/controlplane.yaml -i > nodes/node2.yaml +talm template -e 192.168.123.13 --nodes 192.168.123.13 -t templates/controlplane.yaml -i > nodes/node3.yaml ``` The `--insecure` (`-i`) parameter is required because Talm must retrieve configuration data diff --git a/content/en/docs/v1.3/install/kubernetes/talm.md b/content/en/docs/v1.3/install/kubernetes/talm.md index c1962e3c..03211cd6 100644 --- a/content/en/docs/v1.3/install/kubernetes/talm.md +++ b/content/en/docs/v1.3/install/kubernetes/talm.md @@ -219,9 +219,9 @@ Create a `nodes` directory and collect the information from each node into a nod ```bash mkdir nodes -talm template -e 192.168.123.11 -n 192.168.123.11 -t templates/controlplane.yaml -i > nodes/node1.yaml -talm template -e 192.168.123.12 -n 192.168.123.12 -t templates/controlplane.yaml -i > nodes/node2.yaml -talm template -e 192.168.123.13 -n 192.168.123.13 -t templates/controlplane.yaml -i > nodes/node3.yaml +talm template -e 192.168.123.11 --nodes 192.168.123.11 -t templates/controlplane.yaml -i > nodes/node1.yaml +talm template -e 192.168.123.12 --nodes 192.168.123.12 -t templates/controlplane.yaml -i > nodes/node2.yaml +talm template -e 192.168.123.13 --nodes 192.168.123.13 -t templates/controlplane.yaml -i > nodes/node3.yaml ``` The `--insecure` (`-i`) parameter is required because Talm must retrieve configuration data From 5781e29d5e9f0c80b8eac9147f959738eb59d48d Mon Sep 17 00:00:00 2001 From: Aleksei Sviridkin Date: Thu, 14 May 2026 15:03:57 +0300 Subject: [PATCH 3/4] docs(talm): document --cluster-endpoint flag and talm.key recovery hint Adds coverage for two recently-shipped operator-UX fixes in talm: - `--cluster-endpoint ` 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 Signed-off-by: Aleksei Sviridkin --- content/en/docs/next/install/kubernetes/talm.md | 14 ++++++++++++-- content/en/docs/v1.3/install/kubernetes/talm.md | 14 ++++++++++++-- 2 files changed, 24 insertions(+), 4 deletions(-) diff --git a/content/en/docs/next/install/kubernetes/talm.md b/content/en/docs/next/install/kubernetes/talm.md index 6e57c138..8349e853 100644 --- a/content/en/docs/next/install/kubernetes/talm.md +++ b/content/en/docs/next/install/kubernetes/talm.md @@ -114,11 +114,21 @@ Run `talm init -h` for the canonical list. Grouped by mode: - `-p, --preset ` - preset for file generation. - `-N, --name ` - cluster name. -- `--endpoints ` - Talos API endpoints (comma-separated). +- `--endpoints ` - Talos API endpoints (comma-separated) embedded into `talosconfig.contexts..endpoints` for the talosctl client. See "Endpoint flags: talosctl client vs Kubernetes control plane" below. +- `--cluster-endpoint ` - Kubernetes control-plane URL written to `values.yaml::endpoint` (e.g. `https://:6443`). Validated for scheme + host + port at init time. - `--image ` - override the Talos installer image written to the preset's `values.yaml` (e.g. `factory.talos.dev/installer/:`). - `--talos-version ` - desired Talos contract version for backwards-compatibility templating (e.g. `v1.12`). - `--force` - overwrite existing files without prompt. +##### Endpoint flags: talosctl client vs Kubernetes control plane + +Two distinct concepts share the word "endpoint" in talm projects: + +- **`talosconfig.contexts..endpoints`** - list of `host[:port]` entries the talosctl client uses to reach the Talos API. Populated by `--endpoints` (plural, comma-separated list). +- **`values.yaml::endpoint`** - single URL with scheme + host + port that the chart renders into `cluster.controlPlane.endpoint` of every node's MachineConfig. This is what kubelet and kube-proxy dial. Populated by `--cluster-endpoint` (singular, full URL). + +When `--endpoints` is given exactly one value, init auto-derives `values.yaml::endpoint` as `https://:6443` because the single-target case is unambiguous. Multi-endpoint inputs never auto-derive (picking one node would silently couple cluster availability to it) - pass `--cluster-endpoint` explicitly or fill `values.yaml::endpoint` later by hand. The init flow prints a hint at the end when the field is left empty. + **Update an existing project to the latest bundled library chart:** - `-u, --update` - re-extract `charts/talm/` and other preset-shipped files from the talm binary. `--preset` is required; `--name` is not. @@ -150,7 +160,7 @@ talm init --encrypt # secrets.yaml -> secrets.encrypted.yaml; talosconfig -> t talm init --decrypt # reverse — does not require --preset or --name ``` -Lose the `talm.key` file and the encrypted counterparts become unreadable, so keep a backup of the key out-of-band. +Lose the `talm.key` file and the encrypted counterparts become unreadable, so keep a backup of the key out-of-band. When `talm init --decrypt` runs against a project where `talm.key` is missing, talm surfaces both recovery paths in the error hint: restore the backed-up key, or re-run `talm init` to regenerate (with the explicit warning that regenerating writes new secrets, making the old `secrets.encrypted.yaml` undecryptable without the original key). ### 2.2. Edit Configuration Values and Templates diff --git a/content/en/docs/v1.3/install/kubernetes/talm.md b/content/en/docs/v1.3/install/kubernetes/talm.md index 03211cd6..112af1d1 100644 --- a/content/en/docs/v1.3/install/kubernetes/talm.md +++ b/content/en/docs/v1.3/install/kubernetes/talm.md @@ -114,11 +114,21 @@ Run `talm init -h` for the canonical list. Grouped by mode: - `-p, --preset ` - preset for file generation. - `-N, --name ` - cluster name. -- `--endpoints ` - Talos API endpoints (comma-separated). +- `--endpoints ` - Talos API endpoints (comma-separated) embedded into `talosconfig.contexts..endpoints` for the talosctl client. See "Endpoint flags: talosctl client vs Kubernetes control plane" below. +- `--cluster-endpoint ` - Kubernetes control-plane URL written to `values.yaml::endpoint` (e.g. `https://:6443`). Validated for scheme + host + port at init time. - `--image ` - override the Talos installer image written to the preset's `values.yaml` (e.g. `factory.talos.dev/installer/:`). - `--talos-version ` - desired Talos contract version for backwards-compatibility templating (e.g. `v1.12`). - `--force` - overwrite existing files without prompt. +##### Endpoint flags: talosctl client vs Kubernetes control plane + +Two distinct concepts share the word "endpoint" in talm projects: + +- **`talosconfig.contexts..endpoints`** - list of `host[:port]` entries the talosctl client uses to reach the Talos API. Populated by `--endpoints` (plural, comma-separated list). +- **`values.yaml::endpoint`** - single URL with scheme + host + port that the chart renders into `cluster.controlPlane.endpoint` of every node's MachineConfig. This is what kubelet and kube-proxy dial. Populated by `--cluster-endpoint` (singular, full URL). + +When `--endpoints` is given exactly one value, init auto-derives `values.yaml::endpoint` as `https://:6443` because the single-target case is unambiguous. Multi-endpoint inputs never auto-derive (picking one node would silently couple cluster availability to it) - pass `--cluster-endpoint` explicitly or fill `values.yaml::endpoint` later by hand. The init flow prints a hint at the end when the field is left empty. + **Update an existing project to the latest bundled library chart:** - `-u, --update` - re-extract `charts/talm/` and other preset-shipped files from the talm binary. `--preset` is required; `--name` is not. @@ -150,7 +160,7 @@ talm init --encrypt # secrets.yaml -> secrets.encrypted.yaml; talosconfig -> t talm init --decrypt # reverse — does not require --preset or --name ``` -Lose the `talm.key` file and the encrypted counterparts become unreadable, so keep a backup of the key out-of-band. +Lose the `talm.key` file and the encrypted counterparts become unreadable, so keep a backup of the key out-of-band. When `talm init --decrypt` runs against a project where `talm.key` is missing, talm surfaces both recovery paths in the error hint: restore the backed-up key, or re-run `talm init` to regenerate (with the explicit warning that regenerating writes new secrets, making the old `secrets.encrypted.yaml` undecryptable without the original key). ### 2.2. Edit Configuration Values and Templates From bc7c16580844b550ce705ac66fe47126cabd0f5e Mon Sep 17 00:00:00 2001 From: Aleksei Sviridkin Date: Fri, 15 May 2026 23:06:03 +0300 Subject: [PATCH 4/4] docs(talm): document operator extension points (extra* values keys) Talm v0.30 exposes four extra* values keys on the cozystack and generic presets for extending the rendered Talos config (kernel modules, sysctls, kubelet args, machine files) without forking the chart preset. Document the keys, their shape, the append-vs-collision-fails semantics on cozystack, and the emit-only-when-set behaviour on generic. Signed-off-by: Aleksei Sviridkin --- .../en/docs/next/install/kubernetes/talm.md | 27 +++++++++++++++++++ .../en/docs/v1.3/install/kubernetes/talm.md | 27 +++++++++++++++++++ 2 files changed, 54 insertions(+) diff --git a/content/en/docs/next/install/kubernetes/talm.md b/content/en/docs/next/install/kubernetes/talm.md index 8349e853..de34fc2f 100644 --- a/content/en/docs/next/install/kubernetes/talm.md +++ b/content/en/docs/next/install/kubernetes/talm.md @@ -198,6 +198,33 @@ certSANs: [] You don't need to fill in the node IPs at this step. Instead, you will provide them later, when you generate node configurations. +#### Extending the rendered Talos config (Talm v0.30+) + +The `cozystack` preset ships curated defaults for `machine.kernel.modules`, `machine.sysctls`, `machine.kubelet.extraConfig`, and `machine.files`. Operators wanting to add to any of these without forking the chart use four `extra*` values keys: + +| Key | Shape | Semantics on the `cozystack` preset | +| --- | --- | --- | +| `extraKernelModules` | list | Appended to the built-in modules (`openvswitch`, `drbd`, `zfs`, `spl`, `vfio_pci`, `vfio_iommu_type1`). Each entry is a Talos kernel-module spec. | +| `extraKubeletExtraArgs` | map | Merged into `kubelet.extraConfig` after the preset's `cpuManagerPolicy: static`, `maxPods: 512`. Operator keys must NOT collide with built-ins — yaml.v3 rejects duplicate map keys on decode, so a collision fails the render with a precise hint pointing at the offending key. Fork the preset if you need a different default. | +| `extraSysctls` | map | Merged into `machine.sysctls` after the preset's `gc_thresh*` entries. Same collision-fails-render contract as `extraKubeletExtraArgs`. Values must be YAML strings (Talos expects strings even for numeric sysctls). | +| `extraMachineFiles` | list | Appended to the preset's CRI customization and `lvm.conf` entries. Talos rejects duplicate `path:` at apply time. | + +Example `values.yaml` addition: + +```yaml +extraKernelModules: + - name: nf_conntrack +extraKubeletExtraArgs: + feature-gates: "NodeSwap=true" +extraSysctls: + net.core.somaxconn: "65535" +extraMachineFiles: + - path: /etc/example.conf + op: create + content: "hello = world" +``` + +The `generic` preset ships no defaults under any of these sections — each block emits only when the matching `extra*` key is non-empty. ### 2.3 Add Keycloak Configuration diff --git a/content/en/docs/v1.3/install/kubernetes/talm.md b/content/en/docs/v1.3/install/kubernetes/talm.md index 112af1d1..1fc334b1 100644 --- a/content/en/docs/v1.3/install/kubernetes/talm.md +++ b/content/en/docs/v1.3/install/kubernetes/talm.md @@ -198,6 +198,33 @@ certSANs: [] You don't need to fill in the node IPs at this step. Instead, you will provide them later, when you generate node configurations. +#### Extending the rendered Talos config (Talm v0.30+) + +The `cozystack` preset ships curated defaults for `machine.kernel.modules`, `machine.sysctls`, `machine.kubelet.extraConfig`, and `machine.files`. Operators wanting to add to any of these without forking the chart use four `extra*` values keys: + +| Key | Shape | Semantics on the `cozystack` preset | +| --- | --- | --- | +| `extraKernelModules` | list | Appended to the built-in modules (`openvswitch`, `drbd`, `zfs`, `spl`, `vfio_pci`, `vfio_iommu_type1`). Each entry is a Talos kernel-module spec. | +| `extraKubeletExtraArgs` | map | Merged into `kubelet.extraConfig` after the preset's `cpuManagerPolicy: static`, `maxPods: 512`. Operator keys must NOT collide with built-ins — yaml.v3 rejects duplicate map keys on decode, so a collision fails the render with a precise hint pointing at the offending key. Fork the preset if you need a different default. | +| `extraSysctls` | map | Merged into `machine.sysctls` after the preset's `gc_thresh*` entries. Same collision-fails-render contract as `extraKubeletExtraArgs`. Values must be YAML strings (Talos expects strings even for numeric sysctls). | +| `extraMachineFiles` | list | Appended to the preset's CRI customization and `lvm.conf` entries. Talos rejects duplicate `path:` at apply time. | + +Example `values.yaml` addition: + +```yaml +extraKernelModules: + - name: nf_conntrack +extraKubeletExtraArgs: + feature-gates: "NodeSwap=true" +extraSysctls: + net.core.somaxconn: "65535" +extraMachineFiles: + - path: /etc/example.conf + op: create + content: "hello = world" +``` + +The `generic` preset ships no defaults under any of these sections — each block emits only when the matching `extra*` key is non-empty. ### 2.3 Add Keycloak Configuration