containerd’s ctr command can import and export container images using the OCI (Open Container Initiative) image format.
Let’s see it in action. Imagine you have a container image called my-app:latest that you want to back up or transfer to another system that might not have direct access to a registry.
First, we’ll export this image into a tarball. This tarball will contain all the layers and the manifest for the image.
ctr image export my-app.tar my-app:latest
This command takes the image my-app:latest and bundles it into a file named my-app.tar. The export subcommand is straightforward: it takes the destination file path and the image reference.
Now, on another machine, or perhaps after cleaning up your local images, you can import this tarball back into containerd.
ctr image import my-app.tar
This command reads the my-app.tar file and reconstructs the image within containerd’s local storage. If the image already exists, ctr image import will update it if the imported version is newer, or do nothing if it’s the same or older.
The magic behind this is the OCI image format. When you export, ctr packages the image into a format that adheres to the OCI Image Specification. This specification defines how image layers (the actual filesystem changes) and image manifests (metadata about the image, including its layers, configuration, and history) are structured. The tarball is essentially a container for these OCI-compliant components. When you import, ctr unpacks this tarball, validates the OCI structure, and registers the image with containerd’s content store and image index.
The ctr image export command actually creates a tarball containing a manifest.json file and a blobs directory. The manifest.json describes the image, referencing the layer blobs. The blobs directory contains the actual layer data, compressed. When you import, ctr reads this manifest.json, reconstructs the image configuration, and places the blobs into its content store.
You can also specify a particular tag during import if you want the imported image to have a different name or tag than what was originally exported.
ctr image import --tag my-new-app:v1.0 my-app.tar
This will import my-app.tar and tag the resulting image as my-new-app:v1.0. If you don’t use --tag, it will use the tag(s) present in the manifest within the tarball.
The primary use case for this is offline image transfer or creating local backups of critical images without relying on a remote registry. It’s also incredibly useful for debugging or for setting up reproducible environments where you want to ensure the exact same image is used, regardless of network connectivity to a registry.
When you perform an import, containerd doesn’t just copy files; it calculates the SHA256 digest of each layer blob. These digests are crucial for content-addressable storage. If a blob with the same digest already exists in containerd’s content store, it’s not duplicated. This deduplication is a core feature that saves disk space and speeds up subsequent imports.
The ctr image export command implicitly uses the OCI image layout. The tarball created is a self-contained representation of an OCI image. This means that the exported tarball can be understood by other OCI-compliant tools, not just ctr. This interoperability is a key benefit of adhering to the OCI standard.
If you export an image that has multiple tags, ctr image export will export the image content associated with the specified tag. However, the tarball itself doesn’t typically store multiple tags for a single image digest. When you import, you can apply new tags. If you need to manage multiple tags for the same image digest, you’d typically do that after importing, using ctr image tag.
Understanding the OCI image format is key here. An OCI image is composed of a manifest, which points to one or more layer blobs, and a configuration blob. The manifest also includes metadata like the image’s architecture and OS. ctr serializes these components into the tarball.
The next step you’ll likely encounter is how to manage these imported images, such as listing them or removing them to free up space.