Skip to content

Commit b012d20

Browse files
lexfreimyasnikovdaniil
authored andcommitted
fix(values): stop claiming --set nests dots in a value
talm warned that strvals reads a dot in a --set value as YAML key nesting, so that `--set endpoint=10.0.0.1` rendered as {endpoint: {10: {0: {0: 1}}}}, and steered operators to --set-string for IP, CIDR and version literals. The flag help and the manual said the same thing. It does not. strvals stops key scanning at '=', so a dot only opens a nesting level on the left of it; the value scanner stops at ',' and typedVal falls back to the raw string once ParseInt fails. Behaviour is identical on helm v3.15.2 and v4, so the migration between them did not introduce this. The screen fired on shapes that were never at risk and told operators their config was silently corrupt when it was not. Drop the screen and describe what --set actually does: it converts integers and booleans, which is the real and only reason to prefer --set-string. A new engine test pins the parser behaviour the old text described, and the help contract now rejects the claim instead of requiring it. Assisted-by: LLM Signed-off-by: Aleksei Sviridkin <[email protected]>
1 parent 1223e10 commit b012d20

10 files changed

Lines changed: 157 additions & 425 deletions

File tree

‎docs/configuration/templates.md‎

Lines changed: 9 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -26,18 +26,21 @@ Querying disks map example:
2626

2727
This returns the system disk device name.
2828

29-
## `--set` vs `--set-string` for IP / version literals
29+
## `--set` vs `--set-string`
3030

31-
Helm's `--set` parser interprets dots in the right-hand side as YAML key nesting:
31+
`--set` converts a value that parses as an integer or a boolean into that type:
3232

3333
```bash
34-
talm template --set endpoint=10.0.0.1 # parsed as: endpoint: {10: {0: {0: 1}}}
34+
talm template --set port=8080 # port: 8080 (integer)
35+
talm template --set enabled=true # enabled: true (boolean)
3536
```
3637

37-
For IP addresses, CIDR blocks, or version strings, use `--set-string` to keep the value verbatim:
38+
Use `--set-string` where the template or the Talos schema wants a string:
3839

3940
```bash
40-
talm template --set-string endpoint=10.0.0.1 # parsed as: endpoint: "10.0.0.1"
41+
talm template --set-string port=8080 # port: "8080"
4142
```
4243

43-
`talm` warns on stderr when it detects an IP-, CIDR-, or version-shaped value in `--set` and points at `--set-string` as the fix. The warning is non-fatal — rendering proceeds with the (likely-broken) nested map so existing automation does not break. For values containing characters Helm's strvals treats specially (e.g. `=`, `,` inside the value, or content that should be opaque to all parsing), use `--set-literal` — it stores the entire RHS as a verbatim string without any escape interpretation.
44+
Dots only nest on the left of the `=`, so `--set a.b=x` sets `a.b` while a dotted value stays whole: `--set endpoint=10.0.0.1` renders `endpoint: "10.0.0.1"`, and IP addresses, CIDR blocks and version strings need no special handling.
45+
46+
For values containing characters Helm's strvals treats specially (e.g. `=`, `,` inside the value, or content that should be opaque to all parsing), use `--set-literal` — it stores the entire RHS as a verbatim string without any escape interpretation.

‎docs/reference/apply.md‎

Lines changed: 2 additions & 2 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎docs/reference/template.md‎

