mirrorregistry

package
v5.36.4 Latest Latest
Warning

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

 Go to latest Published: Feb 18, 2026 License: Apache-2.0 Imports: 31 Imported by: 0

Documentation

Overview

Package mirrorregistry provides mirror registry setup and connection stages for cluster creation. It handles mirror registry provisioning, network creation, and containerd configuration for Kind, K3d, and Talos distributions.

Note: This package handles mirror registries (pull-through caches for external registries). For local development registries, see the localregistry package.

Index

Constants

View Source 
const (
	// RegistryStageTitle is the title for the registry stage that creates and configures registries.
	RegistryStageTitle    = "Create registries..."
	RegistryStageEmoji    = "📦"
	RegistryStageActivity = "creating and configuring registries"
	RegistryStageSuccess  = "registries created"
	RegistryStageFailure  = "failed to create registries"

	// NetworkStageTitle is the title for the network stage that creates Docker network.
	NetworkStageTitle    = "Create network..."
	NetworkStageEmoji    = "🌐"
	NetworkStageActivity = "creating docker network"
	NetworkStageSuccess  = "docker network created"
	NetworkStageFailure  = "failed to create docker network"

	// ConnectStageTitle is the title for the stage that connects registries to Docker network.
	ConnectStageTitle    = "Connect registries..."
	ConnectStageEmoji    = "🔗"
	ConnectStageActivity = "connecting registries to docker network"
	ConnectStageSuccess  = "registries connected to docker network"
	ConnectStageFailure  = "failed to connect registries to docker network"

	// PostClusterConnectStageTitle is the title for the stage that configures containerd inside cluster nodes.
	PostClusterConnectStageTitle    = "Configure registry mirrors..."
	PostClusterConnectStageEmoji    = "⚙️"
	PostClusterConnectStageActivity = "configuring registry mirrors in cluster"
	PostClusterConnectStageSuccess  = "registry mirrors configured"
	PostClusterConnectStageFailure  = "failed to configure registry mirrors"
)

Stage message constants for registry operations.

View Source 
const DefaultNetworkMTU = "1500"

DefaultNetworkMTU is the default MTU for Docker bridge networks. Required by the Talos SDK's Reflect() function which reads com.docker.network.driver.mtu to parse network state.

View Source 
const (
	// MirrorRegistryFlag is the flag name for mirror-registry configuration.
	MirrorRegistryFlag = "mirror-registry"
)

Variables

View Source 
var ConnectInfo = setup.StageInfo{
	Title:         ConnectStageTitle,
	Emoji:         ConnectStageEmoji,
	Activity:      ConnectStageActivity,
	Success:       ConnectStageSuccess,
	FailurePrefix: ConnectStageFailure,
}

ConnectInfo returns the stage info for registry connection.

View Source 
var DefaultMirrors = []string{
	"docker.io=https://registry-1.docker.io",
	"ghcr.io=https://ghcr.io",
	"quay.io=https://quay.io",
	"registry.k8s.io=https://registry.k8s.io",
}

DefaultMirrors are the default mirror registries applied when no config or flags are provided. These registries are used by KSail's installers:

  • docker.io: Calico, Gatekeeper, local-path-provisioner, Hetzner CSI
  • ghcr.io: Flux, Kyverno, kubelet-csr-approver, ArgoCD
  • quay.io: Cilium, Calico (tigera), ArgoCD, cert-manager
  • registry.k8s.io: metrics-server, cloud-provider-kind, CSI sidecars
View Source 
var ErrNoRegistriesFound = errors.New("no registries found on network")

ErrNoRegistriesFound is returned when no registries are found on the network.

View Source 
var NetworkInfo = setup.StageInfo{
	Title:         NetworkStageTitle,
	Emoji:         NetworkStageEmoji,
	Activity:      NetworkStageActivity,
	Success:       NetworkStageSuccess,
	FailurePrefix: NetworkStageFailure,
}

NetworkInfo returns the stage info for network creation.

View Source 
var PostClusterConnectInfo = setup.StageInfo{
	Title:         PostClusterConnectStageTitle,
	Emoji:         PostClusterConnectStageEmoji,
	Activity:      PostClusterConnectStageActivity,
	Success:       PostClusterConnectStageSuccess,
	FailurePrefix: PostClusterConnectStageFailure,
}

