talos

package
v5.63.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 22, 2026 License: Apache-2.0 Imports: 21 Imported by: 0

Documentation

Overview

Package talos provides configuration management for Talos cluster patches.

Unlike Kind and K3d which load configuration from a single YAML file, Talos configuration is composed of patches from multiple directories:

  • talos/cluster/ - patches applied to all nodes
  • talos/control-planes/ - patches applied only to control-plane nodes
  • talos/workers/ - patches applied only to worker nodes

The ConfigManager loads these patches, validates them, and creates a Configs object that wraps the upstream Talos SDK's bundle.Bundle. This provides programmatic access to the merged machine configurations for both control-plane and worker nodes.

Usage: 

manager := talos.NewConfigManager("talos", "my-cluster", "1.32.0", "10.5.0.0/24")
configs, err := manager.Load(configmanager.LoadOptions{})
if err != nil {
    return err
}

// Access control-plane config
cpConfig := configs.ControlPlane()
cniName := cpConfig.Cluster().Network().CNI().Name()

// Access worker config
workerConfig := configs.Worker()

Index

Constants

View Source 
const (
	// DefaultPatchesDir is the default directory for Talos patches.
	DefaultPatchesDir = "talos"
	// DefaultNetworkCIDR is the default CIDR for the cluster network.
	DefaultNetworkCIDR = "10.5.0.0/24"
	// DefaultKubernetesVersion is the default Kubernetes version.
	DefaultKubernetesVersion = "1.32.0"
	// DefaultClusterName is the default cluster name for Talos clusters.
	DefaultClusterName = "talos-default"
)

Default configuration values for Talos clusters.

Variables

View Source 
var (
	// ErrInvalidPatch is returned when a patch cannot be parsed.
	ErrInvalidPatch = errors.New("invalid patch")
	// ErrIPv6NotSupported is returned when IPv6 addresses are used but not supported.
	ErrIPv6NotSupported = errors.New("IPv6 not supported")
	// ErrNegativeOffset is returned when a negative offset is provided for IP calculation.
	ErrNegativeOffset = errors.New("negative offset not allowed")
)

Errors for patch operations.

View Source 
var DefaultTalosImage = talosImage()

DefaultTalosImage is the default Talos container image. This value is read from the Dockerfile in this package which is updated by Dependabot. NOTE: This MUST match the Talos pkg/machinery version to ensure generated machine configs are compatible with the running container.

Functions

func ResolveClusterName 

func ResolveClusterName(
	clusterCfg *v1alpha1.Cluster,
	talosConfig *Configs,
) string

ResolveClusterName returns the effective cluster name from Talos config or cluster config. Priority: talosConfig.Name > clusterCfg.Spec.Cluster.Connection.Context > DefaultClusterName. When using the context, extracts the cluster name from the "admin@<cluster-name>" pattern. Returns DefaultClusterName ("talos-default") if both configs are nil or have empty names.

Types

type ConfigManager 

type ConfigManager struct {
	// contains filtered or unexported fields
}

ConfigManager implements configuration management for Talos cluster patches. Unlike Kind and K3d which load from a single YAML file, Talos patches are loaded from multiple directories and merged into machine configurations.

This implements configmanager.ConfigManager[Configs] interface.

func NewConfigManager 

func NewConfigManager(
	patchesDir, clusterName, kubernetesVersion, networkCIDR string,
) *ConfigManager

NewConfigManager creates a new configuration manager for Talos patches. Parameters:

  • patchesDir: root directory containing talos/cluster, talos/control-planes, talos/workers
  • clusterName: name for the Talos cluster
  • kubernetesVersion: Kubernetes version to deploy
  • networkCIDR: network CIDR for the cluster (e.g., "10.5.0.0/24")

func (*ConfigManager) Load 

func (m *ConfigManager) Load(_ configmanager.LoadOptions) (*Configs, error)

Load loads Talos patches from directories and creates the config bundle. Returns the loaded Configs, either freshly loaded or previously cached. Timer, Silent, IgnoreConfigFile, and SkipValidation options are not currently used.

func (*ConfigManager) ValidateConfigs 

