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
- Variables
- func ResolveClusterName(clusterCfg *v1alpha1.Cluster, talosConfig *Configs) string
- type ConfigManager
- type Configs
- func (c *Configs) ApplyMirrorRegistries(mirrors []MirrorRegistry) error
- func (c *Configs) Bundle() *bundle.Bundle
- func (c *Configs) ControlPlane() talosconfig.Provider
- func (c *Configs) ExtractMirrorHosts() []string
- func (c *Configs) GetClusterName() string
- func (c *Configs) IsCNIDisabled() bool
- func (c *Configs) IsKubeletCertRotationEnabled() bool
- func (c *Configs) NetworkCIDR() string
- func (c *Configs) WithEndpoint(endpointIP string) (*Configs, error)
- func (c *Configs) WithName(name string) (*Configs, error)
- func (c *Configs) Worker() talosconfig.Provider
- type MirrorRegistry
- type Patch
- type PatchScope
Constants ¶
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 ¶
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.
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
GetClusterName returns the cluster name. This implements configmanager.ClusterNameProvider interface.
func (*Configs) IsCNIDisabled ¶
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 ¶
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 ¶
NetworkCIDR returns the network CIDR from the cluster configuration. This is extracted from the pod CIDRs in the cluster network settings.
func (*Configs) WithEndpoint ¶
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 ¶
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 ¶
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 )