PostClusterConnectInfo returns the stage info for post-cluster registry configuration.

View Source 
var RegistryInfo = setup.StageInfo{
	Title:         RegistryStageTitle,
	Emoji:         RegistryStageEmoji,
	Activity:      RegistryStageActivity,
	Success:       RegistryStageSuccess,
	FailurePrefix: RegistryStageFailure,
}

RegistryInfo returns the stage info for registry creation.

View Source 
var StageDefinitions = map[Role]Definition{
	RoleRegistry: {
		Info:           RegistryInfo,
		KindAction:     KindRegistryAction,
		K3dAction:      K3dRegistryAction,
		TalosAction:    TalosRegistryAction,
		VClusterAction: VClusterRegistryAction,
	},
	RoleNetwork: {
		Info:           NetworkInfo,
		KindAction:     KindNetworkAction,
		K3dAction:      K3dNetworkAction,
		TalosAction:    TalosNetworkAction,
		VClusterAction: VClusterNetworkAction,
	},
	RoleConnect: {
		Info:           ConnectInfo,
		KindAction:     KindConnectAction,
		K3dAction:      K3dConnectAction,
		TalosAction:    TalosConnectAction,
		VClusterAction: VClusterConnectAction,
	},
	RolePostClusterConnect: {
		Info:           PostClusterConnectInfo,
		KindAction:     KindPostClusterConnectAction,
		K3dAction:      K3dPostClusterConnectAction,
		TalosAction:    TalosPostClusterConnectAction,
		VClusterAction: VClusterPostClusterConnectAction,
	},
}

StageDefinitions maps stage roles to their definitions.

Functions

func CleanupAll added in v5.16.0 

func CleanupAll(
	cmd *cobra.Command,
	_ *ksailconfigmanager.ConfigManager,
	clusterCfg *v1alpha1.Cluster,
	deps lifecycle.Deps,
	clusterName string,
	deleteVolumes bool,
	cleanupDeps CleanupDependencies,
	preDiscovered *DiscoveredRegistries,
)

CleanupAll cleans up all registries (both mirror and local) during cluster deletion. If preDiscovered is provided, it uses that list instead of discovering registries. This is necessary for distributions like Talos where the network is destroyed during cluster deletion.

func CleanupMirrorRegistries added in v5.16.0 

func CleanupMirrorRegistries(
	cmd *cobra.Command,
	cfgManager *ksailconfigmanager.ConfigManager,
	clusterCfg *v1alpha1.Cluster,
	deps lifecycle.Deps,
	clusterName string,
	deleteVolumes bool,
	cleanupDeps CleanupDependencies,
) error

CleanupMirrorRegistries cleans up registries for Kind after cluster deletion. K3d handles registry cleanup natively through its own configuration.

func CleanupPreDiscoveredRegistries added in v5.19.0 

func CleanupPreDiscoveredRegistries(
	cmd *cobra.Command,
	tmr timer.Timer,
	registries []dockerclient.RegistryInfo,
	deleteVolumes bool,
	cleanupDeps CleanupDependencies,
) error

CleanupPreDiscoveredRegistries deletes registries that were discovered before cluster deletion. This is the exported version for use by the simplified delete command.

func CleanupRegistriesByNetwork added in v5.19.0 

func CleanupRegistriesByNetwork(
	cmd *cobra.Command,
	tmr timer.Timer,
	distribution v1alpha1.Distribution,
	clusterName string,
	deleteVolumes bool,
	cleanupDeps CleanupDependencies,
) error

CleanupRegistriesByNetwork discovers and cleans up all registry containers by network. This is the exported version for use by the simplified delete command. Only registries belonging to the specified cluster (by name prefix) are deleted.

func CollectMirrorSpecs added in v5.16.0 

func CollectMirrorSpecs(
	cmd *cobra.Command,
	cfgManager *ksailconfigmanager.ConfigManager,
	mirrorsDir string,
	provider v1alpha1.Provider,
) ([]registry.MirrorSpec, []string, error)

