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.
🧑🎓 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 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 😎