Skip to content

Commit 8ad47d4

Browse files
Merge pull request #235 from cozystack/feat/docs-site
Documentation site at talm.cozystack.io with a generated CLI reference
2 parents 1d571ba + b012d20 commit 8ad47d4

119 files changed

Lines changed: 5479 additions & 842 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.gitattributes‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,3 +27,8 @@ pkg/generated/** linguist-generated
2727
# not hand-edited. Marking them generated keeps the rendered YAML dumps
2828
# out of language stats and collapses them in PR diffs by default.
2929
pkg/engine/testdata/golden/** linguist-generated
30+
31+
# docs/reference/ is rendered from the cobra command tree by
32+
# `make docs`, not hand-edited. Marking it generated keeps it out of
33+
# language stats and collapses it in PR diffs by default.
34+
docs/reference/*.md linguist-generated
Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
name: Documentation Validation
2+
3+
# No paths filter, deliberately. A workflow skipped by a paths filter stays in
4+
# a Pending check, and a merge blocked on a required check that never reports
5+
# is blocked forever — so a filtered workflow can never be a required check at
6+
# all. This build is the only thing that sees a relative link or an anchor
7+
# inside docs/, so it has to be able to block. The cost is well under a minute
8+
# on a Go-only change.
9+
on:
10+
pull_request:
11+
12+
concurrency:
13+
group: ${{ github.workflow }}-${{ github.event.pull_request.number }}
14+
cancel-in-progress: true
15+
16+
permissions:
17+
contents: read
18+
19+
jobs:
20+
validate:
21+
name: Validate documentation
22+
runs-on: ubuntu-latest
23+
steps:
24+
- name: Checkout repository
25+
uses: actions/checkout@v6
26+
with:
27+
# git-revision-date-localized runs in the build below and reads each
28+
# page's last commit; a shallow clone has none.
29+
fetch-depth: 0
30+
31+
- name: Setup Python
32+
uses: actions/setup-python@v7
33+
with:
34+
python-version: "3.14"
35+
cache: pip
36+
cache-dependency-path: requirements-docs.txt
37+
38+
- name: Install dependencies
39+
run: pip install --requirement requirements-docs.txt
40+
41+
# The site only builds for real on a push to main, where a failure lands
42+
# on the published documentation. Build it here too: relative links and
43+
# anchors inside docs/ are checked by this and nothing else.
44+
#
45+
# --quiet must never be added: --strict fails on the warning COUNT and
46+
# --quiet suppresses the warnings before anything counts them, so the two
47+
# together report success while checking nothing.
48+
- name: Build documentation
49+
run: mkdocs build --strict

‎.github/workflows/docs.yaml‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
name: Documentation
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
paths:
8+
- "docs/**"
9+
- "mkdocs.yml"
10+
- "requirements-docs.in"
11+
- "requirements-docs.txt"
12+
- ".github/workflows/docs.yaml"
13+
workflow_dispatch:
14+
15+
permissions:
16+
contents: read
17+
18+
# Never cancel a deploy mid-flight: the site is replaced wholesale, so a
19+
# cancelled run can leave the artifact half-uploaded. Queue instead.
20+
concurrency:
21+
group: pages
22+
cancel-in-progress: false
23+
24+
jobs:
25+
deploy:
26+
name: Deploy documentation
27+
runs-on: ubuntu-latest
28+
permissions:
29+
contents: read
30+
pages: write
31+
id-token: write
32+
environment:
33+
name: github-pages
34+
url: ${{ steps.deployment.outputs.page_url }}
35+
steps:
36+
- name: Checkout repository
37+
uses: actions/checkout@v6
38+
with:
39+
# git-revision-date-localized reads each page's last commit for the
40+
# footer date; a shallow clone has no history to read it from.
41+
fetch-depth: 0
42+
43+
- name: Setup Python
44+
uses: actions/setup-python@v7
45+
with:
46+
python-version: "3.14"
47+
cache: pip
48+
cache-dependency-path: requirements-docs.txt
49+
50+
# Provisions the Pages site when the repository has none yet, so the
51+
# deploy below does not fail on a repository where Pages was never
52+
# switched on. Idempotent once it exists. The custom domain is not
53+
# expressible here and has to be set in the repository settings.
54+
- name: Configure Pages
55+
uses: actions/configure-pages@v6
56+
with:
57+
enablement: true
58+
59+
- name: Install dependencies
60+
run: pip install --requirement requirements-docs.txt
61+
62+
# --strict fails the build on warnings; the validation block in
63+
# mkdocs.yml is what makes a dead anchor, an unrecognized link and a page
64+
# missing from the nav warnings at all. Both halves are needed.
65+
- name: Build documentation
66+
run: mkdocs build --strict
67+
68+
- name: Upload Pages artifact
69+
uses: actions/upload-pages-artifact@v5
70+
with:
71+
path: site
72+
73+
# Unlike a gh-pages branch push, this waits on the Pages deployment
74+
# itself and fails if it does not converge, so a stalled deploy turns
75+
# this job red instead of leaving a stale site behind a green run.
76+
- name: Deploy to GitHub Pages
77+
id: deployment
78+
uses: actions/deploy-pages@v5

‎.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,6 @@
11
talm
22
dist/
33
.claude/
4+
5+
# MkDocs build output
6+
/site/

‎Makefile‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,3 +9,11 @@ TALOS_VERSION=$(shell go list -m github.com/siderolabs/talos | awk '{sub(/^v/,
99

1010
build:
1111
go build -ldflags="-X 'main.Version=$(VERSION)'"
12+
13+
# Rewrite docs/reference/ from the cobra command tree. TestReferenceDocs
14+
# compares the committed pages against that tree on every `go test ./...`,
15+
# so run this after adding a command or bumping Talos.
16+
docs:
17+
TALM_UPDATE_DOCS=1 go test . -run TestReferenceDocs
18+
19+
.PHONY: build docs

‎README.md‎

Lines changed: 16 additions & 413 deletions
Large diffs are not rendered by default.

‎docs/.nav.yml‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
# Site navigation. This lives here rather than in mkdocs.yml because
2+
# awesome-nav owns the nav tree, and only from here can the generated
3+
# reference/ section expand through its own .nav.yml.
4+
nav:
5+
- Home: index.md
6+
- Getting started:
7+
- Installation: getting-started/installation.md
8+
- Quickstart: getting-started/quickstart.md
9+
- Initializing a project: getting-started/init.md
10+
- Configuration:
11+
- Node files: configuration/node-files.md
12+
- Endpoints and VIPs: configuration/endpoints-and-vips.md
13+
- Talos versions and output format: configuration/talos-versions.md
14+
- Templates and values: configuration/templates.md
15+
- Encryption: configuration/encryption.md
16+
- Operations:
17+
- Applying with side-patches: operations/side-patches.md
18+
- Apply-time safety gates: operations/safety-gates.md
19+
- talosctl-compatible commands: operations/talosctl-commands.md
20+
- Upgrading talm: operations/upgrading.md
21+
- CLI reference: reference
22+
- Cozystack: https://cozystack.io

‎docs/assets/favicon.svg‎

Lines changed: 1 addition & 0 deletions
Loading

‎docs/assets/logo.svg‎

Lines changed: 1 addition & 0 deletions
Loading

‎docs/configuration/encryption.md‎

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
# Encryption
2+
3+
Talm provides built-in encryption support using [age](https://age-encryption.org/) encryption. Sensitive files are encrypted with their values stored in SOPS format (`ENC[AGE,data:...]`), while YAML keys remain unencrypted for better readability.
4+
5+
## Encrypting files
6+
7+
To encrypt all sensitive files (secrets.yaml, talosconfig, kubeconfig):
8+
9+
```bash
10+
talm init --encrypt
11+
# or
12+
talm init -e
13+
```
14+
15+
This command will:
16+
- Generate `talm.key` if it doesn't exist
17+
- Encrypt `secrets.yaml` → `secrets.encrypted.yaml`
18+
- Encrypt `talosconfig` → `talosconfig.encrypted`
19+
- Encrypt `kubeconfig` → `kubeconfig.encrypted` (if exists)
20+
- Encrypt `values-secret.yaml` → `values-secret.encrypted.yaml` (if exists)
21+
- Update `.gitignore` with sensitive files
22+
23+
## Decrypting files
24+
25+
To decrypt all encrypted files:
26+
27+
```bash
28+
talm init --decrypt
29+
# or
30+
talm init -d
31+
```
32+
33+
This command will:
34+
- Decrypt `secrets.encrypted.yaml` → `secrets.yaml`
35+
- Decrypt `talosconfig.encrypted` → `talosconfig`
36+
- Decrypt `kubeconfig.encrypted` → `kubeconfig` (if exists)
37+
- Decrypt `values-secret.encrypted.yaml` → `values-secret.yaml` (if exists)
38+
- Update `.gitignore` with sensitive files
39+
40+
## Encrypted user values
41+
42+
Beyond Talos' own PKI/tokens, you can store **arbitrary secret values that chart templates consume** (a registry password, a KMS plugin's secret-id, etc.) encrypted at rest with the same `talm.key`:
43+
44+
1. Author the secrets in plaintext `values-secret.yaml` (git-ignored), e.g.:
45+
46+
```yaml
47+
registryPassword: hunter2
48+
```
49+
50+
2. Encrypt them with `talm init --encrypt` → produces the committable `values-secret.encrypted.yaml` (per-value `ENC[AGE,...]` envelopes; keys stay readable).
51+
52+
3. Reference the **encrypted** file from `Chart.yaml`:
53+
54+
```yaml
55+
templateOptions:
56+
valueFiles:
57+
- values-secret.encrypted.yaml
58+
```
59+
60+
`talm template` and `talm apply` decrypt it **in memory** via `talm.key` — the plaintext never has to be present at render time. Both commands honor the full value-source set (`--values`, `--set`, `--set-string`, `--set-file`, `--set-json`, `--set-literal`) plus `templateOptions.*`, so a value renders identically whether you preview with `template` or push with `apply`.
61+
62+
Secret values are kept out of committed and printed output:
63+
64+
- `talm template -I` **omits** secret-bearing fields from the rendered `nodes/*.yaml`; the real value is re-injected only at `apply` (which re-renders from the encrypted file).
65+
- `talm template` (stdout) and `talm apply` (drift preview) **redact** them to `***` by default. Reveal verbatim with `talm template --show-secrets` / [`talm apply --show-secrets-in-drift`](../operations/safety-gates.md) (debugging only).
66+
67+
!!! danger "Put the encrypted file in Chart.yaml, not only on the command line"
68+
69+
Reference the encrypted file from `Chart.yaml templateOptions.valueFiles` (as shown above), NOT only via `template --values`. The node-file modeline does not persist value files, so `apply` only re-reads what is in `Chart.yaml` (plus its own `--values`). If an encrypted file is passed solely to `template -I`, the omitted secret is absent from the node file AND never re-rendered at apply — silently lost from the applied config. `template -I` prints a warning when it omits secrets from a file that is not in `Chart.yaml`.
70+
71+
!!! warning "Encrypt only high-entropy values"
72+
73+
Sealing matches by exact value across the whole rendered config, so do not encrypt low-entropy values that collide with ordinary config strings (e.g. a bare port, or a password literally set to `controlplane`) — that unrelated field would be sealed too. Prefer high-entropy secrets. Secret values must be strings (quote them in `values-secret.yaml`); the encryption only covers string leaves.
74+
75+
## Key management
76+
77+
The `talm.key` file is generated in age keygen format and contains:
78+
- Creation timestamp
79+
- Public key (for sharing)
80+
- Private key (keep secure!)
81+
82+
!!! danger "Back up talm.key"
83+
84+
Always backup your `talm.key` file! Without it, you won't be able to decrypt your encrypted secrets. The key file is automatically added to `.gitignore` to prevent accidental commits.
85+
86+
Encrypted files (`*.encrypted.yaml`, `*.encrypted`) can be safely committed to Git, while plain files (`secrets.yaml`, `talosconfig`, `kubeconfig`, `talm.key`) are ignored.

0 commit comments

Comments
 (0)