How to work with container images using ctr

ctr is a command-line client shipped as part of the containerd project. If you have containerd running on a machine, chances are the ctr binary is also present there.

The ctr client is similar to Docker's eponymous CLI, but the commands and flags often differ from their (typically more user-friendly) docker analogs. Historically, the primary users of the ctr client were containerd developers themselves testing the daemon. However, ctr can serve as a great exploration means for a more general audience - it operates right on top of the containerd API, and by examining the available commands, you can get a good idea of what containerd can or cannot do.

Basic image management with ctr

Pulling images with ctr always requires a fully-qualified reference - in other words, you cannot omit the domain or the tag parts (the digest doesn't have to be provided, though). Try the following command to pull the latest nginx image from Docker Hub:

ctr image pull docker.io/library/nginx:latest

And here is how you can pull an image from another registry - in this case, from Quay:

ctr image pull quay.io/quay/busybox:latest

Listing local images with the ctr is pretty straightforward:

ctr image ls

However, despite the fact the containerd is often used by higher-level tools to build container images, it doesn't provide out-of-the-box image building functionality, so there's no ctr image build command.

Luckily, you can load existing images into containerd using ctr image import. To some extent, it can mitigate the absence of the build command. Here is how you can build an image using a traditional docker build command and then import it:

docker build -t example.com/iximiuz/test:latest - <<EOF
FROM busybox:latest
CMD echo just a test
EOF
docker save -o iximiuz-test.tar example.com/iximiuz/test:latest
ctr image import iximiuz-test.tar

Much like in Docker, you can tag local images with ctr image tag. For instance:

ctr image tag example.com/iximiuz/test:latest localhost:5000/iximiuz/test:latest

How about pushing this image to a remote registry? Conveniently, the playground already has one running on port localhost:5000:

ctr image push localhost:5000/iximiuz/test:latest

To remove the (local) image, you can use the ctr image remove command:

ctr image remove localhost:5000/iximiuz/test:latest

Advanced image management with ctr

Sometimes, you may want to inspect the internals of an image. With ctr, you can do it using the ctr image export command that saves the image's content to a tarball:

ctr image export /tmp/nginx.tar docker.io/library/nginx:latest

The exported tarball will contain the nginx image data stored using the OCI Image Layout format.

You can extract the tarball to a temporary directory and explore its contents:

mkdir /tmp/nginx_image
tar -xf /tmp/nginx.tar -C /tmp/nginx_image/
ls -lah /tmp/nginx_image/

The result should look as follows:

total 24K
drwxr-xr-x  3 root root 4.0K Jun  3 11:23 .
drwxrwxrwt 11 root root 4.0K Jun  3 11:23 ..
drwxr-xr-x  3 root root 4.0K Jan  1  1970 blobs
-rw-r--r--  1 root root  323 Jan  1  1970 index.json
-rw-r--r--  1 root root  611 Jan  1  1970 manifest.json
-r--r--r--  1 root root   30 Jan  1  1970 oci-layout

When dealing with raw image layers is not desirable, you can mount the image to a temporary directory on the host and explore its root filesystem as it were a regular directory:

mkdir /tmp/nginx_rootfs
ctr image mount docker.io/library/nginx:latest /tmp/nginx_rootfs

The file and directories of the Nginx image should be available under /tmp/nginx_rootfs path now. Try:

ls -l /tmp/nginx_rootfs/

The result will look like a typical Linux filesystem, and it's not surprising since the Nginx image is based on the Debian Linux distribution:

total 84
drwxr-xr-x 2 root root 4096 May  2 00:00 bin
drwxr-xr-x 2 root root 4096 Apr  2 11:55 boot
drwxr-xr-x 2 root root 4096 May  2 00:00 dev
drwxr-xr-x 1 root root 4096 May  3 19:51 docker-entrypoint.d
-rwxrwxr-x 1 root root 1616 May  3 19:50 docker-entrypoint.sh
drwxr-xr-x 1 root root 4096 May  3 19:51 etc
...

Don't forget to unmount the image when you're done with it 😉

ctr image unmount /tmp/nginx_rootfs

Summary

In this lesson, you've learned how to use the ctr command to manage containerd images. The key takeaways are:

• It's possible to pull, tag, and push images with ctr, and the UX is pretty similar to Docker's.
• There is no ctr build command, but you can import existing images into containerd.
• You can inspect the OCI Layout of the image and very conveniently mount an image's rootfs to a temporary directory on the host - something that is somewhat harder to achieve with Docker.

Now, let's practice what you've learned! It's going to be fun, I promise 😎