Skip to content

Commit fa94120

Browse files
authored
Merge pull request #206 from cozystack/feat/init-endpoint-and-key-hints
feat(init): --cluster-endpoint flag and talm.key recovery hint
2 parents a0301e7 + 31a27cd commit fa94120

6 files changed

Lines changed: 542 additions & 9 deletions

File tree

‎README.md‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -61,7 +61,17 @@ talm init -p cozystack -N myawesomecluster --image factory.talos.dev/installer/<
6161

6262
`--image` rewrites the top-level `image:` field in the preset's `values.yaml` before write. The flag is honored on initial `init` only — for an existing project, edit `values.yaml` directly. The `cozystack` preset declares `image:`; the `generic` preset does not, so `--image --preset generic` is rejected up front.
6363

64-
Edit `values.yaml` to set your cluster's control-plane endpoint. This is the URL every node's kubelet and kube-proxy will dial. The chart leaves it empty on purpose so a missed override fails loudly instead of silently embedding a placeholder.
64+
To set the Kubernetes control-plane URL at init time, pass `--cluster-endpoint`:
65+
66+
```bash
67+
talm init -p cozystack -N myawesomecluster --cluster-endpoint https://vip.example.test:6443
68+
```
69+
70+
`--cluster-endpoint` writes the URL into `values.yaml::endpoint`, which the chart renders into `cluster.controlPlane.endpoint` of every node's MachineConfig (the URL kubelet and kube-proxy dial). The flag is honored on initial `init` only — for an existing project, edit `values.yaml` directly.
71+
72+
`--endpoints` and `--cluster-endpoint` address different concepts: `--endpoints` (plural, list) populates the `talosconfig` context for the talosctl client; `--cluster-endpoint` (singular, full URL) populates the Kubernetes control-plane address inside the chart. When `--endpoints` is given a single value, init auto-derives `values.yaml::endpoint` as `https://<that>:6443` — the single-target case is unambiguous. Multi-endpoint inputs never auto-derive (picking one node would silently couple cluster availability to it); the operator must pass `--cluster-endpoint` explicitly or fill `values.yaml::endpoint` later. The init flow prints a hint at the end when the field is left empty.
73+
74+
Edit `values.yaml` to set your cluster's control-plane endpoint if neither flag set it. This is the URL every node's kubelet and kube-proxy will dial. The chart leaves it empty by default so a missed override fails loudly instead of silently embedding a placeholder.
6575

6676
Endpoint / floatingIP combinations:
6777

