diff --git a/Dockerfile b/Dockerfile index cb309d045f..23fa0263e2 100644 --- a/Dockerfile +++ b/Dockerfile @@ -969,7 +969,7 @@ ARG TARGETOS ARG TARGETARCH WORKDIR /src COPY --from=talosctl-targetarch /talosctl-${TARGETOS}-${TARGETARCH} /bin/talosctl -RUN env HOME=/home/user TAG=latest /bin/talosctl docs --config /tmp \ +RUN env HOME=/home/user TAG=latest /bin/talosctl docs --config /tmp/configuration \ && env HOME=/home/user TAG=latest /bin/talosctl docs --cli /tmp COPY ./pkg/machinery/config/types/v1alpha1/schemas/ /tmp/schemas/ @@ -998,7 +998,7 @@ RUN protoc \ /protos/time/*.proto FROM scratch AS docs -COPY --from=docs-build /tmp/configuration.md /website/content/v1.6/reference/ +COPY --from=docs-build /tmp/configuration/ /website/content/v1.6/reference/configuration/ COPY --from=docs-build /tmp/cli.md /website/content/v1.6/reference/ COPY --from=docs-build /tmp/schemas /website/content/v1.6/schemas/ COPY --from=proto-docs-build /tmp/api.md /website/content/v1.6/reference/ diff --git a/cmd/talosctl/cmd/docs.go b/cmd/talosctl/cmd/docs.go index aa8f0bfbfd..319223b416 100644 --- a/cmd/talosctl/cmd/docs.go +++ b/cmd/talosctl/cmd/docs.go @@ -16,19 +16,32 @@ import ( "github.com/spf13/cobra" "github.com/spf13/cobra/doc" + "sigs.k8s.io/kustomize/kyaml/yaml" + "github.com/siderolabs/talos/pkg/machinery/config/encoder" + "github.com/siderolabs/talos/pkg/machinery/config/types/network" + "github.com/siderolabs/talos/pkg/machinery/config/types/runtime" + "github.com/siderolabs/talos/pkg/machinery/config/types/siderolink" v1alpha1 "github.com/siderolabs/talos/pkg/machinery/config/types/v1alpha1" ) func frontmatter(title, description string) string { - frontmatter := "---\n" + var buf bytes.Buffer - frontmatter += "title: " + title + "\n" - frontmatter += "desription: " + description + "\n" + buf.WriteString("---\n") - frontmatter += "---\n\n" + if err := yaml.NewEncoder(&buf).Encode(map[string]string{ + "title": title, + "description": description, + }); err != nil { + panic(err) + } + + buf.WriteString("---\n") + buf.WriteString("\n") + buf.WriteString("\n\n") - return frontmatter + "\n\n" + return buf.String() } func linkHandler(name string) string { @@ -39,10 +52,7 @@ func linkHandler(name string) string { return "#" + strings.ToLower(base) } -const ( - cliDescription = "Talosctl CLI tool reference." - configurationDescription = "Talos node configuration file reference." -) +const cliDescription = "Talosctl CLI tool reference." var ( cliDocs bool @@ -90,8 +100,36 @@ var docsCmd = &cobra.Command{ } if configDocs || all { - if err := v1alpha1.GetConfigurationDoc().Write(dir, frontmatter("Configuration", configurationDescription)); err != nil { - return fmt.Errorf("failed to generate docs: %w", err) + for _, pkg := range []struct { + name string + fileDoc *encoder.FileDoc + }{ + { + name: "network", + fileDoc: network.GetFileDoc(), + }, + { + name: "runtime", + fileDoc: runtime.GetFileDoc(), + }, + { + name: "siderolink", + fileDoc: siderolink.GetFileDoc(), + }, + { + name: "v1alpha1", + fileDoc: v1alpha1.GetFileDoc(), + }, + } { + path := filepath.Join(dir, pkg.name) + + if err := os.MkdirAll(path, 0o777); err != nil { + return fmt.Errorf("failed to create output directory %q", path) + } + + if err := pkg.fileDoc.Write(path, frontmatter); err != nil { + return fmt.Errorf("failed to generate docs: %w", err) + } } } diff --git a/cmd/talosctl/cmd/mgmt/cluster/internal/firewallpatch/firewallpatch.go b/cmd/talosctl/cmd/mgmt/cluster/internal/firewallpatch/firewallpatch.go index af4f9d8fe5..0a617a030e 100644 --- a/cmd/talosctl/cmd/mgmt/cluster/internal/firewallpatch/firewallpatch.go +++ b/cmd/talosctl/cmd/mgmt/cluster/internal/firewallpatch/firewallpatch.go @@ -24,7 +24,7 @@ func ingressRuleWithinCluster(cidrs []netip.Prefix, gateways []netip.Addr) []net rules = append(rules, network.IngressRule{ Subnet: cidrs[i], - Except: netip.PrefixFrom(gateways[i], gateways[i].BitLen()), + Except: network.Prefix{Prefix: netip.PrefixFrom(gateways[i], gateways[i].BitLen())}, }, ) } diff --git a/hack/docgen/main.go b/hack/docgen/main.go index 8b2122d3d0..bf95ccd9c9 100644 --- a/hack/docgen/main.go +++ b/hack/docgen/main.go @@ -12,6 +12,7 @@ import ( "go/parser" "go/token" "log" + "maps" "os" "path/filepath" "reflect" @@ -39,7 +40,7 @@ import ( {{ range $struct := .Structs -}} func ({{ $struct.Name }}) Doc() *encoder.Doc { doc := &encoder.Doc{ - Type : "{{ $struct.Name }}", + Type : "{{ if $struct.Text.Alias }}{{ $struct.Text.Alias}}{{ else }}{{ $struct.Name }}{{ end }}", Comments: [3]string{ "" /* encoder.HeadComment */, "{{ $struct.Text.Comment }}" /* encoder.LineComment */, "" /* encoder.FootComment */}, Description: "{{ $struct.Text.Description }}", {{ if $struct.AppearsIn -}} @@ -100,8 +101,8 @@ func ({{ $struct.Name }}) Doc() *encoder.Doc { } {{ end -}} -// Get{{ .Name }}Doc returns documentation for the file {{ .File }}. -func Get{{ .Name }}Doc() *encoder.FileDoc { +// GetFileDoc returns documentation for the file {{ .File }}. +func GetFileDoc() *encoder.FileDoc { return &encoder.FileDoc{ Name: "{{ .Name }}", Description: "{{ .Header }}", @@ -153,6 +154,7 @@ type Text struct { Comment string `json:"-"` Description string `json:"description"` Examples []*Example `json:"examples"` + Alias string `json:"alias"` Values []string `json:"values"` Schema *SchemaWrapper `json:"schema"` } @@ -346,6 +348,8 @@ func collectFields(s *structType, aliases map[string]aliasType) (fields []*Field for _, f := range s.node.Fields.List { if f.Names == nil { // This is an embedded struct. + fields = append(fields, &Field{Type: "unknown"}) + continue } @@ -433,34 +437,52 @@ func render(doc *Doc, dest string) { } } -func processFile(inputFile, outputFile, schemaOutputFile, versionTagFile, typeName string) { - abs, err := in(inputFile) - if err != nil { - log.Fatal(err) - } +func processFile(inputFiles []string, outputFile, schemaOutputFile, versionTagFile string) { + var ( + packageName string + packageDoc string + structs []*structType + ) + + aliases := map[string]aliasType{} - fmt.Printf("creating package file set: %q\n", abs) + for _, inputFile := range inputFiles { + abs, err := in(inputFile) + if err != nil { + log.Fatal(err) + } - fset := token.NewFileSet() + fmt.Printf("creating package file set: %q\n", abs) - node, err := parser.ParseFile(fset, abs, nil, parser.ParseComments) - if err != nil { - log.Fatal(err) - } + fset := token.NewFileSet() - packageName := node.Name.Name + node, err := parser.ParseFile(fset, abs, nil, parser.ParseComments) + if err != nil { + log.Fatal(err) + } - tokenFile := fset.File(node.Pos()) - if tokenFile == nil { - log.Fatalf("No token") - } + packageName = node.Name.Name + + if node.Doc != nil && node.Doc.Text() != "" { + packageDoc = node.Doc.Text() + } + + tokenFile := fset.File(node.Pos()) + if tokenFile == nil { + log.Fatalf("No token") + } - fmt.Printf("parsing file in package %q: %s\n", packageName, tokenFile.Name()) + fmt.Printf("parsing file in package %q: %s\n", packageName, tokenFile.Name()) - structs, aliases := collectStructs(node) + fileStructs, fileAliases := collectStructs(node) + + structs = append(structs, fileStructs...) + + maps.Copy(aliases, fileAliases) + } if len(structs) == 0 { - log.Fatalf("failed to find types that could be documented in %s", abs) + log.Fatalf("failed to find types that could be documented in %v", inputFiles) } doc := &Doc{ @@ -501,6 +523,11 @@ func processFile(inputFile, outputFile, schemaOutputFile, versionTagFile, typeNa } for _, s := range doc.Structs { + if s.Text.Alias != "" { + s.Text.Description = strings.ReplaceAll(s.Text.Description, s.Name, s.Text.Alias) + s.Text.Comment = strings.ReplaceAll(s.Text.Comment, s.Name, s.Text.Alias) + } + if extra, ok := extraExamples[s.Name]; ok { s.Text.Examples = append(s.Text.Examples, extra...) } @@ -510,14 +537,9 @@ func processFile(inputFile, outputFile, schemaOutputFile, versionTagFile, typeNa } } - if err == nil { - doc.Package = node.Name.Name - doc.Name = typeName - - if node.Doc != nil { - doc.Header = escape(node.Doc.Text()) - } - } + doc.Package = packageName + doc.Name = doc.Package + doc.Header = escape(packageDoc) doc.File = outputFile render(doc, outputFile) @@ -528,17 +550,14 @@ func processFile(inputFile, outputFile, schemaOutputFile, versionTagFile, typeNa } func main() { + outputFile := flag.String("output", "doc.go", "output file name") + jsonSchemaOutputFile := flag.String("json-schema-output", "", "output file name for json schema") + versionTagFile := flag.String("version-tag-file", "", "file name for version tag") flag.Parse() - if flag.NArg() != 3 && flag.NArg() != 5 { - log.Fatalf("unexpected number of args: %d", flag.NArg()) + if flag.NArg() == 0 { + log.Fatalf("no input files") } - inputFile := flag.Arg(0) - outputFile := flag.Arg(1) - typeName := flag.Arg(2) - jsonSchemaOutputFile := flag.Arg(3) - versionTagFile := flag.Arg(4) - - processFile(inputFile, outputFile, jsonSchemaOutputFile, versionTagFile, typeName) + processFile(flag.Args(), *outputFile, *jsonSchemaOutputFile, *versionTagFile) } diff --git a/hack/docgen/main_test.go b/hack/docgen/main_test.go index 9cb5203e77..a5d05cf9f4 100644 --- a/hack/docgen/main_test.go +++ b/hack/docgen/main_test.go @@ -15,6 +15,5 @@ func TestProcessFile(t *testing.T) { outputFile := filepath.Join(t.TempDir(), "out.go") schemaOutputFile := filepath.Join(t.TempDir(), "out.schema.json") versionTagFile := filepath.Join("..", "..", "pkg", "machinery", "gendata", "data", "tag") - typeName := "Configuration" - processFile(inputFile, outputFile, schemaOutputFile, versionTagFile, typeName) + processFile([]string{inputFile}, outputFile, schemaOutputFile, versionTagFile) } diff --git a/internal/app/machined/pkg/controllers/network/nftables_chain_config_test.go b/internal/app/machined/pkg/controllers/network/nftables_chain_config_test.go index 29572dac0e..022d2c86c0 100644 --- a/internal/app/machined/pkg/controllers/network/nftables_chain_config_test.go +++ b/internal/app/machined/pkg/controllers/network/nftables_chain_config_test.go @@ -41,7 +41,7 @@ func (suite *NfTablesChainConfigTestSuite) injectConfig(block bool) { kubeletIngressCfg.Ingress = []networkcfg.IngressRule{ { Subnet: netip.MustParsePrefix("10.0.0.0/8"), - Except: netip.MustParsePrefix("10.3.0.0/16"), + Except: networkcfg.Prefix{Prefix: netip.MustParsePrefix("10.3.0.0/16")}, }, { Subnet: netip.MustParsePrefix("192.168.0.0/16"), diff --git a/pkg/machinery/config/encoder/markdown.go b/pkg/machinery/config/encoder/markdown.go index 45122b471c..54ebc80dbc 100644 --- a/pkg/machinery/config/encoder/markdown.go +++ b/pkg/machinery/config/encoder/markdown.go @@ -6,51 +6,19 @@ package encoder import ( "bytes" + _ "embed" "fmt" "os" "path/filepath" - "regexp" + "slices" "strings" "text/template" yaml "gopkg.in/yaml.v3" ) -var markdownTemplate = ` -{{ .Description }} -{{- $anchors := .Anchors -}} -{{- $tick := "` + "`" + `" -}} -{{ range $struct := .Structs }} ---- -## {{ $struct.Type }} -{{ if $struct.Description -}} -{{ $struct.Description }} -{{ end }} -{{ if $struct.AppearsIn -}} -Appears in: - -{{ range $appearance := $struct.AppearsIn -}} -- {{ encodeType $appearance.TypeName }}.{{ $appearance.FieldName }} -{{ end -}} -{{ end }} - -{{ range $example := $struct.Examples }} -{{ yaml $example.GetValue "" }} -{{ end }} - -{{ if $struct.Fields -}} -| Field | Type | Description | Value(s) | -|-------|------|-------------|----------| -{{ range $field := $struct.Fields -}} -{{ if $field.Name -}} -| {{- $tick }}{{ $field.Name }}{{ $tick }} | -{{- encodeType $field.Type }} | -{{- fmtDesc $field.Description }} {{ with $field.Examples }}
Show example(s){{ range . }}{{ yaml .GetValue $field.Name }}{{ end }}
{{ end }} | -{{- range $value := $field.Values }}{{ $tick }}{{ $value }}{{ $tick }}
{{ end }} | -{{ end -}} -{{ end }} -{{ end }} -{{ end }}` +//go:embed "markdown.tmpl" +var markdownTemplate string // FileDoc represents a single go file documentation. type FileDoc struct { @@ -60,31 +28,33 @@ type FileDoc struct { Description string // Structs structs defined in the file. Structs []*Doc - Anchors map[string]string - - t *template.Template + // Types is map of all non-trivial types defined in the file. + Types map[string]*Doc } // Encode encodes file documentation as MD file. -func (fd *FileDoc) Encode() ([]byte, error) { - anchors := map[string]string{} - for _, t := range fd.Structs { - anchors[t.Type] = strings.ToLower(t.Type) - } - - fd.Anchors = anchors - - fd.t = template.Must(template.New("file_markdown.tpl"). +func (fd *FileDoc) Encode(root *Doc, frontmatter func(title, description string) string) ([]byte, error) { + t := template.Must(template.New("markdown.tmpl"). Funcs(template.FuncMap{ - "yaml": encodeYaml, - "fmtDesc": formatDescription, - "encodeType": fd.encodeType, + "yaml": encodeYaml, + "fmtDesc": formatDescription, + "dict": tmplDict, + "repeat": strings.Repeat, + "trimPrefix": strings.TrimPrefix, + "add": func(a, b int) int { return a + b }, + "frontmatter": frontmatter, }). Parse(markdownTemplate)) - buf := bytes.Buffer{} + var buf bytes.Buffer - if err := fd.t.Execute(&buf, fd); err != nil { + if err := t.Execute(&buf, struct { + Root *Doc + Types map[string]*Doc + }{ + Root: root, + Types: fd.Types, + }); err != nil { return nil, err } @@ -92,54 +62,85 @@ func (fd *FileDoc) Encode() ([]byte, error) { } // Write dumps documentation string to folder. -func (fd *FileDoc) Write(path, frontmatter string) error { - data, err := fd.Encode() - if err != nil { - return err - } - - if stat, e := os.Stat(path); !os.IsNotExist(e) { +// +//nolint:gocyclo +func (fd *FileDoc) Write(path string, frontmatter func(title, description string) string) error { + if stat, err := os.Stat(path); !os.IsNotExist(err) { if !stat.IsDir() { return fmt.Errorf("destination path should be a directory") } } else { - if e := os.MkdirAll(path, 0o777); e != nil { - return e + if err := os.MkdirAll(path, 0o777); err != nil { + return err } } - f, err := os.Create(filepath.Join(path, fmt.Sprintf("%s.%s", strings.ToLower(fd.Name), "md"))) - if err != nil { + // generate _index.md + if err := os.WriteFile(filepath.Join(path, "_index.md"), []byte(frontmatter(fd.Name, fd.Description)), 0o666); err != nil { return err } - if _, err := f.WriteString(frontmatter); err != nil { - return err - } + // find map of all types + fd.Types = map[string]*Doc{} - if _, err := f.Write(data); err != nil { - return err + for _, t := range fd.Structs { + if t.Type == "" || strings.ToLower(t.Type) == t.Type { + continue + } + + fd.Types[t.Type] = t } - return nil -} + // find root nodes + var roots []*Doc -func (fd *FileDoc) encodeType(t string) string { - re := regexp.MustCompile(`\w+`) + for _, t := range fd.Structs { + if len(t.AppearsIn) == 0 { + roots = append(roots, t) + } + } + + for _, root := range roots { + contents, err := fd.Encode(root, frontmatter) + if err != nil { + return err + } - for _, s := range re.FindAllString(t, -1) { - if anchor, ok := fd.Anchors[s]; ok { - t = strings.ReplaceAll(t, s, formatLink(s, "#"+anchor)) + if err := os.WriteFile(filepath.Join(path, fmt.Sprintf("%s.%s", strings.ToLower(root.Type), "md")), contents, 0o666); err != nil { + return err } } - return t + return nil } -func encodeYaml(in interface{}, name string) string { - if name != "" { - in = map[string]interface{}{ - name: in, +//nolint:gocyclo +func encodeYaml(in any, path string) string { + if path != "" { + parts := strings.Split(path, ".") + + parts = parts[1:] // strip first segment, it's root element + + // if the last element is ""/"-", it means we're at the root of the slice, so we don't need to wrap it once again + if len(parts) > 0 && (parts[len(parts)-1] == "" || parts[len(parts)-1] == "-") { + parts = parts[:len(parts)-1] + } + + slices.Reverse(parts) + + for _, part := range parts { + switch part { + case "": + in = []any{in} + case "-": + in = map[string]any{ + "example.com": in, + } + default: + in = map[string]any{ + part: in, + } + } } } @@ -161,10 +162,6 @@ func encodeYaml(in interface{}, name string) string { return fmt.Sprintf("{{< highlight yaml >}}\n%s{{< /highlight >}}", strings.Join(lines, "\n")) } -func formatLink(text, link string) string { - return fmt.Sprintf(`%s`, link, text) -} - func formatDescription(description string) string { lines := strings.Split(description, "\n") if len(lines) <= 1 { @@ -173,3 +170,22 @@ func formatDescription(description string) string { return fmt.Sprintf("
%s%s
", lines[0], strings.Join(lines[1:], "
")) } + +func tmplDict(vals ...any) (map[string]any, error) { + if len(vals)%2 != 0 { + return nil, fmt.Errorf("invalid number of arguments: %d", len(vals)) + } + + res := map[string]any{} + + for i := 0; i < len(vals); i += 2 { + key, ok := vals[i].(string) + if !ok { + return nil, fmt.Errorf("invalid key type: %T", vals[i]) + } + + res[key] = vals[i+1] + } + + return res, nil +} diff --git a/pkg/machinery/config/encoder/markdown.tmpl b/pkg/machinery/config/encoder/markdown.tmpl new file mode 100644 index 0000000000..f33d44a593 --- /dev/null +++ b/pkg/machinery/config/encoder/markdown.tmpl @@ -0,0 +1,59 @@ +{{ frontmatter .Root.Type .Root.Description }} + +{{ block "struct" dict "Struct" .Root "Level" 1 "Name" .Root.Type "Path" .Root.Type "Types" .Types }} +{{ if gt .Level 1 }}{{ repeat "#" .Level }} {{ .Name }} {#{{ .Path }}}{{ end }} + +{{ if and .Struct.Description (gt .Level 1) -}} +{{ .Struct.Description }} +{{ end }} + +{{ range $example := .Struct.Examples }} +{{ yaml $example.GetValue $.Path }} +{{ end }} + +{{ if .Struct.Fields -}} +| Field | Type | Description | Value(s) | +|-------|------|-------------|----------| +{{ range $field := $.Struct.Fields -}} +{{ if $field.Name -}} +|`{{ $field.Name }}` | + {{- $type := index $.Types $field.Type -}} + {{- if $type -}} + {{ $field.Type }} + {{- else -}} + {{- $type := index $.Types (trimPrefix $field.Type "[]") -}} + {{- if $type -}} + {{ $field.Type }} + {{- else -}} + {{- $type := index $.Types (trimPrefix $field.Type "map[string]") -}} + {{- if $type -}} + {{ $field.Type }} + {{- else -}} + {{ $field.Type }} + {{- end -}} + {{- end -}} + {{- end }} | +{{- fmtDesc $field.Description }} {{ with $field.Examples }}
Show example(s){{ range . }}{{ yaml .GetValue (printf ".%s" $field.Name) }}{{ end }}
{{ end }} | +{{- range $value := $field.Values }}`{{ $value }}`
{{ end }} | +{{ end -}} +{{ end }} +{{ end }} + +{{ range $field := .Struct.Fields }} + {{- $struct := index $.Types $field.Type -}} + {{- if $struct -}} + {{ template "struct" dict "Struct" $struct "Level" (add $.Level 1) "Name" $field.Name "Types" $.Types "Path" (printf "%s.%s" $.Path $field.Name) }} + {{- else -}} + {{- $struct := index $.Types (trimPrefix $field.Type "[]") -}} + {{- if $struct -}} + {{ template "struct" dict "Struct" $struct "Level" (add $.Level 1) "Name" (printf "%s[]" $field.Name) "Types" $.Types "Path" (printf "%s.%s." $.Path $field.Name) }} + {{- else -}} + {{- $struct := index $.Types (trimPrefix $field.Type "map[string]") -}} + {{- if $struct -}} + {{ template "struct" dict "Struct" $struct "Level" (add $.Level 1) "Name" (printf "%s.*" $field.Name) "Types" $.Types "Path" (printf "%s.%s.-" $.Path $field.Name) }} + {{- end -}} + {{- end -}} + {{- end -}} +{{ end }} + +{{ end }} diff --git a/pkg/machinery/config/types/network/default_action_config.go b/pkg/machinery/config/types/network/default_action_config.go index af0b916950..e4cba005a2 100644 --- a/pkg/machinery/config/types/network/default_action_config.go +++ b/pkg/machinery/config/types/network/default_action_config.go @@ -31,10 +31,18 @@ var ( _ config.NetworkRuleConfigSignal = &DefaultActionConfigV1Alpha1{} ) -// DefaultActionConfigV1Alpha1 is a event sink config document. +// DefaultActionConfigV1Alpha1 is a ingress firewall default action configuration document. +// +// examples: +// - value: exampleDefaultActionConfigV1Alpha1() +// alias: NetworkDefaultActionConfig type DefaultActionConfigV1Alpha1 struct { meta.Meta `yaml:",inline"` - + // description: | + // Default action for all not explicitly configured ingress traffic: accept or block. + // values: + // - "accept" + // - "block" Ingress nethelpers.DefaultAction `yaml:"ingress"` } @@ -48,6 +56,13 @@ func NewDefaultActionConfigV1Alpha1() *DefaultActionConfigV1Alpha1 { } } +func exampleDefaultActionConfigV1Alpha1() *DefaultActionConfigV1Alpha1 { + cfg := NewDefaultActionConfigV1Alpha1() + cfg.Ingress = nethelpers.DefaultActionAccept + + return cfg +} + // Clone implements config.Document interface. func (s *DefaultActionConfigV1Alpha1) Clone() config.Document { return s.DeepCopy() diff --git a/pkg/machinery/config/types/network/default_action_config_test.go b/pkg/machinery/config/types/network/default_action_config_test.go index b89591cc3c..5bf81b2346 100644 --- a/pkg/machinery/config/types/network/default_action_config_test.go +++ b/pkg/machinery/config/types/network/default_action_config_test.go @@ -27,7 +27,7 @@ func TestDefaultActionConfigMarshalStability(t *testing.T) { cfg := network.NewDefaultActionConfigV1Alpha1() cfg.Ingress = nethelpers.DefaultActionBlock - marshaled, err := encoder.NewEncoder(cfg).Encode() + marshaled, err := encoder.NewEncoder(cfg, encoder.WithComments(encoder.CommentsDisabled)).Encode() require.NoError(t, err) t.Log(string(marshaled)) diff --git a/pkg/machinery/config/types/network/network.go b/pkg/machinery/config/types/network/network.go index 0210ac9a64..f396a9a012 100644 --- a/pkg/machinery/config/types/network/network.go +++ b/pkg/machinery/config/types/network/network.go @@ -2,7 +2,9 @@ // License, v. 2.0. If a copy of the MPL was not distributed with this // file, You can obtain one at http://mozilla.org/MPL/2.0/. -// Package network provides Talos network config documents. +// Package network provides network machine configuration documents. package network +//go:generate docgen -output network_doc.go network.go default_action_config.go port_range.go rule_config.go + //go:generate deep-copy -type DefaultActionConfigV1Alpha1 -type RuleConfigV1Alpha1 -pointer-receiver -header-file ../../../../../hack/boilerplate.txt -o deep_copy.generated.go . diff --git a/pkg/machinery/config/types/network/network_doc.go b/pkg/machinery/config/types/network/network_doc.go new file mode 100644 index 0000000000..8aacb54566 --- /dev/null +++ b/pkg/machinery/config/types/network/network_doc.go @@ -0,0 +1,165 @@ +// This Source Code Form is subject to the terms of the Mozilla Public +// License, v. 2.0. If a copy of the MPL was not distributed with this +// file, You can obtain one at http://mozilla.org/MPL/2.0/. + +// Code generated by hack/docgen tool. DO NOT EDIT. + +package network + +import ( + "net/netip" + + "github.com/siderolabs/talos/pkg/machinery/config/encoder" +) + +func (DefaultActionConfigV1Alpha1) Doc() *encoder.Doc { + doc := &encoder.Doc{ + Type: "NetworkDefaultActionConfig", + Comments: [3]string{"" /* encoder.HeadComment */, "NetworkDefaultActionConfig is a ingress firewall default action configuration document." /* encoder.LineComment */, "" /* encoder.FootComment */}, + Description: "NetworkDefaultActionConfig is a ingress firewall default action configuration document.", + Fields: []encoder.Doc{ + {}, { + Name: "ingress", + Type: "DefaultAction", + Note: "", + Description: "Default action for all not explicitly configured ingress traffic: accept or block.", + Comments: [3]string{"" /* encoder.HeadComment */, "Default action for all not explicitly configured ingress traffic: accept or block." /* encoder.LineComment */, "" /* encoder.FootComment */}, + Values: []string{ + "accept", + "block", + }, + }, + }, + } + + doc.AddExample("", exampleDefaultActionConfigV1Alpha1()) + + return doc +} + +func (RuleConfigV1Alpha1) Doc() *encoder.Doc { + doc := &encoder.Doc{ + Type: "NetworkRuleConfig", + Comments: [3]string{"" /* encoder.HeadComment */, "NetworkRuleConfig is a network firewall rule config document." /* encoder.LineComment */, "" /* encoder.FootComment */}, + Description: "NetworkRuleConfig is a network firewall rule config document.", + Fields: []encoder.Doc{ + {}, + { + Name: "name", + Type: "string", + Note: "", + Description: "Name of the config document.", + Comments: [3]string{"" /* encoder.HeadComment */, "Name of the config document." /* encoder.LineComment */, "" /* encoder.FootComment */}, + }, + { + Name: "portSelector", + Type: "RulePortSelector", + Note: "", + Description: "Port selector defines which ports and protocols on the host are affected by the rule.", + Comments: [3]string{"" /* encoder.HeadComment */, "Port selector defines which ports and protocols on the host are affected by the rule." /* encoder.LineComment */, "" /* encoder.FootComment */}, + }, + { + Name: "ingress", + Type: "[]IngressRule", + Note: "", + Description: "Ingress defines which source subnets are allowed to access the host ports/protocols defined by the `portSelector`.", + Comments: [3]string{"" /* encoder.HeadComment */, "Ingress defines which source subnets are allowed to access the host ports/protocols defined by the `portSelector`." /* encoder.LineComment */, "" /* encoder.FootComment */}, + }, + }, + } + + doc.AddExample("", exampleRuleConfigV1Alpha1()) + + return doc +} + +func (RulePortSelector) Doc() *encoder.Doc { + doc := &encoder.Doc{ + Type: "RulePortSelector", + Comments: [3]string{"" /* encoder.HeadComment */, "RulePortSelector is a port selector for the network rule." /* encoder.LineComment */, "" /* encoder.FootComment */}, + Description: "RulePortSelector is a port selector for the network rule.", + AppearsIn: []encoder.Appearance{ + { + TypeName: "RuleConfigV1Alpha1", + FieldName: "portSelector", + }, + }, + Fields: []encoder.Doc{ + { + Name: "ports", + Type: "PortRanges", + Note: "", + Description: "Ports defines a list of port ranges or single ports.\nThe port ranges are inclusive, and should not overlap.", + Comments: [3]string{"" /* encoder.HeadComment */, "Ports defines a list of port ranges or single ports." /* encoder.LineComment */, "" /* encoder.FootComment */}, + }, + { + Name: "protocol", + Type: "Protocol", + Note: "", + Description: "Protocol defines traffic protocol (e.g. TCP or UDP).", + Comments: [3]string{"" /* encoder.HeadComment */, "Protocol defines traffic protocol (e.g. TCP or UDP)." /* encoder.LineComment */, "" /* encoder.FootComment */}, + Values: []string{ + "tcp", + "udp", + "icmp", + "icmpv6", + }, + }, + }, + } + + doc.Fields[0].AddExample("", examplePortRanges1()) + doc.Fields[0].AddExample("", examplePortRanges2()) + + return doc +} + +func (IngressRule) Doc() *encoder.Doc { + doc := &encoder.Doc{ + Type: "IngressRule", + Comments: [3]string{"" /* encoder.HeadComment */, "IngressRule is a ingress rule." /* encoder.LineComment */, "" /* encoder.FootComment */}, + Description: "IngressRule is a ingress rule.", + AppearsIn: []encoder.Appearance{ + { + TypeName: "RuleConfigV1Alpha1", + FieldName: "ingress", + }, + }, + Fields: []encoder.Doc{ + { + Name: "subnet", + Type: "Prefix", + Note: "", + Description: "Subnet defines a source subnet.", + Comments: [3]string{"" /* encoder.HeadComment */, "Subnet defines a source subnet." /* encoder.LineComment */, "" /* encoder.FootComment */}, + }, + { + Name: "except", + Type: "Prefix", + Note: "", + Description: "Except defines a source subnet to exclude from the rule, it gets excluded from the `subnet`.", + Comments: [3]string{"" /* encoder.HeadComment */, "Except defines a source subnet to exclude from the rule, it gets excluded from the `subnet`." /* encoder.LineComment */, "" /* encoder.FootComment */}, + }, + }, + } + + doc.Fields[0].AddExample("", netip.MustParsePrefix("10.3.4.0/24")) + doc.Fields[0].AddExample("", netip.MustParsePrefix("2001:db8::/32")) + doc.Fields[0].AddExample("", netip.MustParsePrefix("1.3.4.5/32")) + + return doc +} + +// GetFileDoc returns documentation for the file network_doc.go. +func GetFileDoc() *encoder.FileDoc { + return &encoder.FileDoc{ + Name: "network", + Description: "Package network provides network machine configuration documents.\n", + Structs: []*encoder.Doc{ + DefaultActionConfigV1Alpha1{}.Doc(), + RuleConfigV1Alpha1{}.Doc(), + RulePortSelector{}.Doc(), + IngressRule{}.Doc(), + }, + } +} diff --git a/pkg/machinery/config/types/network/port_range.go b/pkg/machinery/config/types/network/port_range.go index 7f85602d2e..b9371be190 100644 --- a/pkg/machinery/config/types/network/port_range.go +++ b/pkg/machinery/config/types/network/port_range.go @@ -2,7 +2,6 @@ // License, v. 2.0. If a copy of the MPL was not distributed with this // file, You can obtain one at http://mozilla.org/MPL/2.0/. -// Package network provides Talos network config documents. package network import ( @@ -14,6 +13,8 @@ import ( ) // PortRange is a port range. +// +//docgen:nodoc type PortRange struct { Lo uint16 Hi uint16 @@ -71,6 +72,8 @@ func (pr PortRange) String() string { } // PortRanges is a slice of port ranges. +// +//docgen:nodoc type PortRanges []PortRange // Validate the port ranges. @@ -100,3 +103,17 @@ func (prs PortRanges) Validate() error { return nil } + +func examplePortRanges1() PortRanges { + return PortRanges{ + {Lo: 80, Hi: 80}, + {Lo: 443, Hi: 443}, + } +} + +func examplePortRanges2() PortRanges { + return PortRanges{ + {Lo: 1200, Hi: 1299}, + {Lo: 8080, Hi: 8080}, + } +} diff --git a/pkg/machinery/config/types/network/rule_config.go b/pkg/machinery/config/types/network/rule_config.go index d3995e62a1..e871a0dbf8 100644 --- a/pkg/machinery/config/types/network/rule_config.go +++ b/pkg/machinery/config/types/network/rule_config.go @@ -41,27 +41,78 @@ var ( ) // RuleConfigV1Alpha1 is a network firewall rule config document. +// +// examples: +// - value: exampleRuleConfigV1Alpha1() +// alias: NetworkRuleConfig type RuleConfigV1Alpha1 struct { meta.Meta `yaml:",inline"` - MetaName string `yaml:"name"` - + // description: | + // Name of the config document. + MetaName string `yaml:"name"` + // description: | + // Port selector defines which ports and protocols on the host are affected by the rule. PortSelector RulePortSelector `yaml:"portSelector"` - Ingress IngressConfig `yaml:"ingress"` + // description: | + // Ingress defines which source subnets are allowed to access the host ports/protocols defined by the `portSelector`. + Ingress IngressConfig `yaml:"ingress"` } // RulePortSelector is a port selector for the network rule. type RulePortSelector struct { - Ports PortRanges `yaml:"ports"` + // description: | + // Ports defines a list of port ranges or single ports. + // The port ranges are inclusive, and should not overlap. + // examples: + // - value: > + // examplePortRanges1() + // - value: > + // examplePortRanges2() + Ports PortRanges `yaml:"ports"` + // description: | + // Protocol defines traffic protocol (e.g. TCP or UDP). + // values: + // - "tcp" + // - "udp" + // - "icmp" + // - "icmpv6" Protocol nethelpers.Protocol `yaml:"protocol"` } // IngressConfig is a ingress config. +// +//docgen:alias type IngressConfig []IngressRule // IngressRule is a ingress rule. type IngressRule struct { + // description: | + // Subnet defines a source subnet. + // examples: + // - value: > + // netip.MustParsePrefix("10.3.4.0/24") + // - value: > + // netip.MustParsePrefix("2001:db8::/32") + // - value: > + // netip.MustParsePrefix("1.3.4.5/32") Subnet netip.Prefix `yaml:"subnet"` - Except netip.Prefix `yaml:"except,omitempty"` + // description: | + // Except defines a source subnet to exclude from the rule, it gets excluded from the `subnet`. + Except Prefix `yaml:"except,omitempty"` +} + +// Prefix is a wrapper for netip.Prefix. +// +// It implements IsZero() so that yaml.Marshal correctly skips empty values. +// +//docgen:nodoc +type Prefix struct { + netip.Prefix +} + +// IsZero implements yaml.IsZeroer interface. +func (n Prefix) IsZero() bool { + return n.Prefix == netip.Prefix{} } // NewRuleConfigV1Alpha1 creates a new RuleConfig config document. @@ -74,6 +125,22 @@ func NewRuleConfigV1Alpha1() *RuleConfigV1Alpha1 { } } +func exampleRuleConfigV1Alpha1() *RuleConfigV1Alpha1 { + cfg := NewRuleConfigV1Alpha1() + cfg.MetaName = "ingress-apid" + cfg.PortSelector.Protocol = nethelpers.ProtocolTCP + cfg.PortSelector.Ports = PortRanges{ + {Lo: 50000, Hi: 50000}, + } + cfg.Ingress = IngressConfig{ + { + Subnet: netip.MustParsePrefix("192.168.0.0/16"), + }, + } + + return cfg +} + // Name implements config.NamedDocument interface. func (s *RuleConfigV1Alpha1) Name() string { return s.MetaName @@ -148,7 +215,7 @@ func (s *RuleConfigV1Alpha1) ExceptSubnets() []netip.Prefix { }, ), func(rule IngressRule) netip.Prefix { - return rule.Except + return rule.Except.Prefix }, ) } diff --git a/pkg/machinery/config/types/network/rule_config_test.go b/pkg/machinery/config/types/network/rule_config_test.go index 1605155ffa..6300dd4732 100644 --- a/pkg/machinery/config/types/network/rule_config_test.go +++ b/pkg/machinery/config/types/network/rule_config_test.go @@ -39,14 +39,14 @@ func TestRuleConfigMarshalStability(t *testing.T) { cfg.Ingress = network.IngressConfig{ { Subnet: netip.MustParsePrefix("192.168.0.0/16"), - Except: netip.MustParsePrefix("192.168.0.3/32"), + Except: network.Prefix{netip.MustParsePrefix("192.168.0.3/32")}, }, { Subnet: netip.MustParsePrefix("2001::/16"), }, } - marshaled, err := encoder.NewEncoder(cfg).Encode() + marshaled, err := encoder.NewEncoder(cfg, encoder.WithComments(encoder.CommentsDisabled)).Encode() require.NoError(t, err) t.Log(string(marshaled)) @@ -79,7 +79,7 @@ func TestRuleConfigUnmarshal(t *testing.T) { Ingress: network.IngressConfig{ { Subnet: netip.MustParsePrefix("192.168.0.0/16"), - Except: netip.MustParsePrefix("192.168.0.3/32"), + Except: network.Prefix{netip.MustParsePrefix("192.168.0.3/32")}, }, { Subnet: netip.MustParsePrefix("2001::/16"), @@ -159,7 +159,7 @@ func TestRuleConfigValidate(t *testing.T) { cfg.Ingress = network.IngressConfig{ { Subnet: netip.MustParsePrefix("192.168.0.0/16"), - Except: netip.MustParsePrefix("192.168.3.0/24"), + Except: network.Prefix{netip.MustParsePrefix("192.168.3.0/24")}, }, { Subnet: netip.MustParsePrefix("2001::/16"), diff --git a/pkg/machinery/config/types/runtime/event_sink.go b/pkg/machinery/config/types/runtime/event_sink.go index e920831822..307ebf9121 100644 --- a/pkg/machinery/config/types/runtime/event_sink.go +++ b/pkg/machinery/config/types/runtime/event_sink.go @@ -38,9 +38,18 @@ var ( ) // EventSinkV1Alpha1 is a event sink config document. +// +// examples: +// - value: exampleEventSinkV1Alpha1() +// alias: EventSinkConfig type EventSinkV1Alpha1 struct { meta.Meta `yaml:",inline"` - Endpoint string `yaml:"endpoint"` + // description: | + // The endpoint for the event sink as 'host:port'. + // examples: + // - value: > + // "10.3.7.3:2810" + Endpoint string `yaml:"endpoint"` } // NewEventSinkV1Alpha1 creates a new eventsink config document. @@ -53,6 +62,13 @@ func NewEventSinkV1Alpha1() *EventSinkV1Alpha1 { } } +func exampleEventSinkV1Alpha1() *EventSinkV1Alpha1 { + cfg := NewEventSinkV1Alpha1() + cfg.Endpoint = "192.168.10.3:3247" + + return cfg +} + // Clone implements config.Document interface. func (s *EventSinkV1Alpha1) Clone() config.Document { return s.DeepCopy() diff --git a/pkg/machinery/config/types/runtime/event_sink_test.go b/pkg/machinery/config/types/runtime/event_sink_test.go index 50abb0f09e..d0b0b81b29 100644 --- a/pkg/machinery/config/types/runtime/event_sink_test.go +++ b/pkg/machinery/config/types/runtime/event_sink_test.go @@ -22,7 +22,7 @@ func TestEventSinkMarshalStability(t *testing.T) { cfg := runtime.NewEventSinkV1Alpha1() cfg.Endpoint = "10.0.0.1:3333" - marshaled, err := encoder.NewEncoder(cfg).Encode() + marshaled, err := encoder.NewEncoder(cfg, encoder.WithComments(encoder.CommentsDisabled)).Encode() require.NoError(t, err) t.Log(string(marshaled)) diff --git a/pkg/machinery/config/types/runtime/kmsg_log.go b/pkg/machinery/config/types/runtime/kmsg_log.go index 000bcb2a46..96735efc64 100644 --- a/pkg/machinery/config/types/runtime/kmsg_log.go +++ b/pkg/machinery/config/types/runtime/kmsg_log.go @@ -8,6 +8,8 @@ import ( "fmt" "net/url" + "github.com/siderolabs/gen/ensure" + "github.com/siderolabs/talos/pkg/machinery/config/config" "github.com/siderolabs/talos/pkg/machinery/config/internal/registry" "github.com/siderolabs/talos/pkg/machinery/config/types/meta" @@ -36,9 +38,23 @@ var ( ) // KmsgLogV1Alpha1 is a event sink config document. +// +// examples: +// - value: exampleKmsgLogV1Alpha1() +// alias: KmsgLogConfig type KmsgLogV1Alpha1 struct { - meta.Meta `yaml:",inline"` - MetaName string `yaml:"name"` + meta.Meta `yaml:",inline"` + // description: | + // Name of the config document. + MetaName string `yaml:"name"` + // description: | + // The URL encodes the log destination. + // The scheme must be tcp:// or udp://. + // The path must be empty. + // The port is required. + // examples: + // - value: > + // "udp://10.3.7.3:2810" KmsgLogURL meta.URL `yaml:"url"` } @@ -52,6 +68,14 @@ func NewKmsgLogV1Alpha1() *KmsgLogV1Alpha1 { } } +func exampleKmsgLogV1Alpha1() *KmsgLogV1Alpha1 { + cfg := NewKmsgLogV1Alpha1() + cfg.MetaName = "remote-log" + cfg.KmsgLogURL.URL = ensure.Value(url.Parse("tcp://192.168.3.7:3478/")) + + return cfg +} + // Name implements config.NamedDocument interface. func (s *KmsgLogV1Alpha1) Name() string { return s.MetaName diff --git a/pkg/machinery/config/types/runtime/kmsg_log_test.go b/pkg/machinery/config/types/runtime/kmsg_log_test.go index 486283e47e..adeecd6115 100644 --- a/pkg/machinery/config/types/runtime/kmsg_log_test.go +++ b/pkg/machinery/config/types/runtime/kmsg_log_test.go @@ -25,7 +25,7 @@ func TestKmsgLogMarshalStability(t *testing.T) { cfg.MetaName = "apiSink" cfg.KmsgLogURL.URL = ensure.Value(url.Parse("https://kmsglog.api/logs")) - marshaled, err := encoder.NewEncoder(cfg).Encode() + marshaled, err := encoder.NewEncoder(cfg, encoder.WithComments(encoder.CommentsDisabled)).Encode() require.NoError(t, err) t.Log(string(marshaled)) diff --git a/pkg/machinery/config/types/runtime/runtime.go b/pkg/machinery/config/types/runtime/runtime.go index 6d225b8311..d3a93b7848 100644 --- a/pkg/machinery/config/types/runtime/runtime.go +++ b/pkg/machinery/config/types/runtime/runtime.go @@ -2,7 +2,9 @@ // License, v. 2.0. If a copy of the MPL was not distributed with this // file, You can obtain one at http://mozilla.org/MPL/2.0/. -// Package runtime provides Talos runtime config documents. +// Package runtime provides runtime machine configuration documents. package runtime +//go:generate docgen -output runtime_doc.go runtime.go kmsg_log.go event_sink.go + //go:generate deep-copy -type EventSinkV1Alpha1 -type KmsgLogV1Alpha1 -pointer-receiver -header-file ../../../../../hack/boilerplate.txt -o deep_copy.generated.go . diff --git a/pkg/machinery/config/types/runtime/runtime_doc.go b/pkg/machinery/config/types/runtime/runtime_doc.go new file mode 100644 index 0000000000..b11bae8a54 --- /dev/null +++ b/pkg/machinery/config/types/runtime/runtime_doc.go @@ -0,0 +1,77 @@ +// This Source Code Form is subject to the terms of the Mozilla Public +// License, v. 2.0. If a copy of the MPL was not distributed with this +// file, You can obtain one at http://mozilla.org/MPL/2.0/. + +// Code generated by hack/docgen tool. DO NOT EDIT. + +package runtime + +import ( + "github.com/siderolabs/talos/pkg/machinery/config/encoder" +) + +func (KmsgLogV1Alpha1) Doc() *encoder.Doc { + doc := &encoder.Doc{ + Type: "KmsgLogConfig", + Comments: [3]string{"" /* encoder.HeadComment */, "KmsgLogConfig is a event sink config document." /* encoder.LineComment */, "" /* encoder.FootComment */}, + Description: "KmsgLogConfig is a event sink config document.", + Fields: []encoder.Doc{ + {}, + { + Name: "name", + Type: "string", + Note: "", + Description: "Name of the config document.", + Comments: [3]string{"" /* encoder.HeadComment */, "Name of the config document." /* encoder.LineComment */, "" /* encoder.FootComment */}, + }, + { + Name: "url", + Type: "URL", + Note: "", + Description: "The URL encodes the log destination.\nThe scheme must be tcp:// or udp://.\nThe path must be empty.\nThe port is required.", + Comments: [3]string{"" /* encoder.HeadComment */, "The URL encodes the log destination." /* encoder.LineComment */, "" /* encoder.FootComment */}, + }, + }, + } + + doc.AddExample("", exampleKmsgLogV1Alpha1()) + + doc.Fields[2].AddExample("", "udp://10.3.7.3:2810") + + return doc +} + +func (EventSinkV1Alpha1) Doc() *encoder.Doc { + doc := &encoder.Doc{ + Type: "EventSinkConfig", + Comments: [3]string{"" /* encoder.HeadComment */, "EventSinkConfig is a event sink config document." /* encoder.LineComment */, "" /* encoder.FootComment */}, + Description: "EventSinkConfig is a event sink config document.", + Fields: []encoder.Doc{ + {}, { + Name: "endpoint", + Type: "string", + Note: "", + Description: "The endpoint for the event sink as 'host:port'.", + Comments: [3]string{"" /* encoder.HeadComment */, "The endpoint for the event sink as 'host:port'." /* encoder.LineComment */, "" /* encoder.FootComment */}, + }, + }, + } + + doc.AddExample("", exampleEventSinkV1Alpha1()) + + doc.Fields[1].AddExample("", "10.3.7.3:2810") + + return doc +} + +// GetFileDoc returns documentation for the file runtime_doc.go. +func GetFileDoc() *encoder.FileDoc { + return &encoder.FileDoc{ + Name: "runtime", + Description: "Package runtime provides runtime machine configuration documents.\n", + Structs: []*encoder.Doc{ + KmsgLogV1Alpha1{}.Doc(), + EventSinkV1Alpha1{}.Doc(), + }, + } +} diff --git a/pkg/machinery/config/types/siderolink/siderolink.go b/pkg/machinery/config/types/siderolink/siderolink.go index 29da74872c..56054172ba 100644 --- a/pkg/machinery/config/types/siderolink/siderolink.go +++ b/pkg/machinery/config/types/siderolink/siderolink.go @@ -2,19 +2,23 @@ // License, v. 2.0. If a copy of the MPL was not distributed with this // file, You can obtain one at http://mozilla.org/MPL/2.0/. -// Package siderolink provides siderolink config documents. +// Package siderolink provides SideroLink machine configuration documents. package siderolink import ( "fmt" "net/url" + "github.com/siderolabs/gen/ensure" + "github.com/siderolabs/talos/pkg/machinery/config/config" "github.com/siderolabs/talos/pkg/machinery/config/internal/registry" "github.com/siderolabs/talos/pkg/machinery/config/types/meta" "github.com/siderolabs/talos/pkg/machinery/config/validation" ) +//go:generate docgen -output ./siderolink_doc.go ./siderolink.go + //go:generate deep-copy -type ConfigV1Alpha1 -pointer-receiver -header-file ../../../../../hack/boilerplate.txt -o deep_copy.generated.go . // Kind is a siderolink config document kind. @@ -38,9 +42,18 @@ var ( _ config.Validator = &ConfigV1Alpha1{} ) -// ConfigV1Alpha1 is a siderolink config document. +// ConfigV1Alpha1 is a SideroLink connection machine configuration document. +// +// examples: +// - value: exampleConfigV1Alpha1() +// alias: SideroLinkConfig type ConfigV1Alpha1 struct { - meta.Meta `yaml:",inline"` + meta.Meta `yaml:",inline"` + // description: | + // SideroLink API URL to connect to. + // examples: + // - value: > + // "https://siderolink.api/join?token=secret" APIUrlConfig meta.URL `yaml:"apiUrl"` } @@ -54,6 +67,13 @@ func NewConfigV1Alpha1() *ConfigV1Alpha1 { } } +func exampleConfigV1Alpha1() *ConfigV1Alpha1 { + cfg := NewConfigV1Alpha1() + cfg.APIUrlConfig.URL = ensure.Value(url.Parse("https://siderolink.api/join?token=secret")) + + return cfg +} + // Clone implements config.Document interface. func (s *ConfigV1Alpha1) Clone() config.Document { return s.DeepCopy() diff --git a/pkg/machinery/config/types/siderolink/siderolink_doc.go b/pkg/machinery/config/types/siderolink/siderolink_doc.go new file mode 100644 index 0000000000..88f18eb697 --- /dev/null +++ b/pkg/machinery/config/types/siderolink/siderolink_doc.go @@ -0,0 +1,45 @@ +// This Source Code Form is subject to the terms of the Mozilla Public +// License, v. 2.0. If a copy of the MPL was not distributed with this +// file, You can obtain one at http://mozilla.org/MPL/2.0/. + +// Code generated by hack/docgen tool. DO NOT EDIT. + +package siderolink + +import ( + "github.com/siderolabs/talos/pkg/machinery/config/encoder" +) + +func (ConfigV1Alpha1) Doc() *encoder.Doc { + doc := &encoder.Doc{ + Type: "SideroLinkConfig", + Comments: [3]string{"" /* encoder.HeadComment */, "SideroLinkConfig is a SideroLink connection machine configuration document." /* encoder.LineComment */, "" /* encoder.FootComment */}, + Description: "SideroLinkConfig is a SideroLink connection machine configuration document.", + Fields: []encoder.Doc{ + {}, { + Name: "apiUrl", + Type: "URL", + Note: "", + Description: "SideroLink API URL to connect to.", + Comments: [3]string{"" /* encoder.HeadComment */, "SideroLink API URL to connect to." /* encoder.LineComment */, "" /* encoder.FootComment */}, + }, + }, + } + + doc.AddExample("", exampleConfigV1Alpha1()) + + doc.Fields[1].AddExample("", "https://siderolink.api/join?token=secret") + + return doc +} + +// GetFileDoc returns documentation for the file ./siderolink_doc.go. +func GetFileDoc() *encoder.FileDoc { + return &encoder.FileDoc{ + Name: "siderolink", + Description: "Package siderolink provides SideroLink machine configuration documents.\n", + Structs: []*encoder.Doc{ + ConfigV1Alpha1{}.Doc(), + }, + } +} diff --git a/pkg/machinery/config/types/siderolink/siderolink_test.go b/pkg/machinery/config/types/siderolink/siderolink_test.go index e86daab224..c9a532e38d 100644 --- a/pkg/machinery/config/types/siderolink/siderolink_test.go +++ b/pkg/machinery/config/types/siderolink/siderolink_test.go @@ -39,7 +39,7 @@ func TestMarshalStability(t *testing.T) { cfg := siderolink.NewConfigV1Alpha1() cfg.APIUrlConfig.URL = ensure.Value(url.Parse("https://siderolink.api/join?jointoken=secret&user=alice")) - marshaled, err := encoder.NewEncoder(cfg).Encode() + marshaled, err := encoder.NewEncoder(cfg, encoder.WithComments(encoder.CommentsDisabled)).Encode() require.NoError(t, err) assert.Equal(t, expectedDocument, marshaled) diff --git a/pkg/machinery/config/types/v1alpha1/schemas/v1alpha1_config.schema.json b/pkg/machinery/config/types/v1alpha1/schemas/v1alpha1_config.schema.json index fc1acacd2c..78f3149203 100644 --- a/pkg/machinery/config/types/v1alpha1/schemas/v1alpha1_config.schema.json +++ b/pkg/machinery/config/types/v1alpha1/schemas/v1alpha1_config.schema.json @@ -701,12 +701,6 @@ "markdownDescription": "Enable verbose logging to the console.\nAll system containers logs will flow into serial console.\n\n**Note:** To avoid breaking Talos bootstrap flow enable this option only if serial console can handle high message throughput.", "x-intellij-html-description": "\u003cp\u003eEnable verbose logging to the console.\nAll system containers logs will flow into serial console.\u003c/p\u003e\n\n\u003cp\u003e\u003cstrong\u003eNote:\u003c/strong\u003e To avoid breaking Talos bootstrap flow enable this option only if serial console can handle high message throughput.\u003c/p\u003e\n" }, - "persist": { - "type": "boolean", - "title": "persist", - "markdownDescription": "", - "x-intellij-html-description": "" - }, "machine": { "$ref": "#/$defs/MachineConfig", "title": "machine", @@ -2395,19 +2389,6 @@ "additionalProperties": false, "type": "object" }, - "PodCheckpointer": { - "properties": { - "image": { - "type": "string", - "title": "image", - "description": "The image field is an override to the default pod-checkpointer image.\n", - "markdownDescription": "The `image` field is an override to the default pod-checkpointer image.", - "x-intellij-html-description": "\u003cp\u003eThe \u003ccode\u003eimage\u003c/code\u003e field is an override to the default pod-checkpointer image.\u003c/p\u003e\n" - } - }, - "additionalProperties": false, - "type": "object" - }, "ProxyConfig": { "properties": { "disabled": { diff --git a/pkg/machinery/config/types/v1alpha1/v1alpha1_examples.go b/pkg/machinery/config/types/v1alpha1/v1alpha1_examples.go index f157b5637b..18a6f82dad 100644 --- a/pkg/machinery/config/types/v1alpha1/v1alpha1_examples.go +++ b/pkg/machinery/config/types/v1alpha1/v1alpha1_examples.go @@ -30,12 +30,10 @@ func mustParseURL(uri string) *url.URL { func configExample() any { return struct { Version string `yaml:"version"` - Persist bool Machine *yaml.Node Cluster *yaml.Node }{ Version: "v1alpha1", - Persist: true, Machine: &yaml.Node{Kind: yaml.ScalarNode, LineComment: "..."}, Cluster: &yaml.Node{Kind: yaml.ScalarNode, LineComment: "..."}, } diff --git a/pkg/machinery/config/types/v1alpha1/v1alpha1_types.go b/pkg/machinery/config/types/v1alpha1/v1alpha1_types.go index b11bc62b12..6f965cb189 100644 --- a/pkg/machinery/config/types/v1alpha1/v1alpha1_types.go +++ b/pkg/machinery/config/types/v1alpha1/v1alpha1_types.go @@ -3,17 +3,17 @@ // file, You can obtain one at http://mozilla.org/MPL/2.0/. /* -Package v1alpha1 configuration file contains all the options available for configuring a machine. +Package v1alpha1 contains definition of the `v1alpha1` configuration document. -To generate a set of basic configuration files, run: +Even though the machine configuration in Talos Linux is multi-document, at the moment +this configuration document contains most of the configuration options. - talosctl gen config --version v1alpha1 - -This will generate a machine config for each node type, and a talosconfig for the CLI. +It is expected that new configuration options will be added as new documents, and existing ones +migrated to their own documents. */ package v1alpha1 -//go:generate docgen ./v1alpha1_types.go ./v1alpha1_types_doc.go Configuration ./schemas/v1alpha1_config.schema.json ../../../gendata/data/tag +//go:generate docgen -output ./v1alpha1_types_doc.go -json-schema-output ./schemas/v1alpha1_config.schema.json -version-tag-file ../../../gendata/data/tag ./v1alpha1_types.go //go:generate deepcopy-gen --input-dirs ../v1alpha1/ --go-header-file ../../../../../hack/boilerplate.txt --bounding-dirs ../v1alpha1 -O zz_generated.deepcopy @@ -42,7 +42,7 @@ func init() { }) } -// Config defines the v1alpha1 configuration file. +// Config defines the v1alpha1.Config Talos machine configuration document. // // examples: // - value: configExample() @@ -63,7 +63,9 @@ type Config struct { // - false // - no ConfigDebug *bool `yaml:"debug,omitempty"` - //docgen:nodoc + // docgen:nodoc + // + // Deprecated: Not supported anymore. ConfigPersist *bool `yaml:"persist,omitempty"` // description: | // Provides machine specific configuration options. @@ -1002,6 +1004,8 @@ type RegistriesConfig struct { } // PodCheckpointer represents the pod-checkpointer config values. +// +//docgen:nodoc type PodCheckpointer struct { // description: | // The `image` field is an override to the default pod-checkpointer image. @@ -2181,6 +2185,8 @@ type VolumeMountConfig struct { } // ClusterInlineManifests is a list of ClusterInlineManifest. +// +//docgen:alias type ClusterInlineManifests []ClusterInlineManifest // UnmarshalYAML implements yaml.Unmarshaler. diff --git a/pkg/machinery/config/types/v1alpha1/v1alpha1_types_doc.go b/pkg/machinery/config/types/v1alpha1/v1alpha1_types_doc.go index 05dbc7c991..da0b838358 100644 --- a/pkg/machinery/config/types/v1alpha1/v1alpha1_types_doc.go +++ b/pkg/machinery/config/types/v1alpha1/v1alpha1_types_doc.go @@ -16,8 +16,8 @@ import ( func (Config) Doc() *encoder.Doc { doc := &encoder.Doc{ Type: "Config", - Comments: [3]string{"" /* encoder.HeadComment */, "Config defines the v1alpha1 configuration file." /* encoder.LineComment */, "" /* encoder.FootComment */}, - Description: "Config defines the v1alpha1 configuration file.", + Comments: [3]string{"" /* encoder.HeadComment */, "Config defines the v1alpha1.Config Talos machine configuration document." /* encoder.LineComment */, "" /* encoder.FootComment */}, + Description: "Config defines the v1alpha1.Config Talos machine configuration document.", Fields: []encoder.Doc{ { Name: "version", @@ -42,13 +42,7 @@ func (Config) Doc() *encoder.Doc { "no", }, }, - { - Name: "persist", - Type: "bool", - Note: "", - Description: "", - Comments: [3]string{"" /* encoder.HeadComment */, "" /* encoder.LineComment */, "" /* encoder.FootComment */}, - }, + {}, { Name: "machine", Type: "MachineConfig", @@ -491,7 +485,7 @@ func (ClusterConfig) Doc() *encoder.Doc { }, { Name: "inlineManifests", - Type: "ClusterInlineManifests", + Type: "[]ClusterInlineManifest", Note: "", Description: "A list of inline Kubernetes manifests.\nThese will get automatically deployed as part of the bootstrap.", Comments: [3]string{"" /* encoder.HeadComment */, "A list of inline Kubernetes manifests." /* encoder.LineComment */, "" /* encoder.FootComment */}, @@ -1256,25 +1250,6 @@ func (RegistriesConfig) Doc() *encoder.Doc { return doc } -func (PodCheckpointer) Doc() *encoder.Doc { - doc := &encoder.Doc{ - Type: "PodCheckpointer", - Comments: [3]string{"" /* encoder.HeadComment */, "PodCheckpointer represents the pod-checkpointer config values." /* encoder.LineComment */, "" /* encoder.FootComment */}, - Description: "PodCheckpointer represents the pod-checkpointer config values.", - Fields: []encoder.Doc{ - { - Name: "image", - Type: "string", - Note: "", - Description: "The `image` field is an override to the default pod-checkpointer image.", - Comments: [3]string{"" /* encoder.HeadComment */, "The `image` field is an override to the default pod-checkpointer image." /* encoder.LineComment */, "" /* encoder.FootComment */}, - }, - }, - } - - return doc -} - func (CoreDNS) Doc() *encoder.Doc { doc := &encoder.Doc{ Type: "CoreDNS", @@ -1324,7 +1299,9 @@ func (Endpoint) Doc() *encoder.Doc { FieldName: "endpoint", }, }, - Fields: []encoder.Doc{}, + Fields: []encoder.Doc{ + {}, + }, } doc.AddExample("", clusterEndpointExample1()) @@ -3516,6 +3493,12 @@ func (ClusterInlineManifest) Doc() *encoder.Doc { Type: "ClusterInlineManifest", Comments: [3]string{"" /* encoder.HeadComment */, "ClusterInlineManifest struct describes inline bootstrap manifests for the user." /* encoder.LineComment */, "" /* encoder.FootComment */}, Description: "ClusterInlineManifest struct describes inline bootstrap manifests for the user.", + AppearsIn: []encoder.Appearance{ + { + TypeName: "ClusterConfig", + FieldName: "inlineManifests", + }, + }, Fields: []encoder.Doc{ { Name: "name", @@ -3534,6 +3517,8 @@ func (ClusterInlineManifest) Doc() *encoder.Doc { }, } + doc.AddExample("", clusterInlineManifestsExample()) + doc.Fields[0].AddExample("", "csi") doc.Fields[1].AddExample("", "/etc/kubernetes/auth") @@ -3954,11 +3939,11 @@ func (KernelModuleConfig) Doc() *encoder.Doc { return doc } -// GetConfigurationDoc returns documentation for the file ./v1alpha1_types_doc.go. -func GetConfigurationDoc() *encoder.FileDoc { +// GetFileDoc returns documentation for the file ./v1alpha1_types_doc.go. +func GetFileDoc() *encoder.FileDoc { return &encoder.FileDoc{ - Name: "Configuration", - Description: "Package v1alpha1 configuration file contains all the options available for configuring a machine.\n\nTo generate a set of basic configuration files, run:\n\n talosctl gen config --version v1alpha1 \n\nThis will generate a machine config for each node type, and a talosconfig for the CLI.\n", + Name: "v1alpha1", + Description: "Package v1alpha1 contains definition of the `v1alpha1` configuration document.\n\nEven though the machine configuration in Talos Linux is multi-document, at the moment\nthis configuration document contains most of the configuration options.\n\nIt is expected that new configuration options will be added as new documents, and existing ones\nmigrated to their own documents.\n", Structs: []*encoder.Doc{ Config{}.Doc(), MachineConfig{}.Doc(), @@ -3977,7 +3962,6 @@ func GetConfigurationDoc() *encoder.FileDoc { InstallExtensionConfig{}.Doc(), TimeConfig{}.Doc(), RegistriesConfig{}.Doc(), - PodCheckpointer{}.Doc(), CoreDNS{}.Doc(), Endpoint{}.Doc(), ControlPlaneConfig{}.Doc(), diff --git a/website/config.toml b/website/config.toml index fc00f4a6b8..691c454dcb 100644 --- a/website/config.toml +++ b/website/config.toml @@ -68,6 +68,11 @@ style = "solarized-dark" # Uncomment if you want your chosen highlight style used for code blocks without a specified language # guessSyntax = "true" + [markup.tableOfContents] + endLevel = 6 + ordered = false + startLevel = 2 + # Everything below this are Site Params # Comment out if you don't want the "print entire section" link enabled. diff --git a/website/content/v1.6/reference/cli.md b/website/content/v1.6/reference/cli.md index 6e215db24a..d347be68f9 100644 --- a/website/content/v1.6/reference/cli.md +++ b/website/content/v1.6/reference/cli.md @@ -1,6 +1,6 @@ --- +description: Talosctl CLI tool reference. title: CLI -desription: Talosctl CLI tool reference. --- diff --git a/website/content/v1.6/reference/configuration/_index.md b/website/content/v1.6/reference/configuration/_index.md new file mode 100644 index 0000000000..6018f4c6ed --- /dev/null +++ b/website/content/v1.6/reference/configuration/_index.md @@ -0,0 +1,28 @@ +--- +title: Configuration +description: Talos Linux machine configuration reference. +--- + +Talos Linux machine is fully configured via a single YAML file called *machine configuration*. + +The file might contain one or more configuration documents separated by `---` (three dashes) lines. +At the moment, majority of the configuration options are within the [v1alpha1]({{< relref "./v1alpha1" >}}) document, so +this is the only mandatory document in the configuration file. + +Configuration documents might be named (contain a `name:` field) or unnamed. +Unnamed documents can be supplied to the machine configuration file only once, while named documents can be supplied multiple times with unique names. + +The `v1alpha1` document has its own (legacy) structure, while every other document has the following set of fields: + +```yaml +apiVersion: v1alpha1 # version of the document +kind: NetworkRuleConfig # type of document +name: rule1 # only for named documents +``` + +This section contains the configuration reference, to learn more about Talos Linux machine configuration management, please see: + +* [quick guide to configuration generation]({{< relref "../../introduction/getting-started#configure-talos-linux" >}}) +* [configuration management in production]({{< relref "../../introduction/prodnotes#configure-talos" >}}) +* [configuration patches]({{< relref "../../talos-guides/configuration/patching" >}}) +* [editing live machine configuration]({{< relref "../../talos-guides/configuration/editing-machine-configuration" >}}) diff --git a/website/content/v1.6/reference/configuration/network/_index.md b/website/content/v1.6/reference/configuration/network/_index.md new file mode 100644 index 0000000000..21649f9f71 --- /dev/null +++ b/website/content/v1.6/reference/configuration/network/_index.md @@ -0,0 +1,8 @@ +--- +description: | + Package network provides network machine configuration documents. +title: network +--- + + + diff --git a/website/content/v1.6/reference/configuration/network/networkdefaultactionconfig.md b/website/content/v1.6/reference/configuration/network/networkdefaultactionconfig.md new file mode 100644 index 0000000000..1fa4a8220a --- /dev/null +++ b/website/content/v1.6/reference/configuration/network/networkdefaultactionconfig.md @@ -0,0 +1,31 @@ +--- +description: NetworkDefaultActionConfig is a ingress firewall default action configuration document. +title: NetworkDefaultActionConfig +--- + + + + + + + + + + + +{{< highlight yaml >}} +apiVersion: v1alpha1 +kind: NetworkDefaultActionConfig +ingress: accept # Default action for all not explicitly configured ingress traffic: accept or block. +{{< /highlight >}} + + +| Field | Type | Description | Value(s) | +|-------|------|-------------|----------| +|`ingress` |DefaultAction |Default action for all not explicitly configured ingress traffic: accept or block. |`accept`
`block`
| + + + + + + diff --git a/website/content/v1.6/reference/configuration/network/networkruleconfig.md b/website/content/v1.6/reference/configuration/network/networkruleconfig.md new file mode 100644 index 0000000000..2052b13f09 --- /dev/null +++ b/website/content/v1.6/reference/configuration/network/networkruleconfig.md @@ -0,0 +1,90 @@ +--- +description: NetworkRuleConfig is a network firewall rule config document. +title: NetworkRuleConfig +--- + + + + + + + + + + + +{{< highlight yaml >}} +apiVersion: v1alpha1 +kind: NetworkRuleConfig +name: ingress-apid # Name of the config document. +# Port selector defines which ports and protocols on the host are affected by the rule. +portSelector: + # Ports defines a list of port ranges or single ports. + ports: + - 50000 + protocol: tcp # Protocol defines traffic protocol (e.g. TCP or UDP). +# Ingress defines which source subnets are allowed to access the host ports/protocols defined by the `portSelector`. +ingress: + - subnet: 192.168.0.0/16 # Subnet defines a source subnet. +{{< /highlight >}} + + +| Field | Type | Description | Value(s) | +|-------|------|-------------|----------| +|`name` |string |Name of the config document. | | +|`portSelector` |RulePortSelector |Port selector defines which ports and protocols on the host are affected by the rule. | | +|`ingress` |[]IngressRule |Ingress defines which source subnets are allowed to access the host ports/protocols defined by the `portSelector`. | | + + + + +## portSelector {#NetworkRuleConfig.portSelector} + +RulePortSelector is a port selector for the network rule. + + + + +| Field | Type | Description | Value(s) | +|-------|------|-------------|----------| +|`ports` |PortRanges |
Ports defines a list of port ranges or single ports.The port ranges are inclusive, and should not overlap.
Show example(s){{< highlight yaml >}} +ports: + - 80 + - 443 +{{< /highlight >}}{{< highlight yaml >}} +ports: + - 1200-1299 + - 8080 +{{< /highlight >}}
| | +|`protocol` |Protocol |Protocol defines traffic protocol (e.g. TCP or UDP). |`tcp`
`udp`
`icmp`
`icmpv6`
| + + + + + + +## ingress[] {#NetworkRuleConfig.ingress.} + +IngressRule is a ingress rule. + + + + +| Field | Type | Description | Value(s) | +|-------|------|-------------|----------| +|`subnet` |Prefix |Subnet defines a source subnet.
Show example(s){{< highlight yaml >}} +subnet: 10.3.4.0/24 +{{< /highlight >}}{{< highlight yaml >}} +subnet: 2001:db8::/32 +{{< /highlight >}}{{< highlight yaml >}} +subnet: 1.3.4.5/32 +{{< /highlight >}}
| | +|`except` |Prefix |Except defines a source subnet to exclude from the rule, it gets excluded from the `subnet`. | | + + + + + + + + diff --git a/website/content/v1.6/reference/configuration/runtime/_index.md b/website/content/v1.6/reference/configuration/runtime/_index.md new file mode 100644 index 0000000000..9b0a110cc2 --- /dev/null +++ b/website/content/v1.6/reference/configuration/runtime/_index.md @@ -0,0 +1,8 @@ +--- +description: | + Package runtime provides runtime machine configuration documents. +title: runtime +--- + + + diff --git a/website/content/v1.6/reference/configuration/runtime/eventsinkconfig.md b/website/content/v1.6/reference/configuration/runtime/eventsinkconfig.md new file mode 100644 index 0000000000..37e401dc17 --- /dev/null +++ b/website/content/v1.6/reference/configuration/runtime/eventsinkconfig.md @@ -0,0 +1,33 @@ +--- +description: EventSinkConfig is a event sink config document. +title: EventSinkConfig +--- + + + + + + + + + + + +{{< highlight yaml >}} +apiVersion: v1alpha1 +kind: EventSinkConfig +endpoint: 192.168.10.3:3247 # The endpoint for the event sink as 'host:port'. +{{< /highlight >}} + + +| Field | Type | Description | Value(s) | +|-------|------|-------------|----------| +|`endpoint` |string |The endpoint for the event sink as 'host:port'.
Show example(s){{< highlight yaml >}} +endpoint: 10.3.7.3:2810 +{{< /highlight >}}
| | + + + + + + diff --git a/website/content/v1.6/reference/configuration/runtime/kmsglogconfig.md b/website/content/v1.6/reference/configuration/runtime/kmsglogconfig.md new file mode 100644 index 0000000000..bdbcf7e733 --- /dev/null +++ b/website/content/v1.6/reference/configuration/runtime/kmsglogconfig.md @@ -0,0 +1,35 @@ +--- +description: KmsgLogConfig is a event sink config document. +title: KmsgLogConfig +--- + + + + + + + + + + + +{{< highlight yaml >}} +apiVersion: v1alpha1 +kind: KmsgLogConfig +name: remote-log # Name of the config document. +url: tcp://192.168.3.7:3478/ # The URL encodes the log destination. +{{< /highlight >}} + + +| Field | Type | Description | Value(s) | +|-------|------|-------------|----------| +|`name` |string |Name of the config document. | | +|`url` |URL |
The URL encodes the log destination.The scheme must be tcp:// or udp://.
The path must be empty.
The port is required.
Show example(s){{< highlight yaml >}} +url: udp://10.3.7.3:2810 +{{< /highlight >}}
| | + + + + + + diff --git a/website/content/v1.6/reference/configuration/siderolink/_index.md b/website/content/v1.6/reference/configuration/siderolink/_index.md new file mode 100644 index 0000000000..fec4301b8f --- /dev/null +++ b/website/content/v1.6/reference/configuration/siderolink/_index.md @@ -0,0 +1,8 @@ +--- +description: | + Package siderolink provides SideroLink machine configuration documents. +title: siderolink +--- + + + diff --git a/website/content/v1.6/reference/configuration/siderolink/siderolinkconfig.md b/website/content/v1.6/reference/configuration/siderolink/siderolinkconfig.md new file mode 100644 index 0000000000..7644d25a80 --- /dev/null +++ b/website/content/v1.6/reference/configuration/siderolink/siderolinkconfig.md @@ -0,0 +1,33 @@ +--- +description: SideroLinkConfig is a SideroLink connection machine configuration document. +title: SideroLinkConfig +--- + + + + + + + + + + + +{{< highlight yaml >}} +apiVersion: v1alpha1 +kind: SideroLinkConfig +apiUrl: https://siderolink.api/join?token=secret # SideroLink API URL to connect to. +{{< /highlight >}} + + +| Field | Type | Description | Value(s) | +|-------|------|-------------|----------| +|`apiUrl` |URL |SideroLink API URL to connect to.
Show example(s){{< highlight yaml >}} +apiUrl: https://siderolink.api/join?token=secret +{{< /highlight >}}
| | + + + + + + diff --git a/website/content/v1.6/reference/configuration/v1alpha1/_index.md b/website/content/v1.6/reference/configuration/v1alpha1/_index.md new file mode 100644 index 0000000000..ca78907941 --- /dev/null +++ b/website/content/v1.6/reference/configuration/v1alpha1/_index.md @@ -0,0 +1,14 @@ +--- +description: | + Package v1alpha1 contains definition of the `v1alpha1` configuration document. + + Even though the machine configuration in Talos Linux is multi-document, at the moment + this configuration document contains most of the configuration options. + + It is expected that new configuration options will be added as new documents, and existing ones + migrated to their own documents. +title: v1alpha1 +--- + + + diff --git a/website/content/v1.6/reference/configuration.md b/website/content/v1.6/reference/configuration/v1alpha1/config.md similarity index 54% rename from website/content/v1.6/reference/configuration.md rename to website/content/v1.6/reference/configuration/v1alpha1/config.md index 17cf0468fb..6487ed035c 100644 --- a/website/content/v1.6/reference/configuration.md +++ b/website/content/v1.6/reference/configuration/v1alpha1/config.md @@ -1,29 +1,20 @@ --- -title: Configuration -desription: Talos node configuration file reference. +description: Config defines the v1alpha1.Config Talos machine configuration document. +title: Config --- -Package v1alpha1 configuration file contains all the options available for configuring a machine. -To generate a set of basic configuration files, run: - talosctl gen config --version v1alpha1 -This will generate a machine config for each node type, and a talosconfig for the CLI. - ---- -## Config -Config defines the v1alpha1 configuration file. {{< highlight yaml >}} version: v1alpha1 -persist: true machine: # ... cluster: # ... {{< /highlight >}} @@ -33,43 +24,40 @@ cluster: # ... |-------|------|-------------|----------| |`version` |string |Indicates the schema used to decode the contents. |`v1alpha1`
| |`debug` |bool |
Enable verbose logging to the console.All system containers logs will flow into serial console.

