containerd - The Container Runtime That Actually Just Works

So you've heard containerd is "the boring container runtime that Kubernetes uses" - but what does that actually mean for you? containerd is what happens when you rip out the container runtime from Docker and make it standalone. Docker Inc. extracted it years ago because everyone realized the fat Docker daemon was overkill for production Kubernetes. Now containerd handles the boring shit - starting containers, managing images, cleaning up when things die - while other tools handle the flashy stuff.

Why Kubernetes Ditched Docker (And Why You Should Know)

Back in 2020, Kubernetes announced Docker deprecation and everyone panicked. Turns out it was much ado about nothing - Kubernetes wasn't using Docker's fancy features anyway, just containerd underneath. So they cut out the middleman.

Here's how it actually works: containerd manages container lifecycle through a gRPC API, then hands off the actual container execution to runc. It's like having a manager (containerd) who delegates the real work to someone else (runc). The OCI Runtime Specification defines exactly how this handoff works. Boring but reliable.

What containerd Actually Does

containerd handles the unglamorous but critical parts:

• Image Management: Downloads and stores your bloated container images without bitching about disk space. Uses content-addressable storage to deduplicate layers.
• Container Lifecycle: Starts your containers fast, kills them when asked, cleans up the mess. The container lifecycle API is actually sane.
• Networking: Sets up basic networking then gets out of the way for CNI plugins to do the heavy lifting
• Storage: Copy-on-write filesystem snapshots so you're not copying 500MB base images around like an idiot. Multiple snapshotters available (overlayfs, zfs, btrfs).
• Security: Rootless containers, user namespaces, all the security theater that actually works

Current version is containerd 2.1.4 as of August 2025. The 1.7.x series is LTS until March 2026, so you have time to procrastinate upgrades. Note that the 2.x series introduced breaking changes in the config format and some API endpoints - test thoroughly before upgrading production systems.

Where You'll Actually Encounter This

Kubernetes: Every major cloud provider (AWS EKS, Google GKE, Azure AKS) switched to containerd. If you're deploying to managed k8s, you're using containerd whether you know it or not.

Local Development: Tools like nerdctl give you Docker-like commands (nerdctl run, nerdctl build) but with containerd underneath. It's for people who want Docker functionality without Docker Inc's increasingly hostile licensing.

Why It's Actually Better

containerd starts containers roughly 20-30% faster than Docker because there's less crap in the way. Memory usage is lower because it's not running a kitchen-sink daemon. These gains matter when you're spinning up thousands of containers, not so much for your 3-container development environment.

The CNCF graduated containerd, meaning it passed their bureaucracy test and won't randomly disappear. Big tech companies like Google, AWS, and Microsoft bet their infrastructure on it, so it's probably not going anywhere.

So containerd is clearly important and here to stay - but actually using it? That's where things get interesting. The theory is clean, but the practice has some sharp edges you need to know about.

Now that you understand what containerd is and why it matters, let's talk about the reality of actually using it in production. The official docs make everything sound straightforward, but there are gotchas that'll waste hours of your time if you're not prepared.

Installation: It's Not As Simple As They Say

The official docs make installation sound straightforward, but there are gotchas. On Ubuntu, don't just apt install containerd - you'll get an ancient version that's broken. Add Docker's repo first: curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg then install containerd.io.

On CentOS/RHEL, the containerd package from the base repo is often broken. Use Docker's repo or build from source if you enjoy pain. Windows users: containerd works for Windows containers but the WSL2 integration is flaky at best.

The Configuration Nightmare

containerd's config lives in /etc/containerd/config.toml and the format changed between major versions. If you're upgrading from 1.x to 2.x, your config file will break. Run containerd config default > /etc/containerd/config.toml to generate a working starting point.

The config is TOML and looks like this clusterfuck:

[plugins."io.containerd.grpc.v1.cri".containerd.runtimes.runc.options]
  SystemdCgroup = true

Key things that will bite you:

• SystemdCgroup = true: Required for k8s with systemd. Forget this and pods will randomly fail to start
• Registry configuration: Goes in /etc/containerd/certs.d/ now, not in the main config. The hosts.toml documentation is your friend
• Runtime selection: Default is runc. If you want gVisor or Kata, good luck with the configuration hell

Real-World Deployment Pain

Development Setup: Install nerdctl if you want Docker-like commands. nerdctl run nginx works like docker run nginx, but some Docker Compose features are missing or broken. BuildKit integration exists but it's not as seamless as Docker's.

Kubernetes: Most managed k8s services (EKS, GKE, AKS) use containerd by default now. You won't notice unless something breaks, then you'll miss Docker's better error messages. containerd errors are cryptic: failed to create containerd container: mount callback failed tells you nothing useful.

The ctr CLI Tool from Hell

containerd ships with `ctr`, which is the most user-hostile CLI tool ever created. Commands look like:

ctr namespace create test
ctr -n test image pull docker.io/library/nginx:latest
ctr -n test run --rm -t docker.io/library/nginx:latest nginx

Everything needs a namespace (-n). The default namespace is default but k8s uses k8s.io. Forget the namespace and your containers disappear into the void.

Monitoring: It Exists But It's Basic

containerd exposes Prometheus metrics at /metrics but they're low-level: containerd_container_blkio_io_serviced_recursive_total. You'll need something like cAdvisor or node-exporter for useful container metrics.

For debugging, logs go to journald (journalctl -u containerd) and they're verbose. Enable debug logging at your own risk - it will fill your disk. The tracing guide helps with deeper issues.

Security: Rootless Works But Setup Sucks

Rootless containerd is possible but the setup is painful. You need:

• User namespace support in your kernel
• Multiple config files in the right places
• The rootlesskit wrapper around everything
• Prayers to the container gods

Most people just run as root and deal with the security implications.

When Things Break

Common issues you'll hit:

• "failed to start container": Usually cgroup issues. Check if systemd cgroups are enabled in /etc/containerd/config.toml. The error might also appear as "failed to create shim task" in the logs
• Image pulls hang: Registry configuration is fucked. Check /etc/containerd/certs.d/ for proxy settings or auth issues. Look for "connection timeout" or "x509" certificate errors in journalctl -u containerd
• Containers won't stop: containerd is waiting for something. kill -9 the containerd process and start over. This often happens when the shim process gets stuck - check ps aux | grep containerd-shim for orphaned processes
• Permission denied: SELinux or AppArmor is blocking something. Check ausearch -m avc for SELinux violations or disable temporarily with setenforce 0 to test. Also verify user has access to /run/containerd/containerd.sock

The GitHub issues are your best bet for troubleshooting. Stack Overflow has fewer containerd answers than Docker ones. Check the troubleshooting guide and common issues docs first.