How to Upgrade to containerd 2.3: First Annual LTS Release with Kubernetes-Aligned Cadence

March 18, 2026•Stackxx•DevOps, Kubernetes

containerd 2.3.0-beta.0 dropped on March 18, 2026, marking a significant shift for the project’s release strategy. For the first time, containerd is moving to an annual LTS (Long Term Stable) release model with a predictable 4-month minor release cadence aligned with Kubernetes releases.

What’s New in containerd 2.3

This release introduces several important features alongside the new LTS commitment:

Plugin config migration on load – Configuration updates now apply automatically when plugins load
CDI vendor detection – Better GPU support with automatic device ID generation for --gpus flags
Sandbox API spec field – Extended API flexibility for custom sandbox implementations
CRI improvements – Per-layer image labels, proper ImageId in container status, and annotation support in CreateSandbox
NRI enhancements – Container user info, seccomp policies, and POSIX rlimits now passed to plugins

Goal

Upgrade containerd to 2.3.0 while maintaining workload availability and understanding the LTS implications for production clusters.

Prerequisites

containerd 1.7.x or 2.0.x currently running
Kubernetes 1.30+ (for full CRI feature support)
Node drain capability or maintenance window
Backup of /etc/containerd/config.toml

Steps

1. Check current version

sudo ctr version

2. Download containerd 2.3

wget https://github.com/containerd/containerd/releases/download/v2.3.0-beta.0/containerd-2.3.0-beta.0-linux-amd64.tar.gz
sudo tar Cxzvf /usr/local containerd-2.3.0-beta.0-linux-amd64.tar.gz

3. Migrate configuration

containerd 2.3 automatically migrates plugin configs on load, but verify your config:

sudo containerd config migrate > /etc/containerd/config.toml.new
sudo cp /etc/containerd/config.toml /etc/containerd/config.toml.backup
sudo mv /etc/containerd/config.toml.new /etc/containerd/config.toml

4. Restart service

sudo systemctl restart containerd
sudo systemctl status containerd

Common Pitfalls

Issue	Cause	Fix
GPU workloads fail	CDI spec changes	Update nvidia-container-toolkit to 1.17+
NRI plugins break	New uid/gid/seccomp fields	Update plugins to handle new proto fields
Image pull failures	Different snapshotter behavior	Clear `/var/lib/containerd` and re-pull

Verify

# Check containerd version
ctr version

# Verify CRI is functional
crictl version
crictl pods

# Test GPU access (if applicable)
ctr run --gpus 0 --rm docker.io/nvidia/cuda:12.0-base test nvidia-smi

Sources

Next signal