Skip to content

021 · Nerdctl

Lab 021 - Nerdctl (nerdctl)

Module 021

  • Goal: Master nerdctl - the Docker-compatible CLI for containerd.
  • Objective: Learn to use nerdctl as a drop-in Docker replacement that talks directly to containerd, with full support for building, running, composing, and debugging containers.

What you’ll learn

  • What nerdctl is and how it compares to docker, ctr, and crictl
  • How to pull, build, tag, push, and remove images
  • How to run, list, inspect, stop, and remove containers
  • How to use nerdctl compose as a Docker Compose alternative
  • How to inspect Kubernetes containers via containerd namespaces
  • How to use nerdctl for networking, volumes, and logs

Background

The Container Stack
graph LR
    A["kubectl / k8s API<br/><i>orchestrator</i>"] --> B
    B["kubelet<br/><i>node agent</i>"] --> C
    C["CRI (containerd shim)<br/><i>container runtime interface</i>"] --> D
    D["containerd<br/><i>container runtime</i>"] --> E
    E["runc<br/><i>OCI runtime - creates Linux cgroups/namespaces</i>"]
  • containerd is the core container runtime used by Docker and Kubernetes.
  • nerdctl is a Docker-compatible CLI that talks directly to containerd - it aims to be a drop-in replacement for docker.
  • Unlike ctr (low-level, minimal), nerdctl provides a user-friendly experience with familiar Docker commands.
  • nerdctl supports features like build (via BuildKit), compose, networking, and volumes - things ctr cannot do.
When to use nerdctl vs other tools
Tool Use case
docker Developer workflow, requires Docker daemon
crictl Kubernetes CRI-level debugging (Lab 020)
ctr Low-level containerd debugging (Lab 019)
nerdctl Docker-compatible CLI for containerd
Why nerdctl?
  • No Docker daemon needed - talks directly to containerd
  • Docker-compatible syntax - nerdctl run = docker run
  • Rootless containers - run containers without root privileges
  • Lazy-pulling (eStargz) - start containers before full image download
  • Image encryption - encrypt container images with OCIcrypt
  • P2P image distribution - share images via IPFS
  • Compose support - nerdctl compose up works like docker compose

Web Terminal

This lab includes an interactive xterm.js web terminal that connects directly to your Kind cluster nodes via docker exec. You get tabbed terminals for each node (control-plane, worker, worker2) with the lab documentation side-by-side.

Architecture
graph TD
    subgraph Tabs["Kind Cluster"]
        T1["CP"]
        T2["worker"]
        T3["worker2"]
    end
    Tabs -->|WebSocket| Server["server.js<br/>node-pty"]
    Server -->|"docker exec -it"| CP["control-plane"]
    Server -->|"docker exec -it"| W1["worker"]
    Server -->|"docker exec -it"| W2["worker2"]
Start the Web Terminal
cd Labs/021-Nerdctl
npm install
npm start

Open http://localhost:3016 in your browser. Each tab gives you a shell inside a Kind node where you can run nerdctl commands directly.


01. Getting Started with nerdctl

Step 1.1 - Check nerdctl availability

On a Kubernetes node (or inside a kind node), use the web terminal tabs above or manually:

# Enter the kind worker node
docker exec -it workshop-worker bash

# Verify nerdctl is installed
nerdctl --version

Expected output:

nerdctl version 1.x.x

Installing nerdctl

If nerdctl is not available on the node, you can install it:

# Download the latest release
curl -sSL https://github.com/containerd/nerdctl/releases/download/v1.7.7/nerdctl-1.7.7-linux-amd64.tar.gz \
  | tar -xz -C /usr/local/bin nerdctl
nerdctl --version

Step 1.2 - nerdctl help and subcommands
nerdctl --help

Key subcommands (Docker-compatible):

Subcommand Purpose
run Run a container
exec Execute a command in a container
ps List containers
images List images
pull Pull an image
build Build an image (via BuildKit)
logs Fetch container logs
inspect Inspect containers/images
compose Docker Compose compatible
network Manage networks
volume Manage volumes
namespace Manage containerd namespaces

02. nerdctl vs docker - Command Comparison

The beauty of nerdctl is that most Docker commands translate 1:1.