CollectMirrorSpecs collects and merges mirror specs from flags and existing config. Returns the merged specs, registry names, and any error.

func CollectTalosMirrorSpecs added in v5.16.0 

func CollectTalosMirrorSpecs(
	cmd *cobra.Command,
	cfgManager *ksailconfigmanager.ConfigManager,
	provider v1alpha1.Provider,
) ([]registry.MirrorSpec, []string)

CollectTalosMirrorSpecs collects mirror specs from Talos config and command line flags. This extracts mirror hosts from the loaded Talos config bundle which includes any mirror-registries.yaml patches that were applied during cluster creation.

func ConfigureRegistryMirrorsInCluster 

func ConfigureRegistryMirrorsInCluster(params StageParams) error

ConfigureRegistryMirrorsInCluster configures containerd inside cluster nodes after cluster creation.

func ConnectRegistriesToNetwork 

func ConnectRegistriesToNetwork(params StageParams) error

ConnectRegistriesToNetwork connects registries to the Docker network before cluster creation.

func CreateNetwork 

func CreateNetwork(params StageParams) error

CreateNetwork creates the Docker network for the cluster.

func DisconnectLocalRegistryWithWarning added in v5.16.0 

func DisconnectLocalRegistryWithWarning(
	cmd *cobra.Command,
	cfgManager *ksailconfigmanager.ConfigManager,
	clusterCfg *v1alpha1.Cluster,
	deps lifecycle.Deps,
	clusterName string,
	cleanupDeps CleanupDependencies,
)

DisconnectLocalRegistryWithWarning disconnects the local registry from the cluster network. This is used for Talos which needs registries disconnected BEFORE cluster deletion because the registry is connected to the cluster network.

func DisconnectMirrorRegistries added in v5.16.0 

func DisconnectMirrorRegistries(
	cmd *cobra.Command,
	cfgManager *ksailconfigmanager.ConfigManager,
	clusterName string,
	cleanupDeps CleanupDependencies,
	provider v1alpha1.Provider,
) error

DisconnectMirrorRegistries disconnects mirror registries from the Talos network. This allows the network to be removed during cluster deletion without "active endpoints" errors.

func DisconnectMirrorRegistriesWithWarning added in v5.16.0 

func DisconnectMirrorRegistriesWithWarning(
	cmd *cobra.Command,
	cfgManager *ksailconfigmanager.ConfigManager,
	clusterName string,
	cleanupDeps CleanupDependencies,
	provider v1alpha1.Provider,
)

DisconnectMirrorRegistriesWithWarning disconnects mirror registries from the network. This is used for Talos which needs registries disconnected BEFORE cluster deletion due to network dependencies, while actual container cleanup happens after deletion.

func DisconnectRegistriesFromNetwork added in v5.19.0 

func DisconnectRegistriesFromNetwork(
	cmd *cobra.Command,
	networkName string,
	cleanupDeps CleanupDependencies,
) error

DisconnectRegistriesFromNetwork disconnects all registries from a network. This is used for Talos which needs registries disconnected BEFORE cluster deletion.

func EnsureDockerNetworkExists 

func EnsureDockerNetworkExists(
	ctx context.Context,
	dockerClient client.APIClient,
	networkName string,
	networkCIDR string,
	writer io.Writer,
) error

EnsureDockerNetworkExists creates a Docker network if it doesn't already exist. This is used to pre-create the cluster network before registry setup, allowing registry containers to be connected and accessible via Docker DNS when nodes start pulling images during boot.

The network is created with Talos-compatible labels and CIDR so that the Talos SDK will recognize and reuse it when creating the cluster.

func GetKindMirrorsDir deprecated 

func GetKindMirrorsDir(clusterCfg *v1alpha1.Cluster) string

GetKindMirrorsDir returns the configured Kind mirrors directory or the default.

Deprecated: Use kindconfigmanager.ResolveMirrorsDir instead.

func GetMirrorRegistriesWithDefaults added in v5.28.9 

func GetMirrorRegistriesWithDefaults(
	cmd *cobra.Command,
	cfgManager *ksailconfigmanager.ConfigManager,
	provider v1alpha1.Provider,
) []string

