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.

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.

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:

sudo 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:

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

Listing local images with ctr is pretty straightforward:

sudo 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

sudo ctr image import iximiuz-test.tar

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

sudo ctr image tag example.com/iximiuz/test:latest \
  registry.iximiuz.com/test:latest

How about pushing this image to a remote registry? Conveniently, the playground has an ephemeral registry available at registry.iximiuz.com. This registry is configured to use basic authentication, and since there is no docker login equivalent in ctr, you'll need to provide the --user <user>:<pass> flag to authenticate with it:

sudo ctr image push --user iximiuzlabs:rules! registry.iximiuz.com/test:latest

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

sudo ctr image remove registry.iximiuz.com/test:latest

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:

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

Now you can explore the contents of the /tmp/nginx.tar file. 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
sudo ctr image mount docker.io/library/nginx:latest /tmp/nginx_rootfs

Now you can explore the rootfs of the Nginx image. 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 😉

sudo ctr image unmount /tmp/nginx_rootfs

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 😎

And now, a series of exercises to help you internalize the ctr image management commands, because learning-by-doing rocks! 😉 Unlike in the preceding lesson, these challenges come without solutions - you'll have to figure them out yourself. But fear not, there will be hints along the way. Good luck!

Hope you'll enjoy the challenges and learn something new on the way. See you in the next lesson!