# containerd v2.2.1

2025-12-18 · [릴리스 노트 원문](https://github.com/containerd/containerd/releases/tag/v2.2.1) · [전체 정리](https://ratatosk.io/ko/releases/containerd/v2.2.1)

보안 1 · 호환성 변경 3 · 중요 수정 9 · 기능·개선 17 · 의존성 갱신 29 · 기타 34

## 업그레이드 전 확인

### 전제 조건

- **권장 containerd 릴리스 아카이브**: 권장 `containerd-<VERSION>-<OS>-<ARCH>.tar.gz` 아카이브는 Ubuntu 22.04에서 사용하는 버전인 glibc 2.35를 대상으로 동적 링크됩니다.
  > * `containerd-<VERSION>-<OS>-<ARCH>.tar.gz`:         ✅Recommended. Dynamically linked with glibc 2.35 (Ubuntu 22.04).
- **containerd와 runc 동반 설치**
  > In addition to containerd, typically you will have to install [runc](https://github.com/opencontainers/runc/releases)
- **CNI 플러그인 설치 전제 조건**: CNI 플러그인도 보통 공식 사이트에서 설치해야 합니다.
  > and [CNI plugins](https://github.com/containernetworking/plugins/releases) from their official sites too.

## 보안 (1)

### CRI 이미지 RPC 오류 로그의 URL 쿼리 파라미터 마스킹

- 영향 대상: CRI `PullImage`, `ListImages`, `ImageStatus`, `RemoveImage` RPC (추정)

이 RPC 중 하나가 `*url.Error`를 포함한 오류로 실패하면, 로그에 기록되는 오류의 쿼리 파라미터 값을 마스킹합니다. 그 외 오류는 `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))

## 호환성 변경 (3)

### Darwin에서 `ctr pull`의 기본 플랫폼을 Linux로 설정

- 영향 대상: Darwin에서 `--platform`을 생략하고 `--all-platforms`를 사용하지 않는 `ctr pull` 호출

이전에는 이런 pull에서 언팩 플랫폼이 기본적으로 Darwin으로 설정됐습니다. 하지만 Darwin 이미지는 정의되어 있지 않고, 기본 snapshotter와 differ는 Linux만 지원합니다.

근거: “// 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 쓰기 가능 레이어 기본값 64 MiB

- 영향 대상: 비리눅스 플랫폼의 EROFS 스냅샷터

할당 크기는 사용자 설정이나 스냅샷별로 조정할 수 있습니다.

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

### NRI 스텁에 로거 설정 및 `Logger()` 인터페이스 메서드 추가

- 영향 대상: NRI 스텁의 `Stub` 인터페이스를 구현하는 애플리케이션 (추정)

이전에는 스텁이 전역 로거를 사용했기 때문에, 스텁을 라이브러리로 사용하는 애플리케이션은 구조체 멤버를 통해 해당 스텁의 로깅을 사용자 지정할 수 없었습니다.

근거: “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

## 중요 수정 (9)

### Darwin 트랜스퍼 서비스의 기본 Linux 언팩

- 영향 대상: 기본 언팩 설정을 사용하는 Darwin 트랜스퍼 서비스

설정에서 `defaults.DefaultSnapshotter`와 `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

### 비리눅스 EROFS 쓰기 가능 레이어 크기 기본값을 64 MiB로 수정

- 영향 대상: 쓰기 가능 레이어 크기 재정의가 없는 비리눅스 EROFS 스냅샷터

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

### Darwin EROFS diff 생성 시 기본 블록 크기 4096바이트 적용

- 영향 대상: Darwin EROFS diff를 생성할 때 `mkfsExtraOpts`에 `-b`로 시작하는 옵션이 없는 경우

해당 옵션이 없으면 사용할 수 없는 블록 크기가 사용될 수 있습니다. 이제 기본값 `-b4096`을 삽입합니다.

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

### `WithMediaTypeKeyPrefix`에서 발생할 수 있는 패닉 수정

- 영향 대상: context에 키 프리픽스 맵이 이미 있는 상태에서 `WithMediaTypeKeyPrefix`를 호출하는 경우 (추정)

context에 맵이 이미 있으면 함수는 이전에 그 맵을 직접 사용했지만, 이제는 복제본을 사용합니다.

> * **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>

### 번들 `runc`의 tmpfs `mode=` 회귀 수정

- 영향 대상: `mode=` 인수를 지정한 `runc` tmpfs 마운트를 사용하는 워크로드

이전에는 대상 경로가 존재하는지와 관계없이 tmpfs 마운트에 `mode=`가 적용됐습니다. 업데이트된 `runc`에서 이 회귀를 수정했습니다.

> * **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` 파싱 수정

- 영향 대상: `hugetlb.<size>.events` 파일에서 cgroup v2 HugeTLB 통계를 수집하는 설정 (추정)

`Failcnt`는 HugeTLB 할당 실패를 기록하는 `max` 항목에서 가져옵니다.

> * **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 전송 서비스의 기본 Linux 언팩 설정

- 영향 대상: 전송 서비스의 기본 언팩 설정을 사용하는 Darwin 환경

기본 설정에서 `defaults.DefaultSnapshotter`와 `defaults.DefaultDiffer`를 사용합니다.

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

### Darwin에서 EROFS 기본 블록 크기 추가

- 영향 대상: macOS에서 `-b` 옵션 없이 EROFS diff를 수행하는 경우

이 설정에서 EROFS diff를 수행할 때 사용할 수 없는 블록 크기가 적용될 수 있었습니다. Darwin에서는 기존 옵션 중 `-b`로 시작하는 항목이 없으면 `mkfs.erofs`에 `-b4096`을 전달합니다.

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

### NRI 샘플 로거 시작 실패 수정

- 영향 대상: `--events` 값을 명시하지 않은 NRI 샘플 로거 구성 (추정)

`--events` 값을 명시하지 않으면 로거가 기본값을 `all`로 설정했습니다. pod 업데이트 이벤트가 도입된 뒤에는 시작에 실패하며 처리하지 못한 `UpdatePodSandbox,PostUpdatePodSandbox` 이벤트를 보고했습니다. 이제 이벤트 마스크를 설정하지 않아 스텁이 구독할 이벤트를 결정합니다.

> * 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.

## 기능·개선 (17)

- NRI 플러그인에 전달되는 Linux 보안 프로파일
- Linux RDT 제약 조건을 NRI 플러그인에 전달
- NRI 플러그인에 전달되는 Linux 네트워크 디바이스
- NRI 플러그인에 전달되는 리눅스 스케줄러 속성
- NRI 플러그인에 Linux I/O 우선순위 전달
- `HTTPStatusCodeAttributes` 응답 상태 코드 어트리뷰트 추가
- NRI WASM 지원의 컴파일 시 비활성화 (사용 조건: `nri_no_wasm` 빌드 태그)
- NRI 플러그인의 Intel RDT 설정 조정 및 제거 (사용 조건: 필드별 런타임 지원: `closID`는 runc와 crun에서 지원됩니다. `schemata`는 runc(출시 예정인 v1.4)와 crun v1.22+에서 지원됩니다. `enableMonitoring`은 runc(출시 예정인 v1.4)에서 지원되지만 crun(v1.24+)에서는 지원되지 않습니다.)
- 플러그인용 사용자 지정 NRI 소켓 경로 옵션 (사용 조건: `socket-path` 플래그; differ 플러그인의 `socketPath` 구성 필드)
- NRI API에 선택적 문자열 컬렉션용 `OptionalRepeatedString` 추가
- 컨테이너 커널 스케줄링 정책 속성에 대한 NRI 지원
- NRI 플러그인의 리눅스 네트워크 디바이스 조정 및 주입 (사용 조건: `LinuxNetDevice`를 지원하는 OCI 런타임(예: `runc` 또는 `crun`))
- NRI sysctl 조정 지원
- 사용자 지정 `UnderlyingGenerator` 구현을 허용하는 `SpecGenerator`
- NRI 컨테이너 API에서 컨테이너 사용자 및 그룹 ID 제공
- NRI 플러그인 이미지 서명 (사용 조건: pull request가 아닌 이벤트로 트리거된 워크플로 실행)
- containerd/nri 모듈의 Go 버전 요구 사항 하향

## 의존성 갱신 (29)

그 외 29건 · 보안 언급 없음

- `` * [`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`

## 기타 (34)

- Darwin diff 서비스 기본 differ 설정 추가
- v2.2.1 릴리스 노트 준비 완료
- NRI 조정값이 nil일 때 `WithContainerAdjustment`의 spec 생성 건너뛰기
- Runtime v2 gRPC 클라이언트에 OpenTelemetry 통계 핸들러 적용
- CI CIFuzz 액션의 Ubuntu 24.04 지원
- core/mount의 autoclear 테스트 및 오류 보고 업데이트
- Windows CI에서 `window-2022`용 critest 케이스 5개 건너뜀
- Darwin 기본 differ 구성 업데이트
- Docker fetch reader의 `ReadAt` 구현 되돌림
- Cgroups CI 린트 설정 업데이트
- `hugePageSizes` 디렉터리 닫기 지연
- cgroup1 및 cgroup2 RDMA 키/값 파싱에 `strings.Cut` 사용
- 메모리 테스트의 드모르간 법칙 적용과 명시적 타입 생략
- cgroups 빌드 워크플로의 `actions/checkout` 6 업데이트
- verbose 모드에서 Device-injector 인젝션 요약 로그 출력
- 적응 테스트 헬퍼의 추가 플러그인 동기화
- WASM 예제 플러그인은 `init()`에서 등록하고 `main()`은 비워 두기
- Makefile의 `build-proto` 타깃에서 프로토콜 파일을 항상 재생성
- CPU 및 메모리 리소스가 채워진 상태로 시작하는 적응 테스트
- NRI의 `build/tools` 기반 `protoc` 및 플러그인 설치·사용
- NRI 메모리·CPU 리소스 조정 처리 리팩터링
- OCI 훅을 이용한 컨테이너별 RDT 모니터링용 Kustomize 샘플
- NRI 린트 설정에서 `QF1008` 경고 비활성화
- NRI CI의 `golangci-lint` v2.4 업그레이드
- NRI 소스에 `nolint` 지시문 추가
- NRI 공개 심볼 주석 추가 및 수정
- NRI generator의 마운트 정렬에서 승격 메서드와 필드 사용
- `.idea` 무시 항목 되돌림 및 전역 `.gitignore` 주석 추가
- 저장소의 `.gitignore`에 `.idea` 추가
- NRI 린트 지시문 정리 및 표준화
- API/protobuf 빌드용 `build-proto-dockerized` 타깃
- containerd/zfs CI 워크플로 및 린트 업데이트
- `containerd/zfs` 린트 정리 및 리시버 이름 통일
- containerd/zfs 스냅샷 크기 제한 오류의 대소문자 수정

---

정리 내용은 AI가 작성하므로 틀릴 수 있으며, 보증 없이 제공합니다.