Docker Command nerdctl Equivalent Notes
docker run nerdctl run Same flags
docker ps nerdctl ps Same output
docker images nerdctl images Same output
docker pull nerdctl pull Same syntax
docker build nerdctl build Requires BuildKit
docker compose up nerdctl compose up Built-in, no separate binary
docker logs nerdctl logs Same flags
docker exec nerdctl exec Same flags
docker inspect nerdctl inspect Same JSON output
docker network ls nerdctl network ls CNI-based networking
docker volume ls nerdctl volume ls Same concept
docker tag nerdctl tag Same syntax
docker push nerdctl push Same syntax
Key Differences
# Docker uses its own daemon
docker ps

# nerdctl talks to containerd directly
nerdctl ps

# nerdctl supports containerd namespaces
nerdctl -n k8s.io ps    # see Kubernetes containers!
nerdctl -n default ps    # see default namespace containers

03. Containerd Namespaces with nerdctl

Just like ctr, nerdctl respects containerd namespaces.

Step 3.1 - List namespaces
nerdctl namespace list
# OR short form
nerdctl namespace ls

Expected output:

NAME    CONTAINERS    IMAGES    VOLUMES    LABELS
k8s.io  42            28        0

Extra info

Unlike ctr ns list, nerdctl namespace ls shows the count of containers, images, and volumes per namespace.

Step 3.2 - Work with the Kubernetes namespace
# List Kubernetes containers
nerdctl -n k8s.io ps

# List Kubernetes images
nerdctl -n k8s.io images
Step 3.3 - Create and use a custom namespace
# Create a namespace
nerdctl namespace create workshop-debug

# Run a container in the custom namespace
nerdctl -n workshop-debug run --rm alpine echo "Hello from workshop-debug!"

# Clean up
nerdctl namespace remove workshop-debug

04. Image Management

Step 4.1 - List images
# List images in default namespace
nerdctl images

# List images in k8s.io namespace
nerdctl -n k8s.io images

# Quiet mode (IDs only)
nerdctl -n k8s.io images -q
Step 4.2 - Pull an image
nerdctl pull alpine:3.19
Step 4.3 - Tag an image
nerdctl tag alpine:3.19 my-alpine:latest
Step 4.4 - Inspect an image
nerdctl image inspect alpine:3.19

This outputs detailed JSON including: - Image config (env, cmd, entrypoint) - Layer digests - Platform info - Creation timestamp

Step 4.5 - Image history
nerdctl image history alpine:3.19

Docker equivalent

This is exactly like docker image history - shows all layers and their sizes.

Step 4.6 - Remove an image
nerdctl rmi my-alpine:latest
Step 4.7 - Save and load images
# Save an image to a tar file
nerdctl save -o alpine.tar alpine:3.19

# Load an image from a tar file
nerdctl load -i alpine.tar

ctr vs nerdctl

ctr uses export/import while nerdctl uses save/load (matching Docker’s syntax).


05. Running Containers

Step 5.1 - Run a container (foreground)
nerdctl run --rm alpine:3.19 echo "Hello from nerdctl"
Step 5.2 - Run a container (interactive)
nerdctl run --rm -it alpine:3.19 sh

Inside the container:

hostname
cat /etc/os-release
ls /
exit

Step 5.3 - Run a container (detached)
nerdctl run -d --name my-nginx -p 8080:80 nginx:alpine
Step 5.4 - List running containers
# List running containers
nerdctl ps

# List all containers (including stopped)
nerdctl ps -a
Step 5.5 - View container logs
nerdctl logs my-nginx

# Follow logs
nerdctl logs -f my-nginx

# Show last 10 lines
nerdctl logs --tail 10 my-nginx
Step 5.6 - Exec into a running container
nerdctl exec -it my-nginx sh

Inside:

nginx -v
cat /etc/nginx/nginx.conf
exit

Step 5.7 - Inspect a container
nerdctl inspect my-nginx
Step 5.8 - Stop and remove
nerdctl stop my-nginx
nerdctl rm my-nginx

06. Networking

Step 6.1 - List networks
nerdctl network ls
Step 6.2 - Create a custom network
nerdctl network create my-network
Step 6.3 - Run containers on a custom network
# Start two containers on the same network
nerdctl run -d --name web --network my-network nginx:alpine
nerdctl run -d --name client --network my-network alpine:3.19 sleep 3600

# Test connectivity
nerdctl exec client ping -c 3 web
Step 6.4 - Inspect a network
nerdctl network inspect my-network
Step 6.5 - Clean up networking
nerdctl stop web client
nerdctl rm web client
nerdctl network rm my-network

07. Volumes

Step 7.1 - Create a volume
nerdctl volume create my-data
Step 7.2 - Use a volume
# Run a container with the volume mounted
nerdctl run --rm -v my-data:/data alpine:3.19 sh -c "echo 'persistent data' > /data/test.txt"

