Nerdctl: AI-Optimized Technical Reference

Overview

Container CLI that communicates directly with containerd runtime, bypassing Docker daemon layer. Drop-in replacement for Docker commands with Kubernetes integration capabilities.

Architecture & Core Problem

• Docker path: CLI → dockerd → containerd → container
• Nerdctl path: CLI → containerd → container
• Elimination: Removes Docker daemon overhead layer
• Kubernetes reality: K8s clusters already use containerd as runtime

Configuration Requirements

Critical Dependencies

1. containerd daemon (must be running)
2. CNI networking plugins (required for networking)
3. BuildKit daemon (required for image builds)
4. systemd services (proper configuration needed)

Installation Reality

• Recommended: nerdctl-full tarball (includes dependencies)
• Avoid: minimal version (missing critical components)
• Platform limitation: macOS requires Lima VM wrapper

Network Configuration (Critical Failure Point)

Default failure: CNI bridge networking not configured
Error symptoms:

• Commands hang for 5+ minutes
• "CNI plugin bridge not found"
• "context deadline exceeded"

Required setup:

# CNI plugins location: /opt/cni/bin/
# CNI config location: /etc/cni/net.d/
# Minimum config: 10-bridge.conflist with bridge type

OS-specific issues:

• RHEL/CentOS 8: firewall blocks CNI by default
• Ubuntu 20.04: SELinux conflicts in rootless mode
• Ubuntu 22.04: works without modifications

BuildKit Integration (High Failure Rate)

Critical Requirements

• Separate daemon: buildkitd must run independently
• Socket path: /run/buildkit/buildkitd.sock (version-dependent)
• Version compatibility: BuildKit 0.11+ changed default paths

Common Failures

• Silent failures: BuildKit runs out of /tmp space
• Cryptic errors: "rpc error: code = Unknown desc = failed to receive status"
• Version mismatches: containerd/BuildKit upgrades break compatibility
• Service startup: systemd service may not auto-start

Resolution

sudo systemctl enable --now buildkit
# Verify: systemctl status buildkit

Command Compatibility Matrix

Direct Replacements (100% Compatible)

• docker run → nerdctl run
• docker ps → nerdctl ps
• docker build → nerdctl build
• docker-compose up → nerdctl compose up

Syntax Differences (Breaking Changes)

• Volume mounting: path handling varies
• Port publishing: syntax differences exist
• Network creation: command variations
• docker-compose: edge cases in complex configurations

Resource Requirements

Time Investment

• Initial setup: 3+ hours (first-time users)
• Network configuration: 2-4 hours (if unfamiliar with CNI)
• BuildKit troubleshooting: 2-6 hours (common failure scenario)
• Migration testing: 1-3 days (for production workloads)

Expertise Prerequisites

• containerd knowledge: documentation assumes existing expertise
• CNI networking: required for network troubleshooting
• systemd services: needed for daemon management
• Kubernetes concepts: beneficial for advanced features

Performance Characteristics

Measurable Improvements

• K8s environments: eliminates Docker daemon overhead
• Large images (10GB+): lazy pulling with Stargz snapshotter
• Container startup: marginal improvement over Docker

Performance Reality

• Simple containers: negligible difference vs Docker
• Complex workloads: depends on containerd optimization
• Network operations: can be slower due to CNI complexity

Critical Warnings & Failure Modes

Production Blockers

1. Third-party tools: many expect Docker socket specifically
2. GUI dependencies: no Docker Desktop equivalent
3. Error messaging: less informative than Docker
4. Community size: smaller support ecosystem

Breaking Points

• 1000+ containers: UI performance degrades significantly
• Rootless networking: distribution-specific failures
• CNI plugin conflicts: multiple network managers cause issues
• BuildKit memory: requires adequate /tmp space allocation

Migration Risks

• CI/CD pipelines: volume mount differences break builds
• Development workflows: local setup complexity increases
• Team knowledge: learning curve for containerd concepts

Kubernetes Integration Advantages

Unique Capabilities

# Direct pod access (bypasses kubectl)
nerdctl --namespace k8s.io ps
nerdctl --namespace k8s.io exec -it pod-name bash

# Build images without registry
nerdctl --namespace k8s.io build -t debug-app .

Operational Benefits

• Debugging efficiency: direct container access
• Registry bypass: local image builds for K8s
• Native integration: uses existing containerd runtime

Security Features

Rootless Mode

• Setup complexity: more involved than Docker rootless
• Distribution support: Ubuntu 20.04 has known issues
• Kernel requirements: specific modules needed

Image Encryption

• Built-in support: ocicrypt integration
• Compliance value: useful for regulated environments
• Implementation: simpler than Docker third-party solutions

Decision Criteria

Migrate When

• Running Kubernetes in production (containerd already present)
• Need image encryption/advanced security
• Want to avoid Docker licensing costs
• Require lazy pulling for large images
• Need direct K8s pod debugging

Stay with Docker When

• Docker works without issues
• Team lacks containerd expertise
• Development primarily on macOS
• Third-party tools require Docker socket
• Setup/maintenance overhead concerns outweigh benefits

Resource Cost Analysis

• Migration effort: 1-4 weeks depending on complexity
• Training overhead: 2-8 hours per team member
• Operational complexity: increased troubleshooting difficulty
• Support costs: smaller community, fewer resources

Troubleshooting Decision Tree

Container Startup Failures

1. Check containerd: journalctl -u containerd
2. Verify CNI: ls /etc/cni/net.d/
3. Test basic networking: bridge configuration
4. Validate BuildKit: systemctl status buildkit

Build Failures

1. Confirm BuildKit daemon status
2. Check /tmp space availability
3. Verify socket path compatibility
4. Review BuildKit logs for specific errors

Network Issues

1. Validate CNI plugin installation
2. Check firewall rules (RHEL/CentOS)
3. Test bridge network creation
4. Verify network namespace configuration