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

- Link: https://thestackobserver.com/upgrade-containerd-2-3-lts-kubernetes/
- Published: 2026-03-18T14:35:04-04:00
- Author: Stackxx

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

    ```wp-block-code
    sudo ctr version
    ```

### 2. Download containerd 2.3

    ```wp-block-code
    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:

    ```wp-block-code
    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

    ```wp-block-code
    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

    ```wp-block-code
    # 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

 * [containerd 2.3.0-beta.0 Release Notes](https://github.com/containerd/containerd/releases/tag/v2.3.0-beta.0)
 * [Kubernetes Container Runtimes Documentation](https://kubernetes.io/docs/setup/production-environment/container-runtimes/)