mirrorregistry

package
v5.21.2 Latest Latest
Warning

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

 Go to latest Published: Jan 18, 2026 License: Apache-2.0 Imports: 29 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.

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 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,
	},
	RoleNetwork: {
		Info:        NetworkInfo,
		KindAction:  KindNetworkAction,
		K3dAction:   K3dNetworkAction,
		TalosAction: TalosNetworkAction,
	},
	RoleConnect: {
		Info:        ConnectInfo,
		KindAction:  KindConnectAction,
		K3dAction:   K3dConnectAction,
		TalosAction: TalosConnectAction,
	},
	RolePostClusterConnect: {
		Info:        PostClusterConnectInfo,
		KindAction:  KindPostClusterConnectAction,
		K3dAction:   K3dPostClusterConnectAction,
		TalosAction: TalosPostClusterConnectAction,
	},
}

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.

func CollectMirrorSpecs added in v5.16.0 

func CollectMirrorSpecs(
	cfgManager *ksailconfigmanager.ConfigManager,
	mirrorsDir string,
) ([]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(
	cfgManager *ksailconfigmanager.ConfigManager,
) ([]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,
) 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,
)

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 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,
	cfgManager *ksailconfigmanager.ConfigManager,
	kindConfig *v1alpha4.Cluster,
) 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.

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 RunStage 

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

RunStage executes the registry stage for the given role.

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 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 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
	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
}

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.

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 = helpers.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 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
	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.