cli: print only the required keys with generate config --minimal

With every other key defaulted, server_url alone is a configuration.

Updates #1926
This commit is contained in:
Kristoffer Dalby committed 2026-11-11 15:02:16 +01:00
1 parent 86129dd5ce
commit b600c1f391
4 files changed
+104 -3

No files matched your search

+6 -2
View File
@@ -20,6 +20,8 @@ func init() {
generateConfigCmd.Flags().Bool("no-docs", false, "Leave out the documentation comments")
generateConfigCmd.Flags().Bool("running", false, "Print the running server's configuration, secrets redacted, instead of the defaults")
generateConfigCmd.Flags().Bool("minimal", false, "Print only the keys every server must set")
generateConfigCmd.MarkFlagsMutuallyExclusive("minimal", "running")
generateCmd.AddCommand(generateConfigCmd)
generateNixOSOptionsCmd.Flags().Bool("release", false, "Stamp the version and commit of this binary, which must be a clean build of a known commit")
@@ -57,7 +59,8 @@ var generateConfigCmd = &cobra.Command{
Short: "Print a configuration file with every key",
Long: `Print a YAML configuration with every key, its default and its
documentation as comments, e.g. for "> /etc/headscale/config.yaml". Set the
keys marked "Required" before starting headscale.
keys marked "Required" before starting headscale. With --minimal, print only
those keys.
With --running, print instead the configuration of the running server,
without the client-only cli section: literal secrets, DNS provider settings
@@ -67,6 +70,7 @@ kept as written.`,
RunE: func(cmd *cobra.Command, _ []string) error {
noDocs, _ := cmd.Flags().GetBool("no-docs")
running, _ := cmd.Flags().GetBool("running")
minimal, _ := cmd.Flags().GetBool("minimal")
if running {
return printRunningConfig(cmd, !noDocs)
@@ -74,7 +78,7 @@ kept as written.`,
d := config.Default()
out, err := config.GenerateExample(&d, config.ExampleOptions{Docs: !noDocs})
out, err := config.GenerateExample(&d, config.ExampleOptions{Docs: !noDocs, Minimal: minimal})
if err != nil {
return fmt.Errorf("generating config: %w", err)
}
+4
View File
@@ -303,6 +303,10 @@ func TestGenerateConfigCommand(t *testing.T) {
{name: "example", args: []string{"generate", "config"}, wantStdout: []string{"# Every key"}, wantLoaded: true},
{name: "alias", args: []string{"gen", "config"}, wantLoaded: true},
{name: "no docs", args: []string{"generate", "config", "--no-docs"}, hideStdout: []string{"#"}, wantLoaded: true},
{name: "minimal", args: []string{"generate", "config", "--minimal"}, wantStdout: []string{`server_url: ""`}, hideStdout: []string{"listen_addr"}, wantLoaded: true},
{name: "minimal no docs", args: []string{"generate", "config", "--minimal", "--no-docs"}, wantExact: "server_url: \"\"\n"},
// Cobra's flag-group error.
{name: "minimal running", args: []string{"-c", ok, "generate", "config", "--minimal", "--running"}, wantErr: true, wantStderr: []string{"none of the others can be"}},
{name: "running", args: []string{"-c", ok, "generate", "config", "--running"}, wantExact: running, wantStderr: []string{warning}},
{name: "running no docs", args: []string{"-c", ok, "generate", "config", "--running", "--no-docs"}, wantExact: runningNoDocs, wantStderr: []string{warning}},
{name: "running log level error", args: []string{"-c", logging("error", "level: error"), "generate", "config", "--running"}, wantExact: running, wantStderr: []string{warning}},
+14 -1
View File
@@ -19,10 +19,14 @@ type ExampleOptions struct {
// OmitClientOnly leaves out the keys only the CLI reads, which a
// server's configuration has no use for.
OmitClientOnly bool
// Minimal keeps only the keys every server must set, under their
// sections.
Minimal bool
}
const (
exampleHeader = "# Every key: https://headscale.net/stable/ref/configuration-options/\n"
minimalHeader = "# The keys every server must set.\n" + exampleHeader
commentWidth = 80
)
@@ -60,6 +64,12 @@ func exampleOf(keys []keyInfo, cfg *types.Config, opts ExampleOptions, root stri
continue
}
if opts.Minimal && !slices.ContainsFunc(keys, func(l keyInfo) bool {
return l.Required && l.RequiredWhen == "" && (l.Path == k.Path || strings.HasPrefix(l.Path, k.Path+"."))
}) {
continue
}
parent, name := "", k.Path
if i := strings.LastIndex(k.Path, "."); i >= 0 {
parent, name = k.Path[:i], k.Path[i+1:]
@@ -88,7 +98,10 @@ func exampleOf(keys []keyInfo, cfg *types.Config, opts ExampleOptions, root stri
var b bytes.Buffer
if opts.Docs && root == "" {
switch {
case opts.Docs && root == "" && opts.Minimal:
b.WriteString(minimalHeader)
case opts.Docs && root == "":
b.WriteString(exampleHeader)
}
+80
View File
@@ -346,3 +346,83 @@ func TestGenerateExampleSubtree(t *testing.T) {
})
}
}
// TestGenerateExampleMinimal: the minimal example holds only the keys every
// server must set, under their sections; it and the full example, with
// server_url set, load without warnings and validate.
func TestGenerateExampleMinimal(t *testing.T) {
d := Default()
tests := []struct {
name string
opts ExampleOptions
wantExact string // all of the output, when set
wantPrefix string
wantText string
wantKeys []string // top-level keys and leaves, when set
}{
{name: "minimal", opts: ExampleOptions{Minimal: true}, wantExact: "server_url: \"\"\n"},
{
name: "minimal docs",
opts: ExampleOptions{Docs: true, Minimal: true},
wantPrefix: minimalHeader + "\n",
wantText: "Required. Example: https://headscale.example.com",
wantKeys: []string{"server_url"},
},
{name: "full docs", opts: ExampleOptions{Docs: true}, wantPrefix: exampleHeader + "\n"},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
out, err := GenerateExample(&d, tt.opts)
require.NoError(t, err)
text := string(out)
if tt.wantExact != "" {
assert.Equal(t, tt.wantExact, text)
}
assert.True(t, strings.HasPrefix(text, tt.wantPrefix), text)
assert.Contains(t, text, tt.wantText)
if tt.wantKeys != nil {
top, leaves := exampleKeys(t, out)
assert.Equal(t, tt.wantKeys, top)
assert.Equal(t, tt.wantKeys, leaves)
}
// The leading newline matches a first line too.
require.Contains(t, "\n"+text, "\nserver_url: \"\"\n")
set := strings.Replace("\n"+text, "\nserver_url: \"\"\n", "\nserver_url: https://headscale.example.com\n", 1)
path := filepath.Join(t.TempDir(), "config.yaml")
require.NoError(t, os.WriteFile(path, []byte(set), 0o600))
l, err := Load(path, true, nil)
require.NoError(t, err, set)
assert.Empty(t, l.Warnings)
assert.NoError(t, Validate(l.Config))
})
}
t.Run("nested", func(t *testing.T) {
keys, err := schema()
require.NoError(t, err)
for _, k := range []struct{ path, when string }{
{path: "noise.private_key_path"},
{path: "database.sqlite.path", when: "`database.type` is `sqlite`"},
} {
i := slices.IndexFunc(keys, func(ki keyInfo) bool { return ki.Path == k.path })
require.GreaterOrEqual(t, i, 0, k.path)
keys[i].Required, keys[i].RequiredWhen = true, k.when
}
out, err := exampleOf(keys, &d, ExampleOptions{Minimal: true}, "")
require.NoError(t, err)
top, leaves := exampleKeys(t, out)
assert.Equal(t, []string{"server_url", "noise"}, top)
assert.Equal(t, []string{"server_url", "noise.private_key_path"}, leaves)
})
}