# Verify data persists
nerdctl run --rm -v my-data:/data alpine:3.19 cat /data/test.txt
Step 7.3 - List and inspect volumes
nerdctl volume ls
nerdctl volume inspect my-data
Step 7.4 - Remove a volume
nerdctl volume rm my-data

08. Inspecting Kubernetes Containers

This is where nerdctl shines for debugging - it gives you a Docker-like experience for inspecting Kubernetes containers.

Step 8.1 - List Kubernetes containers
nerdctl -n k8s.io ps

This shows all containers managed by Kubernetes on this node, in a familiar docker ps format.

Step 8.2 - Find a specific pod’s containers
nerdctl -n k8s.io ps | grep -i apphub
Step 8.3 - Get container logs (Kubernetes containers)
CONTAINER_ID=$(nerdctl -n k8s.io ps | grep apphub | head -1 | awk '{print $1}')
nerdctl -n k8s.io logs "${CONTAINER_ID}"

vs kubectl logs

kubectl logs goes through the API server → kubelet → CRI → containerd. nerdctl -n k8s.io logs goes directly to containerd - useful when the API server is down!

Step 8.4 - Inspect a Kubernetes container
nerdctl -n k8s.io inspect "${CONTAINER_ID}"
Step 8.5 - Exec into a Kubernetes container
nerdctl -n k8s.io exec -it "${CONTAINER_ID}" sh

Caution

Exec-ing into K8s containers via nerdctl bypasses Kubernetes RBAC. Use this only for node-level debugging.


09. Building Images with nerdctl

nerdctl supports building images using BuildKit - the same build engine used by modern Docker.

Step 9.1 - Build an image
# Create a simple Dockerfile
cat > /tmp/Dockerfile <<'EOF'
FROM alpine:3.19
RUN apk add --no-cache curl
CMD ["curl", "--version"]
EOF

# Build the image
nerdctl build -t my-curl:latest /tmp/

BuildKit Required

nerdctl build requires BuildKit (buildkitd). On systems without BuildKit, you’ll get an error. In that case, build images with Docker and load them into containerd.

Step 9.2 - Verify the built image
nerdctl images | grep my-curl
nerdctl run --rm my-curl:latest

10. Compose Support

nerdctl compose is a built-in Docker Compose compatible feature - no separate binary needed.

Step 10.1 - Create a compose file
cat > /tmp/docker-compose.yml <<'EOF'
services:
  web:
    image: nginx:alpine
    ports:
      - "8080:80"
  redis:
    image: redis:alpine
EOF
Step 10.2 - Start services
cd /tmp
nerdctl compose up -d
Step 10.3 - Check running services
nerdctl compose ps
Step 10.4 - View logs
nerdctl compose logs
Step 10.5 - Stop and clean up
nerdctl compose down

11. Advanced Features

Step 11.1 - System-wide information
nerdctl system info
Step 11.2 - Disk usage
nerdctl system df
Step 11.3 - Prune unused resources
# Remove stopped containers
nerdctl container prune -f

# Remove unused images
nerdctl image prune -f

# Remove everything unused
nerdctl system prune -f
Step 11.4 - Copy files to/from containers
nerdctl run -d --name copy-test alpine:3.19 sleep 3600

# Copy file into container
echo "hello" > /tmp/test.txt
nerdctl cp /tmp/test.txt copy-test:/tmp/test.txt

# Copy file from container
nerdctl cp copy-test:/etc/hostname /tmp/hostname.txt
cat /tmp/hostname.txt

# Clean up
nerdctl stop copy-test && nerdctl rm copy-test

12. Practical Exercises

Exercise 1 - Docker Migration

Translate these Docker commands to nerdctl and run them:

# 1. Pull nginx:alpine
nerdctl pull nginx:alpine

# 2. Run it with port mapping
nerdctl run -d --name web -p 8080:80 nginx:alpine

# 3. Check logs
nerdctl logs web

# 4. Exec into the container
nerdctl exec -it web sh -c "echo 'Hello from nerdctl' > /usr/share/nginx/html/index.html"

# 5. Verify the change
nerdctl exec web cat /usr/share/nginx/html/index.html

# 6. Stop and remove
nerdctl stop web && nerdctl rm web
Exercise 2 - Kubernetes Container Investigation
# 1. List all Kubernetes containers on this node
nerdctl -n k8s.io ps