func (m *ConfigManager) ValidateConfigs() (*Configs, error)

ValidateConfigs performs semantic validation by actually loading patches. This catches issues that YAML syntax checking alone misses.

func (*ConfigManager) ValidatePatchDirectory 

func (m *ConfigManager) ValidatePatchDirectory() (string, error)

ValidatePatchDirectory validates that patch directories exist and contain valid YAML files. Returns a warning message if the talos directory doesn't exist (patches are optional), or an error if YAML files are invalid.

func (*ConfigManager) WithAdditionalPatches 

func (m *ConfigManager) WithAdditionalPatches(patches []Patch) *ConfigManager

WithAdditionalPatches adds runtime patches to be applied after file patches. This is useful for programmatic patches like CNI disable or mirror registries.

type Configs 

type Configs struct {
	// Name is the cluster name.
	Name string
	// contains filtered or unexported fields
}

Configs holds the loaded Talos machine configurations with patches applied. It wraps the upstream bundle.Bundle and provides convenient accessors.

Usage: 

manager := NewConfigManager("talos", "my-cluster", "1.32.0", "10.5.0.0/24")
configs, err := manager.Load(configmanager.LoadOptions{})
if err != nil {
    return err
}

// Access programmatically
cpConfig := configs.ControlPlane()
workerConfig := configs.Worker()

// Access specific config sections
cniName := cpConfig.Cluster().Network().CNI().Name()
kubeletImage := cpConfig.Machine().Kubelet().Image()

func NewDefaultConfigs 

func NewDefaultConfigs() (*Configs, error)

NewDefaultConfigs creates a new Talos Configs with default settings. This is used when no scaffolded project exists and default configurations are needed. It creates a valid config bundle with:

  • Cluster name: DefaultClusterName ("talos-default")
  • Kubernetes version: DefaultKubernetesVersion ("1.32.0")
  • Network CIDR: DefaultNetworkCIDR ("10.5.0.0/24")
  • allowSchedulingOnControlPlanes: true (for single-node/control-plane-only clusters)

func NewDefaultConfigsWithPatches 

func NewDefaultConfigsWithPatches(additionalPatches []Patch) (*Configs, error)

NewDefaultConfigsWithPatches creates a new Talos Configs with default settings plus additional patches. This is used when no scaffolded project exists but additional runtime patches are needed (e.g., kubelet-csr-approver extraManifests when metrics-server is enabled).

The additional patches are applied after the default allowSchedulingOnControlPlanes patch.

func (*Configs) ApplyMirrorRegistries 

func (c *Configs) ApplyMirrorRegistries(mirrors []MirrorRegistry) error

ApplyMirrorRegistries modifies the configs to add registry mirror configurations. This directly patches the underlying v1alpha1.Config structs. It adds both the mirror endpoints and the registry config with insecureSkipVerify: true to allow HTTP connections to local registry containers.

func (*Configs) Bundle 

func (c *Configs) Bundle() *bundle.Bundle

Bundle returns the underlying Talos config bundle. This provides full access to all bundle functionality.

func (*Configs) ControlPlane 

func (c *Configs) ControlPlane() talosconfig.Provider

ControlPlane returns the control-plane machine configuration. This config has cluster and control-plane patches applied.

The returned config.Provider gives programmatic access to all config fields:

  • Machine() - machine-specific settings (network, kubelet, files, etc.)
  • Cluster() - cluster-wide settings (CNI, API server, etcd, etc.)

Returns nil if the bundle is not loaded or if the control plane config is not set. This prevents panics from the upstream Talos SDK's bundle.ControlPlane() method which panics when ControlPlaneCfg is nil.

func (*Configs) ExtractMirrorHosts 

func (c *Configs) ExtractMirrorHosts() []string

ExtractMirrorHosts returns a list of registry hosts that have mirror configurations. This extracts hosts from the loaded config bundle, which includes any patches that were applied (including scaffolded mirror-registries.yaml patches). Returns nil if no mirrors are configured.

Note: This method only returns host names, not remote URLs. For full MirrorSpec extraction including remotes, parsing from the generator-created patch files is needed, or use DefaultGenerateUpstreamURL to derive conventional upstream URLs.

