021 · Nerdctl
Lab 021 - Nerdctl (nerdctl)
Module 021
- Goal: Master
nerdctl- the Docker-compatible CLI for containerd. - Objective: Learn to use
nerdctlas 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
nerdctlis and how it compares todocker,ctr, andcrictl - How to pull, build, tag, push, and remove images
- How to run, list, inspect, stop, and remove containers
- How to use
nerdctl composeas a Docker Compose alternative - How to inspect Kubernetes containers via containerd namespaces
- How to use
nerdctlfor 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.
nerdctlis a Docker-compatible CLI that talks directly to containerd - it aims to be a drop-in replacement fordocker.- Unlike
ctr(low-level, minimal),nerdctlprovides a user-friendly experience with familiar Docker commands. nerdctlsupports features like build (via BuildKit), compose, networking, and volumes - thingsctrcannot 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 upworks likedocker 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
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:
Installing nerdctl
If nerdctl is not available on the node, you can install it:
Step 1.2 - nerdctl help and subcommands
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
Expected output:
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
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
Step 4.3 - Tag an image
Step 4.4 - Inspect an image
This outputs detailed JSON including: - Image config (env, cmd, entrypoint) - Layer digests - Platform info - Creation timestamp
Step 4.5 - Image history
Docker equivalent
This is exactly like docker image history - shows all layers and their sizes.
Step 4.6 - Remove an image
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)
Step 5.2 - Run a container (interactive)
Inside the container:
Step 5.3 - Run a container (detached)
Step 5.4 - List running containers
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
Inside:
Step 5.7 - Inspect a container
Step 5.8 - Stop and remove
06. Networking
Step 6.1 - List networks
Step 6.2 - Create a custom 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
Step 6.5 - Clean up networking
07. Volumes
Step 7.1 - Create a volume
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
Step 7.4 - Remove a volume
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
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
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
Step 8.5 - Exec into a Kubernetes container
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
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
Step 10.3 - Check running services
Step 10.4 - View logs
Step 10.5 - Stop and clean up
11. Advanced Features
Step 11.1 - System-wide information
Step 11.2 - Disk usage
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.