# 2. Count running containers
nerdctl -n k8s.io ps -q | wc -l

# 3. Find workshop-related containers
nerdctl -n k8s.io ps | grep -iE "app[1-4]|apphub"

# 4. Get logs from a workshop container
CONTAINER_ID=$(nerdctl -n k8s.io ps | grep apphub | head -1 | awk '{print $1}')
nerdctl -n k8s.io logs --tail 20 "${CONTAINER_ID}"

# 5. Inspect the container
nerdctl -n k8s.io inspect "${CONTAINER_ID}" | python3 -m json.tool | head -50
Exercise 3 - Networking Deep Dive
# 1. Create a custom network
nerdctl network create debug-net

# 2. Run two containers on it
nerdctl run -d --name server --network debug-net nginx:alpine
nerdctl run -d --name client --network debug-net alpine:3.19 sleep 3600

# 3. Test DNS resolution
nerdctl exec client nslookup server

# 4. Test connectivity
nerdctl exec client wget -qO- http://server

# 5. Clean up
nerdctl stop server client
nerdctl rm server client
nerdctl network rm debug-net
Exercise 4 - Image Forensics
# 1. Compare image sizes between namespaces
echo "=== Default namespace ==="
nerdctl images
echo ""
echo "=== Kubernetes namespace ==="
nerdctl -n k8s.io images

# 2. Check image history for a K8s image
K8S_IMAGE=$(nerdctl -n k8s.io images --format '{{.Repository}}:{{.Tag}}' | head -1)
nerdctl -n k8s.io image history "${K8S_IMAGE}"

# 3. Save a K8s image as a tarball
nerdctl -n k8s.io save -o /tmp/k8s-image.tar "${K8S_IMAGE}"
ls -lh /tmp/k8s-image.tar

Quick Reference

nerdctl Cheat Sheet
# ── Container Lifecycle ──
nerdctl run --rm <image> <cmd>            # run (foreground)
nerdctl run --rm -it <image> sh           # run (interactive)
nerdctl run -d --name <n> <image>         # run (detached)
nerdctl ps                                # list running
nerdctl ps -a                             # list all
nerdctl logs <container>                  # view logs
nerdctl logs -f <container>               # follow logs
nerdctl exec -it <container> sh           # exec into container
nerdctl inspect <container>               # inspect container
nerdctl stop <container>                  # stop container
nerdctl rm <container>                    # remove container

# ── Images ──
nerdctl images                            # list images
nerdctl pull <image>                      # pull image
nerdctl build -t <tag> <path>             # build image (BuildKit)
nerdctl tag <src> <dst>                   # tag image
nerdctl push <image>                      # push image
nerdctl rmi <image>                       # remove image
nerdctl save -o out.tar <image>           # save to tarball
nerdctl load -i in.tar                    # load from tarball
nerdctl image inspect <image>             # inspect image
nerdctl image history <image>             # show layers

# ── Networking ──
nerdctl network ls                        # list networks
nerdctl network create <name>             # create network
nerdctl network inspect <name>            # inspect network
nerdctl network rm <name>                 # remove network

# ── Volumes ──
nerdctl volume ls                         # list volumes
nerdctl volume create <name>              # create volume
nerdctl volume inspect <name>             # inspect volume
nerdctl volume rm <name>                  # remove volume

# ── Compose ──
nerdctl compose up -d                     # start services
nerdctl compose ps                        # list services
nerdctl compose logs                      # view logs
nerdctl compose down                      # stop & remove

# ── Namespaces ──
nerdctl namespace ls                      # list namespaces
nerdctl -n k8s.io ps                      # K8s containers
nerdctl -n k8s.io images                  # K8s images

# ── System ──
nerdctl system info                       # system info
nerdctl system df                         # disk usage
nerdctl system prune -f                   # clean up
nerdctl cp <src> <dst>                    # copy files

Summary

Concept What you learned
nerdctl Docker-compatible CLI for containerd
Namespaces Same containerd namespaces as ctr - use -n k8s.io
Images Pull, tag, save, load - Docker syntax on containerd
Containers Run, exec, logs, inspect - familiar Docker workflow
Networking CNI-based networks, DNS resolution between containers
Volumes Persistent storage, same as Docker volumes
Compose Built-in nerdctl compose - no separate binary needed
K8s Debugging Inspect K8s containers directly via containerd namespace

Key Takeaway

nerdctl bridges the gap between the simplicity of docker and the directness of ctr. Use it when you want Docker-like UX without a Docker daemon.