Nerdctl - Skip Docker's Daemon Bullshit

If you're running K8s in production, you're already using containerd as the container runtime anyway. Docker Desktop just adds an extra layer on top of what you already have. Nerdctl lets you talk directly to containerd with commands that work exactly like Docker.

The Problem Nerdctl Solves

Docker's architecture is annoying as hell. Every docker run command goes through the Docker daemon (dockerd), which then talks to containerd, which actually runs your shit. That's two layers when you only need one. I've spent way too many hours debugging Docker daemon issues that turn out to be containerd problems in disguise.

In K8s clusters, containerd runs your pods directly. But if you want to debug a container or build an image on a K8s node, you're stuck with the low-level ctr command that nobody wants to learn. Nerdctl gives you Docker commands that work directly with containerd.

What Actually Works

The good news is most Docker commands work identically:

• nerdctl run -it ubuntu bash - works exactly like Docker
• nerdctl build -t myapp . - builds images with BuildKit
• nerdctl compose up - runs your docker-compose files
• nerdctl ps - lists containers

Your muscle memory from Docker just works. No need to learn new commands or change your scripts.

Gotchas You'll Hit

Setup is More Involved

Unlike Docker Desktop which "just works", nerdctl requires you to install and configure several components:

• containerd daemon
• CNI networking plugins
• BuildKit for image builds
• Various snapshotters for different features

The nerdctl-full tarball bundles most dependencies, but you'll still need to configure networking and systemd services. I spent 3 hours figuring this out the first time because the docs assume you already know containerd inside and out. Spoiler: nobody does.

On RHEL/CentOS 8, the default firewall rules block CNI networking. Ubuntu 22.04 works fine but 20.04 has SELinux issues with rootless mode.

CNI Networking Can Be a Pain

Docker handles networking automatically. With nerdctl, you need to understand CNI plugins. The default bridge network might not work the way you expect. Port publishing works differently. If you've never configured CNI plugins before, expect to spend time reading documentation that assumes you're already a networking expert. I wasn't, and it showed - spent an entire afternoon trying to get port forwarding to work properly.

BuildKit Integration is Finicky

Image building requires BuildKit daemon running separately from containerd. Sometimes BuildKit fails to start for no obvious reason. Sometimes it runs out of disk space in /tmp and fails silently. The error messages are complete garbage when this happens - you'll get cryptic bullshit like "failed to solve: rpc error: code = Unknown desc = failed to receive status" that tells you fuck-all about what actually broke. I've wasted entire afternoons on this exact error.

BuildKit version 0.11+ changed the default socket path from /run/buildkit/buildkitd.sock to something completely different, so if you upgrade containerd but not BuildKit (or vice versa), everything breaks with zero indication of what's wrong. Found this out the hard way during a system update.

Some Docker Features Don't Exist

• No equivalent to Docker Desktop's GUI
• Volume mounting syntax is slightly different
• Some docker-compose features have edge cases
• Third-party tools that expect Docker specifically won't work

Advanced Features That Are Actually Useful

Direct Kubernetes Access

This is the killer feature. On a K8s node, you can debug pods directly:

nerdctl --namespace k8s.io ps
nerdctl --namespace k8s.io exec -it pod-name bash

No need to set up kubectl or deal with registries for debugging. This alone justifies using nerdctl if you're debugging K8s issues regularly.

Lazy Pulling with Stargz

Large images start faster because nerdctl can pull layers on-demand. Works great for machine learning images that are 10GB+ but you only need the first few layers to start.

Image Encryption

Built-in support for encrypted container images. Actually useful for regulated environments where you need encryption at rest.

Current Version Status

Version 2.1.4 came out like a week ago. Still actively developed, which is good because containerd keeps changing shit and breaking backwards compatibility.

Here's what actually happens when you try to install nerdctl and the problems you'll run into.

Installation Reality Check

Option 1: The \"Easy\" Binary Install

Download the nerdctl-full tarball because the minimal version is missing half the shit you need:

wget https://github.com/containerd/nerdctl/releases/download/v2.1.4/nerdctl-full-2.1.4-linux-amd64.tar.gz
sudo tar -xzf nerdctl-full-2.1.4-linux-amd64.tar.gz -C /usr/local

