Containers Runtimes Docker 29

containerd Image Store (Default)

The containerd image store is now the default for all new installations, replacing Docker's legacy graphdriver-based image management. This is the most significant architectural change.

What changed:

• Image pull, push, and storage are handled by containerd's content store and snapshotter
• Images stored at /var/lib/containerd/io.containerd.content.v1.content/ instead of /var/lib/docker/image/
• containerd's overlayfs snapshotter replaces Docker's overlay2 storage driver for image layers
• Multi-platform image support is native (image index handling built into containerd)

Impact on existing installations:

• Existing Docker Engine installations upgrading from v28 retain their legacy storage unless explicitly migrated
• New installations get containerd image store by default
• docker images, docker pull, docker push work identically from the user perspective
• Images from legacy storage are not automatically migrated -- re-pull is required when switching

To verify which store is active:

docker info | grep "Storage Driver"
docker info | grep "containerd-snapshotter"

To opt-in on upgraded installations:

{
  "features": {
    "containerd-snapshotter": true
  }
}

Minimum API Version Raised to 1.44

Docker Engine 29 requires API version 1.44 or newer. Older clients that negotiate lower API versions will receive errors.

Affected clients:

• Docker CLI versions before 25.0 (check with docker version)
• Third-party tools using the Docker API must be updated
• CI/CD pipelines with pinned Docker client versions

Fix:

# Upgrade Docker CLI to match engine version
apt-get install docker-ce-cli=5:29.3.1-1~ubuntu.24.04~noble

# Or set API version explicitly (if client supports it)
export DOCKER_API_VERSION=1.44

nftables Support (Experimental Stabilized)

Docker Engine 29 can generate nftables rules directly instead of routing through the iptables-nft translation layer. This was experimental in v28 and is now considered stable-experimental.

Enable nftables:

{
  "iptables": true,
  "ip6tables": true,
  "experimental": true
}

Benefits over iptables-nft translation:

• Direct nftables rule generation eliminates translation overhead
• Better compatibility with modern Linux distributions that are deprecating iptables
• Cleaner rule sets for debugging (nft list ruleset)

When NOT to use nftables yet:

• If you depend on tools that inspect iptables rules (fail2ban, some monitoring agents)
• If your host has complex existing nftables rules that may conflict

HTTP Keep-Alive for Registry Connections

Docker Engine 29.3.1 enables HTTP keep-alive for registry connections, reusing TCP/TLS connections across multiple blob transfers during pull and push operations.

Impact:

• Faster multi-layer image pulls (no repeated TLS handshakes per layer)
• Reduced registry connection overhead
• Most visible improvement on images with many small layers

Removed Features

Security Fixes in 29.x

• Plugin installation hardening: Stricter validation of plugin manifests
• Git URL validation in BuildKit: Prevents SSRF via malicious Git URLs in build contexts
• Untrusted frontend protection: BuildKit validates frontend images before execution

Migration from Docker Engine 28.x

Pre-Migration Checklist

1. Check storage driver: docker info | grep "Storage Driver" -- if devicemapper or aufs, migrate to overlay2 first
2. Check API clients: Verify all tools support API 1.44+ (docker version on all clients)
3. Check Schema 1 images: docker inspect <image> | grep SchemaVersion -- re-push Schema 1 images
4. Back up: /var/lib/docker/, /etc/docker/daemon.json, volume data

Migration Steps

# 1. Stop containers (or use live-restore)
docker compose down  # for each project

# 2. Back up
cp -r /etc/docker/daemon.json /etc/docker/daemon.json.bak
tar czf /backup/docker-data.tar.gz /var/lib/docker/

# 3. Update packages
apt-get update
apt-get install docker-ce=5:29.3.1-1~ubuntu.24.04~noble \
  docker-ce-cli=5:29.3.1-1~ubuntu.24.04~noble \
  containerd.io

# 4. Verify
docker version
docker info
docker ps -a

# 5. Opt into containerd image store (optional for upgrades)
# Add to /etc/docker/daemon.json: "features": {"containerd-snapshotter": true}
# Then: systemctl restart docker
# Then re-pull images: docker pull <image>

Post-Migration Validation

# Check containerd version
docker info | grep containerd

# Verify all containers run
docker ps --format '{{.Names}}: {{.Status}}'

# Check for warnings
journalctl -u docker.service --since "10 min ago" | grep -i warn

# Verify network connectivity
docker exec <container> wget -qO- http://other-container:port/health

Version Boundaries

Features NOT available in Docker Engine 29.x:

• nftables is stable-experimental but not the default networking backend (iptables remains default)
• No built-in Kubernetes integration (use Docker Desktop or a separate K8s deployment)

Features introduced in Docker Engine 29.x:

• containerd image store as default (new installs)
• nftables stabilized (experimental flag)
• API minimum 1.44
• HTTP keep-alive for registries (29.3.1)
• containerd 2.2.2 bundled

Common Pitfalls

1. Upgrading without checking API clients: Existing CI/CD pipelines or monitoring tools using API < 1.44 will break immediately
2. Expecting automatic image migration: Switching to containerd image store requires re-pulling images; they are not automatically migrated from the legacy store
3. devicemapper/aufs users: These drivers are completely removed, not just deprecated. Upgrading without migrating to overlay2 first will fail to start the daemon
4. Schema 1 images: Very old images (pre-2017) in Schema 1 format cannot be pulled. Re-push them in OCI or Docker schema 2 format
5. Mixing containerd configs: Docker's containerd instance uses /etc/docker/containerd/ config, not /etc/containerd/config.toml. Do not conflate the two if running standalone containerd alongside Docker

Reference Files

• ../references/architecture.md -- Daemon/containerd/runc internals, networking, storage
• ../references/diagnostics.md -- Troubleshooting commands and workflows
• ../references/best-practices.md -- Dockerfile patterns, security, Compose patterns