GetMirrorRegistriesWithDefaults returns mirror registries with default values applied. This function manually handles mirror-registry flag merging because it's not bound to Viper.

Behavior (REPLACE semantics for flags):

  • If --mirror-registry flag is explicitly set:
  • If set to empty string (""): DISABLE (return empty array)
  • With values: REPLACE (flag values completely override defaults AND config values)
  • If flag not set:
  • With config values: use config values from ksail.yaml
  • Without config values: use defaults (docker.io and ghcr.io) for Docker provider, or empty for cloud providers (Hetzner) since they cannot use local Docker mirrors.

Note: This is intentionally REPLACE semantics, not EXTEND. When a user provides --mirror-registry flags, they explicitly specify the complete list of mirrors they want.

func GetNetworkNameForDistribution added in v5.36.0 

func GetNetworkNameForDistribution(distribution v1alpha1.Distribution, clusterName string) string

GetNetworkNameForDistribution returns the Docker network name for a given distribution.

func K3dConnectAction 

func K3dConnectAction(ctx *Context) func(context.Context, client.APIClient) error

K3dConnectAction returns the action function for K3d registry connection.

func K3dNetworkAction 

func K3dNetworkAction(ctx *Context) func(context.Context, client.APIClient) error

K3dNetworkAction returns the action function for K3d network creation.

func K3dPostClusterConnectAction 

func K3dPostClusterConnectAction(_ *Context) func(context.Context, client.APIClient) error

K3dPostClusterConnectAction returns the action function for post-cluster registry configuration. For K3d, this is a no-op since registry mirrors are configured via k3d config before cluster creation.

func K3dRegistryAction 

func K3dRegistryAction(ctx *Context) func(context.Context, client.APIClient) error

K3dRegistryAction returns the action function for K3d registry creation.

func KindConnectAction 

func KindConnectAction(ctx *Context) func(context.Context, client.APIClient) error

KindConnectAction returns the action function for Kind registry connection.

func KindNetworkAction 

func KindNetworkAction(ctx *Context) func(context.Context, client.APIClient) error

KindNetworkAction returns the action function for Kind network creation.

func KindPostClusterConnectAction 

func KindPostClusterConnectAction(ctx *Context) func(context.Context, client.APIClient) error

KindPostClusterConnectAction returns the action function for post-cluster registry configuration.

func KindRegistryAction 

func KindRegistryAction(ctx *Context) func(context.Context, client.APIClient) error

KindRegistryAction returns the action function for Kind registry creation.

func PrepareK3dConfigWithMirrors 

func PrepareK3dConfigWithMirrors(
	clusterCfg *v1alpha1.Cluster,
	k3dConfig *v1alpha5.SimpleConfig,
	mirrorSpecs []registry.MirrorSpec,
) bool

PrepareK3dConfigWithMirrors prepares the K3d config by setting up mirror registries. When local registry is enabled, it configures K3d's native registry support via Registries.Create, which automatically handles DNS resolution, network connectivity, and cluster lifecycle integration. Returns true if registry configuration is needed, false otherwise.

func PrepareKindConfigWithMirrors 

func PrepareKindConfigWithMirrors(
	clusterCfg *v1alpha1.Cluster,
	kindConfig *v1alpha4.Cluster,
	mirrorSpecs []registry.MirrorSpec,
) bool

PrepareKindConfigWithMirrors prepares the Kind config by setting up hosts directory for mirrors. Returns true if mirror configuration is needed, false otherwise. This uses the modern hosts directory pattern instead of deprecated ContainerdConfigPatches. Note: mirrorSpecs should be the pre-computed merged specs from RunStage.

func PrepareTalosConfigWithMirrors 

func PrepareTalosConfigWithMirrors(
	clusterCfg *v1alpha1.Cluster,
	talosConfig *talosconfigmanager.Configs,
	mirrorSpecs []registry.MirrorSpec,
	clusterName string,
) bool

PrepareTalosConfigWithMirrors prepares the Talos config by setting up mirror registries. Returns true if mirror configuration is needed, false otherwise.

func PrepareVClusterConfigWithMirrors added in v5.36.0 

func PrepareVClusterConfigWithMirrors(
	clusterCfg *v1alpha1.Cluster,
	mirrorSpecs []registry.MirrorSpec,
) bool