This gives you nerdctl binary plus CNI plugins, BuildKit, and other dependencies. But you still need to:

1. Start containerd daemon (it doesn't auto-start like Docker)
2. Configure systemd services properly
3. Set up CNI networking (bridge networks won't work by default)
4. Make sure BuildKit daemon starts for image builds

I learned this the hard way - the first time I tried running nerdctl run hello-world, it just hung for 5 minutes before timing out with "FATA[0300] failed to create container: context deadline exceeded" which told me fuck-all about what was actually broken.

Option 2: Package Managers

brew install nerdctl

This installs just the binary. You still need containerd running and configured. On macOS, you're better off using Lima which gives you a Linux VM with everything pre-configured.

Option 3: Use Someone Else's Setup

If you're on a K8s node, containerd is already running. Just install the nerdctl binary and you're mostly done. This is actually the easiest path.

First Commands That Work

These Docker commands work identically with nerdctl:

## Basic container operations
nerdctl run -d --name test nginx:alpine
nerdctl ps
nerdctl logs test  
nerdctl exec -it test sh
nerdctl stop test && nerdctl rm test

## Image management
nerdctl pull redis:alpine
nerdctl images
nerdctl rmi redis:alpine

First Commands That Break

Networking Will Bite You

## This might not work the same as Docker
nerdctl run -p 8080:80 nginx

## Error: CNI plugin bridge not found
## Fix: Install CNI plugins and configure /etc/cni/net.d/

Docker handles bridge networking automatically. Nerdctl expects you to configure CNI plugins. The error messages are complete shit - you'll get "CNI plugin bridge not found" which doesn't tell you where to put the damn plugins or even what a CNI plugin is supposed to look like.

Building Images Fails Silently

## This will hang or fail mysteriously  
nerdctl build -t myapp .

## Error: BuildKit daemon not running
## Fix: Start buildkitd daemon separately

Image builds need BuildKit daemon running. Sometimes it starts automatically, sometimes it doesn't. Check with systemctl status buildkit or look for a buildkitd process. I've wasted hours troubleshooting this when the fix was literally just sudo systemctl start buildkit. The daemon was dead and nerdctl just said "buildkit not found" instead of "hey dumbass, start the daemon."

Volume Mounts Are Different

## Docker way works differently
nerdctl run -v /host/path:/container/path nginx

## Might need different options or paths

Volume mounting syntax varies slightly. Check the containerd mount documentation if mounts aren't working.

Docker Compose Support

This actually works well:

nerdctl compose up -f docker-compose.yml

Your existing docker-compose files work without changes. This is one of nerdctl's best features.

Kubernetes Integration (The Useful Part)

If you're on a K8s node, this is why you'd want nerdctl:

## Debug Kubernetes pods directly
nerdctl --namespace k8s.io ps
nerdctl --namespace k8s.io exec -it pod-12345-abcde /bin/bash

## Build images that K8s can use without a registry
nerdctl --namespace k8s.io build -t debug-app .
kubectl run debug --image=debug-app:latest

This bypasses kubectl and registries for debugging. Actually useful.

Advanced Features You Might Actually Use

Lazy Pulling for Large Images

## Use Stargz for on-demand layer pulling
nerdctl --snapshotter=stargz run tensorflow/tensorflow:latest

Starts containers before the full image downloads. Good for 5GB+ machine learning images.

Rootless Mode (Security)

## Install rootless setup
containerd-rootless-setuptool.sh install

## Run without root privileges
nerdctl run --rm hello-world

More secure than Docker's rootless mode, but setup is more involved. On Ubuntu 20.04, the rootless setup script breaks if you don't have the right kernel modules loaded.

Migration from Docker

1. Keep Docker running while you test nerdctl
2. Start with simple commands to verify basic functionality
3. Test your docker-compose files with nerdctl compose
4. Fix networking issues by configuring CNI properly
5. Update scripts gradually once you're confident it works

Don't try to migrate everything at once. Test thoroughly with your actual workloads. I made the mistake of switching our CI pipeline to nerdctl without testing the BuildKit setup first - took down builds for half a day until I figured out the daemon wasn't starting properly because of a fucking systemd configuration issue.