Container Runtime Integration (CRI)

Relevant source files

The following files were used as context for generating this wiki page:

• internal/container_runtime/containerd.go
• internal/container_runtime/docker.go
• internal/container_runtime/host.go
• cmd/main.go
• pkg/config/validate.go
• CLAUDE.md
• README.md

The Container Runtime Integration (CRI) module is a core component of Harbor Satellite responsible for managing and modifying the configuration of local container runtimes. Its primary purpose is to configure these runtimes to use the local Satellite registry (typically Zot) as a mirror for upstream registries. This ensures that edge devices pull container images from the local cache first, reducing bandwidth usage and enabling operations in air-gapped or intermittently connected environments.

The module supports multiple runtimes including Docker, containerd, CRI-O, and Podman. It operates by identifying the runtime on the host and updating specific configuration files (e.g., daemon.json for Docker or hosts.toml for containerd) to inject mirror settings. This process often requires elevated privileges (sudo) and may necessitate a service restart for changes to take effect.

Sources: README.md:121-125, CLAUDE.md:104-111, cmd/main.go:95-99

Core Architecture and Workflow

The CRI integration logic is triggered during the Satellite startup sequence. It processes mirror mappings provided via CLI flags or environment variables and applies them to the detected runtime configuration.

The diagram above illustrates the sequential flow of how the Satellite configures the host container runtime to utilize the local registry as a mirror.

Configuration Injection Logic

The application accepts mirror configurations in the format CRI:registry1,registry2. For example, --mirrors=containerd:docker.io,quay.io instructs the system to configure containerd to treat the local Satellite registry as a mirror for both Docker Hub and Quay.

• Runtime Detection: The system determines which configuration logic to execute based on the prefix of the mirror flag.
• Endpoint Resolution: The local registry endpoint is derived from the Zot configuration, specifically the HTTP address and port.
• Validation: Configurations are validated to ensure URLs are properly formatted and target runtimes are supported.

Sources: cmd/main.go:21-31, cmd/main.go:90-99, CLAUDE.md:104-108

Supported Runtimes

Runtime	Config Path	Implementation Detail
containerd	/etc/containerd/certs.d	Uses hosts.toml files per registry and updates the main config.toml registry plugin path.
Docker	/etc/docker/daemon.json	Updates the registry-mirrors array and restarts the Docker service via systemctl.
CRI-O	N/A	Supported via the mirroring interface for edge Kubernetes environments.
Podman	N/A	Configured to point to the local Satellite registry for upstream resolution.

Sources: internal/container_runtime/containerd.go:13-14, internal/container_runtime/docker.go:13, CLAUDE.md:104-106

Runtime-Specific Implementations

containerd Integration

The containerd implementation utilizes the "CRI registry config path" feature. It creates a directory structure under /etc/containerd/certs.d for each upstream registry and populates it with a hosts.toml file.

Key steps include:

1. Main Config Update: Updating /etc/containerd/config.toml to set plugins."io.containerd.cri.v1.images".registry.config_path to the certificates directory.
2. Host TOML Generation: Creating a hosts.toml for each upstream registry that defines the local Satellite as a host with pull and resolve capabilities.

Sources: internal/container_runtime/containerd.go:18-30, internal/container_runtime/containerd.go:67-80

Docker Integration

Docker integration focuses on the daemon.json configuration file. The implementation:

1. Reads existing config: Loads the current JSON configuration using the viper library.
2. Appends mirror: Adds the local registry URL to the registry-mirrors list if it is not already present.
3. Service Restart: Executes systemctl restart docker to apply the changes.

Sources: internal/container_runtime/docker.go:15-35, internal/container_runtime/docker.go:53-58

The sequence diagram shows the interaction between the Satellite and the host system to update Docker's mirroring configuration.

Key Structures and Functions

containerd Configuration Structures

Containerd uses specific TOML structures to define mirroring behavior.

// internal/container_runtime/containerd.go:42-50
type ContainerdHosts struct {
	Server string          `toml:"server"`
	Host   map[string]Host `toml:"host"`
}

type Host struct {
	Capabilities []string `toml:"capabilities"`
}

Sources: internal/container_runtime/containerd.go:42-50

Primary Functions

• ApplyCRIConfigs(mirrors mirrorFlags, localRegistryEndpoint string): The entry point called in main.go to process all mirror flags.
• setContainerdConfig(upstreamRegistries []string, localMirror string): Orchestrates the creation of directory structures and TOML files for containerd.
• setDockerdConfig(mirrors []string, localRegistry string): Manages the JSON updates and service lifecycle for Docker.

Sources: cmd/main.go:95, internal/container_runtime/containerd.go:18, internal/container_runtime/docker.go:15

Conclusion

The Container Runtime Integration ensures that Harbor Satellite is not just a passive cache but an active participant in the host's image acquisition workflow. By automating the configuration of mirrors for Docker and containerd, it provides a transparent deployment process for edge applications, ensuring high availability of container images even in environments with restricted or unreliable egress data flow.

Sources: README.md:15-20, README.md:121-125