PrepareVClusterConfigWithMirrors checks if VCluster mirror configuration is needed. Returns true if mirror specs are available, false otherwise.

func RunStage 

func RunStage(
	cmd *cobra.Command,
	clusterCfg *v1alpha1.Cluster,
	deps lifecycle.Deps,
	cfgManager *ksailconfigmanager.ConfigManager,
	kindConfig *v1alpha4.Cluster,
	k3dConfig *v1alpha5.SimpleConfig,
	talosConfig *talosconfigmanager.Configs,
	vclusterConfig *clusterprovisioner.VClusterConfig,
	role Role,
	dockerInvoker DockerClientInvoker,
) error

RunStage executes the registry stage for the given role.

func SetBackendFactoryForTests added in v5.28.9 

func SetBackendFactoryForTests(factory BackendFactory) func()

SetBackendFactoryForTests is an alias for registry.SetBackendFactoryForTests.

func SetupRegistries 

func SetupRegistries(params StageParams) error

SetupRegistries creates and configures registry containers before cluster creation.

func TalosConnectAction 

func TalosConnectAction(ctx *Context) func(context.Context, client.APIClient) error

TalosConnectAction returns the action function for Talos registry connection.

func TalosNetworkAction 

func TalosNetworkAction(ctx *Context) func(context.Context, client.APIClient) error

TalosNetworkAction returns the action function for Talos network creation.

func TalosPostClusterConnectAction 

func TalosPostClusterConnectAction(_ *Context) func(context.Context, client.APIClient) error

TalosPostClusterConnectAction returns the action function for post-cluster registry configuration. For Talos, this is a no-op since registry mirrors are configured via machine config before boot.

func TalosRegistryAction 

func TalosRegistryAction(ctx *Context) func(context.Context, client.APIClient) error

TalosRegistryAction returns the action function for Talos registry creation.

func VClusterConnectAction added in v5.36.0 

func VClusterConnectAction(ctx *Context) func(context.Context, client.APIClient) error

VClusterConnectAction returns the action function for VCluster registry connection.

func VClusterNetworkAction added in v5.36.0 

func VClusterNetworkAction(ctx *Context) func(context.Context, client.APIClient) error

VClusterNetworkAction returns the action function for VCluster network creation. Pre-creates the Docker network so mirror registries can be connected before cluster creation. The VCluster SDK reuses an existing network with this name.

func VClusterPostClusterConnectAction added in v5.36.0 

func VClusterPostClusterConnectAction(ctx *Context) func(context.Context, client.APIClient) error

VClusterPostClusterConnectAction returns the action function for post-cluster registry configuration. This injects hosts.toml files into VCluster nodes via docker exec, the same approach used by Kind.

func VClusterRegistryAction added in v5.36.0 

func VClusterRegistryAction(ctx *Context) func(context.Context, client.APIClient) error

VClusterRegistryAction returns the action function for VCluster registry creation.

func WaitForRegistriesReady 

func WaitForRegistriesReady(
	ctx context.Context,
	dockerAPIClient client.APIClient,
	registryInfos []registry.Info,
	writer io.Writer,
) error

WaitForRegistriesReady waits for mirror registries to become ready. This is a shared helper used by Kind, K3d, and Talos registry stages.

Types

type BackendFactory added in v5.28.9 

type BackendFactory = registry.BackendFactory

BackendFactory is an alias for registry.BackendFactory for convenience.

func GetBackendFactory added in v5.28.9 

func GetBackendFactory() BackendFactory

GetBackendFactory returns the current backend factory from the registry package.

type CleanupDependencies added in v5.16.0 

type CleanupDependencies struct {
	DockerInvoker     func(*cobra.Command, func(client.APIClient) error) error
	LocalRegistryDeps localregistry.Dependencies
}

CleanupDependencies holds dependencies for mirror registry cleanup operations.

func DefaultCleanupDependencies added in v5.16.0 

func DefaultCleanupDependencies() CleanupDependencies

DefaultCleanupDependencies returns the default cleanup dependencies.

type Context 

