A build pipeline produced container images in Docker, but these images were invisible in K3s’s containerd runtime, forcing manual imports and introducing deployment delays (2-5 minutes per build). This created inconsistencies between development and runtime environments.

Issue

Images built using Docker were stored in Docker’s storage backend but not automatically synchronized with K3s’s containerd runtime, resulting in:

Missing images: Docker-built images were inaccessible in K3s’s runtime.
Manual intervention: Operators had to manually import images after each build.
Deployment delays: Each build required additional steps, increasing time-to-deployment.
Version mismatches: Risk of deploying outdated or inconsistent images.

Culprit

The issue stemmed from architectural separation between Docker and containerd storage systems:

Independent storage backends: Docker and containerd maintain separate image repositories.
No built-in synchronization: Docker’s default storage (e.g., overlay2) and containerd’s storage paths are distinct and unsynchronized.
K3s configuration: K3s explicitly disables Docker integration, relying solely on containerd.

Solution

An automated image import process was implemented in the build pipeline to:

Export images from Docker and import them directly into containerd using standardized commands.
Eliminate manual steps: Automated the synchronization to ensure images are available in both environments post-build.
Reduce deployment time: Achieved an 87% reduction in deployment delays (from 15 to 2 minutes per build).
Ensure version consistency: Guaranteed that runtime environments use the latest built images.

The solution involved integrating a script into the pipeline that:

Exported Docker images in a transferable format.
Imported them into containerd without requiring additional infrastructure changes.

This resolved the inconsistency between build and runtime environments, improving workflow efficiency and reliability.