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.
ctr client is similar to Docker's eponymous CLI, but the commands and flags often differ from their (typically more user-friendly)
Historically, the primary users of the
ctr client were containerd developers themselves testing the daemon.
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.
🧑🎓 The playground in this lesson is a regular Linux server with Docker pre-installed. Since Docker utilizes containerd under the hood, both the
containerd daemon and the
ctr client are also available on this server - try running
ctr version in the online terminal.
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
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.
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
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
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 buildcommand, 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 😎