# containerd v2.2.1

2025-12-18 · [Original release notes](https://github.com/containerd/containerd/releases/tag/v2.2.1) · [Full summary](https://ratatosk.io/en/releases/containerd/v2.2.1)

Security 1 · Breaking changes 3 · Important fixes 9 · Enhancements 17 · Dependency updates 29 · Other changes 34

## Check before upgrading

### Prerequisites

- **Recommended containerd release archive**: The recommended `containerd-<VERSION>-<OS>-<ARCH>.tar.gz` archive is dynamically linked with glibc 2.35, the version used by Ubuntu 22.04.
  > * `containerd-<VERSION>-<OS>-<ARCH>.tar.gz`:         ✅Recommended. Dynamically linked with glibc 2.35 (Ubuntu 22.04).
- **runc installation alongside containerd**
  > In addition to containerd, typically you will have to install [runc](https://github.com/opencontainers/runc/releases)
- **CNI plugin installation prerequisite**: CNI plugins typically must also be installed from their official sites.
  > and [CNI plugins](https://github.com/containernetworking/plugins/releases) from their official sites too.

## Security (1)

### CRI image RPC error logs redact URL query parameters

- Affects: CRI `PullImage`, `ListImages`, `ImageStatus`, and `RemoveImage` RPCs (Inferred)

When one of these RPCs fails with an error containing a `*url.Error`, query parameters in the logged error are replaced with redacted values; other errors are returned unchanged by `SanitizeError`.

> * Redact all query parameters in CRI error logs ([#12546](https://github.com/containerd/containerd/pull/12546))
>   * [`c707f771a`](https://github.com/containerd/containerd/commit/c707f771a872f9dd22ad8f2f827317a800e4a74f) fix: redact all query parameters in CRI error logs
> * **Redact all query parameters in CRI error logs** ([#12546](https://github.com/containerd/containerd/pull/12546))

## Breaking changes (3)

### `ctr pull` on Darwin defaults to Linux

- Affects: Darwin `ctr pull` invocations that omit `--platform` and do not use `--all-platforms`

Previously, these pulls defaulted to Darwin for unpacking, although Darwin images are not defined and the default snapshotter and differ support only Linux.

Evidence: “// Use linux by default for unpacking images on darwin as configured by transfer service” https://github.com/containerd/containerd/pull/12544

> * **Fix image defaults on Darwin to usable configuration** ([#12544](https://github.com/containerd/containerd/pull/12544))

### EROFS writable layers now default to 64 MiB on non-Linux platforms

- Affects: EROFS snapshotter on non-Linux platforms

The allocation can be adjusted in user configuration or per snapshot.

>   * [`9da97686d`](https://github.com/containerd/containerd/commit/9da97686d151da046d5512bb9f7f1d67ea4c8393) Use default writable size in erofs snapshotter for non-Linux hosts

### NRI stub adds logger configuration and a `Logger()` interface method

- Affects: applications implementing the NRI stub's `Stub` interface (Inferred)

Previously, the stub used a global logger, so applications using it as a library could not customize logging for that stub through a struct member.

Evidence: “Previously, the stub package used a global logger instance, making it difficult for applications using the stub as a library to customize logging behavior, by using `nrilog.Set()`” https://github.com/containerd/nri/pull/239

> * feat: Make logger a configurable struct member for stub ([containerd/nri#239](https://github.com/containerd/nri/pull/239))
>   * [`08a891a`](https://github.com/containerd/nri/commit/08a891a81d90b03b5e5ae14734f5ad74e74c264b) feat: Make logger a configurable struct member for stub

## Important fixes (9)

### Darwin transfer service defaults to Linux unpacking

- Affects: Darwin transfer service using its default unpack configuration

The configuration uses `defaults.DefaultSnapshotter` and `defaults.DefaultDiffer`.

> * **Fix image defaults on Darwin to usable configuration** ([#12544](https://github.com/containerd/containerd/pull/12544))
> * Fix image defaults on Darwin to usable configuration ([#12544](https://github.com/containerd/containerd/pull/12544))
>   * [`d154e234b`](https://github.com/containerd/containerd/commit/d154e234b29c5bed4f14a72d605e92e4728415a2) Update the ctr pull defaults when using the transfer service

### Non-Linux EROFS writable-layer size default fixed at 64 MiB

- Affects: Non-Linux EROFS snapshotters without a writable-layer size override

> * **Fix image defaults on Darwin to usable configuration** ([#12544](https://github.com/containerd/containerd/pull/12544))

### Darwin EROFS diff creation defaults to 4096-byte blocks

- Affects: Darwin EROFS diff creation with `mkfsExtraOpts` lacking an option beginning with `-b`

Without that option, an unusable block size could otherwise be used. The default `-b4096` is now inserted.

> * **Fix image defaults on Darwin to usable configuration** ([#12544](https://github.com/containerd/containerd/pull/12544))

### Possible panic in `WithMediaTypeKeyPrefix` fixed

- Affects: calls to `WithMediaTypeKeyPrefix` with a key-prefix map already in the context (Inferred)

When the context already held the map, the function used it directly; it now works with a clone instead.

> * **Fix possible panic from WithMediaTypeKeyPrefix** ([#12516](https://github.com/containerd/containerd/pull/12516))
> * Fix possible panic from WithMediaTypeKeyPrefix ([#12516](https://github.com/containerd/containerd/pull/12516))
>   * [`8b73c2de3`](https://github.com/containerd/containerd/commit/8b73c2de310e95fe3a143473b511fcf99d03692f) remotes: fix possible panic from WithMediaTypeKeyPrefix
> </p>
> </details>

### Bundled `runc` tmpfs `mode=` regression fixed

- Affects: workloads using runc tmpfs mounts with a `mode=` argument

Previously, `mode=` was applied to tmpfs mounts whether or not the target path existed. The updated `runc` fixes this regression.

> * **Update runc binary to v1.3.4** ([#12593](https://github.com/containerd/containerd/pull/12593))
> * Update runc binary to v1.3.4 ([#12593](https://github.com/containerd/containerd/pull/12593))
>   * [`fb5b818a9`](https://github.com/containerd/containerd/commit/fb5b818a9a34ad4fe3b0901c73cd7432ae4bb8bc) runc: Update runc binary to v1.3.4

### HugeTLB `Failcnt` parsing fixed

- Affects: setups using cgroup v2 HugeTLB stats from `hugetlb.<size>.events` files (Inferred)

`Failcnt` now comes from the `max` entry, which records HugeTLB allocation failures.

> * **Fix parsing of hugetlb.<size>.events files** ([containerd/cgroups#379](https://github.com/containerd/cgroups/pull/379))
> * Fix parsing of hugetlb.<size>.events files ([containerd/cgroups#379](https://github.com/containerd/cgroups/pull/379))
>   * [`2ad7a12`](https://github.com/containerd/cgroups/commit/2ad7a1241827ef1bc4f964fe8a5248b073f2db82) hugetlb: correctly parse hugetlb.<size>.events files

### Darwin transfer service defaults to Linux unpacking

- Affects: Darwin setups using the transfer service's default unpack configuration

The default configuration uses `defaults.DefaultSnapshotter` and `defaults.DefaultDiffer`.

>   * [`09364216d`](https://github.com/containerd/containerd/commit/09364216de92aab056118507da59fabf642d88ac) Fix transfer unpack defaults on darwin

### Default EROFS block size added on Darwin

- Affects: macOS EROFS diffing without a `-b` option

During an EROFS diff in this setup, an unusable block size could be used. On Darwin, `mkfs.erofs` now receives `-b4096` unless an existing option starts with `-b`.

>   * [`eeb0f889a`](https://github.com/containerd/containerd/commit/eeb0f889aed826b58a3033a5a5b14dff6ccd1979) Update default erofs block size on macOS during erofs diff

### NRI sample logger startup failure fixed

- Affects: NRI sample logger setups without an explicit `--events` value (Inferred)

Without an explicit `--events` value, the logger defaulted to `all` and failed to start after pod-update events were introduced, reporting unhandled `UpdatePodSandbox,PostUpdatePodSandbox` events. It now leaves the event mask unset so the stub determines its subscriptions.

> * plugins/logger: fix default event subscription mask. ([containerd/nri#158](https://github.com/containerd/nri/pull/158))
>   * [`33b1db1`](https://github.com/containerd/nri/commit/33b1db1add2e9a603f7c47e1efa95d386f4af560) logger: fix default event subscription mask.

## Enhancements (17)

- Linux security profiles passed to NRI plugins
- Linux RDT constraints passed to NRI plugins
- Linux network devices passed to NRI plugins
- Linux scheduler attributes passed to NRI plugins
- Linux I/O priority passed to NRI plugins
- `HTTPStatusCodeAttributes` adds the response status-code attribute
- NRI WASM support can be disabled at compile time (To use: `nri_no_wasm` build tag)
- NRI plugins can adjust or remove Intel RDT configuration (To use: Runtime support is field-dependent: `closID` is supported by runc and crun; `schemata` by runc (upcoming v1.4) and crun v1.22+; `enableMonitoring` by runc (upcoming v1.4), but not by crun (v1.24+).)
- Custom NRI socket path options for plugins (To use: `socket-path` flag; `socketPath` configuration field for the differ plugin)
- NRI API adds `OptionalRepeatedString` for optional string collections
- NRI support for container kernel scheduling policy attributes
- NRI plugins can adjust and inject Linux network devices (To use: An OCI runtime with `LinuxNetDevice` support, such as `runc` or `crun`)
- NRI sysctl adjustment support
- `SpecGenerator` accepts custom `UnderlyingGenerator` implementations
- NRI container API exposes container user and group IDs
- NRI plugin images signed (To use: Workflow runs triggered by events other than pull requests.)
- Go version requirement lowered for containerd/nri modules

## Dependency updates (29)

29 more, none mentioning security

- `` * [`01d5490ae`](https://github.com/containerd/containerd/commit/01d5490ae26a05b1a73ca9e253761005c7286754) go.{mod,sum}: bump NRI deps to v0.11.0, re-vendor. ``
- `` * go.{mod,sum}: bump CDI deps to v1.1.0. ([#12664](https://github.com/containerd/containerd/pull/12664)) * [`c166a577d`](https://github.com/containerd/containerd/commit/c166a577d0638de704d6c9f999858ed47cf06a60) go.{mod,sum} bump CDI deps to v1.1.0. ``
- `` * go.mod: containerd/zfs v2.0.0; remove exclude rules ([#12654](https://github.com/containerd/containerd/pull/12654)) * [`73a08aa00`](https://github.com/containerd/containerd/commit/73a08aa00dc98a0662a40d45ed50dac534dce1e6) go.mod: remove exclude rules * [`cee08c8af`](https://github.com/containerd/containerd/commit/cee08c8af836002863b30e2ef8cd3c45b6ae56ad) build(deps): bump github.com/containerd/zfs/v2 from 2.0.0-rc.0 to 2.0.0 ``
- `` * go.mod: github.com/containernetworking/plugins v1.9.0 ([#12658](https://github.com/containerd/containerd/pull/12658)) * [`8a5fc8641`](https://github.com/containerd/containerd/commit/8a5fc86416926d2a2189861391cd77b07d7f4443) go.mod: github.com/containernetworking/plugins v1.9.0 ``
- `` * go.mod: golang.org/x/crypto v0.45.0 ([#12638](https://github.com/containerd/containerd/pull/12638)) * [`55c93d6fb`](https://github.com/containerd/containerd/commit/55c93d6fb85333d4988122b2ae97b947bcde02b7) go.mod: golang.org/x/crypto v0.45.0 ``
- `` * ci :bump Go 1.24.11, 1.25.5 ([#12625](https://github.com/containerd/containerd/pull/12625)) * [`aedd29bb4`](https://github.com/containerd/containerd/commit/aedd29bb4ecabfae1d8806dc1011a347a3401fb2) ci: bump Go 1.24.11, 1.25.5 * [`26628f139`](https://github.com/containerd/containerd/commit/26628f1397f991a9ee2fe7de32a6a2df70ab89bd) ci: bump Go 1.24.10, 1.25.4 * [`8bb0e9be6`](https://github.com/containerd/containerd/commit/8bb0e9be6ceebc1ad1d76c88a661bacf84921b3d) ci(release): set GO_VERSION in Dockerfile ``
- `` * : update containerd/cgroups from v3.1.0 to v3.1.2 ([#12598](https://github.com/containerd/containerd/pull/12598)) * [`51582ed27`](https://github.com/containerd/containerd/commit/51582ed27b13941f6bbf1526d909a00deadfcc0f) bump containerd/cgroups to v3.1.2 * [`50d0e4fd4`](https://github.com/containerd/containerd/commit/50d0e4fd4cb909829d9965d9da5be04ee812fe29) build(deps): bump github.com/containerd/cgroups/v3 from 3.1.0 to 3.1.1 ``
- `` * build(deps): bump github.com/opencontainers/selinux ([#12589](https://github.com/containerd/containerd/pull/12589)) * [`e3bf2b80b`](https://github.com/containerd/containerd/commit/e3bf2b80b9ca3280fd64a2bd0436fcdb894c4410) build(deps): bump github.com/opencontainers/selinux ``
- `` * go.mod: github.com/opencontainers/runtime-spec v1.3.0 ([containerd/cgroups#376](https://github.com/containerd/cgroups/pull/376)) * [`34ef430`](https://github.com/containerd/cgroups/commit/34ef430d727e569c31b4f2bbc7d83bffeb1c0165) go.mod: github.com/opencontainers/runtime-spec v1.3.0 ``
- `` * update wazero/wazero version to v1.10.1 ([containerd/nri#252](https://github.com/containerd/nri/pull/252)) * [`9eb9a0f`](https://github.com/containerd/nri/commit/9eb9a0f0f6e223e6060805b55957f117f159f5cc) update tetratelabs/wazero version to v1.10.1 ``
- `` * deps: bump runtime-spec to v1.3.0. ([containerd/nri#243](https://github.com/containerd/nri/pull/243)) * [`29c5811`](https://github.com/containerd/nri/commit/29c581117267cb5d2289ff08902a93ff263caf0e) (v0.1.0) examples: lock NRI, runtime spec deps. * [`d812952`](https://github.com/containerd/nri/commit/d8129529588cca090c972aa5e5f7775162af59da) v010-adapter: lock NRI, runtime spec and tools deps. * [`7dd7c7f`](https://github.com/containerd/nri/commit/7dd7c7f8b21c08242de41634b12ab2ee71b91000) api,runtime-tools: adjust for runtime-spec v1.3.0. * [`5d5d4c4`](https://github.com/containerd/nri/commit/5d5d4c4c877fdef4fe0938e627b11b97234195b8) go.{mod,sum}: update runtime-tools, runtime-spec to v1.3.0. ``
- `` * go.mod: update to stable containerd v2.0 ([containerd/zfs#89](https://github.com/containerd/zfs/pull/89)) * [`f11f891`](https://github.com/containerd/zfs/commit/f11f891ff42b3f8cd6f15d0fb18b2644a002bb85) go.mod: update to stable containerd v2.0 ``
- `* **github.com/containerd/cgroups/v3**                  v3.1.0 -> v3.1.2`
- `* **github.com/containerd/nri**                         v0.10.0 -> v0.11.0`
- `* **github.com/containerd/zfs/v2**                      v2.0.0-rc.0 -> v2.0.0`
- `* **github.com/containernetworking/plugins**            v1.8.0 -> v1.9.0`
- `* **github.com/cyphar/filepath-securejoin**             v0.5.1 **_new_**`
- `* **github.com/opencontainers/runtime-spec**            v1.2.1 -> v1.3.0`
- `* **github.com/opencontainers/runtime-tools**           0ea5ed0382a2 -> edf4cb3d2116`
- `* **github.com/opencontainers/selinux**                 v1.12.0 -> v1.13.1`
- `* **github.com/tetratelabs/wazero**                     v1.9.0 -> v1.10.1`
- `* **golang.org/x/crypto**                               v0.41.0 -> v0.45.0`
- `* **golang.org/x/net**                                  v0.43.0 -> v0.47.0`
- `* **golang.org/x/sync**                                 v0.17.0 -> v0.18.0`
- `* **golang.org/x/sys**                                  v0.37.0 -> v0.38.0`
- `* **golang.org/x/term**                                 v0.34.0 -> v0.37.0`
- `* **golang.org/x/text**                                 v0.28.0 -> v0.31.0`
- `* **tags.cncf.io/container-device-interface**           v1.0.1 -> v1.1.0`
- `* **tags.cncf.io/container-device-interface/specs-go**  v1.0.0 -> v1.1.0`

## Other changes (34)

- Darwin diff service gains a default differ configuration
- v2.2.1 release notes prepared
- Nil NRI adjustments now skip spec generation in `WithContainerAdjustment`
- Runtime v2 gRPC client adopts an OpenTelemetry stats handler
- CI CIFuzz actions now support Ubuntu 24.04
- core/mount autoclear test and error reporting updated
- Five critest cases skipped in Windows CI for `window-2022`
- Darwin default differ configuration updated
- `ReadAt` implementation reverted on the Docker fetch reader
- Cgroups CI lint configuration updated
- `hugePageSizes` now defers directory closure
- cgroup1 and cgroup2 RDMA key/value parsing uses `strings.Cut`
- Memory tests apply De Morgan's law and omit explicit types
- cgroups build workflow updated to `actions/checkout` 6
- Device-injector injection summaries logged in verbose mode
- Additional plugin synchronization in adaptation test helper
- WASM example plugin registration in `init()` with an empty `main()`
- Makefile `build-proto` always regenerates protocol files
- Adaptation tests start with populated CPU and memory resources
- NRI now installs and uses `protoc` and its plugins from `build/tools`
- NRI memory and CPU resource adjustment processing refactored
- Kustomize sample for per-container RDT monitoring with OCI hooks
- NRI lint configuration disables the `QF1008` warning
- NRI CI upgrades `golangci-lint` to v2.4
- Added `nolint` directives in NRI source
- NRI comments for exported symbols added or fixed
- NRI generator mount sorting uses promoted methods and fields
- `.idea` ignore entry reverted; global `.gitignore` comment added
- `.idea` added to the repository `.gitignore`
- NRI lint directives cleaned up and standardized
- `build-proto-dockerized` target for API/protobuf builds
- containerd/zfs CI workflow and lint updates
- `containerd/zfs` lint cleanup and consistent receiver names
- containerd/zfs snapshot size-limit error capitalization fixed

---

Summaries are produced by AI, so they can be wrong, and they are provided without warranty.