‎docs/manual-test-plan.md‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -98,6 +98,65 @@ Expected: clear error mentioning the missing key path.
9898
rm -rf /tmp/talm-init-test
9999
```
100100

101+
### A6a. `init --decrypt` without `talm.key` surfaces recovery hint
102+
103+
```bash
104+
mkdir -p /tmp/talm-decrypt-test && cd /tmp/talm-decrypt-test
105+
/tmp/talm-safety init --preset cozystack --name test --endpoints 192.0.2.1
106+
mv talm.key /tmp/talm.key.backup
107+
/tmp/talm-safety init --decrypt
108+
mv /tmp/talm.key.backup talm.key # restore for next run
109+
rm -rf /tmp/talm-decrypt-test
110+
```
111+
112+
Expected: error `failed to decrypt secrets: load key: read key file: open <path>/talm.key: no such file or directory` followed by hint `talm.key is required to decrypt secrets.encrypted.yaml. Restore your backed-up key, or re-run \`talm init\` to regenerate (this writes new secrets — the old secrets.encrypted.yaml will not be decryptable without the original key).`
113+
114+
Regression anchor: the hint must name BOTH recovery paths (restore from backup, re-run init to regenerate) AND include the warning that regeneration writes new secrets making the old encrypted secrets undecryptable. A regression that drops either path or the warning silently invites operators to "just run init again" without understanding the data-loss tradeoff.
115+
116+
### A9. `init --cluster-endpoint` populates values.yaml::endpoint
117+
118+
```bash
119+
mkdir -p /tmp/talm-cluster-ep-test && cd /tmp/talm-cluster-ep-test
120+
/tmp/talm-safety init --preset cozystack --name test \
121+
--endpoints 10.0.0.1,10.0.0.2,10.0.0.3 \
122+
--cluster-endpoint https://vip.example.test:6443
123+
grep "^endpoint:" values.yaml
124+
grep -A 3 "endpoints:" talosconfig | head -5
125+
rm -rf /tmp/talm-cluster-ep-test
126+
```
127+
128+
Expected: `values.yaml` has `endpoint: "https://vip.example.test:6443"` (operator's VIP, explicit), `talosconfig` has all three `10.0.0.1`/`10.0.0.2`/`10.0.0.3` under the context's endpoints array. The two flags address different concepts — `--cluster-endpoint` is the kube-apiserver URL, `--endpoints` is the talosctl-client list — and both round-trip independently.
129+
130+
Regression anchor: removing `--cluster-endpoint` and passing only `--endpoints 10.0.0.1,10.0.0.2,10.0.0.3` MUST leave `values.yaml::endpoint` empty (the multi-endpoint case never auto-derives — picking one node would silently couple cluster availability to it). The init flow MUST then print a hint at the end pointing the operator at `values.yaml::endpoint` with examples for VIP / LB shapes.
131+
132+
### A10. `init --endpoints` with single entry auto-derives values.yaml::endpoint
133+
134+
```bash
135+
mkdir -p /tmp/talm-single-ep-test && cd /tmp/talm-single-ep-test
136+
/tmp/talm-safety init --preset cozystack --name test --endpoints 192.0.2.10
137+
grep "^endpoint:" values.yaml
138+
rm -rf /tmp/talm-single-ep-test
139+
```
140+
141+
Expected: `endpoint: "https://192.0.2.10:6443"` — the single-endpoint case is unambiguously "this is also the cluster URL", so init derives the canonical `https://<host>:6443` form. No hint printed at end of init for this case.
142+
143+
Regression anchor: this auto-derive ONLY fires when `len(--endpoints) == 1`. Multi-endpoint inputs MUST leave the field empty (see A9).
144+
145+
### A11. `init --cluster-endpoint` rejects malformed URL before any files land on disk
146+
147+
```bash
148+
mkdir -p /tmp/talm-bad-ep-test && cd /tmp/talm-bad-ep-test
149+
/tmp/talm-safety init --preset cozystack --name test \
150+
--endpoints 192.0.2.10 \
151+
--cluster-endpoint "not-a-url"
152+
ls -la # should be empty
153+
rm -rf /tmp/talm-bad-ep-test
154+
```
155+
156+
Expected: error `cluster-endpoint "not-a-url" is missing scheme, host, or port` with hint pointing at the canonical form. Directory remains empty — NO `talosconfig`, NO `.gitignore`, NO `secrets.yaml` written. Validation happens in PreRunE before any file writes so a malformed flag never produces a half-initialised project tree.
157+
158+
Regression anchor: a regression that defers validation to RunE (i.e. after the secret-bundle generation) would leave `talosconfig` and `.gitignore` behind — verify by checking `ls -la` after the failing command finds an empty directory.
159+
101160
### A8. `init --update` without `--preset` and without preset dep in Chart.yaml
102161

103162
```bash

‎pkg/age/age.go‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -104,6 +104,20 @@ func LoadKey(rootDir string) (*age.X25519Identity, error) {
104104

105105
keyData, err := os.ReadFile(keyFile)
106106
if err != nil {
107+
if errors.Is(err, os.ErrNotExist) {
108+
// Talm.key absence is a real operational scenario
109+
// (laptop swap, lost backup, fresh checkout) and the
110+
// raw "open ...: no such file" surfaces as if it's an
111+
// internal bug. Attach the recovery hint naming both
112+
// paths the operator can take so the error reads as
113+
// "what to do next", not "talm is broken".
114+
//nolint:wrapcheck // cockroachdb/errors.WithHint is the project's wrapping/hinting idiom at boundaries.
115+
return nil, errors.WithHint(
116+
errors.Wrap(err, "read key file"),
117+
"talm.key is required to decrypt secrets.encrypted.yaml. Restore your backed-up key, or re-run `talm init` to regenerate (this writes new secrets — the old secrets.encrypted.yaml will not be decryptable without the original key).",
118+
)
119+
}
120+
107121
return nil, errors.Wrap(err, "read key file")
108122
}
109123

‎pkg/age/contract_test.go‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,7 @@ import (
3636
"strings"
3737
"testing"
3838

39+
cerrors "github.com/cockroachdb/errors"
3940
"github.com/cozystack/talm/pkg/age"
4041
"gopkg.in/yaml.v3"
4142
)
@@ -181,6 +182,31 @@ func TestContract_Age_LoadKey_MissingFileErrors(t *testing.T) {
181182
}
182183
}
183184

185+
// TestContract_Age_LoadKey_MissingFileSurfacesRecoveryHint pins the
186+
// operator-facing recovery message attached to a missing talm.key.
187+
// Without the hint, operators see a raw "open talm.key: no such
188+
// file" stack-style line and assume it's a bug in talm. The hint
189+
// must name BOTH recovery paths: restore from backup, or re-run
190+
// `talm init` to regenerate (which writes new secrets — old
191+
// secrets.encrypted.yaml becomes undecryptable without the
192+
// original key).
193+
func TestContract_Age_LoadKey_MissingFileSurfacesRecoveryHint(t *testing.T) {
194+
dir := t.TempDir() // no talm.key inside
195+
196+
_, err := age.LoadKey(dir)
197+
if err == nil {
198+
t.Fatal("expected error for missing talm.key")
199+
}
200+
201+
hints := cerrors.GetAllHints(err)
202+
joinedLower := strings.ToLower(strings.Join(hints, "\n"))
203+
for _, want := range []string{"talm.key", "restore", "talm init"} {
204+
if !strings.Contains(joinedLower, want) {
205+
t.Errorf("missing-key hint must mention %q so operator knows the recovery path; got hints:\n%s", want, strings.Join(hints, "\n"))
206+
}
207+
}
208+
}
209+
184210
// === GetPublicKey / GetPublicKeyFromFile ===
185211

186212
// Contract: GetPublicKey returns the recipient string from an

0 commit comments

Comments
 (0)