containerd 이미지 스토어와 Docker Engine

containerd 이미지 스토어와 Docker Engine

Docker Engine 29.0부터 새로 설치하는 환경에서는 containerd 이미지 스토어가 기본 스토리지 백엔드로 사용돼요. 이전 버전에서 업그레이드했다면 직접 활성화하기 전까지 기존의 overlay2 그래프 드라이버를 계속 사용하게 되죠. 이 문서에서는 containerd 이미지 스토어가 무엇인지, 왜 사용하는지, 어떻게 활성화하는지 차근차근 설명드릴게요.

출처: 공식문서

본문

containerd 이미지 스토어란?

containerd는 업계 표준 컨테이너 런타임으로, 이미지와 컨테이너 데이터를 저장할 때 클래식 스토리지 드라이버 대신 스냅샷터(snapshotter)를 사용해요.

참고: 사용자 네임스페이스 리매핑(userns-remap)을 사용하는 환경에서는 containerd 이미지 스토어를 사용할 수 없어요. 자세한 내용은 moby#47377을 확인해 주세요.

왜 containerd 이미지 스토어를 사용하나요?

containerd 이미지 스토어는 스냅샷터를 통해 이미지 레이어를 파일시스템에 저장하고 접근하는 방식을 관리해요. overlay2 같은 클래식 그래프 드라이버와는 방식이 다르죠.

containerd 이미지 스토어를 사용하면 다음과 같은 것들이 가능해져요:

  • 멀티 플랫폼 이미지를 로컬에서 빌드하고 저장할 수 있어요. 클래식 스토리지 드라이버에서는 멀티 플랫폼 이미지를 만들려면 외부 빌더가 필요했어요.
  • 증명(attestation)이 포함된 이미지를 다룰 수 있어요. 출처 증명(provenance)이나 SBOM 같은 것이 포함된 이미지인데, 이런 이미지는 클래식 스토어가 지원하지 않는 이미지 인덱스를 사용해요.
  • Wasm 컨테이너를 실행할 수 있어요. containerd 이미지 스토어는 WebAssembly 워크로드를 지원해요.
  • 고급 스냅샷터를 사용할 수 있어요. containerd는 플러그인 방식의 스냅샷터를 지원해서, 이미지 지연 풀(lazy-pull, stargz)이나 피어투피어 이미지 배포(nydus, dragonfly) 같은 기능을 활용할 수 있어요.

대부분의 사용자에게 containerd 이미지 스토어로의 전환은 투명하게 이루어져요. 스토리지 백엔드만 바뀌고 작업 흐름은 그대로니까요.

디스크 공간 사용량

containerd 이미지 스토어는 같은 이미지에 대해 기존 스토리지 드라이버보다 더 많은 디스크 공간을 사용해요. containerd가 이미지를 압축된 형식과 압축되지 않은 형식으로 모두 저장하기 때문이에요. 기존 드라이버는 압축되지 않은 레이어만 저장했거든요.

이미지를 풀(pull)하면 containerd는 레지스트리에서 받은 압축 레이어를 유지하면서, 동시에 디스크에 압축을 풀어서 추출해요. 이렇게 이중으로 저장하기 때문에 각 레이어가 더 많은 공간을 차지해요. 압축된 형식 덕분에 풀과 푸시(push)는 더 빨라지지만, 그만큼 추가 디스크 용량이 필요해요.

중요: containerd는 Docker 데이터 디렉터리와 별도의 스토리지 경로를 사용해요. Docker용 커스텀 데이터 디렉터리를 미리 설정한 경우(예: 다른 파티션을 사용하려고), containerd의 스토리지는 자동으로 그 위치로 이동하지 않아요. 루트 파티션이 가득 차지 않도록 containerd의 데이터 디렉터리를 별도로 설정해야 해요.

containerd 데이터 디렉터리 설정 방법은 데이터 디렉터리 위치 설정 문서를 참고하세요.

디스크 공간이 부족하다면 다음을 고려해 보세요:

  • docker image prune으로 사용하지 않는 이미지를 주기적으로 정리하세요
  • docker system df로 디스크 사용량을 모니터링하세요
  • 데이터 디렉터리 설정으로 충분한 공간이 있는 파티션을 사용하세요

Docker Engine에서 containerd 이미지 스토어 활성화하기

이전 Docker Engine 버전에서 업그레이드하는 경우 containerd 이미지 스토어를 수동으로 활성화해야 해요.

중요: 스토리지 백엔드를 전환하면 다른 백엔드로 생성된 이미지와 컨테이너가 일시적으로 숨겨져요. 데이터는 디스크에 그대로 남아 있어요. 이전 이미지에 다시 접근하려면 이전 스토리지 설정으로 되돌리면 돼요.

/etc/docker/daemon.json 파일에 다음 설정을 추가하세요:

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

파일을 저장하고 데몬을 재시작하세요:

$ sudo systemctl restart docker

데몬 재시작 후 containerd 이미지 스토어가 사용 중인지 확인해 보세요:

$ docker info -f '{{ .DriverStatus }}'
[[driver-type io.containerd.snapshotter.v1]]

Docker Engine은 기본적으로 overlayfs containerd 스냅샷터를 사용해요.

참고: containerd 이미지 스토어를 활성화하면 overlay2 드라이버의 기존 이미지와 컨테이너는 디스크에 남아 있지만 숨겨져요. overlay2로 다시 전환하면 다시 나타나요. 기존 이미지를 containerd 이미지 스토어에서 사용하려면 먼저 레지스트리에 푸시하거나 docker save로 내보낸 후 사용하세요.

실험적인 자동 마이그레이션

Docker Engine에는 특정 조건에서 자동으로 containerd 이미지 스토어로 전환해 주는 실험적 기능이 포함되어 있어요. 이 기능은 실험적이에요. 테스트해 보고 싶은 사람들을 위해 제공되지만, 처음부터 새로 시작하는 것이 권장되는 방법이에요.

주의: 자동 마이그레이션 기능은 실험적이며 모든 시나리오에서 안정적으로 작동하지 않을 수 있어요. 사용 전에 백업을 만들어 두세요.

자동 마이그레이션을 활성화하려면 /etc/docker/daemon.json에 containerd-migration 기능을 추가하세요:

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

또한 DOCKER_MIGRATE_SNAPSHOTTER_THRESHOLD 환경 변수를 설정하면, 컨테이너가 없고 모든 이미지 레이어의 총 크기가 임계값 이하일 때 데몬이 자동으로 전환돼요. 값은 사람이 읽기 쉬운 크기 형식(예: 200M 또는 1G)으로 지정해요. systemd를 사용한다면:

$ sudo systemctl edit docker.service

다음을 추가하세요:

[Service]
Environment="DOCKER_MIGRATE_SNAPSHOTTER_THRESHOLD=200M"

실행 중이거나 중지된 컨테이너가 없고 모든 이미지 레이어의 총 크기가 200M 이하라면, 데몬은 재시작 시 containerd 이미지 스토어로 전환돼요. overlay2 데이터는 디스크에 남아 있지만 숨겨지게 돼요.

더 알아보기

Docker Desktop에서 containerd 이미지 스토어와 그 기능에 대해 더 자세히 알아보려면 Docker Desktop의 containerd 이미지 스토어 문서를 확인해 보세요.