Lines changed: 2 additions & 2 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎pkg/commands/apply.go‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1222,8 +1222,8 @@ func init() {
12221222
applyCmd.Flags().BoolVarP(&applyCmdFlags.insecure, "insecure", "i", false, "apply using the insecure (encrypted with no auth) maintenance service")
12231223
applyCmd.Flags().StringSliceVarP(&applyCmdFlags.configFiles, "file", "f", nil, "node config files / patches (`.yaml` / `.yml`; shell completion narrows to these extensions). First -f is the modelined anchor (must live under a `talm init`'d project root); subsequent -f files are side-patches stacked onto the anchor's rendered config and may live anywhere.")
12241224
applyCmd.Flags().StringSliceVar(&applyCmdFlags.valueFiles, "values", []string{}, "specify values in a YAML file (can specify multiple). Must match `talm template` — apply re-renders from the modeline and would otherwise drop value files supplied at template time.")
1225-
applyCmd.Flags().StringArrayVar(&applyCmdFlags.values, "set", []string{}, "set values on the command line (can specify multiple or separate values with commas: key1=val1,key2=val2). For IP / CIDR / version literals use --set-string — dots in --set values are interpreted as YAML key nesting.")
1226-
applyCmd.Flags().StringArrayVar(&applyCmdFlags.stringValues, "set-string", []string{}, "set STRING values on the command line (can specify multiple or separate values with commas: key1=val1,key2=val2). Use for IP addresses, CIDR blocks, version strings, or any literal value where dots must NOT be interpreted as YAML key nesting.")
1225+
applyCmd.Flags().StringArrayVar(&applyCmdFlags.values, "set", []string{}, "set values on the command line (can specify multiple or separate values with commas: key1=val1,key2=val2). Values that parse as an integer or a boolean are converted to that type; use --set-string to keep them as strings.")
1226+
applyCmd.Flags().StringArrayVar(&applyCmdFlags.stringValues, "set-string", []string{}, "set STRING values on the command line (can specify multiple or separate values with commas: key1=val1,key2=val2). Nothing is type-converted, so the value reaches the template exactly as typed.")
12271227
applyCmd.Flags().StringArrayVar(&applyCmdFlags.fileValues, "set-file", []string{}, "set values from respective files specified via the command line (can specify multiple or separate values with commas: key1=path1,key2=path2)")
12281228
applyCmd.Flags().StringArrayVar(&applyCmdFlags.jsonValues, "set-json", []string{}, "set JSON values on the command line (can specify multiple or separate values with commas: key1=jsonval1,key2=jsonval2)")
12291229
applyCmd.Flags().StringArrayVar(&applyCmdFlags.literalValues, "set-literal", []string{}, "set a literal STRING value on the command line")

‎pkg/commands/contract_template_set_help_test.go‎

Lines changed: 58 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -19,58 +19,72 @@ import (
1919
"testing"
2020
)
2121

22-
// TestTemplateFlag_SetHelpText_MentionsSetString pins the operator-
23-
// facing UX: `talm template --help` must surface the --set-string
24-
// escape hatch directly in the --set flag description. Operators
25-
// hitting the strvals dot-nesting footgun (e.g.
26-
// `--set endpoint=10.0.0.1` parsed as nested map) check --help
27-
// before CHANGELOG. The Usage string must name --set-string so the
28-
// hint lands in front of them.
29-
func TestTemplateFlag_SetHelpText_MentionsSetString(t *testing.T) {
30-
flag := templateCmd.Flags().Lookup("set")
31-
if flag == nil {
32-
t.Fatal("expected templateCmd to register a --set flag, got nil")
33-
}
22+
// setFlagCommands are the commands that expose the --set family. The help
23+
// contracts below hold for every one of them, so a flag reworded on one
24+
// command and not the other is a failure.
25+
//
26+
//nolint:gochecknoglobals // immutable lookup table read by the help contract tests.
27+
var setFlagCommands = map[string]func(name string) string{
28+
"template": func(name string) string { return templateCmd.Flags().Lookup(name).Usage },
29+
"apply": func(name string) string { return applyCmd.Flags().Lookup(name).Usage },
30+
}
31+
32+
// TestSetHelpText_PointsAtSetString pins the operator-facing UX: an
33+
// operator deciding between the two flags reads `--help`, so the --set
34+
// description has to name --set-string as the alternative.
35+
func TestSetHelpText_PointsAtSetString(t *testing.T) {
36+
t.Parallel()
37+
38+
for name, usage := range setFlagCommands {
39+
t.Run(name, func(t *testing.T) {
40+
t.Parallel()
3441

35-
if !strings.Contains(flag.Usage, "--set-string") {
36-
t.Errorf("--set Usage must point at --set-string as the escape hatch for IP / version literals; got:\n%s", flag.Usage)
42+
if got := usage("set"); !strings.Contains(got, "--set-string") {
43+
t.Errorf("talm %s --set Usage must name --set-string as the alternative; got:\n%s", name, got)
44+
}
45+
})
3746
}
3847
}
3948

40-
// TestTemplateFlag_SetStringHelpText_MentionsLiteralStability pins
41-
// the sibling contract: --set-string Usage must describe its niche
42-
// (IP / CIDR / version literals — values that must not be type-
43-
// coerced or dot-nested). Without this, the help text reads as
44-
// "set STRING values" with no clue when to prefer it over --set.
45-
func TestTemplateFlag_SetStringHelpText_MentionsLiteralStability(t *testing.T) {
46-
flag := templateCmd.Flags().Lookup("set-string")
47-
if flag == nil {
48-
t.Fatal("expected templateCmd to register a --set-string flag, got nil")
49-
}
49+
// TestSetStringHelpText_ExplainsTypeConversion pins the reason to reach
50+
// for --set-string. Integers and booleans are the only values --set
51+
// converts, so "set STRING values" alone leaves an operator with no way
52+
// to tell when it matters.
53+
func TestSetStringHelpText_ExplainsTypeConversion(t *testing.T) {
54+
t.Parallel()
55+
56+
for name, usage := range setFlagCommands {
57+
t.Run(name, func(t *testing.T) {
58+
t.Parallel()
5059

51-
// The Usage must surface the literal-stability niche. The
52-
// word "literal" is the canonical anchor; the sibling words
53-
// (IP / CIDR / version) all describe shapes that need it.
54-
usage := strings.ToLower(flag.Usage)
55-
if !strings.Contains(usage, "literal") {
56-
t.Errorf("--set-string Usage must name the literal-stability use case; got:\n%s", flag.Usage)
60+
if got := usage("set-string"); !strings.Contains(strings.ToLower(got), "convert") {
61+
t.Errorf("talm %s --set-string Usage must say that nothing is type-converted; got:\n%s", name, got)
62+
}
63+
})
5764
}
5865
}
5966

60-
// TestTemplateFlag_SetStringHelpText_DoesNotOverpromiseHostnames pins
61-
// the alignment between the --set-string Usage copy and the actual
62-
// detector in pkg/engine/setvalue_warn.go. The screener matches
63-
// IPv4 / IPv4 CIDR / semver shapes only — hostnames like
64-
// `foo.example.com` are NOT flagged, so the Usage must NOT advertise
65-
// hostname coverage. A previous revision did, which mislead operators
66-
// into thinking `--set host=foo.example.com` would be screened.
67-
func TestTemplateFlag_SetStringHelpText_DoesNotOverpromiseHostnames(t *testing.T) {
68-
flag := templateCmd.Flags().Lookup("set-string")
69-
if flag == nil {
70-
t.Fatal("expected templateCmd to register a --set-string flag, got nil")
71-
}
67+
// TestSetHelpText_DoesNotClaimDotNesting keeps a long-standing false
68+
// claim from coming back. The help text used to tell operators that a
69+
// dot in a --set value nested it into a map, so that
70+
// `--set endpoint=10.0.0.1` supposedly rendered
71+
// {endpoint: {10: {0: {0: 1}}}} and IP literals needed --set-string.
72+
// strvals stops key scanning at '=', so dots only nest on the left of
73+
// it and a dotted value stays whole — see
74+
// TestSetValueDotsNestOnlyInTheKey in pkg/engine, which pins the
75+
// parser behaviour this text describes.
76+
func TestSetHelpText_DoesNotClaimDotNesting(t *testing.T) {
77+
t.Parallel()
78+
79+
for name, usage := range setFlagCommands {
80+
t.Run(name, func(t *testing.T) {
81+
t.Parallel()
7282

73-
if strings.Contains(strings.ToLower(flag.Usage), "hostname") {
74-
t.Errorf("--set-string Usage must NOT claim hostname coverage — the screener does not detect hostname-shaped values; got:\n%s", flag.Usage)
83+
for _, flag := range []string{"set", "set-string"} {
84+
if got := strings.ToLower(usage(flag)); strings.Contains(got, "nesting") || strings.Contains(got, "nested") {
85+
t.Errorf("talm %s --%s Usage must not describe dots in a value as key nesting; got:\n%s", name, flag, got)
86+
}
87+
}
88+
})
7589
}
7690
}

‎pkg/commands/template.go‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -490,8 +490,8 @@ func init() {
490490
templateCmd.Flags().BoolVarP(&templateCmdFlags.inplace, "in-place", "I", false, "re-template and update generated files in place (overwrite them)")
491491
templateCmd.Flags().StringSliceVarP(&templateCmdFlags.valueFiles, "values", "", []string{}, "specify values in a YAML file (can specify multiple)")
492492
templateCmd.Flags().StringSliceVarP(&templateCmdFlags.templateFiles, "template", "t", []string{}, "specify templates to render manifest from (can specify multiple)")
493-
templateCmd.Flags().StringArrayVar(&templateCmdFlags.values, "set", []string{}, "set values on the command line (can specify multiple or separate values with commas: key1=val1,key2=val2). For IP / CIDR / version literals use --set-string — dots in --set values are interpreted as YAML key nesting.")
494-
templateCmd.Flags().StringArrayVar(&templateCmdFlags.stringValues, "set-string", []string{}, "set STRING values on the command line (can specify multiple or separate values with commas: key1=val1,key2=val2). Use for IP addresses, CIDR blocks, version strings, or any literal value where dots must NOT be interpreted as YAML key nesting.")
493+
templateCmd.Flags().StringArrayVar(&templateCmdFlags.values, "set", []string{}, "set values on the command line (can specify multiple or separate values with commas: key1=val1,key2=val2). Values that parse as an integer or a boolean are converted to that type; use --set-string to keep them as strings.")
494+
templateCmd.Flags().StringArrayVar(&templateCmdFlags.stringValues, "set-string", []string{}, "set STRING values on the command line (can specify multiple or separate values with commas: key1=val1,key2=val2). Nothing is type-converted, so the value reaches the template exactly as typed.")
495495
templateCmd.Flags().StringArrayVar(&templateCmdFlags.fileValues, "set-file", []string{}, "set values from respective files specified via the command line (can specify multiple or separate values with commas: key1=path1,key2=path2)")
496496
templateCmd.Flags().StringArrayVar(&templateCmdFlags.jsonValues, "set-json", []string{}, "set JSON values on the command line (can specify multiple or separate values with commas: key1=jsonval1,key2=jsonval2)")
497497
templateCmd.Flags().StringArrayVar(&templateCmdFlags.literalValues, "set-literal", []string{}, "set a literal STRING value on the command line")

0 commit comments

Comments
 (0)