Technotes for future me

How to work with container images using ctr

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).

ctr image pull
ctr image pull

Listing local images

ctr image ls

Build and Load images

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 - <<EOF
FROM busybox:latest
CMD echo just a test

docker save -o iximiuz-test.tar

ctr image import iximiuz-test.tar

Tag images

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

Push images

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

Remove images

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

Export and Inspect images

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

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 /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
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


Last updated on 20 Jun 2023
Published on 20 Jun 2023
Edit on GitHub