func (*Configs) GetClusterName 

func (c *Configs) GetClusterName() string

GetClusterName returns the cluster name. This implements configmanager.ClusterNameProvider interface.

func (*Configs) IsCNIDisabled 

func (c *Configs) IsCNIDisabled() bool

IsCNIDisabled returns true if the default CNI is disabled (set to "none"). This is used to determine whether to skip CNI-dependent checks during bootstrap.

func (*Configs) IsKubeletCertRotationEnabled 

func (c *Configs) IsKubeletCertRotationEnabled() bool

IsKubeletCertRotationEnabled returns true if kubelet serving certificate rotation is enabled. This is detected by the presence of "rotate-server-certificates" in kubelet extra args. When enabled with CNI disabled, the kubelet-serving-cert-approver pod cannot schedule (node is NotReady without CNI), so kubelet has no serving certificate, and Talos cannot connect to kubelet to populate StaticPodStatus resources.

func (*Configs) NetworkCIDR 

func (c *Configs) NetworkCIDR() string

NetworkCIDR returns the network CIDR from the cluster configuration. This is extracted from the pod CIDRs in the cluster network settings.

func (*Configs) WithEndpoint 

func (c *Configs) WithEndpoint(endpointIP string) (*Configs, error)

WithEndpoint creates a new Configs with a specific endpoint IP for the Talos API and Kubernetes API. This is used for cloud deployments (e.g., Hetzner) where the public IP is different from the internal network IP. The endpoint is embedded in certificates and must match the IP that clients will use to connect.

The endpoint should be the public IP address of the first control plane node. Returns a new Configs instance; the original is not modified. Returns an error if bundle regeneration fails.

IMPORTANT: This preserves the existing PKI (CA, certificates) to ensure that configs applied to servers and the talosconfig for authentication use the same CA.

func (*Configs) WithName 

func (c *Configs) WithName(name string) (*Configs, error)

WithName creates a new Configs with a different cluster name. This regenerates the underlying Talos bundle with the new cluster name, which is necessary because the cluster name is embedded in PKI certificates and the kubeconfig context name (admin@<cluster-name>).

Returns a new Configs instance; the original is not modified. Returns an error if bundle regeneration fails.

func (*Configs) Worker 

func (c *Configs) Worker() talosconfig.Provider

Worker returns the worker machine configuration. This config has cluster and worker patches applied.

The returned config.Provider gives programmatic access to all config fields:

  • Machine() - machine-specific settings (network, kubelet, files, etc.)
  • Cluster() - cluster-wide settings (CNI, API server, etcd, etc.)

Returns nil if the bundle is not loaded or if the worker config is not set. This prevents panics from the upstream Talos SDK's bundle.Worker() method which panics when WorkerCfg is nil.

type MirrorRegistry 

type MirrorRegistry struct {
	// Host is the registry host (e.g., "docker.io", "ghcr.io").
	Host string
	// Endpoints are the mirror endpoints to use (e.g., "http://docker.io:5000").
	Endpoints []string
	// Username is the optional username for registry authentication.
	// Environment variable placeholders should be resolved before passing.
	Username string

	Password string
}

MirrorRegistry represents a registry mirror configuration.

type Patch 

type Patch struct {
	// Path is the source file path or identifier for the patch.
	Path string
	// Scope indicates which nodes this patch applies to.
	Scope PatchScope
	// Content is the raw YAML patch content.
	Content []byte
}

Patch represents a Talos machine config patch with its scope.

func LoadPatches 

func LoadPatches(patchesDir string) ([]Patch, error)

LoadPatches loads all Talos patches from the configured directories. Returns patches from cluster/, control-planes/, and workers/ subdirectories.

type PatchScope 

type PatchScope int

PatchScope indicates which nodes a patch should be applied to. 

const (
	// PatchScopeCluster applies to all nodes (control-planes and workers).
	PatchScopeCluster PatchScope = iota
	// PatchScopeControlPlane applies only to control-plane nodes.
	PatchScopeControlPlane
	// PatchScopeWorker applies only to worker nodes.
	PatchScopeWorker
)

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.