**Note:** To avoid breaking Talos bootstrap flow enable this option only if serial console can handle high message throughput.
|`true`
`yes`
`false`
`no`
| -|`persist` |bool | | | -|`machine` |MachineConfig |Provides machine specific configuration options. | | -|`cluster` |ClusterConfig |Provides cluster specific configuration options. | | +|`machine` |MachineConfig |Provides machine specific configuration options. | | +|`cluster` |ClusterConfig |Provides cluster specific configuration options. | | ---- -## MachineConfig -MachineConfig represents the machine-specific config values. -Appears in: +## machine {#Config.machine} -- Config.machine +MachineConfig represents the machine-specific config values. {{< highlight yaml >}} -type: controlplane -# InstallConfig represents the installation options for preparing a node. -install: - disk: /dev/sda # The disk used for installations. - # Allows for supplying extra kernel args via the bootloader. - extraKernelArgs: - - console=ttyS1 - - panic=10 - image: ghcr.io/siderolabs/installer:latest # Allows for supplying the image used to perform the installation. - wipe: false # Indicates if the installation disk should be wiped at installation time. - - # # Look up disk using disk attributes like model, size, serial and others. - # diskSelector: - # size: 4GB # Disk size. - # model: WDC* # Disk model `/sys/block//device/model`. - # busPath: /pci0000:00/0000:00:17.0/ata1/host0/target0:0:0/0:0:0:0 # Disk bus path. - - # # Allows for supplying additional system extension images to install on top of base Talos image. - # extensions: - # - image: ghcr.io/siderolabs/gvisor:20220117.0-v1.0.0 # System extension image. +machine: + type: controlplane + # InstallConfig represents the installation options for preparing a node. + install: + disk: /dev/sda # The disk used for installations. + # Allows for supplying extra kernel args via the bootloader. + extraKernelArgs: + - console=ttyS1 + - panic=10 + image: ghcr.io/siderolabs/installer:latest # Allows for supplying the image used to perform the installation. + wipe: false # Indicates if the installation disk should be wiped at installation time. + + # # Look up disk using disk attributes like model, size, serial and others. + # diskSelector: + # size: 4GB # Disk size. + # model: WDC* # Disk model `/sys/block//device/model`. + # busPath: /pci0000:00/0000:00:17.0/ata1/host0/target0:0:0/0:0:0:0 # Disk bus path. + + # # Allows for supplying additional system extension images to install on top of base Talos image. + # extensions: + # - image: ghcr.io/siderolabs/gvisor:20220117.0-v1.0.0 # System extension image. {{< /highlight >}} @@ -90,7 +78,7 @@ certSANs: - 172.16.0.10 - 192.168.0.10 {{< /highlight >}} | | -|`controlPlane` |MachineControlPlaneConfig |Provides machine specific control plane configuration options.
Show example(s){{< highlight yaml >}} +|`controlPlane` |MachineControlPlaneConfig |Provides machine specific control plane configuration options.
Show example(s){{< highlight yaml >}} controlPlane: # Controller manager machine specific configuration options. controllerManager: @@ -99,7 +87,7 @@ controlPlane: scheduler: disabled: true # Disable kube-scheduler on the node. {{< /highlight >}}
| | -|`kubelet` |KubeletConfig |Used to provide additional options to the kubelet.
Show example(s){{< highlight yaml >}} +|`kubelet` |KubeletConfig |Used to provide additional options to the kubelet.
Show example(s){{< highlight yaml >}} kubelet: image: ghcr.io/siderolabs/kubelet:v1.29.0-rc.1 # The `image` field is an optional reference to an alternative kubelet image. # The `extraArgs` field is used to provide additional flags to the kubelet. @@ -160,7 +148,7 @@ pods: - image: nginx name: nginx {{< /highlight >}}
| | -|`network` |NetworkConfig |Provides machine specific network configuration options.
Show example(s){{< highlight yaml >}} +|`network` |NetworkConfig |Provides machine specific network configuration options.
Show example(s){{< highlight yaml >}} network: hostname: worker-1 # Used to statically set the hostname for the machine. # `interfaces` is used to define the network interface configuration. @@ -269,7 +257,7 @@ network: # kubespan: # enabled: true # Enable the KubeSpan feature. {{< /highlight >}}
| | -|`disks` |[]MachineDisk |
Used to partition, format and mount additional disks.Since the rootfs is read only with the exception of `/var`, mounts are only valid if they are under `/var`.
Note that the partitioning and formatting is done only once, if and only if no existing XFS partitions are found.
If `size:` is omitted, the partition is sized to occupy the full disk.
Show example(s){{< highlight yaml >}} +|`disks` |[]MachineDisk |
Used to partition, format and mount additional disks.Since the rootfs is read only with the exception of `/var`, mounts are only valid if they are under `/var`.
Note that the partitioning and formatting is done only once, if and only if no existing XFS partitions are found.
If `size:` is omitted, the partition is sized to occupy the full disk.
Show example(s){{< highlight yaml >}} disks: - device: /dev/sdb # The name of the disk to use. # A list of partitions to create on the disk. @@ -283,7 +271,7 @@ disks: # # Precise value in bytes. # size: 1073741824 {{< /highlight >}}
| | -|`install` |InstallConfig |
Used to provide instructions for installations.
Note that this configuration section gets silently ignored by Talos images that are considered pre-installed.
To make sure Talos installs according to the provided configuration, Talos should be booted with ISO or PXE-booted.
Show example(s){{< highlight yaml >}} +|`install` |InstallConfig |
Used to provide instructions for installations.
Note that this configuration section gets silently ignored by Talos images that are considered pre-installed.
To make sure Talos installs according to the provided configuration, Talos should be booted with ISO or PXE-booted.
Show example(s){{< highlight yaml >}} install: disk: /dev/sda # The disk used for installations. # Allows for supplying extra kernel args via the bootloader. @@ -303,7 +291,7 @@ install: # extensions: # - image: ghcr.io/siderolabs/gvisor:20220117.0-v1.0.0 # System extension image. {{< /highlight >}}
| | -|`files` |[]MachineFile |
Allows the addition of user specified files.The value of `op` can be `create`, `overwrite`, or `append`.
In the case of `create`, `path` must not exist.
In the case of `overwrite`, and `append`, `path` must be a valid file.
If an `op` value of `append` is used, the existing file will be appended.
Note that the file contents are not required to be base64 encoded.
Show example(s){{< highlight yaml >}} +|`files` |[]MachineFile |
Allows the addition of user specified files.The value of `op` can be `create`, `overwrite`, or `append`.
In the case of `create`, `path` must not exist.
In the case of `overwrite`, and `append`, `path` must be a valid file.
If an `op` value of `append` is used, the existing file will be appended.
Note that the file contents are not required to be base64 encoded.
Show example(s){{< highlight yaml >}} files: - content: '...' # The contents of the file. permissions: 0o666 # The file's permissions in octal. @@ -323,7 +311,7 @@ env: env: https_proxy: http://DOMAIN\USERNAME:PASSWORD@SERVER:PORT/ {{< /highlight >}}
|``GRPC_GO_LOG_VERBOSITY_LEVEL``
``GRPC_GO_LOG_SEVERITY_LEVEL``
``http_proxy``
``https_proxy``
``no_proxy``
| -|`time` |TimeConfig |Used to configure the machine's time settings.
Show example(s){{< highlight yaml >}} +|`time` |TimeConfig |Used to configure the machine's time settings.
Show example(s){{< highlight yaml >}} time: disabled: false # Indicates if the time service is disabled for the machine. # Specifies time (NTP) servers to use for setting the system time. @@ -341,7 +329,7 @@ sysctls: sysfs: devices.system.cpu.cpu0.cpufreq.scaling_governor: performance {{< /highlight >}}
| | -|`registries` |RegistriesConfig |
Used to configure the machine's container image registry mirrors.
Automatically generates matching CRI configuration for registry mirrors.

