Working with Images

Rancher Desktop provides the ability to build, push, and pull images via the NERDCTL project and the Docker CLI.

Note, both nerdctl and docker are put into the path automatically. This occurs during the installer on Windows, and upon first run on macOS and Linux.

General Usage

Using either tool requires Rancher Desktop to be running with the appropriate container runtime. For nerdctl, use the containerd runtime. For docker, use the Moby runtime.

You can learn about all of the command options and display the help documentation by running:

  • nerdctl
  • docker
  1. nerdctl -h

Unlike Docker, containerd features its own namespaces. By default, nerdctl images are stored in the default namespace. If you want your images available for use by Kubernetes, use the --namespace k8s.io or -n k8s.io CLI argument. You can also switch to a namespace called default or any other name using the option --namespace <NAMESPACE_NAME>. Note that nerdctl namespaces are separate and independent from Kubernetes and kubectl namespaces.

  1. docker --help

Listing Images

To see the images currently available, run the following command:

  • nerdctl
  • docker
  1. nerdctl images
  1. docker images

Building Images

  • nerdctl
  • docker

Building images has a similar feel to existing tools. For example, consider running nerdctl from a directory with a Dockerfile where the Dockerfile is using a scratch image.

  1. nerdctl build .
  2. [+] Building 0.1s (4/4) FINISHED
  3.  => [internal] load build definition from Dockerfile
  4.  => => transferring dockerfile: 31B
  5.  => [internal] load .dockerignore
  6.  => => transferring context: 2B
  7.  => [internal] load build context
  8.  => => transferring context: 33B
  9.  => CACHED [1/1] ADD anvil-app /

nerdctl has options for tagging at the same time as building and other options you’ve come to expect.

  1. nerdctl build -t TAG .

To build an image for use with Kubernetes, specify the k8s.io namespace as follows:

  1. nerdctl build -n k8s.io .

Consider running docker from a directory with a Dockerfile where the Dockerfile is using a scratch image.

  1. docker build .
  2. Sending build context to Docker daemon  13.93MB
  3. Step 1/5 : FROM some-repo/some-image
  4.  ---> e57ace221dff
  5. ...
  6.  ---> fd984c4cbf97
  7. Successfully built fd984c4cbf97

docker has options for tagging at the same time as building and other options you’ve come to expect.

  1. docker build -t TAG .

Building Local Images

In order to demonstrate the steps to build local images and run apps, a sample nodejs app is provided within the Rancher Desktop docs repository. To get started, clone the repository and cd into assets/express-sample in a terminal.

Run the following command to build image from Dockerfile:

  • nerdctl
  • docker
  1. nerdctl --namespace k8s.io build -t expressapp:v1.0 .
  1. docker build -t expressapp:v1.0 .

Run the following command to run container:

  1. kubectl run --image expressapp:v1.0 expressapp
  2. kubectl port-forward pods/expressapp 3000:3000

Note: When adding the latest tag, be sure to also specify the following:

  1. imagePullPolicy: Never

Tagging Images

If you want to tag an existing image you’ve built you can use the following command:

  • nerdctl
  • docker
  1. nerdctl tag SOURCE_IMAGE[:TAG] TARGET_IMAGE[:TAG]
  1. docker tag SOURCE_IMAGE[:TAG] TARGET_IMAGE[:TAG]

Removing Images

To remove an image, run the following command:

  • nerdctl
  • docker
  1. nerdctl rmi IMAGE
  1. docker rmi IMAGE