containerd: AI-Optimized Technical Reference

Executive Summary

containerd is a container runtime that Kubernetes uses instead of Docker. It's 20-30% faster with lower memory usage (~40MB vs 200MB+) but lacks image building capabilities and has a hostile CLI interface.

Critical Configuration Requirements

Installation Failure Modes

• Ubuntu: apt install containerd installs broken ancient version
  • Solution: Add Docker's repo first, install containerd.io
• CentOS/RHEL: Base repo package often broken
  • Solution: Use Docker's repo or build from source
• Windows: WSL2 integration is unreliable

Configuration Breaking Points

• Config location: /etc/containerd/config.toml
• Version migration: 1.x to 2.x breaks config format
• Critical setting: SystemdCgroup = true (required for k8s with systemd)
  • Failure consequence: Pods randomly fail to start
• Registry config: Now in /etc/containerd/certs.d/, not main config

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

Operational Intelligence

Performance Characteristics

• Container startup: 20-30% faster than Docker
• Memory footprint: ~40MB (containerd) vs 200MB+ (Docker)
• Significance: Matters at scale (thousands of containers), negligible for development

Version Strategy

• Production: containerd 1.7.x (LTS until March 2026)
• Avoid: Distribution packages (ancient/broken)
• Current: 2.1.4 as of August 2025 (breaking changes from 1.x)

Runtime Comparison Matrix

Runtime	Memory	Build Images	Rootless	k8s Default	Best Use Case
containerd	~40MB	No (needs BuildKit)	Complex setup	Yes	Production k8s
Docker	200MB+	Yes (built-in)	Half-broken	Deprecated	Development
Podman	~60MB	Yes (buildah)	Designed for it	Needs CRI setup	Rootless environments
CRI-O	~50MB	No	Works	OpenShift default	k8s purist

Critical Failure Scenarios

Common Breaking Points

1. "failed to start container"

   • Root cause: cgroup misconfiguration
   • Diagnostic: Check SystemdCgroup setting
   • Alternative error: "failed to create shim task"

2. Image pulls hang

   • Root cause: Registry configuration issues
   • Diagnostic: Check /etc/containerd/certs.d/
   • Symptoms: "connection timeout" or "x509" errors in journalctl -u containerd

3. Containers won't stop

   • Root cause: Stuck shim processes
   • Diagnostic: ps aux | grep containerd-shim
   • Nuclear option: kill -9 containerd process

4. Permission denied

   • Root cause: SELinux/AppArmor blocking
   • Diagnostic: ausearch -m avc for SELinux violations
   • Test: setenforce 0 temporarily

CLI Interface Reality

• Native tool: ctr (user-hostile, requires namespaces for everything)
• Better alternative: nerdctl (Docker-like commands)
• Namespace gotcha: k8s uses k8s.io, default is default

# ctr (painful)
ctr -n k8s.io containers list

# nerdctl (sane)
nerdctl ps

Resource Requirements

Expertise Investment

• Minimal: If using managed k8s (EKS/GKE/AKS) - runs transparently
• Moderate: For direct installation/configuration
• High: For rootless setup, custom runtimes (gVisor/Kata)

Time Investment

• Installation: 30 minutes (if using correct repos)
• Basic config: 1-2 hours
• Rootless setup: 4-8 hours (multiple config files, kernel requirements)
• Troubleshooting: Significantly longer than Docker (fewer Stack Overflow answers)

Decision Criteria

Use containerd When:

• Running production Kubernetes (already using it)
• Need rootless containers (better than Docker)
• Want faster container startup at scale
• Avoiding Docker licensing fees

Stick with Docker When:

• Local development (better tooling ecosystem)
• Need integrated image building
• Want mature troubleshooting resources
• Using Docker Compose extensively

Avoid containerd When:

• Need GUI management tools
• Require Windows container support
• Team lacks container runtime expertise

Monitoring and Debugging

Metrics

• Endpoint: /metrics (Prometheus format)
• Quality: Low-level metrics like containerd_container_blkio_io_serviced_recursive_total
• Requirement: Need cAdvisor or node-exporter for useful container metrics

Logging

• Location: journald (journalctl -u containerd)
• Debug mode: Fills disk rapidly
• Container logs: Handled by calling system (usually k8s)

Support Channels

1. GitHub Issues: Primary troubleshooting resource
2. Official Slack: Real-time community support
3. Stack Overflow: Limited containerd content compared to Docker

Security Considerations

Rootless Implementation

• Setup complexity: High (rootlesskit, multiple configs, kernel requirements)
• Adoption: Most run as root despite security implications
• Prerequisites: User namespace kernel support, specific file permissions

Production Security

• Default: Runs as root
• Hardening: User namespaces, SELinux/AppArmor policies
• Supply chain: Notary v2 integration available for image signing

Integration Ecosystem

Image Building

• containerd: No native building
• Solutions: BuildKit, buildah, kaniko
• Complexity: More setup than Docker's integrated approach

Orchestration

• Kubernetes: Native integration (default runtime)
• Docker Compose: Limited nerdctl support, some features missing
• Single containers: Use nerdctl for Docker-like experience

Registry Integration

• Configuration: /etc/containerd/certs.d/ directory structure
• Authentication: hosts.toml format
• Private registries: Requires explicit configuration (not auto-discovered)

Migration Considerations

From Docker

• Images: Compatible (same OCI format)
• Compose files: Limited compatibility via nerdctl
• Build processes: Need separate BuildKit setup
• Monitoring: Different metrics format

Kubernetes Migration

• Timeline: Most managed services already migrated
• Impact: Transparent to applications
• Troubleshooting: Different error messages, fewer familiar debugging tools

Breaking Changes and Gotchas

Version 2.x Changes

• Config format: TOML structure changed
• API endpoints: Some breaking changes
• Migration: Test thoroughly, regenerate config with containerd config default

Production Deployment Warnings

• Don't: Use distribution packages
• Don't: Upgrade major versions without testing config
• Don't: Assume Docker Compose full compatibility
• Do: Monitor GitHub releases for security updates
• Do: Test rootless setup extensively before production use