The `mirrors` section allows to redirect requests for images to a non-default registry,
which might be a local registry or a caching mirror.

The `config` section provides a way to authenticate to the registry with TLS client
identity, provide registry CA, or authentication information.
Authentication information has same meaning with the corresponding field in [`.docker/config.json`](https://docs.docker.com/engine/api/v1.41/#section/Authentication).

See also matching configuration for [CRI containerd plugin](https://github.com/containerd/cri/blob/master/docs/registry.md).
Show example(s){{< highlight yaml >}} +|`registries` |RegistriesConfig |
Used to configure the machine's container image registry mirrors.
Automatically generates matching CRI configuration for registry mirrors.

The `mirrors` section allows to redirect requests for images to a non-default registry,
which might be a local registry or a caching mirror.

The `config` section provides a way to authenticate to the registry with TLS client
identity, provide registry CA, or authentication information.
Authentication information has same meaning with the corresponding field in [`.docker/config.json`](https://docs.docker.com/engine/api/v1.41/#section/Authentication).

See also matching configuration for [CRI containerd plugin](https://github.com/containerd/cri/blob/master/docs/registry.md).
Show example(s){{< highlight yaml >}} registries: # Specifies mirror configuration for each registry host namespace. mirrors: @@ -363,7 +351,7 @@ registries: username: username # Optional registry authentication. password: password # Optional registry authentication. {{< /highlight >}}
| | -|`systemDiskEncryption` |SystemDiskEncryptionConfig |
Machine system disk encryption configuration.Defines each system partition encryption parameters.
Show example(s){{< highlight yaml >}} +|`systemDiskEncryption` |SystemDiskEncryptionConfig |
Machine system disk encryption configuration.Defines each system partition encryption parameters.
Show example(s){{< highlight yaml >}} systemDiskEncryption: # Ephemeral partition encryption. ephemeral: @@ -389,7 +377,7 @@ systemDiskEncryption: # - no_read_workqueue # - no_write_workqueue {{< /highlight >}}
| | -|`features` |FeaturesConfig |Features describe individual Talos features that can be switched on or off.
Show example(s){{< highlight yaml >}} +|`features` |FeaturesConfig |Features describe individual Talos features that can be switched on or off.
Show example(s){{< highlight yaml >}} features: rbac: true # Enable role-based access control (RBAC). @@ -403,26 +391,26 @@ features: # allowedKubernetesNamespaces: # - kube-system {{< /highlight >}}
| | -|`udev` |UdevConfig |Configures the udev system.
Show example(s){{< highlight yaml >}} +|`udev` |UdevConfig |Configures the udev system.
Show example(s){{< highlight yaml >}} udev: # List of udev rules to apply to the udev system rules: - SUBSYSTEM=="drm", KERNEL=="renderD*", GROUP="44", MODE="0660" {{< /highlight >}}
| | -|`logging` |LoggingConfig |Configures the logging system.
Show example(s){{< highlight yaml >}} +|`logging` |LoggingConfig |Configures the logging system.
Show example(s){{< highlight yaml >}} logging: # Logging destination. destinations: - endpoint: tcp://1.2.3.4:12345 # Where to send logs. Supported protocols are "tcp" and "udp". format: json_lines # Logs format. {{< /highlight >}}
| | -|`kernel` |KernelConfig |Configures the kernel.
Show example(s){{< highlight yaml >}} +|`kernel` |KernelConfig |Configures the kernel.
Show example(s){{< highlight yaml >}} kernel: # Kernel modules to load. modules: - name: brtfs # Module name. {{< /highlight >}}
| | -|`seccompProfiles` |[]MachineSeccompProfile |Configures the seccomp profiles for the machine.
Show example(s){{< highlight yaml >}} +|`seccompProfiles` |[]MachineSeccompProfile |Configures the seccomp profiles for the machine.
Show example(s){{< highlight yaml >}} seccompProfiles: - name: audit.json # The `name` field is used to provide the file name of the seccomp profile. # The `value` field is used to provide the seccomp profile. @@ -440,411 +428,123 @@ nodeTaints: ---- -## MachineSeccompProfile -MachineSeccompProfile defines seccomp profiles for the machine. -Appears in: +### controlPlane {#Config.machine.controlPlane} -- MachineConfig.seccompProfiles +MachineControlPlaneConfig machine specific configuration options. {{< highlight yaml >}} -- name: audit.json # The `name` field is used to provide the file name of the seccomp profile. - # The `value` field is used to provide the seccomp profile. - value: - defaultAction: SCMP_ACT_LOG +machine: + controlPlane: + # Controller manager machine specific configuration options. + controllerManager: + disabled: false # Disable kube-controller-manager on the node. + # Scheduler machine specific configuration options. + scheduler: + disabled: true # Disable kube-scheduler on the node. {{< /highlight >}} | Field | Type | Description | Value(s) | |-------|------|-------------|----------| -|`name` |string |The `name` field is used to provide the file name of the seccomp profile. | | -|`value` |Unstructured |The `value` field is used to provide the seccomp profile. | | +|`controllerManager` |MachineControllerManagerConfig |Controller manager machine specific configuration options. | | +|`scheduler` |MachineSchedulerConfig |Scheduler machine specific configuration options. | | ---- -## ClusterConfig -ClusterConfig represents the cluster-wide config values. -Appears in: - -- Config.cluster +#### controllerManager {#Config.machine.controlPlane.controllerManager} +MachineControllerManagerConfig represents the machine specific ControllerManager config values. -{{< highlight yaml >}} -# ControlPlaneConfig represents the control plane configuration options. -controlPlane: - endpoint: https://1.2.3.4 # Endpoint is the canonical controlplane endpoint, which can be an IP address or a DNS hostname. - localAPIServerPort: 443 # The port that the API server listens on internally. -clusterName: talos.local -# ClusterNetworkConfig represents kube networking configuration options. -network: - # The CNI used. - cni: - name: flannel # Name of CNI to use. - dnsDomain: cluster.local # The domain used by Kubernetes DNS. - # The pod subnet CIDR. - podSubnets: - - 10.244.0.0/16 - # The service subnet CIDR. - serviceSubnets: - - 10.96.0.0/12 -{{< /highlight >}} | Field | Type | Description | Value(s) | |-------|------|-------------|----------| -|`id` |string |Globally unique identifier for this cluster (base64 encoded random 32 bytes). | | -|`secret` |string |
Shared secret of cluster (base64 encoded random 32 bytes).This secret is shared among cluster members but should never be sent over the network.
| | -|`controlPlane` |ControlPlaneConfig |Provides control plane specific configuration options.
Show example(s){{< highlight yaml >}} -controlPlane: - endpoint: https://1.2.3.4 # Endpoint is the canonical controlplane endpoint, which can be an IP address or a DNS hostname. - localAPIServerPort: 443 # The port that the API server listens on internally. -{{< /highlight >}}
| | -|`clusterName` |string |Configures the cluster's name. | | -|`network` |ClusterNetworkConfig |Provides cluster specific network configuration options.
Show example(s){{< highlight yaml >}} -network: - # The CNI used. - cni: - name: flannel # Name of CNI to use. - dnsDomain: cluster.local # The domain used by Kubernetes DNS. - # The pod subnet CIDR. - podSubnets: - - 10.244.0.0/16 - # The service subnet CIDR. - serviceSubnets: - - 10.96.0.0/12 -{{< /highlight >}}
| | -|`token` |string |The [bootstrap token](https://kubernetes.io/docs/reference/access-authn-authz/bootstrap-tokens/) used to join the cluster.
Show example(s){{< highlight yaml >}} -token: wlzjyw.bei2zfylhs2by0wd -{{< /highlight >}}
| | -|`aescbcEncryptionSecret` |string |
A key used for the [encryption of secret data at rest](https://kubernetes.io/docs/tasks/administer-cluster/encrypt-data/).Enables encryption with AESCBC.
Show example(s){{< highlight yaml >}} -aescbcEncryptionSecret: z01mye6j16bspJYtTB/5SFX8j7Ph4JXxM2Xuu4vsBPM= -{{< /highlight >}}
| | -|`secretboxEncryptionSecret` |string |
A key used for the [encryption of secret data at rest](https://kubernetes.io/docs/tasks/administer-cluster/encrypt-data/).Enables encryption with secretbox.
Secretbox has precedence over AESCBC.
Show example(s){{< highlight yaml >}} -secretboxEncryptionSecret: z01mye6j16bspJYtTB/5SFX8j7Ph4JXxM2Xuu4vsBPM= -{{< /highlight >}}
| | -|`ca` |PEMEncodedCertificateAndKey |The base64 encoded root certificate authority used by Kubernetes.
Show example(s){{< highlight yaml >}} -ca: - crt: LS0tIEVYQU1QTEUgQ0VSVElGSUNBVEUgLS0t - key: LS0tIEVYQU1QTEUgS0VZIC0tLQ== -{{< /highlight >}}
| | -|`aggregatorCA` |PEMEncodedCertificateAndKey |
The base64 encoded aggregator certificate authority used by Kubernetes for front-proxy certificate generation.
This CA can be self-signed.
Show example(s){{< highlight yaml >}} -aggregatorCA: - crt: LS0tIEVYQU1QTEUgQ0VSVElGSUNBVEUgLS0t - key: LS0tIEVYQU1QTEUgS0VZIC0tLQ== -{{< /highlight >}}
| | -|`serviceAccount` |PEMEncodedKey |The base64 encoded private key for service account token generation.
Show example(s){{< highlight yaml >}} -serviceAccount: - key: LS0tIEVYQU1QTEUgS0VZIC0tLQ== -{{< /highlight >}}
| | -|`apiServer` |APIServerConfig |API server specific configuration options.
Show example(s){{< highlight yaml >}} -apiServer: - image: registry.k8s.io/kube-apiserver:v1.29.0-rc.1 # The container image used in the API server manifest. - # Extra arguments to supply to the API server. - extraArgs: - feature-gates: ServerSideApply=true - http2-max-streams-per-connection: "32" - # Extra certificate subject alternative names for the API server's certificate. - certSANs: - - 1.2.3.4 - - 4.5.6.7 - - # # Configure the API server admission plugins. - # admissionControl: - # - name: PodSecurity # Name is the name of the admission controller. - # # Configuration is an embedded configuration object to be used as the plugin's - # configuration: - # apiVersion: pod-security.admission.config.k8s.io/v1alpha1 - # defaults: - # audit: restricted - # audit-version: latest - # enforce: baseline - # enforce-version: latest - # warn: restricted - # warn-version: latest - # exemptions: - # namespaces: - # - kube-system - # runtimeClasses: [] - # usernames: [] - # kind: PodSecurityConfiguration - - # # Configure the API server audit policy. - # auditPolicy: - # apiVersion: audit.k8s.io/v1 - # kind: Policy - # rules: - # - level: Metadata -{{< /highlight >}}
| | -|`controllerManager` |ControllerManagerConfig |Controller manager server specific configuration options.
Show example(s){{< highlight yaml >}} -controllerManager: - image: registry.k8s.io/kube-controller-manager:v1.29.0-rc.1 # The container image used in the controller manager manifest. - # Extra arguments to supply to the controller manager. - extraArgs: - feature-gates: ServerSideApply=true -{{< /highlight >}}
| | -|`proxy` |ProxyConfig |Kube-proxy server-specific configuration options
Show example(s){{< highlight yaml >}} -proxy: - image: registry.k8s.io/kube-proxy:v1.29.0-rc.1 # The container image used in the kube-proxy manifest. - mode: ipvs # proxy mode of kube-proxy. - # Extra arguments to supply to kube-proxy. - extraArgs: - proxy-mode: iptables +|`disabled` |bool |Disable kube-controller-manager on the node. | | - # # Disable kube-proxy deployment on cluster bootstrap. - # disabled: false -{{< /highlight >}}
| | -|`scheduler` |SchedulerConfig |Scheduler server specific configuration options.
Show example(s){{< highlight yaml >}} -scheduler: - image: registry.k8s.io/kube-scheduler:v1.29.0-rc.1 # The container image used in the scheduler manifest. - # Extra arguments to supply to the scheduler. - extraArgs: - feature-gates: AllBeta=true -{{< /highlight >}}
| | -|`discovery` |ClusterDiscoveryConfig |Configures cluster member discovery.
Show example(s){{< highlight yaml >}} -discovery: - enabled: true # Enable the cluster membership discovery feature. - # Configure registries used for cluster member discovery. - registries: - # Kubernetes registry uses Kubernetes API server to discover cluster members and stores additional information - kubernetes: {} - # Service registry is using an external service to push and pull information about cluster members. - service: - endpoint: https://discovery.talos.dev/ # External service endpoint. -{{< /highlight >}}
| | -|`etcd` |EtcdConfig |Etcd specific configuration options.
Show example(s){{< highlight yaml >}} -etcd: - image: gcr.io/etcd-development/etcd:v3.5.11 # The container image used to create the etcd service. - # The `ca` is the root certificate authority of the PKI. - ca: - crt: LS0tIEVYQU1QTEUgQ0VSVElGSUNBVEUgLS0t - key: LS0tIEVYQU1QTEUgS0VZIC0tLQ== - # Extra arguments to supply to etcd. - extraArgs: - election-timeout: "5000" - # # The `advertisedSubnets` field configures the networks to pick etcd advertised IP from. - # advertisedSubnets: - # - 10.0.0.0/8 -{{< /highlight >}}
| | -|`coreDNS` |CoreDNS |Core DNS specific configuration options.
Show example(s){{< highlight yaml >}} -coreDNS: - image: registry.k8s.io/coredns/coredns:v1.11.1 # The `image` field is an override to the default coredns image. -{{< /highlight >}}
| | -|`externalCloudProvider` |ExternalCloudProviderConfig |External cloud provider configuration.
Show example(s){{< highlight yaml >}} -externalCloudProvider: - enabled: true # Enable external cloud provider. - # A list of urls that point to additional manifests for an external cloud provider. - manifests: - - https://raw.githubusercontent.com/kubernetes/cloud-provider-aws/v1.20.0-alpha.0/manifests/rbac.yaml - - https://raw.githubusercontent.com/kubernetes/cloud-provider-aws/v1.20.0-alpha.0/manifests/aws-cloud-controller-manager-daemonset.yaml -{{< /highlight >}}
| | -|`extraManifests` |[]string |
A list of urls that point to additional manifests.These will get automatically deployed as part of the bootstrap.
Show example(s){{< highlight yaml >}} -extraManifests: - - https://www.example.com/manifest1.yaml - - https://www.example.com/manifest2.yaml -{{< /highlight >}}
| | -|`extraManifestHeaders` |map[string]string |A map of key value pairs that will be added while fetching the extraManifests.
Show example(s){{< highlight yaml >}} -extraManifestHeaders: - Token: "1234567" - X-ExtraInfo: info -{{< /highlight >}}
| | -|`inlineManifests` |ClusterInlineManifests |
A list of inline Kubernetes manifests.These will get automatically deployed as part of the bootstrap.
Show example(s){{< highlight yaml >}} -inlineManifests: - - name: namespace-ci # Name of the manifest. - contents: |- # Manifest contents as a string. - apiVersion: v1 - kind: Namespace - metadata: - name: ci -{{< /highlight >}}
| | -|`adminKubeconfig` |AdminKubeconfigConfig |
Settings for admin kubeconfig generation.Certificate lifetime can be configured.
Show example(s){{< highlight yaml >}} -adminKubeconfig: - certLifetime: 1h0m0s # Admin kubeconfig certificate lifetime (default is 1 year). -{{< /highlight >}}
| | -|`allowSchedulingOnControlPlanes` |bool |Allows running workload on control-plane nodes.
Show example(s){{< highlight yaml >}} -allowSchedulingOnControlPlanes: true -{{< /highlight >}}
|`true`
`yes`
`false`
`no`
| ---- -## LinuxIDMapping -LinuxIDMapping represents the Linux ID mapping. -Appears in: +#### scheduler {#Config.machine.controlPlane.scheduler} -- ExtraMount.uidMappings -- ExtraMount.gidMappings +MachineSchedulerConfig represents the machine specific Scheduler config values. | Field | Type | Description | Value(s) | |-------|------|-------------|----------| -|`containerID` |uint32 |ContainerID is the starting UID/GID in the container. | | -|`hostID` |uint32 |HostID is the starting UID/GID on the host to be mapped to 'ContainerID'. | | -|`size` |uint32 |Size is the number of IDs to be mapped. | | - - - ---- -## ExtraMount -ExtraMount wraps OCI Mount specification. - -Appears in: - -- KubeletConfig.extraMounts - +|`disabled` |bool |Disable kube-scheduler on the node. | | -{{< highlight yaml >}} -- destination: /var/lib/example # Destination is the absolute path where the mount will be placed in the container. - type: bind # Type specifies the mount kind. - source: /var/lib/example # Source specifies the source path of the mount. - # Options are fstab style mount options. - options: - - bind - - rshared - - rw -{{< /highlight >}} -| Field | Type | Description | Value(s) | -|-------|------|-------------|----------| -|`destination` |string |Destination is the absolute path where the mount will be placed in the container. | | -|`type` |string |Type specifies the mount kind. | | -|`source` |string |Source specifies the source path of the mount. | | -|`options` |[]string |Options are fstab style mount options. | | -|`uidMappings` |[]LinuxIDMapping |
UID/GID mappings used for changing file owners w/o calling chown, fs should support it.
Every mount point could have its own mapping.
| | -|`gidMappings` |[]LinuxIDMapping |
UID/GID mappings used for changing file owners w/o calling chown, fs should support it.
Every mount point could have its own mapping.
| | ---- -## MachineControlPlaneConfig -MachineControlPlaneConfig machine specific configuration options. -Appears in: +### kubelet {#Config.machine.kubelet} -- MachineConfig.controlPlane +KubeletConfig represents the kubelet config values. {{< highlight yaml >}} -# Controller manager machine specific configuration options. -controllerManager: - disabled: false # Disable kube-controller-manager on the node. -# Scheduler machine specific configuration options. -scheduler: - disabled: true # Disable kube-scheduler on the node. -{{< /highlight >}} - - -| Field | Type | Description | Value(s) | -|-------|------|-------------|----------| -|`controllerManager` |MachineControllerManagerConfig |Controller manager machine specific configuration options. | | -|`scheduler` |MachineSchedulerConfig |Scheduler machine specific configuration options. | | - - - ---- -## MachineControllerManagerConfig -MachineControllerManagerConfig represents the machine specific ControllerManager config values. - -Appears in: - -- MachineControlPlaneConfig.controllerManager - - - - -| Field | Type | Description | Value(s) | -|-------|------|-------------|----------| -|`disabled` |bool |Disable kube-controller-manager on the node. | | - - - ---- -## MachineSchedulerConfig -MachineSchedulerConfig represents the machine specific Scheduler config values. - -Appears in: - -- MachineControlPlaneConfig.scheduler - - - - -| Field | Type | Description | Value(s) | -|-------|------|-------------|----------| -|`disabled` |bool |Disable kube-scheduler on the node. | | - - - ---- -## KubeletConfig -KubeletConfig represents the kubelet config values. - -Appears in: - -- MachineConfig.kubelet - - - -{{< highlight yaml >}} -image: ghcr.io/siderolabs/kubelet:v1.29.0-rc.1 # The `image` field is an optional reference to an alternative kubelet image. -# The `extraArgs` field is used to provide additional flags to the kubelet. -extraArgs: - feature-gates: ServerSideApply=true - -# # The `ClusterDNS` field is an optional reference to an alternative kubelet clusterDNS ip list. -# clusterDNS: -# - 10.96.0.10 -# - 169.254.2.53 - -# # The `extraMounts` field is used to add additional mounts to the kubelet container. -# extraMounts: -# - destination: /var/lib/example # Destination is the absolute path where the mount will be placed in the container. -# type: bind # Type specifies the mount kind. -# source: /var/lib/example # Source specifies the source path of the mount. -# # Options are fstab style mount options. -# options: -# - bind -# - rshared -# - rw - -# # The `extraConfig` field is used to provide kubelet configuration overrides. -# extraConfig: -# serverTLSBootstrap: true - -# # The `KubeletCredentialProviderConfig` field is used to provide kubelet credential configuration. -# credentialProviderConfig: -# apiVersion: kubelet.config.k8s.io/v1 -# kind: CredentialProviderConfig -# providers: -# - apiVersion: credentialprovider.kubelet.k8s.io/v1 -# defaultCacheDuration: 12h -# matchImages: -# - '*.dkr.ecr.*.amazonaws.com' -# - '*.dkr.ecr.*.amazonaws.com.cn' -# - '*.dkr.ecr-fips.*.amazonaws.com' -# - '*.dkr.ecr.us-iso-east-1.c2s.ic.gov' -# - '*.dkr.ecr.us-isob-east-1.sc2s.sgov.gov' -# name: ecr-credential-provider - -# # The `nodeIP` field is used to configure `--node-ip` flag for the kubelet. -# nodeIP: -# # The `validSubnets` field configures the networks to pick kubelet node IP from. -# validSubnets: -# - 10.0.0.0/8 -# - '!10.0.0.3/32' -# - fdc7::/16 +machine: + kubelet: + image: ghcr.io/siderolabs/kubelet:v1.29.0-rc.1 # The `image` field is an optional reference to an alternative kubelet image. + # The `extraArgs` field is used to provide additional flags to the kubelet. + extraArgs: + feature-gates: ServerSideApply=true + + # # The `ClusterDNS` field is an optional reference to an alternative kubelet clusterDNS ip list. + # clusterDNS: + # - 10.96.0.10 + # - 169.254.2.53 + + # # The `extraMounts` field is used to add additional mounts to the kubelet container. + # extraMounts: + # - destination: /var/lib/example # Destination is the absolute path where the mount will be placed in the container. + # type: bind # Type specifies the mount kind. + # source: /var/lib/example # Source specifies the source path of the mount. + # # Options are fstab style mount options. + # options: + # - bind + # - rshared + # - rw + + # # The `extraConfig` field is used to provide kubelet configuration overrides. + # extraConfig: + # serverTLSBootstrap: true + + # # The `KubeletCredentialProviderConfig` field is used to provide kubelet credential configuration. + # credentialProviderConfig: + # apiVersion: kubelet.config.k8s.io/v1 + # kind: CredentialProviderConfig + # providers: + # - apiVersion: credentialprovider.kubelet.k8s.io/v1 + # defaultCacheDuration: 12h + # matchImages: + # - '*.dkr.ecr.*.amazonaws.com' + # - '*.dkr.ecr.*.amazonaws.com.cn' + # - '*.dkr.ecr-fips.*.amazonaws.com' + # - '*.dkr.ecr.us-iso-east-1.c2s.ic.gov' + # - '*.dkr.ecr.us-isob-east-1.sc2s.sgov.gov' + # name: ecr-credential-provider + + # # The `nodeIP` field is used to configure `--node-ip` flag for the kubelet. + # nodeIP: + # # The `validSubnets` field configures the networks to pick kubelet node IP from. + # validSubnets: + # - 10.0.0.0/8 + # - '!10.0.0.3/32' + # - fdc7::/16 {{< /highlight >}} @@ -862,7 +562,7 @@ clusterDNS: extraArgs: key: value {{< /highlight >}}
| | -|`extraMounts` |[]ExtraMount |
The `extraMounts` field is used to add additional mounts to the kubelet container.Note that either `bind` or `rbind` are required in the `options`.
Show example(s){{< highlight yaml >}} +|`extraMounts` |[]ExtraMount |
The `extraMounts` field is used to add additional mounts to the kubelet container.Note that either `bind` or `rbind` are required in the `options`.
Show example(s){{< highlight yaml >}} extraMounts: - destination: /var/lib/example # Destination is the absolute path where the mount will be placed in the container. type: bind # Type specifies the mount kind. @@ -894,7 +594,7 @@ credentialProviderConfig: {{< /highlight >}}
| | |`defaultRuntimeSeccompProfileEnabled` |bool |Enable container runtime default Seccomp profile. |`true`
`yes`
`false`
`no`
| |`registerWithFQDN` |bool |
The `registerWithFQDN` field is used to force kubelet to use the node FQDN for registration.This is required in clouds like AWS.
|`true`
`yes`
`false`
`no`
| -|`nodeIP` |KubeletNodeIPConfig |
The `nodeIP` field is used to configure `--node-ip` flag for the kubelet.This is used when a node has multiple addresses to choose from.
Show example(s){{< highlight yaml >}} +|`nodeIP` |KubeletNodeIPConfig |
The `nodeIP` field is used to configure `--node-ip` flag for the kubelet.This is used when a node has multiple addresses to choose from.
Show example(s){{< highlight yaml >}} nodeIP: # The `validSubnets` field configures the networks to pick kubelet node IP from. validSubnets: @@ -907,155 +607,229 @@ nodeIP: ---- -## KubeletNodeIPConfig -KubeletNodeIPConfig represents the kubelet node IP configuration. -Appears in: +#### extraMounts[] {#Config.machine.kubelet.extraMounts.} -- KubeletConfig.nodeIP +ExtraMount wraps OCI Mount specification. {{< highlight yaml >}} -# The `validSubnets` field configures the networks to pick kubelet node IP from. -validSubnets: - - 10.0.0.0/8 - - '!10.0.0.3/32' - - fdc7::/16 +machine: + kubelet: + extraMounts: + - destination: /var/lib/example # Destination is the absolute path where the mount will be placed in the container. + type: bind # Type specifies the mount kind. + source: /var/lib/example # Source specifies the source path of the mount. + # Options are fstab style mount options. + options: + - bind + - rshared + - rw {{< /highlight >}} | Field | Type | Description | Value(s) | |-------|------|-------------|----------| -|`validSubnets` |[]string |
The `validSubnets` field configures the networks to pick kubelet node IP from.For dual stack configuration, there should be two subnets: one for IPv4, another for IPv6.
IPs can be excluded from the list by using negative match with `!`, e.g `!10.0.0.0/8`.
Negative subnet matches should be specified last to filter out IPs picked by positive matches.
If not specified, node IP is picked based on cluster podCIDRs: IPv4/IPv6 address or both.
| | +|`destination` |string |Destination is the absolute path where the mount will be placed in the container. | | +|`type` |string |Type specifies the mount kind. | | +|`source` |string |Source specifies the source path of the mount. | | +|`options` |[]string |Options are fstab style mount options. | | +|`uidMappings` |[]LinuxIDMapping |
UID/GID mappings used for changing file owners w/o calling chown, fs should support it.
Every mount point could have its own mapping.
| | +|`gidMappings` |[]LinuxIDMapping |
UID/GID mappings used for changing file owners w/o calling chown, fs should support it.
Every mount point could have its own mapping.
| | ---- -## NetworkConfig -NetworkConfig represents the machine's networking config values. -Appears in: +##### uidMappings[] {#Config.machine.kubelet.extraMounts..uidMappings.} + +LinuxIDMapping represents the Linux ID mapping. + + + + +| Field | Type | Description | Value(s) | +|-------|------|-------------|----------| +|`containerID` |uint32 |ContainerID is the starting UID/GID in the container. | | +|`hostID` |uint32 |HostID is the starting UID/GID on the host to be mapped to 'ContainerID'. | | +|`size` |uint32 |Size is the number of IDs to be mapped. | | + + + + + + +##### gidMappings[] {#Config.machine.kubelet.extraMounts..gidMappings.} + +LinuxIDMapping represents the Linux ID mapping. + + + + +| Field | Type | Description | Value(s) | +|-------|------|-------------|----------| +|`containerID` |uint32 |ContainerID is the starting UID/GID in the container. | | +|`hostID` |uint32 |HostID is the starting UID/GID on the host to be mapped to 'ContainerID'. | | +|`size` |uint32 |Size is the number of IDs to be mapped. | | + -- MachineConfig.network + + + + + + +#### nodeIP {#Config.machine.kubelet.nodeIP} + +KubeletNodeIPConfig represents the kubelet node IP configuration. {{< highlight yaml >}} -hostname: worker-1 # Used to statically set the hostname for the machine. -# `interfaces` is used to define the network interface configuration. -interfaces: - - interface: enp0s1 # The interface name. - # Assigns static IP addresses to the interface. - addresses: - - 192.168.2.0/24 - # A list of routes associated with the interface. - routes: - - network: 0.0.0.0/0 # The route's network (destination). - gateway: 192.168.2.1 # The route's gateway (if empty, creates link scope route). - metric: 1024 # The optional metric for the route. - mtu: 1500 # The interface's MTU. +machine: + kubelet: + nodeIP: + # The `validSubnets` field configures the networks to pick kubelet node IP from. + validSubnets: + - 10.0.0.0/8 + - '!10.0.0.3/32' + - fdc7::/16 +{{< /highlight >}} - # # Picks a network device using the selector. - # # select a device with bus prefix 00:*. - # deviceSelector: - # busPath: 00:* # PCI, USB bus prefix, supports matching by wildcard. - # # select a device with mac address matching `*:f0:ab` and `virtio` kernel driver. - # deviceSelector: - # hardwareAddr: '*:f0:ab' # Device hardware address, supports matching by wildcard. - # driver: virtio # Kernel driver, supports matching by wildcard. - # # select a device with bus prefix 00:*, a device with mac address matching `*:f0:ab` and `virtio` kernel driver. - # deviceSelector: - # - busPath: 00:* # PCI, USB bus prefix, supports matching by wildcard. - # - hardwareAddr: '*:f0:ab' # Device hardware address, supports matching by wildcard. - # driver: virtio # Kernel driver, supports matching by wildcard. +| Field | Type | Description | Value(s) | +|-------|------|-------------|----------| +|`validSubnets` |[]string |
The `validSubnets` field configures the networks to pick kubelet node IP from.For dual stack configuration, there should be two subnets: one for IPv4, another for IPv6.
IPs can be excluded from the list by using negative match with `!`, e.g `!10.0.0.0/8`.
Negative subnet matches should be specified last to filter out IPs picked by positive matches.
If not specified, node IP is picked based on cluster podCIDRs: IPv4/IPv6 address or both.
| | - # # Bond specific options. - # bond: - # # The interfaces that make up the bond. - # interfaces: - # - enp2s0 - # - enp2s1 - # # Picks a network device using the selector. - # deviceSelectors: - # - busPath: 00:* # PCI, USB bus prefix, supports matching by wildcard. - # - hardwareAddr: '*:f0:ab' # Device hardware address, supports matching by wildcard. - # driver: virtio # Kernel driver, supports matching by wildcard. - # mode: 802.3ad # A bond option. - # lacpRate: fast # A bond option. - # # Bridge specific options. - # bridge: - # # The interfaces that make up the bridge. - # interfaces: - # - enxda4042ca9a51 - # - enxae2a6774c259 - # # A bridge option. - # stp: - # enabled: true # Whether Spanning Tree Protocol (STP) is enabled. - # # Indicates if DHCP should be used to configure the interface. - # dhcp: true - # # DHCP specific options. - # dhcpOptions: - # routeMetric: 1024 # The priority of all routes received via DHCP. - # # Wireguard specific configuration. - # # wireguard server example - # wireguard: - # privateKey: ABCDEF... # Specifies a private key configuration (base64 encoded). - # listenPort: 51111 # Specifies a device's listening port. - # # Specifies a list of peer configurations to apply to a device. - # peers: - # - publicKey: ABCDEF... # Specifies the public key of this peer. - # endpoint: 192.168.1.3 # Specifies the endpoint of this peer entry. - # # AllowedIPs specifies a list of allowed IP addresses in CIDR notation for this peer. - # allowedIPs: - # - 192.168.1.0/24 - # # wireguard peer example - # wireguard: - # privateKey: ABCDEF... # Specifies a private key configuration (base64 encoded). - # # Specifies a list of peer configurations to apply to a device. - # peers: - # - publicKey: ABCDEF... # Specifies the public key of this peer. - # endpoint: 192.168.1.2:51822 # Specifies the endpoint of this peer entry. - # persistentKeepaliveInterval: 10s # Specifies the persistent keepalive interval for this peer. - # # AllowedIPs specifies a list of allowed IP addresses in CIDR notation for this peer. - # allowedIPs: - # - 192.168.1.0/24 - # # Virtual (shared) IP address configuration. - # # layer2 vip example - # vip: - # ip: 172.16.199.55 # Specifies the IP address to be used. -# Used to statically set the nameservers for the machine. -nameservers: - - 9.8.7.6 - - 8.7.6.5 +### network {#Config.machine.network} + +NetworkConfig represents the machine's networking config values. + -# # Allows for extra entries to be added to the `/etc/hosts` file -# extraHostEntries: -# - ip: 192.168.1.100 # The IP of the host. -# # The host alias. -# aliases: -# - example -# - example.domain.tld -# # Configures KubeSpan feature. -# kubespan: -# enabled: true # Enable the KubeSpan feature. +{{< highlight yaml >}} +machine: + network: + hostname: worker-1 # Used to statically set the hostname for the machine. + # `interfaces` is used to define the network interface configuration. + interfaces: + - interface: enp0s1 # The interface name. + # Assigns static IP addresses to the interface. + addresses: + - 192.168.2.0/24 + # A list of routes associated with the interface. + routes: + - network: 0.0.0.0/0 # The route's network (destination). + gateway: 192.168.2.1 # The route's gateway (if empty, creates link scope route). + metric: 1024 # The optional metric for the route. + mtu: 1500 # The interface's MTU. + + # # Picks a network device using the selector. + + # # select a device with bus prefix 00:*. + # deviceSelector: + # busPath: 00:* # PCI, USB bus prefix, supports matching by wildcard. + # # select a device with mac address matching `*:f0:ab` and `virtio` kernel driver. + # deviceSelector: + # hardwareAddr: '*:f0:ab' # Device hardware address, supports matching by wildcard. + # driver: virtio # Kernel driver, supports matching by wildcard. + # # select a device with bus prefix 00:*, a device with mac address matching `*:f0:ab` and `virtio` kernel driver. + # deviceSelector: + # - busPath: 00:* # PCI, USB bus prefix, supports matching by wildcard. + # - hardwareAddr: '*:f0:ab' # Device hardware address, supports matching by wildcard. + # driver: virtio # Kernel driver, supports matching by wildcard. + + # # Bond specific options. + # bond: + # # The interfaces that make up the bond. + # interfaces: + # - enp2s0 + # - enp2s1 + # # Picks a network device using the selector. + # deviceSelectors: + # - busPath: 00:* # PCI, USB bus prefix, supports matching by wildcard. + # - hardwareAddr: '*:f0:ab' # Device hardware address, supports matching by wildcard. + # driver: virtio # Kernel driver, supports matching by wildcard. + # mode: 802.3ad # A bond option. + # lacpRate: fast # A bond option. + + # # Bridge specific options. + # bridge: + # # The interfaces that make up the bridge. + # interfaces: + # - enxda4042ca9a51 + # - enxae2a6774c259 + # # A bridge option. + # stp: + # enabled: true # Whether Spanning Tree Protocol (STP) is enabled. + + # # Indicates if DHCP should be used to configure the interface. + # dhcp: true + + # # DHCP specific options. + # dhcpOptions: + # routeMetric: 1024 # The priority of all routes received via DHCP. + + # # Wireguard specific configuration. + + # # wireguard server example + # wireguard: + # privateKey: ABCDEF... # Specifies a private key configuration (base64 encoded). + # listenPort: 51111 # Specifies a device's listening port. + # # Specifies a list of peer configurations to apply to a device. + # peers: + # - publicKey: ABCDEF... # Specifies the public key of this peer. + # endpoint: 192.168.1.3 # Specifies the endpoint of this peer entry. + # # AllowedIPs specifies a list of allowed IP addresses in CIDR notation for this peer. + # allowedIPs: + # - 192.168.1.0/24 + # # wireguard peer example + # wireguard: + # privateKey: ABCDEF... # Specifies a private key configuration (base64 encoded). + # # Specifies a list of peer configurations to apply to a device. + # peers: + # - publicKey: ABCDEF... # Specifies the public key of this peer. + # endpoint: 192.168.1.2:51822 # Specifies the endpoint of this peer entry. + # persistentKeepaliveInterval: 10s # Specifies the persistent keepalive interval for this peer. + # # AllowedIPs specifies a list of allowed IP addresses in CIDR notation for this peer. + # allowedIPs: + # - 192.168.1.0/24 + + # # Virtual (shared) IP address configuration. + + # # layer2 vip example + # vip: + # ip: 172.16.199.55 # Specifies the IP address to be used. + # Used to statically set the nameservers for the machine. + nameservers: + - 9.8.7.6 + - 8.7.6.5 + + # # Allows for extra entries to be added to the `/etc/hosts` file + # extraHostEntries: + # - ip: 192.168.1.100 # The IP of the host. + # # The host alias. + # aliases: + # - example + # - example.domain.tld + + # # Configures KubeSpan feature. + # kubespan: + # enabled: true # Enable the KubeSpan feature. {{< /highlight >}} | Field | Type | Description | Value(s) | |-------|------|-------------|----------| |`hostname` |string |Used to statically set the hostname for the machine. | | -|`interfaces` |[]Device |
`interfaces` is used to define the network interface configuration.By default all network interfaces will attempt a DHCP discovery.
This can be further tuned through this configuration parameter.
Show example(s){{< highlight yaml >}} +|`interfaces` |[]Device |
`interfaces` is used to define the network interface configuration.By default all network interfaces will attempt a DHCP discovery.
This can be further tuned through this configuration parameter.
Show example(s){{< highlight yaml >}} interfaces: - interface: enp0s1 # The interface name. # Assigns static IP addresses to the interface. @@ -1150,7 +924,7 @@ nameservers: - 8.8.8.8 - 1.1.1.1 {{< /highlight >}}
| | -|`extraHostEntries` |[]ExtraHost |Allows for extra entries to be added to the `/etc/hosts` file
Show example(s){{< highlight yaml >}} +|`extraHostEntries` |[]ExtraHost |Allows for extra entries to be added to the `/etc/hosts` file
Show example(s){{< highlight yaml >}} extraHostEntries: - ip: 192.168.1.100 # The IP of the host. # The host alias. @@ -1158,7 +932,7 @@ extraHostEntries: - example - example.domain.tld {{< /highlight >}}
| | -|`kubespan` |NetworkKubeSpan |Configures KubeSpan feature.
Show example(s){{< highlight yaml >}} +|`kubespan` |NetworkKubeSpan |Configures KubeSpan feature.
Show example(s){{< highlight yaml >}} kubespan: enabled: true # Enable the KubeSpan feature. {{< /highlight >}}
| | @@ -1166,1782 +940,2429 @@ kubespan: ---- -## InstallConfig -InstallConfig represents the installation options for preparing a node. -Appears in: +#### interfaces[] {#Config.machine.network.interfaces.} -- MachineConfig.install +Device represents a network interface. {{< highlight yaml >}} -disk: /dev/sda # The disk used for installations. -# Allows for supplying extra kernel args via the bootloader. -extraKernelArgs: - - console=ttyS1 - - panic=10 -image: ghcr.io/siderolabs/installer:latest # Allows for supplying the image used to perform the installation. -wipe: false # Indicates if the installation disk should be wiped at installation time. - -# # Look up disk using disk attributes like model, size, serial and others. -# diskSelector: -# size: 4GB # Disk size. -# model: WDC* # Disk model `/sys/block//device/model`. -# busPath: /pci0000:00/0000:00:17.0/ata1/host0/target0:0:0/0:0:0:0 # Disk bus path. - -# # Allows for supplying additional system extension images to install on top of base Talos image. -# extensions: -# - image: ghcr.io/siderolabs/gvisor:20220117.0-v1.0.0 # System extension image. +machine: + network: + interfaces: + - interface: enp0s1 # The interface name. + # Assigns static IP addresses to the interface. + addresses: + - 192.168.2.0/24 + # A list of routes associated with the interface. + routes: + - network: 0.0.0.0/0 # The route's network (destination). + gateway: 192.168.2.1 # The route's gateway (if empty, creates link scope route). + metric: 1024 # The optional metric for the route. + mtu: 1500 # The interface's MTU. + + # # Picks a network device using the selector. + + # # select a device with bus prefix 00:*. + # deviceSelector: + # busPath: 00:* # PCI, USB bus prefix, supports matching by wildcard. + # # select a device with mac address matching `*:f0:ab` and `virtio` kernel driver. + # deviceSelector: + # hardwareAddr: '*:f0:ab' # Device hardware address, supports matching by wildcard. + # driver: virtio # Kernel driver, supports matching by wildcard. + # # select a device with bus prefix 00:*, a device with mac address matching `*:f0:ab` and `virtio` kernel driver. + # deviceSelector: + # - busPath: 00:* # PCI, USB bus prefix, supports matching by wildcard. + # - hardwareAddr: '*:f0:ab' # Device hardware address, supports matching by wildcard. + # driver: virtio # Kernel driver, supports matching by wildcard. + + # # Bond specific options. + # bond: + # # The interfaces that make up the bond. + # interfaces: + # - enp2s0 + # - enp2s1 + # # Picks a network device using the selector. + # deviceSelectors: + # - busPath: 00:* # PCI, USB bus prefix, supports matching by wildcard. + # - hardwareAddr: '*:f0:ab' # Device hardware address, supports matching by wildcard. + # driver: virtio # Kernel driver, supports matching by wildcard. + # mode: 802.3ad # A bond option. + # lacpRate: fast # A bond option. + + # # Bridge specific options. + # bridge: + # # The interfaces that make up the bridge. + # interfaces: + # - enxda4042ca9a51 + # - enxae2a6774c259 + # # A bridge option. + # stp: + # enabled: true # Whether Spanning Tree Protocol (STP) is enabled. + + # # Indicates if DHCP should be used to configure the interface. + # dhcp: true + + # # DHCP specific options. + # dhcpOptions: + # routeMetric: 1024 # The priority of all routes received via DHCP. + + # # Wireguard specific configuration. + + # # wireguard server example + # wireguard: + # privateKey: ABCDEF... # Specifies a private key configuration (base64 encoded). + # listenPort: 51111 # Specifies a device's listening port. + # # Specifies a list of peer configurations to apply to a device. + # peers: + # - publicKey: ABCDEF... # Specifies the public key of this peer. + # endpoint: 192.168.1.3 # Specifies the endpoint of this peer entry. + # # AllowedIPs specifies a list of allowed IP addresses in CIDR notation for this peer. + # allowedIPs: + # - 192.168.1.0/24 + # # wireguard peer example + # wireguard: + # privateKey: ABCDEF... # Specifies a private key configuration (base64 encoded). + # # Specifies a list of peer configurations to apply to a device. + # peers: + # - publicKey: ABCDEF... # Specifies the public key of this peer. + # endpoint: 192.168.1.2:51822 # Specifies the endpoint of this peer entry. + # persistentKeepaliveInterval: 10s # Specifies the persistent keepalive interval for this peer. + # # AllowedIPs specifies a list of allowed IP addresses in CIDR notation for this peer. + # allowedIPs: + # - 192.168.1.0/24 + + # # Virtual (shared) IP address configuration. + + # # layer2 vip example + # vip: + # ip: 172.16.199.55 # Specifies the IP address to be used. {{< /highlight >}} | Field | Type | Description | Value(s) | |-------|------|-------------|----------| -|`disk` |string |The disk used for installations.
Show example(s){{< highlight yaml >}} -disk: /dev/sda -{{< /highlight >}}{{< highlight yaml >}} -disk: /dev/nvme0 -{{< /highlight >}}
| | -|`diskSelector` |InstallDiskSelector |
Look up disk using disk attributes like model, size, serial and others.Always has priority over `disk`.
Show example(s){{< highlight yaml >}} -diskSelector: - size: '>= 1TB' # Disk size. - model: WDC* # Disk model `/sys/block//device/model`. - - # # Disk bus path. - # busPath: /pci0000:00/0000:00:17.0/ata1/host0/target0:0:0/0:0:0:0 - # busPath: /pci0000:00/* +|`interface` |string |
The interface name.Mutually exclusive with `deviceSelector`.
Show example(s){{< highlight yaml >}} +interface: enp0s3 {{< /highlight >}}
| | -|`extraKernelArgs` |[]string |
Allows for supplying extra kernel args via the bootloader.Existing kernel args can be removed by prefixing the argument with a `-`.
For example `-console` removes all `console=` arguments, whereas `-console=tty0` removes the `console=tty0` default argument.
Show example(s){{< highlight yaml >}} -extraKernelArgs: - - talos.platform=metal - - reboot=k +|`deviceSelector` |NetworkDeviceSelector |
Picks a network device using the selector.Mutually exclusive with `interface`.
Supports partial match using wildcard syntax.
Show example(s){{< highlight yaml >}} +deviceSelector: + busPath: 00:* # PCI, USB bus prefix, supports matching by wildcard. +{{< /highlight >}}{{< highlight yaml >}} +deviceSelector: + hardwareAddr: '*:f0:ab' # Device hardware address, supports matching by wildcard. + driver: virtio # Kernel driver, supports matching by wildcard. {{< /highlight >}}
| | -|`image` |string |
Allows for supplying the image used to perform the installation.Image reference for each Talos release can be found on
[GitHub releases page](https://github.com/siderolabs/talos/releases).
Show example(s){{< highlight yaml >}} -image: ghcr.io/siderolabs/installer:latest +|`addresses` |[]string |
Assigns static IP addresses to the interface.An address can be specified either in proper CIDR notation or as a standalone address (netmask of all ones is assumed).
Show example(s){{< highlight yaml >}} +addresses: + - 10.5.0.0/16 + - 192.168.3.7 {{< /highlight >}}
| | -|`extensions` |[]InstallExtensionConfig |Allows for supplying additional system extension images to install on top of base Talos image.
Show example(s){{< highlight yaml >}} -extensions: - - image: ghcr.io/siderolabs/gvisor:20220117.0-v1.0.0 # System extension image. +|`routes` |[]Route |
A list of routes associated with the interface.If used in combination with DHCP, these routes will be appended to routes returned by DHCP server.
Show example(s){{< highlight yaml >}} +routes: + - network: 0.0.0.0/0 # The route's network (destination). + gateway: 10.5.0.1 # The route's gateway (if empty, creates link scope route). + - network: 10.2.0.0/16 # The route's network (destination). + gateway: 10.2.0.1 # The route's gateway (if empty, creates link scope route). {{< /highlight >}}
| | -|`wipe` |bool |
Indicates if the installation disk should be wiped at installation time.Defaults to `true`.
|`true`
`yes`
`false`
`no`
| -|`legacyBIOSSupport` |bool |
Indicates if MBR partition should be marked as bootable (active).Should be enabled only for the systems with legacy BIOS that doesn't support GPT partitioning scheme.
| | - - - ---- -## InstallDiskSelector -InstallDiskSelector represents a disk query parameters for the install disk lookup. - -Appears in: - -- InstallConfig.diskSelector - - - -{{< highlight yaml >}} -size: '>= 1TB' # Disk size. -model: WDC* # Disk model `/sys/block//device/model`. - -# # Disk bus path. -# busPath: /pci0000:00/0000:00:17.0/ata1/host0/target0:0:0/0:0:0:0 -# busPath: /pci0000:00/* -{{< /highlight >}} +|`bond` |Bond |Bond specific options.
Show example(s){{< highlight yaml >}} +bond: + # The interfaces that make up the bond. + interfaces: + - enp2s0 + - enp2s1 + mode: 802.3ad # A bond option. + lacpRate: fast # A bond option. + # # Picks a network device using the selector. -| Field | Type | Description | Value(s) | -|-------|------|-------------|----------| -|`size` |InstallDiskSizeMatcher |Disk size.
Show example(s){{< highlight yaml >}} -size: 4GB -{{< /highlight >}}{{< highlight yaml >}} -size: '> 1TB' -{{< /highlight >}}{{< highlight yaml >}} -size: <= 2TB -{{< /highlight >}}
| | -|`name` |string |Disk name `/sys/block//device/name`. | | -|`model` |string |Disk model `/sys/block//device/model`. | | -|`serial` |string |Disk serial number `/sys/block//serial`. | | -|`modalias` |string |Disk modalias `/sys/block//device/modalias`. | | -|`uuid` |string |Disk UUID `/sys/block//uuid`. | | -|`wwid` |string |Disk WWID `/sys/block//wwid`. | | -|`type` |InstallDiskType |Disk Type. |`ssd`
`hdd`
`nvme`
`sd`
| -|`busPath` |string |Disk bus path.
Show example(s){{< highlight yaml >}} -busPath: /pci0000:00/0000:00:17.0/ata1/host0/target0:0:0/0:0:0:0 -{{< /highlight >}}{{< highlight yaml >}} -busPath: /pci0000:00/* + # # select a device with bus prefix 00:*, a device with mac address matching `*:f0:ab` and `virtio` kernel driver. + # deviceSelectors: + # - busPath: 00:* # PCI, USB bus prefix, supports matching by wildcard. + # - hardwareAddr: '*:f0:ab' # Device hardware address, supports matching by wildcard. + # driver: virtio # Kernel driver, supports matching by wildcard. {{< /highlight >}}
| | +|`bridge` |Bridge |Bridge specific options.
Show example(s){{< highlight yaml >}} +bridge: + # The interfaces that make up the bridge. + interfaces: + - enxda4042ca9a51 + - enxae2a6774c259 + # A bridge option. + stp: + enabled: true # Whether Spanning Tree Protocol (STP) is enabled. +{{< /highlight >}}
| | +|`vlans` |[]Vlan |VLAN specific options. | | +|`mtu` |int |
The interface's MTU.If used in combination with DHCP, this will override any MTU settings returned from DHCP server.
| | +|`dhcp` |bool |
Indicates if DHCP should be used to configure the interface.The following DHCP options are supported:

- `OptionClasslessStaticRoute`
- `OptionDomainNameServer`
- `OptionDNSDomainSearchList`
- `OptionHostName`
Show example(s){{< highlight yaml >}} +dhcp: true +{{< /highlight >}}
| | +|`ignore` |bool |Indicates if the interface should be ignored (skips configuration). | | +|`dummy` |bool |
Indicates if the interface is a dummy interface.`dummy` is used to specify that this interface should be a virtual-only, dummy interface.
| | +|`dhcpOptions` |DHCPOptions |
DHCP specific options.`dhcp` *must* be set to true for these to take effect.
Show example(s){{< highlight yaml >}} +dhcpOptions: + routeMetric: 1024 # The priority of all routes received via DHCP. +{{< /highlight >}}
| | +|`wireguard` |DeviceWireguardConfig |
Wireguard specific configuration.Includes things like private key, listen port, peers.
Show example(s){{< highlight yaml >}} +wireguard: + privateKey: ABCDEF... # Specifies a private key configuration (base64 encoded). + listenPort: 51111 # Specifies a device's listening port. + # Specifies a list of peer configurations to apply to a device. + peers: + - publicKey: ABCDEF... # Specifies the public key of this peer. + endpoint: 192.168.1.3 # Specifies the endpoint of this peer entry. + # AllowedIPs specifies a list of allowed IP addresses in CIDR notation for this peer. + allowedIPs: + - 192.168.1.0/24 +{{< /highlight >}}{{< highlight yaml >}} +wireguard: + privateKey: ABCDEF... # Specifies a private key configuration (base64 encoded). + # Specifies a list of peer configurations to apply to a device. + peers: + - publicKey: ABCDEF... # Specifies the public key of this peer. + endpoint: 192.168.1.2:51822 # Specifies the endpoint of this peer entry. + persistentKeepaliveInterval: 10s # Specifies the persistent keepalive interval for this peer. + # AllowedIPs specifies a list of allowed IP addresses in CIDR notation for this peer. + allowedIPs: + - 192.168.1.0/24 +{{< /highlight >}}
| | +|`vip` |DeviceVIPConfig |Virtual (shared) IP address configuration.
Show example(s){{< highlight yaml >}} +vip: + ip: 172.16.199.55 # Specifies the IP address to be used. +{{< /highlight >}}
| | + + + + +##### deviceSelector {#Config.machine.network.interfaces..deviceSelector} + +NetworkDeviceSelector struct describes network device selector. + +{{< highlight yaml >}} +machine: + network: + interfaces: + - deviceSelector: + busPath: 00:* # PCI, USB bus prefix, supports matching by wildcard. +{{< /highlight >}} ---- -## InstallExtensionConfig -InstallExtensionConfig represents a configuration for a system extension. - -Appears in: - -- InstallConfig.extensions - - +{{< highlight yaml >}} +machine: + network: + interfaces: + - deviceSelector: + hardwareAddr: '*:f0:ab' # Device hardware address, supports matching by wildcard. + driver: virtio # Kernel driver, supports matching by wildcard. +{{< /highlight >}} {{< highlight yaml >}} -- image: ghcr.io/siderolabs/gvisor:20220117.0-v1.0.0 # System extension image. +machine: + network: + interfaces: + - deviceSelector: + - busPath: 00:* # PCI, USB bus prefix, supports matching by wildcard. + - hardwareAddr: '*:f0:ab' # Device hardware address, supports matching by wildcard. + driver: virtio # Kernel driver, supports matching by wildcard. {{< /highlight >}} | Field | Type | Description | Value(s) | |-------|------|-------------|----------| -|`image` |string |System extension image. | | +|`busPath` |string |PCI, USB bus prefix, supports matching by wildcard. | | +|`hardwareAddr` |string |Device hardware address, supports matching by wildcard. | | +|`pciID` |string |PCI ID (vendor ID, product ID), supports matching by wildcard. | | +|`driver` |string |Kernel driver, supports matching by wildcard. | | + ---- -## TimeConfig -TimeConfig represents the options for configuring time on a machine. -Appears in: -- MachineConfig.time +##### routes[] {#Config.machine.network.interfaces..routes.} + +Route represents a network route. {{< highlight yaml >}} -disabled: false # Indicates if the time service is disabled for the machine. -# Specifies time (NTP) servers to use for setting the system time. -servers: - - time.cloudflare.com -bootTimeout: 2m0s # Specifies the timeout when the node time is considered to be in sync unlocking the boot sequence. +machine: + network: + interfaces: + - routes: + - network: 0.0.0.0/0 # The route's network (destination). + gateway: 10.5.0.1 # The route's gateway (if empty, creates link scope route). + - network: 10.2.0.0/16 # The route's network (destination). + gateway: 10.2.0.1 # The route's gateway (if empty, creates link scope route). {{< /highlight >}} | Field | Type | Description | Value(s) | |-------|------|-------------|----------| -|`disabled` |bool |
Indicates if the time service is disabled for the machine.Defaults to `false`.
| | -|`servers` |[]string |
Specifies time (NTP) servers to use for setting the system time.Defaults to `pool.ntp.org`
| | -|`bootTimeout` |Duration |
Specifies the timeout when the node time is considered to be in sync unlocking the boot sequence.NTP sync will be still running in the background.
Defaults to "infinity" (waiting forever for time sync)
| | +|`network` |string |The route's network (destination). | | +|`gateway` |string |The route's gateway (if empty, creates link scope route). | | +|`source` |string |The route's source address (optional). | | +|`metric` |uint32 |The optional metric for the route. | | +|`mtu` |uint32 |The optional MTU for the route. | | + + ---- -## RegistriesConfig -RegistriesConfig represents the image pull options. -Appears in: +##### bond {#Config.machine.network.interfaces..bond} -- MachineConfig.registries +Bond contains the various options for configuring a bonded interface. {{< highlight yaml >}} -# Specifies mirror configuration for each registry host namespace. -mirrors: - docker.io: - # List of endpoints (URLs) for registry mirrors to use. - endpoints: - - https://registry.local -# Specifies TLS & auth configuration for HTTPS image registries. -config: - registry.local: - # The TLS configuration for the registry. - tls: - # Enable mutual TLS authentication with the registry. - clientIdentity: - crt: LS0tIEVYQU1QTEUgQ0VSVElGSUNBVEUgLS0t - key: LS0tIEVYQU1QTEUgS0VZIC0tLQ== - # The auth configuration for this registry. - auth: - username: username # Optional registry authentication. - password: password # Optional registry authentication. +machine: + network: + interfaces: + - bond: + # The interfaces that make up the bond. + interfaces: + - enp2s0 + - enp2s1 + mode: 802.3ad # A bond option. + lacpRate: fast # A bond option. + + # # Picks a network device using the selector. + + # # select a device with bus prefix 00:*, a device with mac address matching `*:f0:ab` and `virtio` kernel driver. + # deviceSelectors: + # - busPath: 00:* # PCI, USB bus prefix, supports matching by wildcard. + # - hardwareAddr: '*:f0:ab' # Device hardware address, supports matching by wildcard. + # driver: virtio # Kernel driver, supports matching by wildcard. {{< /highlight >}} | Field | Type | Description | Value(s) | |-------|------|-------------|----------| -|`mirrors` |map[string]RegistryMirrorConfig |
Specifies mirror configuration for each registry host namespace.This setting allows to configure local pull-through caching registires,
air-gapped installations, etc.

For example, when pulling an image with the reference `example.com:123/image:v1`,
the `example.com:123` key will be used to lookup the mirror configuration.

Optionally the `*` key can be used to configure a fallback mirror.

Registry name is the first segment of image identifier, with 'docker.io'
being default one.
Show example(s){{< highlight yaml >}} -mirrors: - ghcr.io: - # List of endpoints (URLs) for registry mirrors to use. - endpoints: - - https://registry.insecure - - https://ghcr.io/v2/ +|`interfaces` |[]string |The interfaces that make up the bond. | | +|`deviceSelectors` |[]NetworkDeviceSelector |
Picks a network device using the selector.Mutually exclusive with `interfaces`.
Supports partial match using wildcard syntax.
Show example(s){{< highlight yaml >}} +deviceSelectors: + - busPath: 00:* # PCI, USB bus prefix, supports matching by wildcard. + - hardwareAddr: '*:f0:ab' # Device hardware address, supports matching by wildcard. + driver: virtio # Kernel driver, supports matching by wildcard. {{< /highlight >}}
| | -|`config` |map[string]RegistryConfig |
Specifies TLS & auth configuration for HTTPS image registries.Mutual TLS can be enabled with 'clientIdentity' option.

The full hostname and port (if not using a default port 443)
should be used as the key.
The fallback key `*` can't be used for TLS configuration.

TLS configuration can be skipped if registry has trusted
server certificate.
Show example(s){{< highlight yaml >}} -config: - registry.insecure: - # The TLS configuration for the registry. - tls: - insecureSkipVerify: true # Skip TLS server certificate verification (not recommended). +|`arpIPTarget` |[]string |
A bond option.Please see the official kernel documentation.
Not supported at the moment.
| | +|`mode` |string |
A bond option.Please see the official kernel documentation.
| | +|`xmitHashPolicy` |string |
A bond option.Please see the official kernel documentation.
| | +|`lacpRate` |string |
A bond option.Please see the official kernel documentation.
| | +|`adActorSystem` |string |
A bond option.Please see the official kernel documentation.
Not supported at the moment.
| | +|`arpValidate` |string |
A bond option.Please see the official kernel documentation.
| | +|`arpAllTargets` |string |
A bond option.Please see the official kernel documentation.
| | +|`primary` |string |
A bond option.Please see the official kernel documentation.
| | +|`primaryReselect` |string |
A bond option.Please see the official kernel documentation.
| | +|`failOverMac` |string |
A bond option.Please see the official kernel documentation.
| | +|`adSelect` |string |
A bond option.Please see the official kernel documentation.
| | +|`miimon` |uint32 |
A bond option.Please see the official kernel documentation.
| | +|`updelay` |uint32 |
A bond option.Please see the official kernel documentation.
| | +|`downdelay` |uint32 |
A bond option.Please see the official kernel documentation.
| | +|`arpInterval` |uint32 |
A bond option.Please see the official kernel documentation.
| | +|`resendIgmp` |uint32 |
A bond option.Please see the official kernel documentation.
| | +|`minLinks` |uint32 |
A bond option.Please see the official kernel documentation.
| | +|`lpInterval` |uint32 |
A bond option.Please see the official kernel documentation.
| | +|`packetsPerSlave` |uint32 |
A bond option.Please see the official kernel documentation.
| | +|`numPeerNotif` |uint8 |
A bond option.Please see the official kernel documentation.
| | +|`tlbDynamicLb` |uint8 |
A bond option.Please see the official kernel documentation.
| | +|`allSlavesActive` |uint8 |
A bond option.Please see the official kernel documentation.
| | +|`useCarrier` |bool |
A bond option.Please see the official kernel documentation.
| | +|`adActorSysPrio` |uint16 |
A bond option.Please see the official kernel documentation.
| | +|`adUserPortKey` |uint16 |
A bond option.Please see the official kernel documentation.
| | +|`peerNotifyDelay` |uint32 |
A bond option.Please see the official kernel documentation.
| | - # # Enable mutual TLS authentication with the registry. - # clientIdentity: - # crt: LS0tIEVYQU1QTEUgQ0VSVElGSUNBVEUgLS0t - # key: LS0tIEVYQU1QTEUgS0VZIC0tLQ== - # # The auth configuration for this registry. - # auth: - # username: username # Optional registry authentication. - # password: password # Optional registry authentication. -{{< /highlight >}}
| | +###### deviceSelectors[] {#Config.machine.network.interfaces..bond.deviceSelectors.} ---- -## PodCheckpointer -PodCheckpointer represents the pod-checkpointer config values. +NetworkDeviceSelector struct describes network device selector. +{{< highlight yaml >}} +machine: + network: + interfaces: + - bond: + deviceSelectors: + busPath: 00:* # PCI, USB bus prefix, supports matching by wildcard. +{{< /highlight >}} + +{{< highlight yaml >}} +machine: + network: + interfaces: + - bond: + deviceSelectors: + hardwareAddr: '*:f0:ab' # Device hardware address, supports matching by wildcard. + driver: virtio # Kernel driver, supports matching by wildcard. +{{< /highlight >}} + +{{< highlight yaml >}} +machine: + network: + interfaces: + - bond: + deviceSelectors: + - busPath: 00:* # PCI, USB bus prefix, supports matching by wildcard. + - hardwareAddr: '*:f0:ab' # Device hardware address, supports matching by wildcard. + driver: virtio # Kernel driver, supports matching by wildcard. +{{< /highlight >}} | Field | Type | Description | Value(s) | |-------|------|-------------|----------| -|`image` |string |The `image` field is an override to the default pod-checkpointer image. | | +|`busPath` |string |PCI, USB bus prefix, supports matching by wildcard. | | +|`hardwareAddr` |string |Device hardware address, supports matching by wildcard. | | +|`pciID` |string |PCI ID (vendor ID, product ID), supports matching by wildcard. | | +|`driver` |string |Kernel driver, supports matching by wildcard. | | + + ---- -## CoreDNS -CoreDNS represents the CoreDNS config values. -Appears in: -- ClusterConfig.coreDNS + +##### bridge {#Config.machine.network.interfaces..bridge} + +Bridge contains the various options for configuring a bridge interface. {{< highlight yaml >}} -image: registry.k8s.io/coredns/coredns:v1.11.1 # The `image` field is an override to the default coredns image. +machine: + network: + interfaces: + - bridge: + # The interfaces that make up the bridge. + interfaces: + - enxda4042ca9a51 + - enxae2a6774c259 + # A bridge option. + stp: + enabled: true # Whether Spanning Tree Protocol (STP) is enabled. {{< /highlight >}} | Field | Type | Description | Value(s) | |-------|------|-------------|----------| -|`disabled` |bool |Disable coredns deployment on cluster bootstrap. | | -|`image` |string |The `image` field is an override to the default coredns image. | | +|`interfaces` |[]string |The interfaces that make up the bridge. | | +|`stp` |STP |
A bridge option.Please see the official kernel documentation.
| | ---- -## Endpoint -Endpoint represents the endpoint URL parsed out of the machine config. -Appears in: +###### stp {#Config.machine.network.interfaces..bridge.stp} -- ControlPlaneConfig.endpoint -- LoggingDestination.endpoint +STP contains the various options for configuring the STP properties of a bridge interface. -{{< highlight yaml >}} -https://1.2.3.4:6443 -{{< /highlight >}} -{{< highlight yaml >}} -https://cluster1.internal:6443 -{{< /highlight >}} +| Field | Type | Description | Value(s) | +|-------|------|-------------|----------| +|`enabled` |bool |Whether Spanning Tree Protocol (STP) is enabled. | | -{{< highlight yaml >}} -udp://127.0.0.1:12345 -{{< /highlight >}} -{{< highlight yaml >}} -tcp://1.2.3.4:12345 -{{< /highlight >}} ---- -## ControlPlaneConfig -ControlPlaneConfig represents the control plane configuration options. -Appears in: -- ClusterConfig.controlPlane +##### vlans[] {#Config.machine.network.interfaces..vlans.} +Vlan represents vlan settings for a device. -{{< highlight yaml >}} -endpoint: https://1.2.3.4 # Endpoint is the canonical controlplane endpoint, which can be an IP address or a DNS hostname. -localAPIServerPort: 443 # The port that the API server listens on internally. -{{< /highlight >}} | Field | Type | Description | Value(s) | |-------|------|-------------|----------| -|`endpoint` |Endpoint |
Endpoint is the canonical controlplane endpoint, which can be an IP address or a DNS hostname.It is single-valued, and may optionally include a port number.
Show example(s){{< highlight yaml >}} -endpoint: https://1.2.3.4:6443 -{{< /highlight >}}{{< highlight yaml >}} -endpoint: https://cluster1.internal:6443 -{{< /highlight >}}
| | -|`localAPIServerPort` |int |
The port that the API server listens on internally.This may be different than the port portion listed in the endpoint field above.
The default is `6443`.
| | +|`addresses` |[]string |The addresses in CIDR notation or as plain IPs to use. | | +|`routes` |[]Route |A list of routes associated with the VLAN. | | +|`dhcp` |bool |Indicates if DHCP should be used. | | +|`vlanId` |uint16 |The VLAN's ID. | | +|`mtu` |uint32 |The VLAN's MTU. | | +|`vip` |DeviceVIPConfig |The VLAN's virtual IP address configuration. | | +|`dhcpOptions` |DHCPOptions |
DHCP specific options.`dhcp` *must* be set to true for these to take effect.
| | ---- -## APIServerConfig -APIServerConfig represents the kube apiserver configuration options. -Appears in: +###### routes[] {#Config.machine.network.interfaces..vlans..routes.} -- ClusterConfig.apiServer +Route represents a network route. {{< highlight yaml >}} -image: registry.k8s.io/kube-apiserver:v1.29.0-rc.1 # The container image used in the API server manifest. -# Extra arguments to supply to the API server. -extraArgs: - feature-gates: ServerSideApply=true - http2-max-streams-per-connection: "32" -# Extra certificate subject alternative names for the API server's certificate. -certSANs: - - 1.2.3.4 - - 4.5.6.7 - -# # Configure the API server admission plugins. -# admissionControl: -# - name: PodSecurity # Name is the name of the admission controller. -# # Configuration is an embedded configuration object to be used as the plugin's -# configuration: -# apiVersion: pod-security.admission.config.k8s.io/v1alpha1 -# defaults: -# audit: restricted -# audit-version: latest -# enforce: baseline -# enforce-version: latest -# warn: restricted -# warn-version: latest -# exemptions: -# namespaces: -# - kube-system -# runtimeClasses: [] -# usernames: [] -# kind: PodSecurityConfiguration - -# # Configure the API server audit policy. -# auditPolicy: -# apiVersion: audit.k8s.io/v1 -# kind: Policy -# rules: -# - level: Metadata +machine: + network: + interfaces: + - vlans: + - routes: + - network: 0.0.0.0/0 # The route's network (destination). + gateway: 10.5.0.1 # The route's gateway (if empty, creates link scope route). + - network: 10.2.0.0/16 # The route's network (destination). + gateway: 10.2.0.1 # The route's gateway (if empty, creates link scope route). {{< /highlight >}} | Field | Type | Description | Value(s) | |-------|------|-------------|----------| -|`image` |string |The container image used in the API server manifest.
Show example(s){{< highlight yaml >}} -image: registry.k8s.io/kube-apiserver:v1.29.0-rc.1 -{{< /highlight >}}
| | -|`extraArgs` |map[string]string |Extra arguments to supply to the API server. | | -|`extraVolumes` |[]VolumeMountConfig |Extra volumes to mount to the API server static pod. | | -|`env` |Env |The `env` field allows for the addition of environment variables for the control plane component. | | -|`certSANs` |[]string |Extra certificate subject alternative names for the API server's certificate. | | -|`disablePodSecurityPolicy` |bool |Disable PodSecurityPolicy in the API server and default manifests. | | -|`admissionControl` |[]AdmissionPluginConfig |Configure the API server admission plugins.
Show example(s){{< highlight yaml >}} -admissionControl: - - name: PodSecurity # Name is the name of the admission controller. - # Configuration is an embedded configuration object to be used as the plugin's - configuration: - apiVersion: pod-security.admission.config.k8s.io/v1alpha1 - defaults: - audit: restricted - audit-version: latest - enforce: baseline - enforce-version: latest - warn: restricted - warn-version: latest - exemptions: - namespaces: - - kube-system - runtimeClasses: [] - usernames: [] - kind: PodSecurityConfiguration -{{< /highlight >}}
| | -|`auditPolicy` |Unstructured |Configure the API server audit policy.
Show example(s){{< highlight yaml >}} -auditPolicy: - apiVersion: audit.k8s.io/v1 - kind: Policy - rules: - - level: Metadata -{{< /highlight >}}
| | -|`resources` |ResourcesConfig |Configure the API server resources. | | +|`network` |string |The route's network (destination). | | +|`gateway` |string |The route's gateway (if empty, creates link scope route). | | +|`source` |string |The route's source address (optional). | | +|`metric` |uint32 |The optional metric for the route. | | +|`mtu` |uint32 |The optional MTU for the route. | | + ---- -## AdmissionPluginConfig -AdmissionPluginConfig represents the API server admission plugin configuration. -Appears in: -- APIServerConfig.admissionControl +###### vip {#Config.machine.network.interfaces..vlans..vip} + +DeviceVIPConfig contains settings for configuring a Virtual Shared IP on an interface. {{< highlight yaml >}} -- name: PodSecurity # Name is the name of the admission controller. - # Configuration is an embedded configuration object to be used as the plugin's - configuration: - apiVersion: pod-security.admission.config.k8s.io/v1alpha1 - defaults: - audit: restricted - audit-version: latest - enforce: baseline - enforce-version: latest - warn: restricted - warn-version: latest - exemptions: - namespaces: - - kube-system - runtimeClasses: [] - usernames: [] - kind: PodSecurityConfiguration +machine: + network: + interfaces: + - vlans: + - vip: + ip: 172.16.199.55 # Specifies the IP address to be used. {{< /highlight >}} | Field | Type | Description | Value(s) | |-------|------|-------------|----------| -|`name` |string |
Name is the name of the admission controller.It must match the registered admission plugin name.
| | -|`configuration` |Unstructured |
Configuration is an embedded configuration object to be used as the plugin'sconfiguration.
| | - +|`ip` |string |Specifies the IP address to be used. | | +|`equinixMetal` |VIPEquinixMetalConfig |Specifies the Equinix Metal API settings to assign VIP to the node. | | +|`hcloud` |VIPHCloudConfig |Specifies the Hetzner Cloud API settings to assign VIP to the node. | | ---- -## ControllerManagerConfig -ControllerManagerConfig represents the kube controller manager configuration options. -Appears in: -- ClusterConfig.controllerManager +####### equinixMetal {#Config.machine.network.interfaces..vlans..vip.equinixMetal} +VIPEquinixMetalConfig contains settings for Equinix Metal VIP management. -{{< highlight yaml >}} -image: registry.k8s.io/kube-controller-manager:v1.29.0-rc.1 # The container image used in the controller manager manifest. -# Extra arguments to supply to the controller manager. -extraArgs: - feature-gates: ServerSideApply=true -{{< /highlight >}} | Field | Type | Description | Value(s) | |-------|------|-------------|----------| -|`image` |string |The container image used in the controller manager manifest.
Show example(s){{< highlight yaml >}} -image: registry.k8s.io/kube-controller-manager:v1.29.0-rc.1 -{{< /highlight >}}
| | -|`extraArgs` |map[string]string |Extra arguments to supply to the controller manager. | | -|`extraVolumes` |[]VolumeMountConfig |Extra volumes to mount to the controller manager static pod. | | -|`env` |Env |The `env` field allows for the addition of environment variables for the control plane component. | | -|`resources` |ResourcesConfig |Configure the controller manager resources. | | +|`apiToken` |string |Specifies the Equinix Metal API Token. | | ---- -## ProxyConfig -ProxyConfig represents the kube proxy configuration options. -Appears in: -- ClusterConfig.proxy +####### hcloud {#Config.machine.network.interfaces..vlans..vip.hcloud} +VIPHCloudConfig contains settings for Hetzner Cloud VIP management. -{{< highlight yaml >}} -image: registry.k8s.io/kube-proxy:v1.29.0-rc.1 # The container image used in the kube-proxy manifest. -mode: ipvs # proxy mode of kube-proxy. -# Extra arguments to supply to kube-proxy. -extraArgs: - proxy-mode: iptables -# # Disable kube-proxy deployment on cluster bootstrap. -# disabled: false -{{< /highlight >}} | Field | Type | Description | Value(s) | |-------|------|-------------|----------| -|`disabled` |bool |Disable kube-proxy deployment on cluster bootstrap.
Show example(s){{< highlight yaml >}} -disabled: false -{{< /highlight >}}
| | -|`image` |string |The container image used in the kube-proxy manifest.
Show example(s){{< highlight yaml >}} -image: registry.k8s.io/kube-proxy:v1.29.0-rc.1 -{{< /highlight >}}
| | -|`mode` |string |
proxy mode of kube-proxy.The default is 'iptables'.
| | -|`extraArgs` |map[string]string |Extra arguments to supply to kube-proxy. | | - - - ---- -## SchedulerConfig -SchedulerConfig represents the kube scheduler configuration options. - -Appears in: - -- ClusterConfig.scheduler - +|`apiToken` |string |Specifies the Hetzner Cloud API Token. | | -{{< highlight yaml >}} -image: registry.k8s.io/kube-scheduler:v1.29.0-rc.1 # The container image used in the scheduler manifest. -# Extra arguments to supply to the scheduler. -extraArgs: - feature-gates: AllBeta=true -{{< /highlight >}} -| Field | Type | Description | Value(s) | -|-------|------|-------------|----------| -|`image` |string |The container image used in the scheduler manifest.
Show example(s){{< highlight yaml >}} -image: registry.k8s.io/kube-scheduler:v1.29.0-rc.1 -{{< /highlight >}}
| | -|`extraArgs` |map[string]string |Extra arguments to supply to the scheduler. | | -|`extraVolumes` |[]VolumeMountConfig |Extra volumes to mount to the scheduler static pod. | | -|`env` |Env |The `env` field allows for the addition of environment variables for the control plane component. | | -|`resources` |ResourcesConfig |Configure the scheduler resources. | | -|`config` |Unstructured |Specify custom kube-scheduler configuration. | | ---- -## EtcdConfig -EtcdConfig represents the etcd configuration options. -Appears in: +###### dhcpOptions {#Config.machine.network.interfaces..vlans..dhcpOptions} -- ClusterConfig.etcd +DHCPOptions contains options for configuring the DHCP settings for a given interface. {{< highlight yaml >}} -image: gcr.io/etcd-development/etcd:v3.5.11 # The container image used to create the etcd service. -# The `ca` is the root certificate authority of the PKI. -ca: - crt: LS0tIEVYQU1QTEUgQ0VSVElGSUNBVEUgLS0t - key: LS0tIEVYQU1QTEUgS0VZIC0tLQ== -# Extra arguments to supply to etcd. -extraArgs: - election-timeout: "5000" - -# # The `advertisedSubnets` field configures the networks to pick etcd advertised IP from. -# advertisedSubnets: -# - 10.0.0.0/8 +machine: + network: + interfaces: + - vlans: + - dhcpOptions: + routeMetric: 1024 # The priority of all routes received via DHCP. {{< /highlight >}} | Field | Type | Description | Value(s) | |-------|------|-------------|----------| -|`image` |string |The container image used to create the etcd service.
Show example(s){{< highlight yaml >}} -image: gcr.io/etcd-development/etcd:v3.5.11 -{{< /highlight >}}
| | -|`ca` |PEMEncodedCertificateAndKey |
The `ca` is the root certificate authority of the PKI.It is composed of a base64 encoded `crt` and `key`.
Show example(s){{< highlight yaml >}} -ca: - crt: LS0tIEVYQU1QTEUgQ0VSVElGSUNBVEUgLS0t - key: LS0tIEVYQU1QTEUgS0VZIC0tLQ== -{{< /highlight >}}
| | -|`extraArgs` |map[string]string |
Extra arguments to supply to etcd.Note that the following args are not allowed:

- `name`
- `data-dir`
- `initial-cluster-state`
- `listen-peer-urls`
- `listen-client-urls`
- `cert-file`
- `key-file`
- `trusted-ca-file`
- `peer-client-cert-auth`
- `peer-cert-file`
- `peer-trusted-ca-file`
- `peer-key-file`
| | -|`advertisedSubnets` |[]string |
The `advertisedSubnets` field configures the networks to pick etcd advertised IP from.
IPs can be excluded from the list by using negative match with `!`, e.g `!10.0.0.0/8`.
Negative subnet matches should be specified last to filter out IPs picked by positive matches.
If not specified, advertised IP is selected as the first routable address of the node.
Show example(s){{< highlight yaml >}} -advertisedSubnets: - - 10.0.0.0/8 -{{< /highlight >}}
| | -|`listenSubnets` |[]string |
The `listenSubnets` field configures the networks for the etcd to listen for peer and client connections.
If `listenSubnets` is not set, but `advertisedSubnets` is set, `listenSubnets` defaults to
`advertisedSubnets`.

If neither `advertisedSubnets` nor `listenSubnets` is set, `listenSubnets` defaults to listen on all addresses.

IPs can be excluded from the list by using negative match with `!`, e.g `!10.0.0.0/8`.
Negative subnet matches should be specified last to filter out IPs picked by positive matches.
If not specified, advertised IP is selected as the first routable address of the node.
| | - - - ---- -## ClusterNetworkConfig -ClusterNetworkConfig represents kube networking configuration options. - -Appears in: - -- ClusterConfig.network - +|`routeMetric` |uint32 |The priority of all routes received via DHCP. | | +|`ipv4` |bool |Enables DHCPv4 protocol for the interface (default is enabled). | | +|`ipv6` |bool |Enables DHCPv6 protocol for the interface (default is disabled). | | +|`duidv6` |string |Set client DUID (hex string). | | -{{< highlight yaml >}} -# The CNI used. -cni: - name: flannel # Name of CNI to use. -dnsDomain: cluster.local # The domain used by Kubernetes DNS. -# The pod subnet CIDR. -podSubnets: - - 10.244.0.0/16 -# The service subnet CIDR. -serviceSubnets: - - 10.96.0.0/12 -{{< /highlight >}} -| Field | Type | Description | Value(s) | -|-------|------|-------------|----------| -|`cni` |CNIConfig |
The CNI used.Composed of "name" and "urls".
The "name" key supports the following options: "flannel", "custom", and "none".
"flannel" uses Talos-managed Flannel CNI, and that's the default option.
"custom" uses custom manifests that should be provided in "urls".
"none" indicates that Talos will not manage any CNI installation.
Show example(s){{< highlight yaml >}} -cni: - name: custom # Name of CNI to use. - # URLs containing manifests to apply for the CNI. - urls: - - https://docs.projectcalico.org/archive/v3.20/manifests/canal.yaml -{{< /highlight >}}
| | -|`dnsDomain` |string |
The domain used by Kubernetes DNS.The default is `cluster.local`
Show example(s){{< highlight yaml >}} -dnsDomain: cluser.local -{{< /highlight >}}
| | -|`podSubnets` |[]string |The pod subnet CIDR.
Show example(s){{< highlight yaml >}} -podSubnets: - - 10.244.0.0/16 -{{< /highlight >}}
| | -|`serviceSubnets` |[]string |The service subnet CIDR.
Show example(s){{< highlight yaml >}} -serviceSubnets: - - 10.96.0.0/12 -{{< /highlight >}}
| | ---- -## CNIConfig -CNIConfig represents the CNI configuration options. -Appears in: +##### dhcpOptions {#Config.machine.network.interfaces..dhcpOptions} -- ClusterNetworkConfig.cni +DHCPOptions contains options for configuring the DHCP settings for a given interface. {{< highlight yaml >}} -name: custom # Name of CNI to use. -# URLs containing manifests to apply for the CNI. -urls: - - https://docs.projectcalico.org/archive/v3.20/manifests/canal.yaml +machine: + network: + interfaces: + - dhcpOptions: + routeMetric: 1024 # The priority of all routes received via DHCP. {{< /highlight >}} | Field | Type | Description | Value(s) | |-------|------|-------------|----------| -|`name` |string |Name of CNI to use. |`flannel`
`custom`
`none`
| -|`urls` |[]string |
URLs containing manifests to apply for the CNI.Should be present for "custom", must be empty for "flannel" and "none".
| | -|`flannel` |FlannelCNIConfig |
description: |Flannel configuration options.
| | - - - ---- -## FlannelCNIConfig -FlannelCNIConfig represents the Flannel CNI configuration options. - -Appears in: - -- CNIConfig.flannel - +|`routeMetric` |uint32 |The priority of all routes received via DHCP. | | +|`ipv4` |bool |Enables DHCPv4 protocol for the interface (default is enabled). | | +|`ipv6` |bool |Enables DHCPv6 protocol for the interface (default is disabled). | | +|`duidv6` |string |Set client DUID (hex string). | | -| Field | Type | Description | Value(s) | -|-------|------|-------------|----------| -|`extraArgs` |[]string |Extra arguments for 'flanneld'.
Show example(s){{< highlight yaml >}} -extraArgs: - - --iface-can-reach=192.168.1.1 -{{< /highlight >}}
| | ---- -## ExternalCloudProviderConfig -ExternalCloudProviderConfig contains external cloud provider configuration. +##### wireguard {#Config.machine.network.interfaces..wireguard} -Appears in: +DeviceWireguardConfig contains settings for configuring Wireguard network interface. -- ClusterConfig.externalCloudProvider +{{< highlight yaml >}} +machine: + network: + interfaces: + - wireguard: + privateKey: ABCDEF... # Specifies a private key configuration (base64 encoded). + listenPort: 51111 # Specifies a device's listening port. + # Specifies a list of peer configurations to apply to a device. + peers: + - publicKey: ABCDEF... # Specifies the public key of this peer. + endpoint: 192.168.1.3 # Specifies the endpoint of this peer entry. + # AllowedIPs specifies a list of allowed IP addresses in CIDR notation for this peer. + allowedIPs: + - 192.168.1.0/24 +{{< /highlight >}} {{< highlight yaml >}} -enabled: true # Enable external cloud provider. -# A list of urls that point to additional manifests for an external cloud provider. -manifests: - - https://raw.githubusercontent.com/kubernetes/cloud-provider-aws/v1.20.0-alpha.0/manifests/rbac.yaml - - https://raw.githubusercontent.com/kubernetes/cloud-provider-aws/v1.20.0-alpha.0/manifests/aws-cloud-controller-manager-daemonset.yaml +machine: + network: + interfaces: + - wireguard: + privateKey: ABCDEF... # Specifies a private key configuration (base64 encoded). + # Specifies a list of peer configurations to apply to a device. + peers: + - publicKey: ABCDEF... # Specifies the public key of this peer. + endpoint: 192.168.1.2:51822 # Specifies the endpoint of this peer entry. + persistentKeepaliveInterval: 10s # Specifies the persistent keepalive interval for this peer. + # AllowedIPs specifies a list of allowed IP addresses in CIDR notation for this peer. + allowedIPs: + - 192.168.1.0/24 {{< /highlight >}} | Field | Type | Description | Value(s) | |-------|------|-------------|----------| -|`enabled` |bool |Enable external cloud provider. |`true`
`yes`
`false`
`no`
| -|`manifests` |[]string |
A list of urls that point to additional manifests for an external cloud provider.These will get automatically deployed as part of the bootstrap.
Show example(s){{< highlight yaml >}} -manifests: - - https://raw.githubusercontent.com/kubernetes/cloud-provider-aws/v1.20.0-alpha.0/manifests/rbac.yaml - - https://raw.githubusercontent.com/kubernetes/cloud-provider-aws/v1.20.0-alpha.0/manifests/aws-cloud-controller-manager-daemonset.yaml -{{< /highlight >}}
| | - +|`privateKey` |string |
Specifies a private key configuration (base64 encoded).Can be generated by `wg genkey`.
| | +|`listenPort` |int |Specifies a device's listening port. | | +|`firewallMark` |int |Specifies a device's firewall mark. | | +|`peers` |[]DeviceWireguardPeer |Specifies a list of peer configurations to apply to a device. | | ---- -## AdminKubeconfigConfig -AdminKubeconfigConfig contains admin kubeconfig settings. -Appears in: -- ClusterConfig.adminKubeconfig +###### peers[] {#Config.machine.network.interfaces..wireguard.peers.} +DeviceWireguardPeer a WireGuard device peer configuration. -{{< highlight yaml >}} -certLifetime: 1h0m0s # Admin kubeconfig certificate lifetime (default is 1 year). -{{< /highlight >}} | Field | Type | Description | Value(s) | |-------|------|-------------|----------| -|`certLifetime` |Duration |
Admin kubeconfig certificate lifetime (default is 1 year).Field format accepts any Go time.Duration format ('1h' for one hour, '10m' for ten minutes).
| | +|`publicKey` |string |
Specifies the public key of this peer.Can be extracted from private key by running `wg pubkey < private.key > public.key && cat public.key`.
| | +|`endpoint` |string |Specifies the endpoint of this peer entry. | | +|`persistentKeepaliveInterval` |Duration |
Specifies the persistent keepalive interval for this peer.Field format accepts any Go time.Duration format ('1h' for one hour, '10m' for ten minutes).
| | +|`allowedIPs` |[]string |AllowedIPs specifies a list of allowed IP addresses in CIDR notation for this peer. | | ---- -## MachineDisk -MachineDisk represents the options available for partitioning, formatting, and -mounting extra disks. -Appears in: -- MachineConfig.disks +##### vip {#Config.machine.network.interfaces..vip} -{{< highlight yaml >}} -- device: /dev/sdb # The name of the disk to use. - # A list of partitions to create on the disk. - partitions: - - mountpoint: /var/mnt/extra # Where to mount the partition. +DeviceVIPConfig contains settings for configuring a Virtual Shared IP on an interface. - # # The size of partition: either bytes or human readable representation. If `size:` is omitted, the partition is sized to occupy the full disk. - # # Human readable representation. - # size: 100 MB - # # Precise value in bytes. - # size: 1073741824 + +{{< highlight yaml >}} +machine: + network: + interfaces: + - vip: + ip: 172.16.199.55 # Specifies the IP address to be used. {{< /highlight >}} | Field | Type | Description | Value(s) | |-------|------|-------------|----------| -|`device` |string |The name of the disk to use. | | -|`partitions` |[]DiskPartition |A list of partitions to create on the disk. | | +|`ip` |string |Specifies the IP address to be used. | | +|`equinixMetal` |VIPEquinixMetalConfig |Specifies the Equinix Metal API settings to assign VIP to the node. | | +|`hcloud` |VIPHCloudConfig |Specifies the Hetzner Cloud API settings to assign VIP to the node. | | ---- -## DiskPartition -DiskPartition represents the options for a disk partition. -Appears in: +###### equinixMetal {#Config.machine.network.interfaces..vip.equinixMetal} -- MachineDisk.partitions +VIPEquinixMetalConfig contains settings for Equinix Metal VIP management. | Field | Type | Description | Value(s) | |-------|------|-------------|----------| -|`size` |DiskSize |The size of partition: either bytes or human readable representation. If `size:` is omitted, the partition is sized to occupy the full disk.
Show example(s){{< highlight yaml >}} -size: 100 MB -{{< /highlight >}}{{< highlight yaml >}} -size: 1073741824 -{{< /highlight >}}
| | -|`mountpoint` |string |Where to mount the partition. | | +|`apiToken` |string |Specifies the Equinix Metal API Token. | | ---- -## EncryptionConfig -EncryptionConfig represents partition encryption settings. -Appears in: -- SystemDiskEncryptionConfig.state -- SystemDiskEncryptionConfig.ephemeral +###### hcloud {#Config.machine.network.interfaces..vip.hcloud} +VIPHCloudConfig contains settings for Hetzner Cloud VIP management. -| Field | Type | Description | Value(s) | -|-------|------|-------------|----------| -|`provider` |string |Encryption provider to use for the encryption.
Show example(s){{< highlight yaml >}} -provider: luks2 -{{< /highlight >}}
| | -|`keys` |[]EncryptionKey |Defines the encryption keys generation and storage method. | | -|`cipher` |string |Cipher kind to use for the encryption. Depends on the encryption provider.
Show example(s){{< highlight yaml >}} -cipher: aes-xts-plain64 -{{< /highlight >}}
|`aes-xts-plain64`
`xchacha12,aes-adiantum-plain64`
`xchacha20,aes-adiantum-plain64`
| -|`keySize` |uint |Defines the encryption key length. | | -|`blockSize` |uint64 |Defines the encryption sector size.
Show example(s){{< highlight yaml >}} -blockSize: 4096 -{{< /highlight >}}
| | -|`options` |[]string |Additional --perf parameters for the LUKS2 encryption.
Show example(s){{< highlight yaml >}} -options: - - no_read_workqueue - - no_write_workqueue -{{< /highlight >}}
|`no_read_workqueue`
`no_write_workqueue`
`same_cpu_crypt`
| +| Field | Type | Description | Value(s) | +|-------|------|-------------|----------| +|`apiToken` |string |Specifies the Hetzner Cloud API Token. | | ---- -## EncryptionKey -EncryptionKey represents configuration for disk encryption key. -Appears in: -- EncryptionConfig.keys -| Field | Type | Description | Value(s) | -|-------|------|-------------|----------| -|`static` |EncryptionKeyStatic |Key which value is stored in the configuration file. | | -|`nodeID` |EncryptionKeyNodeID |Deterministically generated key from the node UUID and PartitionLabel. | | -|`kms` |EncryptionKeyKMS |KMS managed encryption key.
Show example(s){{< highlight yaml >}} -kms: - endpoint: https://192.168.88.21:4443 # KMS endpoint to Seal/Unseal the key. -{{< /highlight >}}
| | -|`slot` |int |Key slot number for LUKS2 encryption. | | -|`tpm` |EncryptionKeyTPM |Enable TPM based disk encryption. | | ---- -## EncryptionKeyStatic -EncryptionKeyStatic represents throw away key type. +#### extraHostEntries[] {#Config.machine.network.extraHostEntries.} -Appears in: +ExtraHost represents a host entry in /etc/hosts. -- EncryptionKey.static +{{< highlight yaml >}} +machine: + network: + extraHostEntries: + - ip: 192.168.1.100 # The IP of the host. + # The host alias. + aliases: + - example + - example.domain.tld +{{< /highlight >}} | Field | Type | Description | Value(s) | |-------|------|-------------|----------| -|`passphrase` |string |Defines the static passphrase value. | | +|`ip` |string |The IP of the host. | | +|`aliases` |[]string |The host alias. | | + ---- -## EncryptionKeyKMS -EncryptionKeyKMS represents a key that is generated and then sealed/unsealed by the KMS server. -Appears in: -- EncryptionKey.kms +#### kubespan {#Config.machine.network.kubespan} + +NetworkKubeSpan struct describes KubeSpan configuration. {{< highlight yaml >}} -endpoint: https://192.168.88.21:4443 # KMS endpoint to Seal/Unseal the key. +machine: + network: + kubespan: + enabled: true # Enable the KubeSpan feature. {{< /highlight >}} | Field | Type | Description | Value(s) | |-------|------|-------------|----------| -|`endpoint` |string |KMS endpoint to Seal/Unseal the key. | | +|`enabled` |bool |
Enable the KubeSpan feature.Cluster discovery should be enabled with .cluster.discovery.enabled for KubeSpan to be enabled.
| | +|`advertiseKubernetesNetworks` |bool |
Control whether Kubernetes pod CIDRs are announced over KubeSpan from the node.If disabled, CNI handles encapsulating pod-to-pod traffic into some node-to-node tunnel,
and KubeSpan handles the node-to-node traffic.
If enabled, KubeSpan will take over pod-to-pod traffic and send it over KubeSpan directly.
When enabled, KubeSpan should have a way to detect complete pod CIDRs of the node which
is not always the case with CNIs not relying on Kubernetes for IPAM.
| | +|`allowDownPeerBypass` |bool |
Skip sending traffic via KubeSpan if the peer connection state is not up.This provides configurable choice between connectivity and security: either traffic is always
forced to go via KubeSpan (even if Wireguard peer connection is not up), or traffic can go directly
to the peer if Wireguard connection can't be established.
| | +|`mtu` |uint32 |
KubeSpan link MTU size.Default value is 1420.
| | +|`filters` |KubeSpanFilters |
KubeSpan advanced filtering of network addresses .
Settings in this section are optional, and settings apply only to the node.
| | ---- -## EncryptionKeyTPM -EncryptionKeyTPM represents a key that is generated and then sealed/unsealed by the TPM. -Appears in: +##### filters {#Config.machine.network.kubespan.filters} + +KubeSpanFilters struct describes KubeSpan advanced network addresses filtering. -- EncryptionKey.tpm +| Field | Type | Description | Value(s) | +|-------|------|-------------|----------| +|`endpoints` |[]string |
Filter node addresses which will be advertised as KubeSpan endpoints for peer-to-peer Wireguard connections.
By default, all addresses are advertised, and KubeSpan cycles through all endpoints until it finds one that works.

Default value: no filtering.
Show example(s){{< highlight yaml >}} +endpoints: + - 0.0.0.0/0 + - '!192.168.0.0/16' + - ::/0 +{{< /highlight >}}
| | ---- -## EncryptionKeyNodeID -EncryptionKeyNodeID represents deterministically generated key from the node UUID and PartitionLabel. -Appears in: -- EncryptionKey.nodeID +### disks[] {#Config.machine.disks.} ---- -## ResourcesConfig -ResourcesConfig represents the pod resources. +MachineDisk represents the options available for partitioning, formatting, and +mounting extra disks. -Appears in: -- APIServerConfig.resources -- ControllerManagerConfig.resources -- SchedulerConfig.resources +{{< highlight yaml >}} +machine: + disks: + - device: /dev/sdb # The name of the disk to use. + # A list of partitions to create on the disk. + partitions: + - mountpoint: /var/mnt/extra # Where to mount the partition. + + # # The size of partition: either bytes or human readable representation. If `size:` is omitted, the partition is sized to occupy the full disk. + + # # Human readable representation. + # size: 100 MB + # # Precise value in bytes. + # size: 1073741824 +{{< /highlight >}} | Field | Type | Description | Value(s) | |-------|------|-------------|----------| -|`requests` |Unstructured |Requests configures the reserved cpu/memory resources.
Show example(s){{< highlight yaml >}} -requests: - cpu: 1 - memory: 1Gi -{{< /highlight >}}
| | -|`limits` |Unstructured |Limits configures the maximum cpu/memory resources a container can use.
Show example(s){{< highlight yaml >}} -limits: - cpu: 2 - memory: 2500Mi -{{< /highlight >}}
| | - +|`device` |string |The name of the disk to use. | | +|`partitions` |[]DiskPartition |A list of partitions to create on the disk. | | ---- -## MachineFile -MachineFile represents a file to write to disk. -Appears in: -- MachineConfig.files +#### partitions[] {#Config.machine.disks..partitions.} +DiskPartition represents the options for a disk partition. -{{< highlight yaml >}} -- content: '...' # The contents of the file. - permissions: 0o666 # The file's permissions in octal. - path: /tmp/file.txt # The path of the file. - op: append # The operation to use -{{< /highlight >}} | Field | Type | Description | Value(s) | |-------|------|-------------|----------| -|`content` |string |The contents of the file. | | -|`permissions` |FileMode |The file's permissions in octal. | | -|`path` |string |The path of the file. | | -|`op` |string |The operation to use |`create`
`append`
`overwrite`
| +|`size` |DiskSize |The size of partition: either bytes or human readable representation. If `size:` is omitted, the partition is sized to occupy the full disk.
Show example(s){{< highlight yaml >}} +size: 100 MB +{{< /highlight >}}{{< highlight yaml >}} +size: 1073741824 +{{< /highlight >}}
| | +|`mountpoint` |string |Where to mount the partition. | | ---- -## ExtraHost -ExtraHost represents a host entry in /etc/hosts. -Appears in: -- NetworkConfig.extraHostEntries + + + +### install {#Config.machine.install} + +InstallConfig represents the installation options for preparing a node. {{< highlight yaml >}} -- ip: 192.168.1.100 # The IP of the host. - # The host alias. - aliases: - - example - - example.domain.tld +machine: + install: + disk: /dev/sda # The disk used for installations. + # Allows for supplying extra kernel args via the bootloader. + extraKernelArgs: + - console=ttyS1 + - panic=10 + image: ghcr.io/siderolabs/installer:latest # Allows for supplying the image used to perform the installation. + wipe: false # Indicates if the installation disk should be wiped at installation time. + + # # Look up disk using disk attributes like model, size, serial and others. + # diskSelector: + # size: 4GB # Disk size. + # model: WDC* # Disk model `/sys/block//device/model`. + # busPath: /pci0000:00/0000:00:17.0/ata1/host0/target0:0:0/0:0:0:0 # Disk bus path. + + # # Allows for supplying additional system extension images to install on top of base Talos image. + # extensions: + # - image: ghcr.io/siderolabs/gvisor:20220117.0-v1.0.0 # System extension image. {{< /highlight >}} | Field | Type | Description | Value(s) | |-------|------|-------------|----------| -|`ip` |string |The IP of the host. | | -|`aliases` |[]string |The host alias. | | +|`disk` |string |The disk used for installations.
Show example(s){{< highlight yaml >}} +disk: /dev/sda +{{< /highlight >}}{{< highlight yaml >}} +disk: /dev/nvme0 +{{< /highlight >}}
| | +|`diskSelector` |InstallDiskSelector |
Look up disk using disk attributes like model, size, serial and others.Always has priority over `disk`.
Show example(s){{< highlight yaml >}} +diskSelector: + size: '>= 1TB' # Disk size. + model: WDC* # Disk model `/sys/block//device/model`. + + # # Disk bus path. + # busPath: /pci0000:00/0000:00:17.0/ata1/host0/target0:0:0/0:0:0:0 + # busPath: /pci0000:00/* +{{< /highlight >}}
| | +|`extraKernelArgs` |[]string |
Allows for supplying extra kernel args via the bootloader.Existing kernel args can be removed by prefixing the argument with a `-`.
For example `-console` removes all `console=` arguments, whereas `-console=tty0` removes the `console=tty0` default argument.
Show example(s){{< highlight yaml >}} +extraKernelArgs: + - talos.platform=metal + - reboot=k +{{< /highlight >}}
| | +|`image` |string |
Allows for supplying the image used to perform the installation.Image reference for each Talos release can be found on
[GitHub releases page](https://github.com/siderolabs/talos/releases).
Show example(s){{< highlight yaml >}} +image: ghcr.io/siderolabs/installer:latest +{{< /highlight >}}
| | +|`extensions` |[]InstallExtensionConfig |Allows for supplying additional system extension images to install on top of base Talos image.
Show example(s){{< highlight yaml >}} +extensions: + - image: ghcr.io/siderolabs/gvisor:20220117.0-v1.0.0 # System extension image. +{{< /highlight >}}
| | +|`wipe` |bool |
Indicates if the installation disk should be wiped at installation time.Defaults to `true`.
|`true`
`yes`
`false`
`no`
| +|`legacyBIOSSupport` |bool |
Indicates if MBR partition should be marked as bootable (active).Should be enabled only for the systems with legacy BIOS that doesn't support GPT partitioning scheme.
| | ---- -## Device -Device represents a network interface. -Appears in: +#### diskSelector {#Config.machine.install.diskSelector} -- NetworkConfig.interfaces +InstallDiskSelector represents a disk query parameters for the install disk lookup. {{< highlight yaml >}} -- interface: enp0s1 # The interface name. - # Assigns static IP addresses to the interface. - addresses: - - 192.168.2.0/24 - # A list of routes associated with the interface. - routes: - - network: 0.0.0.0/0 # The route's network (destination). - gateway: 192.168.2.1 # The route's gateway (if empty, creates link scope route). - metric: 1024 # The optional metric for the route. - mtu: 1500 # The interface's MTU. - - # # Picks a network device using the selector. - - # # select a device with bus prefix 00:*. - # deviceSelector: - # busPath: 00:* # PCI, USB bus prefix, supports matching by wildcard. - # # select a device with mac address matching `*:f0:ab` and `virtio` kernel driver. - # deviceSelector: - # hardwareAddr: '*:f0:ab' # Device hardware address, supports matching by wildcard. - # driver: virtio # Kernel driver, supports matching by wildcard. - # # select a device with bus prefix 00:*, a device with mac address matching `*:f0:ab` and `virtio` kernel driver. - # deviceSelector: - # - busPath: 00:* # PCI, USB bus prefix, supports matching by wildcard. - # - hardwareAddr: '*:f0:ab' # Device hardware address, supports matching by wildcard. - # driver: virtio # Kernel driver, supports matching by wildcard. - - # # Bond specific options. - # bond: - # # The interfaces that make up the bond. - # interfaces: - # - enp2s0 - # - enp2s1 - # # Picks a network device using the selector. - # deviceSelectors: - # - busPath: 00:* # PCI, USB bus prefix, supports matching by wildcard. - # - hardwareAddr: '*:f0:ab' # Device hardware address, supports matching by wildcard. - # driver: virtio # Kernel driver, supports matching by wildcard. - # mode: 802.3ad # A bond option. - # lacpRate: fast # A bond option. - - # # Bridge specific options. - # bridge: - # # The interfaces that make up the bridge. - # interfaces: - # - enxda4042ca9a51 - # - enxae2a6774c259 - # # A bridge option. - # stp: - # enabled: true # Whether Spanning Tree Protocol (STP) is enabled. - - # # Indicates if DHCP should be used to configure the interface. - # dhcp: true - - # # DHCP specific options. - # dhcpOptions: - # routeMetric: 1024 # The priority of all routes received via DHCP. - - # # Wireguard specific configuration. - - # # wireguard server example - # wireguard: - # privateKey: ABCDEF... # Specifies a private key configuration (base64 encoded). - # listenPort: 51111 # Specifies a device's listening port. - # # Specifies a list of peer configurations to apply to a device. - # peers: - # - publicKey: ABCDEF... # Specifies the public key of this peer. - # endpoint: 192.168.1.3 # Specifies the endpoint of this peer entry. - # # AllowedIPs specifies a list of allowed IP addresses in CIDR notation for this peer. - # allowedIPs: - # - 192.168.1.0/24 - # # wireguard peer example - # wireguard: - # privateKey: ABCDEF... # Specifies a private key configuration (base64 encoded). - # # Specifies a list of peer configurations to apply to a device. - # peers: - # - publicKey: ABCDEF... # Specifies the public key of this peer. - # endpoint: 192.168.1.2:51822 # Specifies the endpoint of this peer entry. - # persistentKeepaliveInterval: 10s # Specifies the persistent keepalive interval for this peer. - # # AllowedIPs specifies a list of allowed IP addresses in CIDR notation for this peer. - # allowedIPs: - # - 192.168.1.0/24 - - # # Virtual (shared) IP address configuration. - - # # layer2 vip example - # vip: - # ip: 172.16.199.55 # Specifies the IP address to be used. +machine: + install: + diskSelector: + size: '>= 1TB' # Disk size. + model: WDC* # Disk model `/sys/block//device/model`. + + # # Disk bus path. + # busPath: /pci0000:00/0000:00:17.0/ata1/host0/target0:0:0/0:0:0:0 + # busPath: /pci0000:00/* {{< /highlight >}} | Field | Type | Description | Value(s) | |-------|------|-------------|----------| -|`interface` |string |
The interface name.Mutually exclusive with `deviceSelector`.
Show example(s){{< highlight yaml >}} -interface: enp0s3 -{{< /highlight >}}
| | -|`deviceSelector` |NetworkDeviceSelector |
Picks a network device using the selector.Mutually exclusive with `interface`.
Supports partial match using wildcard syntax.
Show example(s){{< highlight yaml >}} -deviceSelector: - busPath: 00:* # PCI, USB bus prefix, supports matching by wildcard. +|`size` |InstallDiskSizeMatcher |Disk size.
Show example(s){{< highlight yaml >}} +size: 4GB {{< /highlight >}}{{< highlight yaml >}} -deviceSelector: - hardwareAddr: '*:f0:ab' # Device hardware address, supports matching by wildcard. - driver: virtio # Kernel driver, supports matching by wildcard. -{{< /highlight >}}
| | -|`addresses` |[]string |
Assigns static IP addresses to the interface.An address can be specified either in proper CIDR notation or as a standalone address (netmask of all ones is assumed).
Show example(s){{< highlight yaml >}} -addresses: - - 10.5.0.0/16 - - 192.168.3.7 +size: '> 1TB' +{{< /highlight >}}{{< highlight yaml >}} +size: <= 2TB {{< /highlight >}}
| | -|`routes` |[]Route |
A list of routes associated with the interface.If used in combination with DHCP, these routes will be appended to routes returned by DHCP server.
Show example(s){{< highlight yaml >}} -routes: - - network: 0.0.0.0/0 # The route's network (destination). - gateway: 10.5.0.1 # The route's gateway (if empty, creates link scope route). - - network: 10.2.0.0/16 # The route's network (destination). - gateway: 10.2.0.1 # The route's gateway (if empty, creates link scope route). +|`name` |string |Disk name `/sys/block//device/name`. | | +|`model` |string |Disk model `/sys/block//device/model`. | | +|`serial` |string |Disk serial number `/sys/block//serial`. | | +|`modalias` |string |Disk modalias `/sys/block//device/modalias`. | | +|`uuid` |string |Disk UUID `/sys/block//uuid`. | | +|`wwid` |string |Disk WWID `/sys/block//wwid`. | | +|`type` |InstallDiskType |Disk Type. |`ssd`
`hdd`
`nvme`
`sd`
| +|`busPath` |string |Disk bus path.
Show example(s){{< highlight yaml >}} +busPath: /pci0000:00/0000:00:17.0/ata1/host0/target0:0:0/0:0:0:0 +{{< /highlight >}}{{< highlight yaml >}} +busPath: /pci0000:00/* {{< /highlight >}}
| | -|`bond` |Bond |Bond specific options.
Show example(s){{< highlight yaml >}} -bond: - # The interfaces that make up the bond. - interfaces: - - enp2s0 - - enp2s1 - mode: 802.3ad # A bond option. - lacpRate: fast # A bond option. - # # Picks a network device using the selector. - # # select a device with bus prefix 00:*, a device with mac address matching `*:f0:ab` and `virtio` kernel driver. - # deviceSelectors: - # - busPath: 00:* # PCI, USB bus prefix, supports matching by wildcard. - # - hardwareAddr: '*:f0:ab' # Device hardware address, supports matching by wildcard. - # driver: virtio # Kernel driver, supports matching by wildcard. -{{< /highlight >}}
| | -|`bridge` |Bridge |Bridge specific options.
Show example(s){{< highlight yaml >}} -bridge: - # The interfaces that make up the bridge. - interfaces: - - enxda4042ca9a51 - - enxae2a6774c259 - # A bridge option. - stp: - enabled: true # Whether Spanning Tree Protocol (STP) is enabled. -{{< /highlight >}}
| | -|`vlans` |[]Vlan |VLAN specific options. | | -|`mtu` |int |
The interface's MTU.If used in combination with DHCP, this will override any MTU settings returned from DHCP server.
| | -|`dhcp` |bool |
Indicates if DHCP should be used to configure the interface.The following DHCP options are supported:

- `OptionClasslessStaticRoute`
- `OptionDomainNameServer`
- `OptionDNSDomainSearchList`
- `OptionHostName`
Show example(s){{< highlight yaml >}} -dhcp: true -{{< /highlight >}}
| | -|`ignore` |bool |Indicates if the interface should be ignored (skips configuration). | | -|`dummy` |bool |
Indicates if the interface is a dummy interface.`dummy` is used to specify that this interface should be a virtual-only, dummy interface.
| | -|`dhcpOptions` |DHCPOptions |
DHCP specific options.`dhcp` *must* be set to true for these to take effect.
Show example(s){{< highlight yaml >}} -dhcpOptions: - routeMetric: 1024 # The priority of all routes received via DHCP. -{{< /highlight >}}
| | -|`wireguard` |DeviceWireguardConfig |
Wireguard specific configuration.Includes things like private key, listen port, peers.
Show example(s){{< highlight yaml >}} -wireguard: - privateKey: ABCDEF... # Specifies a private key configuration (base64 encoded). - listenPort: 51111 # Specifies a device's listening port. - # Specifies a list of peer configurations to apply to a device. - peers: - - publicKey: ABCDEF... # Specifies the public key of this peer. - endpoint: 192.168.1.3 # Specifies the endpoint of this peer entry. - # AllowedIPs specifies a list of allowed IP addresses in CIDR notation for this peer. - allowedIPs: - - 192.168.1.0/24 -{{< /highlight >}}{{< highlight yaml >}} -wireguard: - privateKey: ABCDEF... # Specifies a private key configuration (base64 encoded). - # Specifies a list of peer configurations to apply to a device. - peers: - - publicKey: ABCDEF... # Specifies the public key of this peer. - endpoint: 192.168.1.2:51822 # Specifies the endpoint of this peer entry. - persistentKeepaliveInterval: 10s # Specifies the persistent keepalive interval for this peer. - # AllowedIPs specifies a list of allowed IP addresses in CIDR notation for this peer. - allowedIPs: - - 192.168.1.0/24 -{{< /highlight >}}
| | -|`vip` |DeviceVIPConfig |Virtual (shared) IP address configuration.
Show example(s){{< highlight yaml >}} -vip: - ip: 172.16.199.55 # Specifies the IP address to be used. -{{< /highlight >}}
| | ---- -## DHCPOptions -DHCPOptions contains options for configuring the DHCP settings for a given interface. -Appears in: +#### extensions[] {#Config.machine.install.extensions.} -- Device.dhcpOptions -- Vlan.dhcpOptions +InstallExtensionConfig represents a configuration for a system extension. {{< highlight yaml >}} -routeMetric: 1024 # The priority of all routes received via DHCP. +machine: + install: + extensions: + - image: ghcr.io/siderolabs/gvisor:20220117.0-v1.0.0 # System extension image. {{< /highlight >}} | Field | Type | Description | Value(s) | |-------|------|-------------|----------| -|`routeMetric` |uint32 |The priority of all routes received via DHCP. | | -|`ipv4` |bool |Enables DHCPv4 protocol for the interface (default is enabled). | | -|`ipv6` |bool |Enables DHCPv6 protocol for the interface (default is disabled). | | -|`duidv6` |string |Set client DUID (hex string). | | +|`image` |string |System extension image. | | ---- -## DeviceWireguardConfig -DeviceWireguardConfig contains settings for configuring Wireguard network interface. -Appears in: -- Device.wireguard -{{< highlight yaml >}} -privateKey: ABCDEF... # Specifies a private key configuration (base64 encoded). -listenPort: 51111 # Specifies a device's listening port. -# Specifies a list of peer configurations to apply to a device. -peers: - - publicKey: ABCDEF... # Specifies the public key of this peer. - endpoint: 192.168.1.3 # Specifies the endpoint of this peer entry. - # AllowedIPs specifies a list of allowed IP addresses in CIDR notation for this peer. - allowedIPs: - - 192.168.1.0/24 -{{< /highlight >}} +### files[] {#Config.machine.files.} + +MachineFile represents a file to write to disk. + + {{< highlight yaml >}} -privateKey: ABCDEF... # Specifies a private key configuration (base64 encoded). -# Specifies a list of peer configurations to apply to a device. -peers: - - publicKey: ABCDEF... # Specifies the public key of this peer. - endpoint: 192.168.1.2:51822 # Specifies the endpoint of this peer entry. - persistentKeepaliveInterval: 10s # Specifies the persistent keepalive interval for this peer. - # AllowedIPs specifies a list of allowed IP addresses in CIDR notation for this peer. - allowedIPs: - - 192.168.1.0/24 +machine: + files: + - content: '...' # The contents of the file. + permissions: 0o666 # The file's permissions in octal. + path: /tmp/file.txt # The path of the file. + op: append # The operation to use {{< /highlight >}} | Field | Type | Description | Value(s) | |-------|------|-------------|----------| -|`privateKey` |string |
Specifies a private key configuration (base64 encoded).Can be generated by `wg genkey`.
| | -|`listenPort` |int |Specifies a device's listening port. | | -|`firewallMark` |int |Specifies a device's firewall mark. | | -|`peers` |[]DeviceWireguardPeer |Specifies a list of peer configurations to apply to a device. | | +|`content` |string |The contents of the file. | | +|`permissions` |FileMode |The file's permissions in octal. | | +|`path` |string |The path of the file. | | +|`op` |string |The operation to use |`create`
`append`
`overwrite`
| ---- -## DeviceWireguardPeer -DeviceWireguardPeer a WireGuard device peer configuration. -Appears in: -- DeviceWireguardConfig.peers + +### time {#Config.machine.time} + +TimeConfig represents the options for configuring time on a machine. + +{{< highlight yaml >}} +machine: + time: + disabled: false # Indicates if the time service is disabled for the machine. + # Specifies time (NTP) servers to use for setting the system time. + servers: + - time.cloudflare.com + bootTimeout: 2m0s # Specifies the timeout when the node time is considered to be in sync unlocking the boot sequence. +{{< /highlight >}} | Field | Type | Description | Value(s) | |-------|------|-------------|----------| -|`publicKey` |string |
Specifies the public key of this peer.Can be extracted from private key by running `wg pubkey < private.key > public.key && cat public.key`.
| | -|`endpoint` |string |Specifies the endpoint of this peer entry. | | -|`persistentKeepaliveInterval` |Duration |
Specifies the persistent keepalive interval for this peer.Field format accepts any Go time.Duration format ('1h' for one hour, '10m' for ten minutes).
| | -|`allowedIPs` |[]string |AllowedIPs specifies a list of allowed IP addresses in CIDR notation for this peer. | | +|`disabled` |bool |
Indicates if the time service is disabled for the machine.Defaults to `false`.
| | +|`servers` |[]string |
Specifies time (NTP) servers to use for setting the system time.Defaults to `pool.ntp.org`
| | +|`bootTimeout` |Duration |
Specifies the timeout when the node time is considered to be in sync unlocking the boot sequence.NTP sync will be still running in the background.
Defaults to "infinity" (waiting forever for time sync)
| | ---- -## DeviceVIPConfig -DeviceVIPConfig contains settings for configuring a Virtual Shared IP on an interface. -Appears in: -- Device.vip -- Vlan.vip + +### registries {#Config.machine.registries} + +RegistriesConfig represents the image pull options. {{< highlight yaml >}} -ip: 172.16.199.55 # Specifies the IP address to be used. +machine: + registries: + # Specifies mirror configuration for each registry host namespace. + mirrors: + docker.io: + # List of endpoints (URLs) for registry mirrors to use. + endpoints: + - https://registry.local + # Specifies TLS & auth configuration for HTTPS image registries. + config: + registry.local: + # The TLS configuration for the registry. + tls: + # Enable mutual TLS authentication with the registry. + clientIdentity: + crt: LS0tIEVYQU1QTEUgQ0VSVElGSUNBVEUgLS0t + key: LS0tIEVYQU1QTEUgS0VZIC0tLQ== + # The auth configuration for this registry. + auth: + username: username # Optional registry authentication. + password: password # Optional registry authentication. {{< /highlight >}} | Field | Type | Description | Value(s) | |-------|------|-------------|----------| -|`ip` |string |Specifies the IP address to be used. | | -|`equinixMetal` |VIPEquinixMetalConfig |Specifies the Equinix Metal API settings to assign VIP to the node. | | -|`hcloud` |VIPHCloudConfig |Specifies the Hetzner Cloud API settings to assign VIP to the node. | | +|`mirrors` |map[string]RegistryMirrorConfig |
Specifies mirror configuration for each registry host namespace.This setting allows to configure local pull-through caching registires,
air-gapped installations, etc.

For example, when pulling an image with the reference `example.com:123/image:v1`,
the `example.com:123` key will be used to lookup the mirror configuration.

Optionally the `*` key can be used to configure a fallback mirror.

Registry name is the first segment of image identifier, with 'docker.io'
being default one.
Show example(s){{< highlight yaml >}} +mirrors: + ghcr.io: + # List of endpoints (URLs) for registry mirrors to use. + endpoints: + - https://registry.insecure + - https://ghcr.io/v2/ +{{< /highlight >}}
| | +|`config` |map[string]RegistryConfig |
Specifies TLS & auth configuration for HTTPS image registries.Mutual TLS can be enabled with 'clientIdentity' option.

The full hostname and port (if not using a default port 443)
should be used as the key.
The fallback key `*` can't be used for TLS configuration.

TLS configuration can be skipped if registry has trusted
server certificate.
Show example(s){{< highlight yaml >}} +config: + registry.insecure: + # The TLS configuration for the registry. + tls: + insecureSkipVerify: true # Skip TLS server certificate verification (not recommended). + + # # Enable mutual TLS authentication with the registry. + # clientIdentity: + # crt: LS0tIEVYQU1QTEUgQ0VSVElGSUNBVEUgLS0t + # key: LS0tIEVYQU1QTEUgS0VZIC0tLQ== + + # # The auth configuration for this registry. + # auth: + # username: username # Optional registry authentication. + # password: password # Optional registry authentication. +{{< /highlight >}}
| | ---- -## VIPEquinixMetalConfig -VIPEquinixMetalConfig contains settings for Equinix Metal VIP management. -Appears in: +#### mirrors.* {#Config.machine.registries.mirrors.-} + +RegistryMirrorConfig represents mirror configuration for a registry. -- DeviceVIPConfig.equinixMetal +{{< highlight yaml >}} +machine: + registries: + mirrors: + ghcr.io: + # List of endpoints (URLs) for registry mirrors to use. + endpoints: + - https://registry.insecure + - https://ghcr.io/v2/ +{{< /highlight >}} | Field | Type | Description | Value(s) | |-------|------|-------------|----------| -|`apiToken` |string |Specifies the Equinix Metal API Token. | | +|`endpoints` |[]string |
List of endpoints (URLs) for registry mirrors to use.Endpoint configures HTTP/HTTPS access mode, host name,
port and path (if path is not set, it defaults to `/v2`).
| | +|`overridePath` |bool |
Use the exact path specified for the endpoint (don't append /v2/).This setting is often required for setting up multiple mirrors
on a single instance of a registry.
| | ---- -## VIPHCloudConfig -VIPHCloudConfig contains settings for Hetzner Cloud VIP management. -Appears in: -- DeviceVIPConfig.hcloud +#### config.* {#Config.machine.registries.config.-} +RegistryConfig specifies auth & TLS config per registry. + + + +{{< highlight yaml >}} +machine: + registries: + config: + registry.insecure: + # The TLS configuration for the registry. + tls: + insecureSkipVerify: true # Skip TLS server certificate verification (not recommended). + + # # Enable mutual TLS authentication with the registry. + # clientIdentity: + # crt: LS0tIEVYQU1QTEUgQ0VSVElGSUNBVEUgLS0t + # key: LS0tIEVYQU1QTEUgS0VZIC0tLQ== + + # # The auth configuration for this registry. + # auth: + # username: username # Optional registry authentication. + # password: password # Optional registry authentication. +{{< /highlight >}} | Field | Type | Description | Value(s) | |-------|------|-------------|----------| -|`apiToken` |string |Specifies the Hetzner Cloud API Token. | | +|`tls` |RegistryTLSConfig |The TLS configuration for the registry.
Show example(s){{< highlight yaml >}} +tls: + # Enable mutual TLS authentication with the registry. + clientIdentity: + crt: LS0tIEVYQU1QTEUgQ0VSVElGSUNBVEUgLS0t + key: LS0tIEVYQU1QTEUgS0VZIC0tLQ== +{{< /highlight >}}{{< highlight yaml >}} +tls: + insecureSkipVerify: true # Skip TLS server certificate verification (not recommended). + + # # Enable mutual TLS authentication with the registry. + # clientIdentity: + # crt: LS0tIEVYQU1QTEUgQ0VSVElGSUNBVEUgLS0t + # key: LS0tIEVYQU1QTEUgS0VZIC0tLQ== +{{< /highlight >}}
| | +|`auth` |RegistryAuthConfig |
The auth configuration for this registry.Note: changes to the registry auth will not be picked up by the CRI containerd plugin without a reboot.
Show example(s){{< highlight yaml >}} +auth: + username: username # Optional registry authentication. + password: password # Optional registry authentication. +{{< /highlight >}}
| | ---- -## Bond -Bond contains the various options for configuring a bonded interface. -Appears in: +##### tls {#Config.machine.registries.config.-.tls} -- Device.bond +RegistryTLSConfig specifies TLS config for HTTPS registries. {{< highlight yaml >}} -# The interfaces that make up the bond. -interfaces: - - enp2s0 - - enp2s1 -mode: 802.3ad # A bond option. -lacpRate: fast # A bond option. - -# # Picks a network device using the selector. +machine: + registries: + config: + example.com: + tls: + # Enable mutual TLS authentication with the registry. + clientIdentity: + crt: LS0tIEVYQU1QTEUgQ0VSVElGSUNBVEUgLS0t + key: LS0tIEVYQU1QTEUgS0VZIC0tLQ== +{{< /highlight >}} -# # select a device with bus prefix 00:*, a device with mac address matching `*:f0:ab` and `virtio` kernel driver. -# deviceSelectors: -# - busPath: 00:* # PCI, USB bus prefix, supports matching by wildcard. -# - hardwareAddr: '*:f0:ab' # Device hardware address, supports matching by wildcard. -# driver: virtio # Kernel driver, supports matching by wildcard. +{{< highlight yaml >}} +machine: + registries: + config: + example.com: + tls: + insecureSkipVerify: true # Skip TLS server certificate verification (not recommended). + + # # Enable mutual TLS authentication with the registry. + # clientIdentity: + # crt: LS0tIEVYQU1QTEUgQ0VSVElGSUNBVEUgLS0t + # key: LS0tIEVYQU1QTEUgS0VZIC0tLQ== {{< /highlight >}} | Field | Type | Description | Value(s) | |-------|------|-------------|----------| -|`interfaces` |[]string |The interfaces that make up the bond. | | -|`deviceSelectors` |[]NetworkDeviceSelector |
Picks a network device using the selector.Mutually exclusive with `interfaces`.
Supports partial match using wildcard syntax.
Show example(s){{< highlight yaml >}} -deviceSelectors: - - busPath: 00:* # PCI, USB bus prefix, supports matching by wildcard. - - hardwareAddr: '*:f0:ab' # Device hardware address, supports matching by wildcard. - driver: virtio # Kernel driver, supports matching by wildcard. +|`clientIdentity` |PEMEncodedCertificateAndKey |
Enable mutual TLS authentication with the registry.Client certificate and key should be base64-encoded.
Show example(s){{< highlight yaml >}} +clientIdentity: + crt: LS0tIEVYQU1QTEUgQ0VSVElGSUNBVEUgLS0t + key: LS0tIEVYQU1QTEUgS0VZIC0tLQ== {{< /highlight >}}
| | -|`arpIPTarget` |[]string |
A bond option.Please see the official kernel documentation.
Not supported at the moment.
| | -|`mode` |string |
A bond option.Please see the official kernel documentation.
| | -|`xmitHashPolicy` |string |
A bond option.Please see the official kernel documentation.
| | -|`lacpRate` |string |
A bond option.Please see the official kernel documentation.
| | -|`adActorSystem` |string |
A bond option.Please see the official kernel documentation.
Not supported at the moment.
| | -|`arpValidate` |string |
A bond option.Please see the official kernel documentation.
| | -|`arpAllTargets` |string |
A bond option.Please see the official kernel documentation.
| | -|`primary` |string |
A bond option.Please see the official kernel documentation.
| | -|`primaryReselect` |string |
A bond option.Please see the official kernel documentation.
| | -|`failOverMac` |string |
A bond option.Please see the official kernel documentation.
| | -|`adSelect` |string |
A bond option.Please see the official kernel documentation.
| | -|`miimon` |uint32 |
A bond option.Please see the official kernel documentation.
| | -|`updelay` |uint32 |
A bond option.Please see the official kernel documentation.
| | -|`downdelay` |uint32 |
A bond option.Please see the official kernel documentation.
| | -|`arpInterval` |uint32 |
A bond option.Please see the official kernel documentation.
| | -|`resendIgmp` |uint32 |
A bond option.Please see the official kernel documentation.
| | -|`minLinks` |uint32 |
A bond option.Please see the official kernel documentation.
| | -|`lpInterval` |uint32 |
A bond option.Please see the official kernel documentation.
| | -|`packetsPerSlave` |uint32 |
A bond option.Please see the official kernel documentation.
| | -|`numPeerNotif` |uint8 |
A bond option.Please see the official kernel documentation.
| | -|`tlbDynamicLb` |uint8 |
A bond option.Please see the official kernel documentation.
| | -|`allSlavesActive` |uint8 |
A bond option.Please see the official kernel documentation.
| | -|`useCarrier` |bool |
A bond option.Please see the official kernel documentation.
| | -|`adActorSysPrio` |uint16 |
A bond option.Please see the official kernel documentation.
| | -|`adUserPortKey` |uint16 |
A bond option.Please see the official kernel documentation.
| | -|`peerNotifyDelay` |uint32 |
A bond option.Please see the official kernel documentation.
| | +|`ca` |Base64Bytes |
CA registry certificate to add the list of trusted certificates.Certificate should be base64-encoded.
| | +|`insecureSkipVerify` |bool |Skip TLS server certificate verification (not recommended). | | + + ---- -## STP -STP contains the various options for configuring the STP properties of a bridge interface. -Appears in: +##### auth {#Config.machine.registries.config.-.auth} + +RegistryAuthConfig specifies authentication configuration for a registry. -- Bridge.stp +{{< highlight yaml >}} +machine: + registries: + config: + example.com: + auth: + username: username # Optional registry authentication. + password: password # Optional registry authentication. +{{< /highlight >}} | Field | Type | Description | Value(s) | |-------|------|-------------|----------| -|`enabled` |bool |Whether Spanning Tree Protocol (STP) is enabled. | | +|`username` |string |
Optional registry authentication.The meaning of each field is the same with the corresponding field in [`.docker/config.json`](https://docs.docker.com/engine/api/v1.41/#section/Authentication).
| | +|`password` |string |
Optional registry authentication.The meaning of each field is the same with the corresponding field in [`.docker/config.json`](https://docs.docker.com/engine/api/v1.41/#section/Authentication).
| | +|`auth` |string |
Optional registry authentication.The meaning of each field is the same with the corresponding field in [`.docker/config.json`](https://docs.docker.com/engine/api/v1.41/#section/Authentication).
| | +|`identityToken` |string |
Optional registry authentication.The meaning of each field is the same with the corresponding field in [`.docker/config.json`](https://docs.docker.com/engine/api/v1.41/#section/Authentication).
| | ---- -## Bridge -Bridge contains the various options for configuring a bridge interface. -Appears in: -- Device.bridge + + + + + +### systemDiskEncryption {#Config.machine.systemDiskEncryption} + +SystemDiskEncryptionConfig specifies system disk partitions encryption settings. {{< highlight yaml >}} -# The interfaces that make up the bridge. -interfaces: - - enxda4042ca9a51 - - enxae2a6774c259 -# A bridge option. -stp: - enabled: true # Whether Spanning Tree Protocol (STP) is enabled. +machine: + systemDiskEncryption: + # Ephemeral partition encryption. + ephemeral: + provider: luks2 # Encryption provider to use for the encryption. + # Defines the encryption keys generation and storage method. + keys: + - # Deterministically generated key from the node UUID and PartitionLabel. + nodeID: {} + slot: 0 # Key slot number for LUKS2 encryption. + + # # KMS managed encryption key. + # kms: + # endpoint: https://192.168.88.21:4443 # KMS endpoint to Seal/Unseal the key. + + # # Cipher kind to use for the encryption. Depends on the encryption provider. + # cipher: aes-xts-plain64 + + # # Defines the encryption sector size. + # blockSize: 4096 + + # # Additional --perf parameters for the LUKS2 encryption. + # options: + # - no_read_workqueue + # - no_write_workqueue {{< /highlight >}} | Field | Type | Description | Value(s) | |-------|------|-------------|----------| -|`interfaces` |[]string |The interfaces that make up the bridge. | | -|`stp` |STP |
A bridge option.Please see the official kernel documentation.
| | +|`state` |EncryptionConfig |State partition encryption. | | +|`ephemeral` |EncryptionConfig |Ephemeral partition encryption. | | ---- -## Vlan -Vlan represents vlan settings for a device. -Appears in: +#### state {#Config.machine.systemDiskEncryption.state} -- Device.vlans +EncryptionConfig represents partition encryption settings. | Field | Type | Description | Value(s) | |-------|------|-------------|----------| -|`addresses` |[]string |The addresses in CIDR notation or as plain IPs to use. | | -|`routes` |[]Route |A list of routes associated with the VLAN. | | -|`dhcp` |bool |Indicates if DHCP should be used. | | -|`vlanId` |uint16 |The VLAN's ID. | | -|`mtu` |uint32 |The VLAN's MTU. | | -|`vip` |DeviceVIPConfig |The VLAN's virtual IP address configuration. | | -|`dhcpOptions` |DHCPOptions |
DHCP specific options.`dhcp` *must* be set to true for these to take effect.
| | +|`provider` |string |Encryption provider to use for the encryption.
Show example(s){{< highlight yaml >}} +provider: luks2 +{{< /highlight >}}
| | +|`keys` |[]EncryptionKey |Defines the encryption keys generation and storage method. | | +|`cipher` |string |Cipher kind to use for the encryption. Depends on the encryption provider.
Show example(s){{< highlight yaml >}} +cipher: aes-xts-plain64 +{{< /highlight >}}
|`aes-xts-plain64`
`xchacha12,aes-adiantum-plain64`
`xchacha20,aes-adiantum-plain64`
| +|`keySize` |uint |Defines the encryption key length. | | +|`blockSize` |uint64 |Defines the encryption sector size.
Show example(s){{< highlight yaml >}} +blockSize: 4096 +{{< /highlight >}}
| | +|`options` |[]string |Additional --perf parameters for the LUKS2 encryption.
Show example(s){{< highlight yaml >}} +options: + - no_read_workqueue + - no_write_workqueue +{{< /highlight >}}
|`no_read_workqueue`
`no_write_workqueue`
`same_cpu_crypt`
| ---- -## Route -Route represents a network route. -Appears in: +##### keys[] {#Config.machine.systemDiskEncryption.state.keys.} -- Device.routes -- Vlan.routes +EncryptionKey represents configuration for disk encryption key. -{{< highlight yaml >}} -- network: 0.0.0.0/0 # The route's network (destination). - gateway: 10.5.0.1 # The route's gateway (if empty, creates link scope route). -- network: 10.2.0.0/16 # The route's network (destination). - gateway: 10.2.0.1 # The route's gateway (if empty, creates link scope route). -{{< /highlight >}} + +| Field | Type | Description | Value(s) | +|-------|------|-------------|----------| +|`static` |EncryptionKeyStatic |Key which value is stored in the configuration file. | | +|`nodeID` |EncryptionKeyNodeID |Deterministically generated key from the node UUID and PartitionLabel. | | +|`kms` |EncryptionKeyKMS |KMS managed encryption key.
Show example(s){{< highlight yaml >}} +kms: + endpoint: https://192.168.88.21:4443 # KMS endpoint to Seal/Unseal the key. +{{< /highlight >}}
| | +|`slot` |int |Key slot number for LUKS2 encryption. | | +|`tpm` |EncryptionKeyTPM |Enable TPM based disk encryption. | | + + + + +###### static {#Config.machine.systemDiskEncryption.state.keys..static} + +EncryptionKeyStatic represents throw away key type. + + | Field | Type | Description | Value(s) | |-------|------|-------------|----------| -|`network` |string |The route's network (destination). | | -|`gateway` |string |The route's gateway (if empty, creates link scope route). | | -|`source` |string |The route's source address (optional). | | -|`metric` |uint32 |The optional metric for the route. | | -|`mtu` |uint32 |The optional MTU for the route. | | +|`passphrase` |string |Defines the static passphrase value. | | + + + + + + +###### nodeID {#Config.machine.systemDiskEncryption.state.keys..nodeID} + +EncryptionKeyNodeID represents deterministically generated key from the node UUID and PartitionLabel. + + + + + ---- -## RegistryMirrorConfig -RegistryMirrorConfig represents mirror configuration for a registry. -Appears in: +###### kms {#Config.machine.systemDiskEncryption.state.keys..kms} -- RegistriesConfig.mirrors +EncryptionKeyKMS represents a key that is generated and then sealed/unsealed by the KMS server. {{< highlight yaml >}} -ghcr.io: - # List of endpoints (URLs) for registry mirrors to use. - endpoints: - - https://registry.insecure - - https://ghcr.io/v2/ +machine: + systemDiskEncryption: + state: + keys: + - kms: + endpoint: https://192.168.88.21:4443 # KMS endpoint to Seal/Unseal the key. {{< /highlight >}} | Field | Type | Description | Value(s) | |-------|------|-------------|----------| -|`endpoints` |[]string |
List of endpoints (URLs) for registry mirrors to use.Endpoint configures HTTP/HTTPS access mode, host name,
port and path (if path is not set, it defaults to `/v2`).
| | -|`overridePath` |bool |
Use the exact path specified for the endpoint (don't append /v2/).This setting is often required for setting up multiple mirrors
on a single instance of a registry.
| | +|`endpoint` |string |KMS endpoint to Seal/Unseal the key. | | + + + + + + +###### tpm {#Config.machine.systemDiskEncryption.state.keys..tpm} + +EncryptionKeyTPM represents a key that is generated and then sealed/unsealed by the TPM. ---- -## RegistryConfig -RegistryConfig specifies auth & TLS config per registry. -Appears in: -- RegistriesConfig.config -{{< highlight yaml >}} -registry.insecure: - # The TLS configuration for the registry. - tls: - insecureSkipVerify: true # Skip TLS server certificate verification (not recommended). - # # Enable mutual TLS authentication with the registry. - # clientIdentity: - # crt: LS0tIEVYQU1QTEUgQ0VSVElGSUNBVEUgLS0t - # key: LS0tIEVYQU1QTEUgS0VZIC0tLQ== - # # The auth configuration for this registry. - # auth: - # username: username # Optional registry authentication. - # password: password # Optional registry authentication. -{{< /highlight >}} + + + +#### ephemeral {#Config.machine.systemDiskEncryption.ephemeral} + +EncryptionConfig represents partition encryption settings. + + | Field | Type | Description | Value(s) | |-------|------|-------------|----------| -|`tls` |RegistryTLSConfig |The TLS configuration for the registry.
Show example(s){{< highlight yaml >}} -tls: - # Enable mutual TLS authentication with the registry. - clientIdentity: - crt: LS0tIEVYQU1QTEUgQ0VSVElGSUNBVEUgLS0t - key: LS0tIEVYQU1QTEUgS0VZIC0tLQ== -{{< /highlight >}}{{< highlight yaml >}} -tls: - insecureSkipVerify: true # Skip TLS server certificate verification (not recommended). - - # # Enable mutual TLS authentication with the registry. - # clientIdentity: - # crt: LS0tIEVYQU1QTEUgQ0VSVElGSUNBVEUgLS0t - # key: LS0tIEVYQU1QTEUgS0VZIC0tLQ== +|`provider` |string |Encryption provider to use for the encryption.
Show example(s){{< highlight yaml >}} +provider: luks2 {{< /highlight >}}
| | -|`auth` |RegistryAuthConfig |
The auth configuration for this registry.Note: changes to the registry auth will not be picked up by the CRI containerd plugin without a reboot.
Show example(s){{< highlight yaml >}} -auth: - username: username # Optional registry authentication. - password: password # Optional registry authentication. +|`keys` |[]EncryptionKey |Defines the encryption keys generation and storage method. | | +|`cipher` |string |Cipher kind to use for the encryption. Depends on the encryption provider.
Show example(s){{< highlight yaml >}} +cipher: aes-xts-plain64 +{{< /highlight >}}
|`aes-xts-plain64`
`xchacha12,aes-adiantum-plain64`
`xchacha20,aes-adiantum-plain64`
| +|`keySize` |uint |Defines the encryption key length. | | +|`blockSize` |uint64 |Defines the encryption sector size.
Show example(s){{< highlight yaml >}} +blockSize: 4096 {{< /highlight >}}
| | +|`options` |[]string |Additional --perf parameters for the LUKS2 encryption.
Show example(s){{< highlight yaml >}} +options: + - no_read_workqueue + - no_write_workqueue +{{< /highlight >}}
|`no_read_workqueue`
`no_write_workqueue`
`same_cpu_crypt`
| ---- -## RegistryAuthConfig -RegistryAuthConfig specifies authentication configuration for a registry. -Appears in: +##### keys[] {#Config.machine.systemDiskEncryption.ephemeral.keys.} -- RegistryConfig.auth +EncryptionKey represents configuration for disk encryption key. -{{< highlight yaml >}} -username: username # Optional registry authentication. -password: password # Optional registry authentication. -{{< /highlight >}} + +| Field | Type | Description | Value(s) | +|-------|------|-------------|----------| +|`static` |EncryptionKeyStatic |Key which value is stored in the configuration file. | | +|`nodeID` |EncryptionKeyNodeID |Deterministically generated key from the node UUID and PartitionLabel. | | +|`kms` |EncryptionKeyKMS |KMS managed encryption key.
Show example(s){{< highlight yaml >}} +kms: + endpoint: https://192.168.88.21:4443 # KMS endpoint to Seal/Unseal the key. +{{< /highlight >}}
| | +|`slot` |int |Key slot number for LUKS2 encryption. | | +|`tpm` |EncryptionKeyTPM |Enable TPM based disk encryption. | | + + + + +###### static {#Config.machine.systemDiskEncryption.ephemeral.keys..static} + +EncryptionKeyStatic represents throw away key type. + + | Field | Type | Description | Value(s) | |-------|------|-------------|----------| -|`username` |string |
Optional registry authentication.The meaning of each field is the same with the corresponding field in [`.docker/config.json`](https://docs.docker.com/engine/api/v1.41/#section/Authentication).
| | -|`password` |string |
Optional registry authentication.The meaning of each field is the same with the corresponding field in [`.docker/config.json`](https://docs.docker.com/engine/api/v1.41/#section/Authentication).
| | -|`auth` |string |
Optional registry authentication.The meaning of each field is the same with the corresponding field in [`.docker/config.json`](https://docs.docker.com/engine/api/v1.41/#section/Authentication).
| | -|`identityToken` |string |
Optional registry authentication.The meaning of each field is the same with the corresponding field in [`.docker/config.json`](https://docs.docker.com/engine/api/v1.41/#section/Authentication).
| | +|`passphrase` |string |Defines the static passphrase value. | | + + + + + + +###### nodeID {#Config.machine.systemDiskEncryption.ephemeral.keys..nodeID} + +EncryptionKeyNodeID represents deterministically generated key from the node UUID and PartitionLabel. + ---- -## RegistryTLSConfig -RegistryTLSConfig specifies TLS config for HTTPS registries. -Appears in: -- RegistryConfig.tls + + + +###### kms {#Config.machine.systemDiskEncryption.ephemeral.keys..kms} + +EncryptionKeyKMS represents a key that is generated and then sealed/unsealed by the KMS server. {{< highlight yaml >}} -# Enable mutual TLS authentication with the registry. -clientIdentity: - crt: LS0tIEVYQU1QTEUgQ0VSVElGSUNBVEUgLS0t - key: LS0tIEVYQU1QTEUgS0VZIC0tLQ== +machine: + systemDiskEncryption: + ephemeral: + keys: + - kms: + endpoint: https://192.168.88.21:4443 # KMS endpoint to Seal/Unseal the key. {{< /highlight >}} -{{< highlight yaml >}} -insecureSkipVerify: true # Skip TLS server certificate verification (not recommended). -# # Enable mutual TLS authentication with the registry. -# clientIdentity: -# crt: LS0tIEVYQU1QTEUgQ0VSVElGSUNBVEUgLS0t -# key: LS0tIEVYQU1QTEUgS0VZIC0tLQ== +| Field | Type | Description | Value(s) | +|-------|------|-------------|----------| +|`endpoint` |string |KMS endpoint to Seal/Unseal the key. | | + + + + + + +###### tpm {#Config.machine.systemDiskEncryption.ephemeral.keys..tpm} + +EncryptionKeyTPM represents a key that is generated and then sealed/unsealed by the TPM. + + + + + + + + + + + + + + + +### features {#Config.machine.features} + +FeaturesConfig describes individual Talos features that can be switched on or off. + + + +{{< highlight yaml >}} +machine: + features: + rbac: true # Enable role-based access control (RBAC). + + # # Configure Talos API access from Kubernetes pods. + # kubernetesTalosAPIAccess: + # enabled: true # Enable Talos API access from Kubernetes pods. + # # The list of Talos API roles which can be granted for access from Kubernetes pods. + # allowedRoles: + # - os:reader + # # The list of Kubernetes namespaces Talos API access is available from. + # allowedKubernetesNamespaces: + # - kube-system {{< /highlight >}} | Field | Type | Description | Value(s) | |-------|------|-------------|----------| -|`clientIdentity` |PEMEncodedCertificateAndKey |
Enable mutual TLS authentication with the registry.Client certificate and key should be base64-encoded.
Show example(s){{< highlight yaml >}} -clientIdentity: - crt: LS0tIEVYQU1QTEUgQ0VSVElGSUNBVEUgLS0t - key: LS0tIEVYQU1QTEUgS0VZIC0tLQ== +|`rbac` |bool |Enable role-based access control (RBAC). | | +|`stableHostname` |bool |Enable stable default hostname. | | +|`kubernetesTalosAPIAccess` |KubernetesTalosAPIAccessConfig |
Configure Talos API access from Kubernetes pods.
This feature is disabled if the feature config is not specified.
Show example(s){{< highlight yaml >}} +kubernetesTalosAPIAccess: + enabled: true # Enable Talos API access from Kubernetes pods. + # The list of Talos API roles which can be granted for access from Kubernetes pods. + allowedRoles: + - os:reader + # The list of Kubernetes namespaces Talos API access is available from. + allowedKubernetesNamespaces: + - kube-system {{< /highlight >}}
| | -|`ca` |Base64Bytes |
CA registry certificate to add the list of trusted certificates.Certificate should be base64-encoded.
| | -|`insecureSkipVerify` |bool |Skip TLS server certificate verification (not recommended). | | +|`apidCheckExtKeyUsage` |bool |Enable checks for extended key usage of client certificates in apid. | | +|`diskQuotaSupport` |bool |
Enable XFS project quota support for EPHEMERAL partition and user disks.Also enables kubelet tracking of ephemeral disk usage in the kubelet via quota.
| | +|`kubePrism` |KubePrism |
KubePrism - local proxy/load balancer on defined port that will distributerequests to all API servers in the cluster.
| | + + + + +#### kubernetesTalosAPIAccess {#Config.machine.features.kubernetesTalosAPIAccess} + +KubernetesTalosAPIAccessConfig describes the configuration for the Talos API access from Kubernetes pods. + + + +{{< highlight yaml >}} +machine: + features: + kubernetesTalosAPIAccess: + enabled: true # Enable Talos API access from Kubernetes pods. + # The list of Talos API roles which can be granted for access from Kubernetes pods. + allowedRoles: + - os:reader + # The list of Kubernetes namespaces Talos API access is available from. + allowedKubernetesNamespaces: + - kube-system +{{< /highlight >}} + + +| Field | Type | Description | Value(s) | +|-------|------|-------------|----------| +|`enabled` |bool |Enable Talos API access from Kubernetes pods. | | +|`allowedRoles` |[]string |
The list of Talos API roles which can be granted for access from Kubernetes pods.
Empty list means that no roles can be granted, so access is blocked.
| | +|`allowedKubernetesNamespaces` |[]string |The list of Kubernetes namespaces Talos API access is available from. | | + + + + + + +#### kubePrism {#Config.machine.features.kubePrism} + +KubePrism describes the configuration for the KubePrism load balancer. + + + + +| Field | Type | Description | Value(s) | +|-------|------|-------------|----------| +|`enabled` |bool |Enable KubePrism support - will start local load balacing proxy. | | +|`port` |int |KubePrism port. | | + + + + + + + + +### udev {#Config.machine.udev} + +UdevConfig describes how the udev system should be configured. + + + +{{< highlight yaml >}} +machine: + udev: + # List of udev rules to apply to the udev system + rules: + - SUBSYSTEM=="drm", KERNEL=="renderD*", GROUP="44", MODE="0660" +{{< /highlight >}} + + +| Field | Type | Description | Value(s) | +|-------|------|-------------|----------| +|`rules` |[]string |List of udev rules to apply to the udev system | | + + + + + + +### logging {#Config.machine.logging} + +LoggingConfig struct configures Talos logging. + + + +{{< highlight yaml >}} +machine: + logging: + # Logging destination. + destinations: + - endpoint: tcp://1.2.3.4:12345 # Where to send logs. Supported protocols are "tcp" and "udp". + format: json_lines # Logs format. +{{< /highlight >}} + + +| Field | Type | Description | Value(s) | +|-------|------|-------------|----------| +|`destinations` |[]LoggingDestination |Logging destination. | | + + + + +#### destinations[] {#Config.machine.logging.destinations.} + +LoggingDestination struct configures Talos logging destination. + + + + +| Field | Type | Description | Value(s) | +|-------|------|-------------|----------| +|`endpoint` |Endpoint |Where to send logs. Supported protocols are "tcp" and "udp".
Show example(s){{< highlight yaml >}} +endpoint: udp://127.0.0.1:12345 +{{< /highlight >}}{{< highlight yaml >}} +endpoint: tcp://1.2.3.4:12345 +{{< /highlight >}}
| | +|`format` |string |Logs format. |`json_lines`
| + + + + +##### endpoint {#Config.machine.logging.destinations..endpoint} + +Endpoint represents the endpoint URL parsed out of the machine config. + + + +{{< highlight yaml >}} +machine: + logging: + destinations: + - endpoint: https://1.2.3.4:6443 +{{< /highlight >}} + +{{< highlight yaml >}} +machine: + logging: + destinations: + - endpoint: https://cluster1.internal:6443 +{{< /highlight >}} + +{{< highlight yaml >}} +machine: + logging: + destinations: + - endpoint: udp://127.0.0.1:12345 +{{< /highlight >}} + +{{< highlight yaml >}} +machine: + logging: + destinations: + - endpoint: tcp://1.2.3.4:12345 +{{< /highlight >}} + + +| Field | Type | Description | Value(s) | +|-------|------|-------------|----------| + + + + + + + + + + +### kernel {#Config.machine.kernel} + +KernelConfig struct configures Talos Linux kernel. + + + +{{< highlight yaml >}} +machine: + kernel: + # Kernel modules to load. + modules: + - name: brtfs # Module name. +{{< /highlight >}} + + +| Field | Type | Description | Value(s) | +|-------|------|-------------|----------| +|`modules` |[]KernelModuleConfig |Kernel modules to load. | | + + + + +#### modules[] {#Config.machine.kernel.modules.} + +KernelModuleConfig struct configures Linux kernel modules to load. + + + + +| Field | Type | Description | Value(s) | +|-------|------|-------------|----------| +|`name` |string |Module name. | | +|`parameters` |[]string |Module parameters, changes applied after reboot. | | + + + + + + + + +### seccompProfiles[] {#Config.machine.seccompProfiles.} + +MachineSeccompProfile defines seccomp profiles for the machine. + + + +{{< highlight yaml >}} +machine: + seccompProfiles: + - name: audit.json # The `name` field is used to provide the file name of the seccomp profile. + # The `value` field is used to provide the seccomp profile. + value: + defaultAction: SCMP_ACT_LOG +{{< /highlight >}} + + +| Field | Type | Description | Value(s) | +|-------|------|-------------|----------| +|`name` |string |The `name` field is used to provide the file name of the seccomp profile. | | +|`value` |Unstructured |The `value` field is used to provide the seccomp profile. | | + + + + + + + + +## cluster {#Config.cluster} + +ClusterConfig represents the cluster-wide config values. + + + +{{< highlight yaml >}} +cluster: + # ControlPlaneConfig represents the control plane configuration options. + controlPlane: + endpoint: https://1.2.3.4 # Endpoint is the canonical controlplane endpoint, which can be an IP address or a DNS hostname. + localAPIServerPort: 443 # The port that the API server listens on internally. + clusterName: talos.local + # ClusterNetworkConfig represents kube networking configuration options. + network: + # The CNI used. + cni: + name: flannel # Name of CNI to use. + dnsDomain: cluster.local # The domain used by Kubernetes DNS. + # The pod subnet CIDR. + podSubnets: + - 10.244.0.0/16 + # The service subnet CIDR. + serviceSubnets: + - 10.96.0.0/12 +{{< /highlight >}} + + +| Field | Type | Description | Value(s) | +|-------|------|-------------|----------| +|`id` |string |Globally unique identifier for this cluster (base64 encoded random 32 bytes). | | +|`secret` |string |
Shared secret of cluster (base64 encoded random 32 bytes).This secret is shared among cluster members but should never be sent over the network.
| | +|`controlPlane` |ControlPlaneConfig |Provides control plane specific configuration options.
Show example(s){{< highlight yaml >}} +controlPlane: + endpoint: https://1.2.3.4 # Endpoint is the canonical controlplane endpoint, which can be an IP address or a DNS hostname. + localAPIServerPort: 443 # The port that the API server listens on internally. +{{< /highlight >}}
| | +|`clusterName` |string |Configures the cluster's name. | | +|`network` |ClusterNetworkConfig |Provides cluster specific network configuration options.
Show example(s){{< highlight yaml >}} +network: + # The CNI used. + cni: + name: flannel # Name of CNI to use. + dnsDomain: cluster.local # The domain used by Kubernetes DNS. + # The pod subnet CIDR. + podSubnets: + - 10.244.0.0/16 + # The service subnet CIDR. + serviceSubnets: + - 10.96.0.0/12 +{{< /highlight >}}
| | +|`token` |string |The [bootstrap token](https://kubernetes.io/docs/reference/access-authn-authz/bootstrap-tokens/) used to join the cluster.
Show example(s){{< highlight yaml >}} +token: wlzjyw.bei2zfylhs2by0wd +{{< /highlight >}}
| | +|`aescbcEncryptionSecret` |string |
A key used for the [encryption of secret data at rest](https://kubernetes.io/docs/tasks/administer-cluster/encrypt-data/).Enables encryption with AESCBC.
Show example(s){{< highlight yaml >}} +aescbcEncryptionSecret: z01mye6j16bspJYtTB/5SFX8j7Ph4JXxM2Xuu4vsBPM= +{{< /highlight >}}
| | +|`secretboxEncryptionSecret` |string |
A key used for the [encryption of secret data at rest](https://kubernetes.io/docs/tasks/administer-cluster/encrypt-data/).Enables encryption with secretbox.
Secretbox has precedence over AESCBC.
Show example(s){{< highlight yaml >}} +secretboxEncryptionSecret: z01mye6j16bspJYtTB/5SFX8j7Ph4JXxM2Xuu4vsBPM= +{{< /highlight >}}
| | +|`ca` |PEMEncodedCertificateAndKey |The base64 encoded root certificate authority used by Kubernetes.
Show example(s){{< highlight yaml >}} +ca: + crt: LS0tIEVYQU1QTEUgQ0VSVElGSUNBVEUgLS0t + key: LS0tIEVYQU1QTEUgS0VZIC0tLQ== +{{< /highlight >}}
| | +|`aggregatorCA` |PEMEncodedCertificateAndKey |
The base64 encoded aggregator certificate authority used by Kubernetes for front-proxy certificate generation.
This CA can be self-signed.
Show example(s){{< highlight yaml >}} +aggregatorCA: + crt: LS0tIEVYQU1QTEUgQ0VSVElGSUNBVEUgLS0t + key: LS0tIEVYQU1QTEUgS0VZIC0tLQ== +{{< /highlight >}}
| | +|`serviceAccount` |PEMEncodedKey |The base64 encoded private key for service account token generation.
Show example(s){{< highlight yaml >}} +serviceAccount: + key: LS0tIEVYQU1QTEUgS0VZIC0tLQ== +{{< /highlight >}}
| | +|`apiServer` |APIServerConfig |API server specific configuration options.
Show example(s){{< highlight yaml >}} +apiServer: + image: registry.k8s.io/kube-apiserver:v1.29.0-rc.1 # The container image used in the API server manifest. + # Extra arguments to supply to the API server. + extraArgs: + feature-gates: ServerSideApply=true + http2-max-streams-per-connection: "32" + # Extra certificate subject alternative names for the API server's certificate. + certSANs: + - 1.2.3.4 + - 4.5.6.7 + + # # Configure the API server admission plugins. + # admissionControl: + # - name: PodSecurity # Name is the name of the admission controller. + # # Configuration is an embedded configuration object to be used as the plugin's + # configuration: + # apiVersion: pod-security.admission.config.k8s.io/v1alpha1 + # defaults: + # audit: restricted + # audit-version: latest + # enforce: baseline + # enforce-version: latest + # warn: restricted + # warn-version: latest + # exemptions: + # namespaces: + # - kube-system + # runtimeClasses: [] + # usernames: [] + # kind: PodSecurityConfiguration + + # # Configure the API server audit policy. + # auditPolicy: + # apiVersion: audit.k8s.io/v1 + # kind: Policy + # rules: + # - level: Metadata +{{< /highlight >}}
| | +|`controllerManager` |ControllerManagerConfig |Controller manager server specific configuration options.
Show example(s){{< highlight yaml >}} +controllerManager: + image: registry.k8s.io/kube-controller-manager:v1.29.0-rc.1 # The container image used in the controller manager manifest. + # Extra arguments to supply to the controller manager. + extraArgs: + feature-gates: ServerSideApply=true +{{< /highlight >}}
| | +|`proxy` |ProxyConfig |Kube-proxy server-specific configuration options
Show example(s){{< highlight yaml >}} +proxy: + image: registry.k8s.io/kube-proxy:v1.29.0-rc.1 # The container image used in the kube-proxy manifest. + mode: ipvs # proxy mode of kube-proxy. + # Extra arguments to supply to kube-proxy. + extraArgs: + proxy-mode: iptables + + # # Disable kube-proxy deployment on cluster bootstrap. + # disabled: false +{{< /highlight >}}
| | +|`scheduler` |SchedulerConfig |Scheduler server specific configuration options.
Show example(s){{< highlight yaml >}} +scheduler: + image: registry.k8s.io/kube-scheduler:v1.29.0-rc.1 # The container image used in the scheduler manifest. + # Extra arguments to supply to the scheduler. + extraArgs: + feature-gates: AllBeta=true +{{< /highlight >}}
| | +|`discovery` |ClusterDiscoveryConfig |Configures cluster member discovery.
Show example(s){{< highlight yaml >}} +discovery: + enabled: true # Enable the cluster membership discovery feature. + # Configure registries used for cluster member discovery. + registries: + # Kubernetes registry uses Kubernetes API server to discover cluster members and stores additional information + kubernetes: {} + # Service registry is using an external service to push and pull information about cluster members. + service: + endpoint: https://discovery.talos.dev/ # External service endpoint. +{{< /highlight >}}
| | +|`etcd` |EtcdConfig |Etcd specific configuration options.
Show example(s){{< highlight yaml >}} +etcd: + image: gcr.io/etcd-development/etcd:v3.5.11 # The container image used to create the etcd service. + # The `ca` is the root certificate authority of the PKI. + ca: + crt: LS0tIEVYQU1QTEUgQ0VSVElGSUNBVEUgLS0t + key: LS0tIEVYQU1QTEUgS0VZIC0tLQ== + # Extra arguments to supply to etcd. + extraArgs: + election-timeout: "5000" + + # # The `advertisedSubnets` field configures the networks to pick etcd advertised IP from. + # advertisedSubnets: + # - 10.0.0.0/8 +{{< /highlight >}}
| | +|`coreDNS` |CoreDNS |Core DNS specific configuration options.
Show example(s){{< highlight yaml >}} +coreDNS: + image: registry.k8s.io/coredns/coredns:v1.11.1 # The `image` field is an override to the default coredns image. +{{< /highlight >}}
| | +|`externalCloudProvider` |ExternalCloudProviderConfig |External cloud provider configuration.
Show example(s){{< highlight yaml >}} +externalCloudProvider: + enabled: true # Enable external cloud provider. + # A list of urls that point to additional manifests for an external cloud provider. + manifests: + - https://raw.githubusercontent.com/kubernetes/cloud-provider-aws/v1.20.0-alpha.0/manifests/rbac.yaml + - https://raw.githubusercontent.com/kubernetes/cloud-provider-aws/v1.20.0-alpha.0/manifests/aws-cloud-controller-manager-daemonset.yaml +{{< /highlight >}}
| | +|`extraManifests` |[]string |
A list of urls that point to additional manifests.These will get automatically deployed as part of the bootstrap.
Show example(s){{< highlight yaml >}} +extraManifests: + - https://www.example.com/manifest1.yaml + - https://www.example.com/manifest2.yaml +{{< /highlight >}}
| | +|`extraManifestHeaders` |map[string]string |A map of key value pairs that will be added while fetching the extraManifests.
Show example(s){{< highlight yaml >}} +extraManifestHeaders: + Token: "1234567" + X-ExtraInfo: info +{{< /highlight >}}
| | +|`inlineManifests` |[]ClusterInlineManifest |
A list of inline Kubernetes manifests.These will get automatically deployed as part of the bootstrap.
Show example(s){{< highlight yaml >}} +inlineManifests: + - name: namespace-ci # Name of the manifest. + contents: |- # Manifest contents as a string. + apiVersion: v1 + kind: Namespace + metadata: + name: ci +{{< /highlight >}}
| | +|`adminKubeconfig` |AdminKubeconfigConfig |
Settings for admin kubeconfig generation.Certificate lifetime can be configured.
Show example(s){{< highlight yaml >}} +adminKubeconfig: + certLifetime: 1h0m0s # Admin kubeconfig certificate lifetime (default is 1 year). +{{< /highlight >}}
| | +|`allowSchedulingOnControlPlanes` |bool |Allows running workload on control-plane nodes.
Show example(s){{< highlight yaml >}} +allowSchedulingOnControlPlanes: true +{{< /highlight >}}
|`true`
`yes`
`false`
`no`
| + + + + +### controlPlane {#Config.cluster.controlPlane} + +ControlPlaneConfig represents the control plane configuration options. + + + +{{< highlight yaml >}} +cluster: + controlPlane: + endpoint: https://1.2.3.4 # Endpoint is the canonical controlplane endpoint, which can be an IP address or a DNS hostname. + localAPIServerPort: 443 # The port that the API server listens on internally. +{{< /highlight >}} + + +| Field | Type | Description | Value(s) | +|-------|------|-------------|----------| +|`endpoint` |Endpoint |
Endpoint is the canonical controlplane endpoint, which can be an IP address or a DNS hostname.It is single-valued, and may optionally include a port number.
Show example(s){{< highlight yaml >}} +endpoint: https://1.2.3.4:6443 +{{< /highlight >}}{{< highlight yaml >}} +endpoint: https://cluster1.internal:6443 +{{< /highlight >}}
| | +|`localAPIServerPort` |int |
The port that the API server listens on internally.This may be different than the port portion listed in the endpoint field above.
The default is `6443`.
| | + + + + +#### endpoint {#Config.cluster.controlPlane.endpoint} + +Endpoint represents the endpoint URL parsed out of the machine config. + + + +{{< highlight yaml >}} +cluster: + controlPlane: + endpoint: https://1.2.3.4:6443 +{{< /highlight >}} + +{{< highlight yaml >}} +cluster: + controlPlane: + endpoint: https://cluster1.internal:6443 +{{< /highlight >}} + +{{< highlight yaml >}} +cluster: + controlPlane: + endpoint: udp://127.0.0.1:12345 +{{< /highlight >}} + +{{< highlight yaml >}} +cluster: + controlPlane: + endpoint: tcp://1.2.3.4:12345 +{{< /highlight >}} + + +| Field | Type | Description | Value(s) | +|-------|------|-------------|----------| + + + + + + + + +### network {#Config.cluster.network} + +ClusterNetworkConfig represents kube networking configuration options. + + + +{{< highlight yaml >}} +cluster: + network: + # The CNI used. + cni: + name: flannel # Name of CNI to use. + dnsDomain: cluster.local # The domain used by Kubernetes DNS. + # The pod subnet CIDR. + podSubnets: + - 10.244.0.0/16 + # The service subnet CIDR. + serviceSubnets: + - 10.96.0.0/12 +{{< /highlight >}} + + +| Field | Type | Description | Value(s) | +|-------|------|-------------|----------| +|`cni` |CNIConfig |
The CNI used.Composed of "name" and "urls".
The "name" key supports the following options: "flannel", "custom", and "none".
"flannel" uses Talos-managed Flannel CNI, and that's the default option.
"custom" uses custom manifests that should be provided in "urls".
"none" indicates that Talos will not manage any CNI installation.
Show example(s){{< highlight yaml >}} +cni: + name: custom # Name of CNI to use. + # URLs containing manifests to apply for the CNI. + urls: + - https://docs.projectcalico.org/archive/v3.20/manifests/canal.yaml +{{< /highlight >}}
| | +|`dnsDomain` |string |
The domain used by Kubernetes DNS.The default is `cluster.local`
Show example(s){{< highlight yaml >}} +dnsDomain: cluser.local +{{< /highlight >}}
| | +|`podSubnets` |[]string |The pod subnet CIDR.
Show example(s){{< highlight yaml >}} +podSubnets: + - 10.244.0.0/16 +{{< /highlight >}}
| | +|`serviceSubnets` |[]string |The service subnet CIDR.
Show example(s){{< highlight yaml >}} +serviceSubnets: + - 10.96.0.0/12 +{{< /highlight >}}
| | + + + + +#### cni {#Config.cluster.network.cni} + +CNIConfig represents the CNI configuration options. + + + +{{< highlight yaml >}} +cluster: + network: + cni: + name: custom # Name of CNI to use. + # URLs containing manifests to apply for the CNI. + urls: + - https://docs.projectcalico.org/archive/v3.20/manifests/canal.yaml +{{< /highlight >}} + + +| Field | Type | Description | Value(s) | +|-------|------|-------------|----------| +|`name` |string |Name of CNI to use. |`flannel`
`custom`
`none`
| +|`urls` |[]string |
URLs containing manifests to apply for the CNI.Should be present for "custom", must be empty for "flannel" and "none".
| | +|`flannel` |FlannelCNIConfig |
description: |Flannel configuration options.
| | + + + + +##### flannel {#Config.cluster.network.cni.flannel} + +FlannelCNIConfig represents the Flannel CNI configuration options. + + + + +| Field | Type | Description | Value(s) | +|-------|------|-------------|----------| +|`extraArgs` |[]string |Extra arguments for 'flanneld'.
Show example(s){{< highlight yaml >}} +extraArgs: + - --iface-can-reach=192.168.1.1 +{{< /highlight >}}
| | + + + + + + + + +### apiServer {#Config.cluster.apiServer} + +APIServerConfig represents the kube apiserver configuration options. + + + +{{< highlight yaml >}} +cluster: + apiServer: + image: registry.k8s.io/kube-apiserver:v1.29.0-rc.1 # The container image used in the API server manifest. + # Extra arguments to supply to the API server. + extraArgs: + feature-gates: ServerSideApply=true + http2-max-streams-per-connection: "32" + # Extra certificate subject alternative names for the API server's certificate. + certSANs: + - 1.2.3.4 + - 4.5.6.7 + + # # Configure the API server admission plugins. + # admissionControl: + # - name: PodSecurity # Name is the name of the admission controller. + # # Configuration is an embedded configuration object to be used as the plugin's + # configuration: + # apiVersion: pod-security.admission.config.k8s.io/v1alpha1 + # defaults: + # audit: restricted + # audit-version: latest + # enforce: baseline + # enforce-version: latest + # warn: restricted + # warn-version: latest + # exemptions: + # namespaces: + # - kube-system + # runtimeClasses: [] + # usernames: [] + # kind: PodSecurityConfiguration + + # # Configure the API server audit policy. + # auditPolicy: + # apiVersion: audit.k8s.io/v1 + # kind: Policy + # rules: + # - level: Metadata +{{< /highlight >}} + + +| Field | Type | Description | Value(s) | +|-------|------|-------------|----------| +|`image` |string |The container image used in the API server manifest.
Show example(s){{< highlight yaml >}} +image: registry.k8s.io/kube-apiserver:v1.29.0-rc.1 +{{< /highlight >}}
| | +|`extraArgs` |map[string]string |Extra arguments to supply to the API server. | | +|`extraVolumes` |[]VolumeMountConfig |Extra volumes to mount to the API server static pod. | | +|`env` |Env |The `env` field allows for the addition of environment variables for the control plane component. | | +|`certSANs` |[]string |Extra certificate subject alternative names for the API server's certificate. | | +|`disablePodSecurityPolicy` |bool |Disable PodSecurityPolicy in the API server and default manifests. | | +|`admissionControl` |[]AdmissionPluginConfig |Configure the API server admission plugins.
Show example(s){{< highlight yaml >}} +admissionControl: + - name: PodSecurity # Name is the name of the admission controller. + # Configuration is an embedded configuration object to be used as the plugin's + configuration: + apiVersion: pod-security.admission.config.k8s.io/v1alpha1 + defaults: + audit: restricted + audit-version: latest + enforce: baseline + enforce-version: latest + warn: restricted + warn-version: latest + exemptions: + namespaces: + - kube-system + runtimeClasses: [] + usernames: [] + kind: PodSecurityConfiguration +{{< /highlight >}}
| | +|`auditPolicy` |Unstructured |Configure the API server audit policy.
Show example(s){{< highlight yaml >}} +auditPolicy: + apiVersion: audit.k8s.io/v1 + kind: Policy + rules: + - level: Metadata +{{< /highlight >}}
| | +|`resources` |ResourcesConfig |Configure the API server resources. | | + + + + +#### extraVolumes[] {#Config.cluster.apiServer.extraVolumes.} + +VolumeMountConfig struct describes extra volume mount for the static pods. + + + + +| Field | Type | Description | Value(s) | +|-------|------|-------------|----------| +|`hostPath` |string |Path on the host.
Show example(s){{< highlight yaml >}} +hostPath: /var/lib/auth +{{< /highlight >}}
| | +|`mountPath` |string |Path in the container.
Show example(s){{< highlight yaml >}} +mountPath: /etc/kubernetes/auth +{{< /highlight >}}
| | +|`readonly` |bool |Mount the volume read only.
Show example(s){{< highlight yaml >}} +readonly: true +{{< /highlight >}}
| | ---- -## SystemDiskEncryptionConfig -SystemDiskEncryptionConfig specifies system disk partitions encryption settings. -Appears in: -- MachineConfig.systemDiskEncryption -{{< highlight yaml >}} -# Ephemeral partition encryption. -ephemeral: - provider: luks2 # Encryption provider to use for the encryption. - # Defines the encryption keys generation and storage method. - keys: - - # Deterministically generated key from the node UUID and PartitionLabel. - nodeID: {} - slot: 0 # Key slot number for LUKS2 encryption. +#### admissionControl[] {#Config.cluster.apiServer.admissionControl.} - # # KMS managed encryption key. - # kms: - # endpoint: https://192.168.88.21:4443 # KMS endpoint to Seal/Unseal the key. +AdmissionPluginConfig represents the API server admission plugin configuration. - # # Cipher kind to use for the encryption. Depends on the encryption provider. - # cipher: aes-xts-plain64 - # # Defines the encryption sector size. - # blockSize: 4096 - # # Additional --perf parameters for the LUKS2 encryption. - # options: - # - no_read_workqueue - # - no_write_workqueue +{{< highlight yaml >}} +cluster: + apiServer: + admissionControl: + - name: PodSecurity # Name is the name of the admission controller. + # Configuration is an embedded configuration object to be used as the plugin's + configuration: + apiVersion: pod-security.admission.config.k8s.io/v1alpha1 + defaults: + audit: restricted + audit-version: latest + enforce: baseline + enforce-version: latest + warn: restricted + warn-version: latest + exemptions: + namespaces: + - kube-system + runtimeClasses: [] + usernames: [] + kind: PodSecurityConfiguration {{< /highlight >}} | Field | Type | Description | Value(s) | |-------|------|-------------|----------| -|`state` |EncryptionConfig |State partition encryption. | | -|`ephemeral` |EncryptionConfig |Ephemeral partition encryption. | | +|`name` |string |
Name is the name of the admission controller.It must match the registered admission plugin name.
| | +|`configuration` |Unstructured |
Configuration is an embedded configuration object to be used as the plugin'sconfiguration.
| | ---- -## FeaturesConfig -FeaturesConfig describes individual Talos features that can be switched on or off. -Appears in: -- MachineConfig.features +#### resources {#Config.cluster.apiServer.resources} +ResourcesConfig represents the pod resources. -{{< highlight yaml >}} -rbac: true # Enable role-based access control (RBAC). -# # Configure Talos API access from Kubernetes pods. -# kubernetesTalosAPIAccess: -# enabled: true # Enable Talos API access from Kubernetes pods. -# # The list of Talos API roles which can be granted for access from Kubernetes pods. -# allowedRoles: -# - os:reader -# # The list of Kubernetes namespaces Talos API access is available from. -# allowedKubernetesNamespaces: -# - kube-system -{{< /highlight >}} | Field | Type | Description | Value(s) | |-------|------|-------------|----------| -|`rbac` |bool |Enable role-based access control (RBAC). | | -|`stableHostname` |bool |Enable stable default hostname. | | -|`kubernetesTalosAPIAccess` |KubernetesTalosAPIAccessConfig |
Configure Talos API access from Kubernetes pods.
This feature is disabled if the feature config is not specified.
Show example(s){{< highlight yaml >}} -kubernetesTalosAPIAccess: - enabled: true # Enable Talos API access from Kubernetes pods. - # The list of Talos API roles which can be granted for access from Kubernetes pods. - allowedRoles: - - os:reader - # The list of Kubernetes namespaces Talos API access is available from. - allowedKubernetesNamespaces: - - kube-system +|`requests` |Unstructured |Requests configures the reserved cpu/memory resources.
Show example(s){{< highlight yaml >}} +requests: + cpu: 1 + memory: 1Gi +{{< /highlight >}}
| | +|`limits` |Unstructured |Limits configures the maximum cpu/memory resources a container can use.
Show example(s){{< highlight yaml >}} +limits: + cpu: 2 + memory: 2500Mi {{< /highlight >}}
| | -|`apidCheckExtKeyUsage` |bool |Enable checks for extended key usage of client certificates in apid. | | -|`diskQuotaSupport` |bool |
Enable XFS project quota support for EPHEMERAL partition and user disks.Also enables kubelet tracking of ephemeral disk usage in the kubelet via quota.
| | -|`kubePrism` |KubePrism |
KubePrism - local proxy/load balancer on defined port that will distributerequests to all API servers in the cluster.
| | - - - ---- -## KubePrism -KubePrism describes the configuration for the KubePrism load balancer. - -Appears in: - -- FeaturesConfig.kubePrism -| Field | Type | Description | Value(s) | -|-------|------|-------------|----------| -|`enabled` |bool |Enable KubePrism support - will start local load balacing proxy. | | -|`port` |int |KubePrism port. | | ---- -## KubernetesTalosAPIAccessConfig -KubernetesTalosAPIAccessConfig describes the configuration for the Talos API access from Kubernetes pods. -Appears in: +### controllerManager {#Config.cluster.controllerManager} -- FeaturesConfig.kubernetesTalosAPIAccess +ControllerManagerConfig represents the kube controller manager configuration options. {{< highlight yaml >}} -enabled: true # Enable Talos API access from Kubernetes pods. -# The list of Talos API roles which can be granted for access from Kubernetes pods. -allowedRoles: - - os:reader -# The list of Kubernetes namespaces Talos API access is available from. -allowedKubernetesNamespaces: - - kube-system +cluster: + controllerManager: + image: registry.k8s.io/kube-controller-manager:v1.29.0-rc.1 # The container image used in the controller manager manifest. + # Extra arguments to supply to the controller manager. + extraArgs: + feature-gates: ServerSideApply=true {{< /highlight >}} | Field | Type | Description | Value(s) | |-------|------|-------------|----------| -|`enabled` |bool |Enable Talos API access from Kubernetes pods. | | -|`allowedRoles` |[]string |
The list of Talos API roles which can be granted for access from Kubernetes pods.
Empty list means that no roles can be granted, so access is blocked.
| | -|`allowedKubernetesNamespaces` |[]string |The list of Kubernetes namespaces Talos API access is available from. | | +|`image` |string |The container image used in the controller manager manifest.
Show example(s){{< highlight yaml >}} +image: registry.k8s.io/kube-controller-manager:v1.29.0-rc.1 +{{< /highlight >}}
| | +|`extraArgs` |map[string]string |Extra arguments to supply to the controller manager. | | +|`extraVolumes` |[]VolumeMountConfig |Extra volumes to mount to the controller manager static pod. | | +|`env` |Env |The `env` field allows for the addition of environment variables for the control plane component. | | +|`resources` |ResourcesConfig |Configure the controller manager resources. | | ---- -## VolumeMountConfig -VolumeMountConfig struct describes extra volume mount for the static pods. -Appears in: +#### extraVolumes[] {#Config.cluster.controllerManager.extraVolumes.} -- APIServerConfig.extraVolumes -- ControllerManagerConfig.extraVolumes -- SchedulerConfig.extraVolumes +VolumeMountConfig struct describes extra volume mount for the static pods. @@ -2960,162 +3381,199 @@ readonly: true ---- -## ClusterInlineManifest -ClusterInlineManifest struct describes inline bootstrap manifests for the user. +#### resources {#Config.cluster.controllerManager.resources} + +ResourcesConfig represents the pod resources. + + | Field | Type | Description | Value(s) | |-------|------|-------------|----------| -|`name` |string |
Name of the manifest.Name should be unique.
Show example(s){{< highlight yaml >}} -name: csi +|`requests` |Unstructured |Requests configures the reserved cpu/memory resources.
Show example(s){{< highlight yaml >}} +requests: + cpu: 1 + memory: 1Gi {{< /highlight >}}
| | -|`contents` |string |Manifest contents as a string.
Show example(s){{< highlight yaml >}} -contents: /etc/kubernetes/auth +|`limits` |Unstructured |Limits configures the maximum cpu/memory resources a container can use.
Show example(s){{< highlight yaml >}} +limits: + cpu: 2 + memory: 2500Mi {{< /highlight >}}
| | ---- -## NetworkKubeSpan -NetworkKubeSpan struct describes KubeSpan configuration. -Appears in: -- NetworkConfig.kubespan + + + +### proxy {#Config.cluster.proxy} + +ProxyConfig represents the kube proxy configuration options. {{< highlight yaml >}} -enabled: true # Enable the KubeSpan feature. +cluster: + proxy: + image: registry.k8s.io/kube-proxy:v1.29.0-rc.1 # The container image used in the kube-proxy manifest. + mode: ipvs # proxy mode of kube-proxy. + # Extra arguments to supply to kube-proxy. + extraArgs: + proxy-mode: iptables + + # # Disable kube-proxy deployment on cluster bootstrap. + # disabled: false {{< /highlight >}} | Field | Type | Description | Value(s) | |-------|------|-------------|----------| -|`enabled` |bool |
Enable the KubeSpan feature.Cluster discovery should be enabled with .cluster.discovery.enabled for KubeSpan to be enabled.
| | -|`advertiseKubernetesNetworks` |bool |
Control whether Kubernetes pod CIDRs are announced over KubeSpan from the node.If disabled, CNI handles encapsulating pod-to-pod traffic into some node-to-node tunnel,
and KubeSpan handles the node-to-node traffic.
If enabled, KubeSpan will take over pod-to-pod traffic and send it over KubeSpan directly.
When enabled, KubeSpan should have a way to detect complete pod CIDRs of the node which
is not always the case with CNIs not relying on Kubernetes for IPAM.
| | -|`allowDownPeerBypass` |bool |
Skip sending traffic via KubeSpan if the peer connection state is not up.This provides configurable choice between connectivity and security: either traffic is always
forced to go via KubeSpan (even if Wireguard peer connection is not up), or traffic can go directly
to the peer if Wireguard connection can't be established.
| | -|`mtu` |uint32 |
KubeSpan link MTU size.Default value is 1420.
| | -|`filters` |KubeSpanFilters |
KubeSpan advanced filtering of network addresses .
Settings in this section are optional, and settings apply only to the node.
| | +|`disabled` |bool |Disable kube-proxy deployment on cluster bootstrap.
Show example(s){{< highlight yaml >}} +disabled: false +{{< /highlight >}}
| | +|`image` |string |The container image used in the kube-proxy manifest.
Show example(s){{< highlight yaml >}} +image: registry.k8s.io/kube-proxy:v1.29.0-rc.1 +{{< /highlight >}}
| | +|`mode` |string |
proxy mode of kube-proxy.The default is 'iptables'.
| | +|`extraArgs` |map[string]string |Extra arguments to supply to kube-proxy. | | + ---- -## KubeSpanFilters -KubeSpanFilters struct describes KubeSpan advanced network addresses filtering. -Appears in: -- NetworkKubeSpan.filters +### scheduler {#Config.cluster.scheduler} + +SchedulerConfig represents the kube scheduler configuration options. +{{< highlight yaml >}} +cluster: + scheduler: + image: registry.k8s.io/kube-scheduler:v1.29.0-rc.1 # The container image used in the scheduler manifest. + # Extra arguments to supply to the scheduler. + extraArgs: + feature-gates: AllBeta=true +{{< /highlight >}} + | Field | Type | Description | Value(s) | |-------|------|-------------|----------| -|`endpoints` |[]string |
Filter node addresses which will be advertised as KubeSpan endpoints for peer-to-peer Wireguard connections.
By default, all addresses are advertised, and KubeSpan cycles through all endpoints until it finds one that works.

Default value: no filtering.
Show example(s){{< highlight yaml >}} -endpoints: - - 0.0.0.0/0 - - '!192.168.0.0/16' - - ::/0 +|`image` |string |The container image used in the scheduler manifest.
Show example(s){{< highlight yaml >}} +image: registry.k8s.io/kube-scheduler:v1.29.0-rc.1 {{< /highlight >}}
| | +|`extraArgs` |map[string]string |Extra arguments to supply to the scheduler. | | +|`extraVolumes` |[]VolumeMountConfig |Extra volumes to mount to the scheduler static pod. | | +|`env` |Env |The `env` field allows for the addition of environment variables for the control plane component. | | +|`resources` |ResourcesConfig |Configure the scheduler resources. | | +|`config` |Unstructured |Specify custom kube-scheduler configuration. | | ---- -## NetworkDeviceSelector -NetworkDeviceSelector struct describes network device selector. -Appears in: +#### extraVolumes[] {#Config.cluster.scheduler.extraVolumes.} -- Device.deviceSelector -- Bond.deviceSelectors +VolumeMountConfig struct describes extra volume mount for the static pods. -{{< highlight yaml >}} -busPath: 00:* # PCI, USB bus prefix, supports matching by wildcard. -{{< /highlight >}} -{{< highlight yaml >}} -hardwareAddr: '*:f0:ab' # Device hardware address, supports matching by wildcard. -driver: virtio # Kernel driver, supports matching by wildcard. -{{< /highlight >}} +| Field | Type | Description | Value(s) | +|-------|------|-------------|----------| +|`hostPath` |string |Path on the host.
Show example(s){{< highlight yaml >}} +hostPath: /var/lib/auth +{{< /highlight >}}
| | +|`mountPath` |string |Path in the container.
Show example(s){{< highlight yaml >}} +mountPath: /etc/kubernetes/auth +{{< /highlight >}}
| | +|`readonly` |bool |Mount the volume read only.
Show example(s){{< highlight yaml >}} +readonly: true +{{< /highlight >}}
| | + + + + + + +#### resources {#Config.cluster.scheduler.resources} + +ResourcesConfig represents the pod resources. + -{{< highlight yaml >}} -- busPath: 00:* # PCI, USB bus prefix, supports matching by wildcard. -- hardwareAddr: '*:f0:ab' # Device hardware address, supports matching by wildcard. - driver: virtio # Kernel driver, supports matching by wildcard. -{{< /highlight >}} | Field | Type | Description | Value(s) | |-------|------|-------------|----------| -|`busPath` |string |PCI, USB bus prefix, supports matching by wildcard. | | -|`hardwareAddr` |string |Device hardware address, supports matching by wildcard. | | -|`pciID` |string |PCI ID (vendor ID, product ID), supports matching by wildcard. | | -|`driver` |string |Kernel driver, supports matching by wildcard. | | +|`requests` |Unstructured |Requests configures the reserved cpu/memory resources.
Show example(s){{< highlight yaml >}} +requests: + cpu: 1 + memory: 1Gi +{{< /highlight >}}
| | +|`limits` |Unstructured |Limits configures the maximum cpu/memory resources a container can use.
Show example(s){{< highlight yaml >}} +limits: + cpu: 2 + memory: 2500Mi +{{< /highlight >}}
| | + + + ---- -## ClusterDiscoveryConfig -ClusterDiscoveryConfig struct configures cluster membership discovery. -Appears in: -- ClusterConfig.discovery +### discovery {#Config.cluster.discovery} + +ClusterDiscoveryConfig struct configures cluster membership discovery. {{< highlight yaml >}} -enabled: true # Enable the cluster membership discovery feature. -# Configure registries used for cluster member discovery. -registries: - # Kubernetes registry uses Kubernetes API server to discover cluster members and stores additional information - kubernetes: {} - # Service registry is using an external service to push and pull information about cluster members. - service: - endpoint: https://discovery.talos.dev/ # External service endpoint. +cluster: + discovery: + enabled: true # Enable the cluster membership discovery feature. + # Configure registries used for cluster member discovery. + registries: + # Kubernetes registry uses Kubernetes API server to discover cluster members and stores additional information + kubernetes: {} + # Service registry is using an external service to push and pull information about cluster members. + service: + endpoint: https://discovery.talos.dev/ # External service endpoint. {{< /highlight >}} | Field | Type | Description | Value(s) | |-------|------|-------------|----------| |`enabled` |bool |
Enable the cluster membership discovery feature.Cluster discovery is based on individual registries which are configured under the registries field.
| | -|`registries` |DiscoveryRegistriesConfig |Configure registries used for cluster member discovery. | | +|`registries` |DiscoveryRegistriesConfig |Configure registries used for cluster member discovery. | | ---- -## DiscoveryRegistriesConfig -DiscoveryRegistriesConfig struct configures cluster membership discovery. -Appears in: +#### registries {#Config.cluster.discovery.registries} -- ClusterDiscoveryConfig.registries +DiscoveryRegistriesConfig struct configures cluster membership discovery. | Field | Type | Description | Value(s) | |-------|------|-------------|----------| -|`kubernetes` |RegistryKubernetesConfig |
Kubernetes registry uses Kubernetes API server to discover cluster members and stores additional informationas annotations on the Node resources.
| | -|`service` |RegistryServiceConfig |Service registry is using an external service to push and pull information about cluster members. | | +|`kubernetes` |RegistryKubernetesConfig |
Kubernetes registry uses Kubernetes API server to discover cluster members and stores additional informationas annotations on the Node resources.
| | +|`service` |RegistryServiceConfig |Service registry is using an external service to push and pull information about cluster members. | | ---- -## RegistryKubernetesConfig -RegistryKubernetesConfig struct configures Kubernetes discovery registry. -Appears in: +##### kubernetes {#Config.cluster.discovery.registries.kubernetes} -- DiscoveryRegistriesConfig.kubernetes +RegistryKubernetesConfig struct configures Kubernetes discovery registry. @@ -3126,13 +3584,12 @@ Appears in: ---- -## RegistryServiceConfig -RegistryServiceConfig struct configures Kubernetes discovery registry. -Appears in: -- DiscoveryRegistriesConfig.service + +##### service {#Config.cluster.discovery.registries.service} + +RegistryServiceConfig struct configures Kubernetes discovery registry. @@ -3146,112 +3603,168 @@ endpoint: https://discovery.talos.dev/ ---- -## UdevConfig -UdevConfig describes how the udev system should be configured. -Appears in: -- MachineConfig.udev + + + + + +### etcd {#Config.cluster.etcd} + +EtcdConfig represents the etcd configuration options. {{< highlight yaml >}} -# List of udev rules to apply to the udev system -rules: - - SUBSYSTEM=="drm", KERNEL=="renderD*", GROUP="44", MODE="0660" +cluster: + etcd: + image: gcr.io/etcd-development/etcd:v3.5.11 # The container image used to create the etcd service. + # The `ca` is the root certificate authority of the PKI. + ca: + crt: LS0tIEVYQU1QTEUgQ0VSVElGSUNBVEUgLS0t + key: LS0tIEVYQU1QTEUgS0VZIC0tLQ== + # Extra arguments to supply to etcd. + extraArgs: + election-timeout: "5000" + + # # The `advertisedSubnets` field configures the networks to pick etcd advertised IP from. + # advertisedSubnets: + # - 10.0.0.0/8 {{< /highlight >}} | Field | Type | Description | Value(s) | |-------|------|-------------|----------| -|`rules` |[]string |List of udev rules to apply to the udev system | | +|`image` |string |The container image used to create the etcd service.
Show example(s){{< highlight yaml >}} +image: gcr.io/etcd-development/etcd:v3.5.11 +{{< /highlight >}}
| | +|`ca` |PEMEncodedCertificateAndKey |
The `ca` is the root certificate authority of the PKI.It is composed of a base64 encoded `crt` and `key`.
Show example(s){{< highlight yaml >}} +ca: + crt: LS0tIEVYQU1QTEUgQ0VSVElGSUNBVEUgLS0t + key: LS0tIEVYQU1QTEUgS0VZIC0tLQ== +{{< /highlight >}}
| | +|`extraArgs` |map[string]string |
Extra arguments to supply to etcd.Note that the following args are not allowed:

- `name`
- `data-dir`
- `initial-cluster-state`
- `listen-peer-urls`
- `listen-client-urls`
- `cert-file`
- `key-file`
- `trusted-ca-file`
- `peer-client-cert-auth`
- `peer-cert-file`
- `peer-trusted-ca-file`
- `peer-key-file`
| | +|`advertisedSubnets` |[]string |
The `advertisedSubnets` field configures the networks to pick etcd advertised IP from.
IPs can be excluded from the list by using negative match with `!`, e.g `!10.0.0.0/8`.
Negative subnet matches should be specified last to filter out IPs picked by positive matches.
If not specified, advertised IP is selected as the first routable address of the node.
Show example(s){{< highlight yaml >}} +advertisedSubnets: + - 10.0.0.0/8 +{{< /highlight >}}
| | +|`listenSubnets` |[]string |
The `listenSubnets` field configures the networks for the etcd to listen for peer and client connections.
If `listenSubnets` is not set, but `advertisedSubnets` is set, `listenSubnets` defaults to
`advertisedSubnets`.

If neither `advertisedSubnets` nor `listenSubnets` is set, `listenSubnets` defaults to listen on all addresses.

IPs can be excluded from the list by using negative match with `!`, e.g `!10.0.0.0/8`.
Negative subnet matches should be specified last to filter out IPs picked by positive matches.
If not specified, advertised IP is selected as the first routable address of the node.
| | ---- -## LoggingConfig -LoggingConfig struct configures Talos logging. -Appears in: -- MachineConfig.logging + +### coreDNS {#Config.cluster.coreDNS} + +CoreDNS represents the CoreDNS config values. {{< highlight yaml >}} -# Logging destination. -destinations: - - endpoint: tcp://1.2.3.4:12345 # Where to send logs. Supported protocols are "tcp" and "udp". - format: json_lines # Logs format. +cluster: + coreDNS: + image: registry.k8s.io/coredns/coredns:v1.11.1 # The `image` field is an override to the default coredns image. {{< /highlight >}} | Field | Type | Description | Value(s) | |-------|------|-------------|----------| -|`destinations` |[]LoggingDestination |Logging destination. | | +|`disabled` |bool |Disable coredns deployment on cluster bootstrap. | | +|`image` |string |The `image` field is an override to the default coredns image. | | + ---- -## LoggingDestination -LoggingDestination struct configures Talos logging destination. -Appears in: -- LoggingConfig.destinations +### externalCloudProvider {#Config.cluster.externalCloudProvider} + +ExternalCloudProviderConfig contains external cloud provider configuration. +{{< highlight yaml >}} +cluster: + externalCloudProvider: + enabled: true # Enable external cloud provider. + # A list of urls that point to additional manifests for an external cloud provider. + manifests: + - https://raw.githubusercontent.com/kubernetes/cloud-provider-aws/v1.20.0-alpha.0/manifests/rbac.yaml + - https://raw.githubusercontent.com/kubernetes/cloud-provider-aws/v1.20.0-alpha.0/manifests/aws-cloud-controller-manager-daemonset.yaml +{{< /highlight >}} + | Field | Type | Description | Value(s) | |-------|------|-------------|----------| -|`endpoint` |Endpoint |Where to send logs. Supported protocols are "tcp" and "udp".
Show example(s){{< highlight yaml >}} -endpoint: udp://127.0.0.1:12345 -{{< /highlight >}}{{< highlight yaml >}} -endpoint: tcp://1.2.3.4:12345 +|`enabled` |bool |Enable external cloud provider. |`true`
`yes`
`false`
`no`
| +|`manifests` |[]string |
A list of urls that point to additional manifests for an external cloud provider.These will get automatically deployed as part of the bootstrap.
Show example(s){{< highlight yaml >}} +manifests: + - https://raw.githubusercontent.com/kubernetes/cloud-provider-aws/v1.20.0-alpha.0/manifests/rbac.yaml + - https://raw.githubusercontent.com/kubernetes/cloud-provider-aws/v1.20.0-alpha.0/manifests/aws-cloud-controller-manager-daemonset.yaml {{< /highlight >}}
| | -|`format` |string |Logs format. |`json_lines`
| ---- -## KernelConfig -KernelConfig struct configures Talos Linux kernel. -Appears in: -- MachineConfig.kernel + +### inlineManifests[] {#Config.cluster.inlineManifests.} + +ClusterInlineManifest struct describes inline bootstrap manifests for the user. {{< highlight yaml >}} -# Kernel modules to load. -modules: - - name: brtfs # Module name. +cluster: + inlineManifests: + - name: namespace-ci # Name of the manifest. + contents: |- # Manifest contents as a string. + apiVersion: v1 + kind: Namespace + metadata: + name: ci {{< /highlight >}} | Field | Type | Description | Value(s) | |-------|------|-------------|----------| -|`modules` |[]KernelModuleConfig |Kernel modules to load. | | +|`name` |string |
Name of the manifest.Name should be unique.
Show example(s){{< highlight yaml >}} +name: csi +{{< /highlight >}}
| | +|`contents` |string |Manifest contents as a string.
Show example(s){{< highlight yaml >}} +contents: /etc/kubernetes/auth +{{< /highlight >}}
| | + ---- -## KernelModuleConfig -KernelModuleConfig struct configures Linux kernel modules to load. -Appears in: -- KernelConfig.modules +### adminKubeconfig {#Config.cluster.adminKubeconfig} + +AdminKubeconfigConfig contains admin kubeconfig settings. +{{< highlight yaml >}} +cluster: + adminKubeconfig: + certLifetime: 1h0m0s # Admin kubeconfig certificate lifetime (default is 1 year). +{{< /highlight >}} + | Field | Type | Description | Value(s) | |-------|------|-------------|----------| -|`name` |string |Module name. | | -|`parameters` |[]string |Module parameters, changes applied after reboot. | | +|`certLifetime` |Duration |
Admin kubeconfig certificate lifetime (default is 1 year).Field format accepts any Go time.Duration format ('1h' for one hour, '10m' for ten minutes).
| | + + + + + + + + diff --git a/website/content/v1.6/schemas/v1alpha1_config.schema.json b/website/content/v1.6/schemas/v1alpha1_config.schema.json index fc1acacd2c..78f3149203 100644 --- a/website/content/v1.6/schemas/v1alpha1_config.schema.json +++ b/website/content/v1.6/schemas/v1alpha1_config.schema.json @@ -701,12 +701,6 @@ "markdownDescription": "Enable verbose logging to the console.\nAll system containers logs will flow into serial console.\n\n**Note:** To avoid breaking Talos bootstrap flow enable this option only if serial console can handle high message throughput.", "x-intellij-html-description": "\u003cp\u003eEnable verbose logging to the console.\nAll system containers logs will flow into serial console.\u003c/p\u003e\n\n\u003cp\u003e\u003cstrong\u003eNote:\u003c/strong\u003e To avoid breaking Talos bootstrap flow enable this option only if serial console can handle high message throughput.\u003c/p\u003e\n" }, - "persist": { - "type": "boolean", - "title": "persist", - "markdownDescription": "", - "x-intellij-html-description": "" - }, "machine": { "$ref": "#/$defs/MachineConfig", "title": "machine", @@ -2395,19 +2389,6 @@ "additionalProperties": false, "type": "object" }, - "PodCheckpointer": { - "properties": { - "image": { - "type": "string", - "title": "image", - "description": "The image field is an override to the default pod-checkpointer image.\n", - "markdownDescription": "The `image` field is an override to the default pod-checkpointer image.", - "x-intellij-html-description": "\u003cp\u003eThe \u003ccode\u003eimage\u003c/code\u003e field is an override to the default pod-checkpointer image.\u003c/p\u003e\n" - } - }, - "additionalProperties": false, - "type": "object" - }, "ProxyConfig": { "properties": { "disabled": { diff --git a/website/content/v1.6/talos-guides/configuration/patching.md b/website/content/v1.6/talos-guides/configuration/patching.md index 0b2c33d434..b1a996a202 100644 --- a/website/content/v1.6/talos-guides/configuration/patching.md +++ b/website/content/v1.6/talos-guides/configuration/patching.md @@ -53,9 +53,11 @@ There are some special rules: When patching a multi-document machine configuration, following rules apply: -- for each document in the patch, the document is merged with the respective document in the machine configuration (matching by `kind`, `apiVersion` and `name` for named documentes) +- for each document in the patch, the document is merged with the respective document in the machine configuration (matching by `kind`, `apiVersion` and `name` for named documents) - if the patch document doesn't exist in the machine configuration, it is appended to the machine configuration +The strategic merge patch itself might be a multi-document YAML, and each document will be applied as a patch to the base machine configuration. + ### RFC6902 (JSON Patches) [JSON patches](https://jsonpatch.com/) can be written either in JSON or YAML format. diff --git a/website/content/v1.6/talos-guides/network/ingress-firewall.md b/website/content/v1.6/talos-guides/network/ingress-firewall.md index 6bbee6ac5f..647e2b4466 100644 --- a/website/content/v1.6/talos-guides/network/ingress-firewall.md +++ b/website/content/v1.6/talos-guides/network/ingress-firewall.md @@ -9,7 +9,8 @@ Talos Linux Ingress Firewall doesn't affect the traffic between the Kubernetes p ## Configuration -Ingress rules are configured as extra documents in the Talos machine configuration: +Ingress rules are configured as extra documents [NetwokDefaultActionConfig]({{< relref "../../reference/configuration/network/networkdefaultactionconfig.md" >}}) and +[NetworkRuleConfig]({{< relref "../../reference/configuration/network/networkruleconfig.md" >}}) in the Talos machine configuration: ```yaml apiVersion: v1alpha1