type Context struct {
	Cmd            *cobra.Command
	ClusterCfg     *v1alpha1.Cluster
	KindConfig     *v1alpha4.Cluster
	K3dConfig      *v1alpha5.SimpleConfig
	TalosConfig    *talosconfigmanager.Configs
	VClusterConfig *clusterprovisioner.VClusterConfig
	MirrorSpecs    []registry.MirrorSpec
}

Context contains all the configuration needed for registry stage execution.

type Definition 

type Definition struct {
	Info           setup.StageInfo
	KindAction     func(*Context) func(context.Context, client.APIClient) error
	K3dAction      func(*Context) func(context.Context, client.APIClient) error
	TalosAction    func(*Context) func(context.Context, client.APIClient) error
	VClusterAction func(*Context) func(context.Context, client.APIClient) error
}

Definition maps a stage role to its info and distribution-specific actions.

type DiscoveredRegistries added in v5.16.0 

type DiscoveredRegistries struct {
	Registries []dockerclient.RegistryInfo
}

DiscoveredRegistries holds registry information discovered before cluster deletion. This is used when the network will be destroyed during cluster deletion (e.g., Talos).

func DiscoverRegistries added in v5.16.0 

func DiscoverRegistries(
	cmd *cobra.Command,
	clusterCfg *v1alpha1.Cluster,
	clusterName string,
	cleanupDeps CleanupDependencies,
) *DiscoveredRegistries

DiscoverRegistries finds all registries connected to the cluster network. This should be called BEFORE cluster deletion for distributions that destroy the network during deletion (e.g., Talos).

func DiscoverRegistriesByNetwork added in v5.19.0 

func DiscoverRegistriesByNetwork(
	cmd *cobra.Command,
	distribution v1alpha1.Distribution,
	clusterName string,
	cleanupDeps CleanupDependencies,
) *DiscoveredRegistries

DiscoverRegistriesByNetwork finds all registries connected to the cluster network. This is a simplified version that doesn't require a cluster config object. Registries are filtered to only include those belonging to the specified cluster.

type DockerClientInvoker 

type DockerClientInvoker = setup.DockerClientInvoker

DockerClientInvoker is a function that invokes Docker client operations. Can be overridden in tests to avoid real Docker connections. This is an alias to the shared setup.DockerClientInvoker type. 

var DefaultDockerClientInvoker DockerClientInvoker = dockerutil.WithDockerClient

DefaultDockerClientInvoker is the default Docker client invoker.

type Handler 

type Handler struct {
	Prepare func() bool
	Action  func(context.Context, client.APIClient) error
}

Handler contains the prepare and action functions for a registry stage.

type PortGetter added in v5.28.9 

type PortGetter interface {
	GetRegistryPort(ctx context.Context, name string) (int, error)
	ListRegistries(ctx context.Context) ([]string, error)
}

PortGetter is an interface for getting used host ports. This is a subset of the Backend interface used for port collection.

type ReadinessChecker added in v5.28.9 

type ReadinessChecker interface {
	WaitForRegistriesReady(ctx context.Context, registryIPs map[string]string) error
}

ReadinessChecker is an interface for checking registry readiness.

type Role 

type Role int

Role represents the type of registry stage operation. 

const (
	// RoleRegistry is the stage that creates registries before network creation.
	RoleRegistry Role = iota
	// RoleNetwork is the stage that creates the Docker network.
	RoleNetwork
	// RoleConnect is the stage that connects registries to the Docker network.
	RoleConnect
	// RolePostClusterConnect is the stage that configures containerd inside cluster nodes.
	RolePostClusterConnect
)

type StageParams 

type StageParams struct {
	Cmd            *cobra.Command
	ClusterCfg     *v1alpha1.Cluster
	Deps           lifecycle.Deps
	CfgManager     *ksailconfigmanager.ConfigManager
	KindConfig     *v1alpha4.Cluster
	K3dConfig      *v1alpha5.SimpleConfig
	TalosConfig    *talosconfigmanager.Configs
	VClusterConfig *clusterprovisioner.VClusterConfig
	DockerInvoker  DockerClientInvoker
}

StageParams bundles all parameters needed for registry stage execution. This reduces code duplication across registry stage functions.

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.