개발 환경이나 로컬 Kubernetes 클러스터를 오래 사용하다 보면 어느 순간 디스크 용량이 부족해지는 경우가 있습니다. 특히 컨테이너 이미지, 빌드 캐시, Pod 로그, 컨테이너 writable layer 등이 계속 쌓이면서 /var 디렉터리의 용량이 커질 수 있습니다.

이번 글에서는 Linux 환경에서 디스크 용량을 확인하는 방법과, Kubernetes에서 사용하는 containerd 및 Docker의 용량을 정리하는 방법을 정리합니다.

전체 디스크 용량 확인

먼저 루트 디렉터리 기준으로 어떤 디렉터리가 용량을 많이 사용하는지 확인합니다.

sudo du -xh / --max-depth=1 | sort -h

옵션의 의미는 다음과 같습니다.

  • du: 디렉터리별 디스크 사용량 확인
  • -x: 다른 파일 시스템은 제외
  • -h: 사람이 읽기 쉬운 단위로 출력
  • --max-depth=1: 바로 아래 단계의 디렉터리까지만 확인
  • sort -h: 용량 기준으로 정렬

일반적으로 서버나 Kubernetes 노드에서는 /var 디렉터리의 용량이 커지는 경우가 많습니다. /var이 크다면 다음과 같이 한 단계 더 좁혀서 확인합니다.

sudo du -xh /var --max-depth=1 | sort -h

이런 방식으로 /var/log, /var/lib, /var/lib/containerd처럼 용량이 큰 경로를 단계적으로 추적할 수 있습니다.

Pod 및 컨테이너 로그 용량 확인

Kubernetes 환경에서는 Pod 로그와 컨테이너 로그가 디스크를 많이 사용할 수 있습니다.

다음 명령어로 로그 디렉터리의 용량을 확인합니다.

sudo du -sh /var/log/pods
sudo du -sh /var/log/containers

/var/log/pods에는 Pod 단위의 로그가 저장되고, /var/log/containers에는 컨테이너 로그에 접근하기 위한 링크 형태의 파일들이 위치합니다.

로그 수집 도구로 Loki, Fluent Bit, Promtail 등을 사용하더라도 노드에 기록되는 컨테이너 로그 자체가 바로 사라지는 것은 아닙니다. 기본적으로 컨테이너 런타임과 kubelet은 로그 파일을 로컬 노드에 기록하고, 수집기는 해당 로그를 읽어서 외부 저장소로 전달하는 방식으로 동작합니다.

따라서 로그 수집 시스템을 사용하더라도 노드의 로그 로테이션 설정은 별도로 확인하는 것이 좋습니다.

containerd 용량 확인

Kubernetes 클러스터에서 containerd를 컨테이너 런타임으로 사용한다면, 이미지와 컨테이너 관련 데이터는 보통 다음 경로에 저장됩니다.

sudo du -sh /var/lib/containerd

이 경로에는 컨테이너 이미지 레이어, 스냅샷, 컨테이너 writable layer 등이 포함될 수 있습니다.

containerd에서 현재 저장된 이미지 목록은 crictl로 확인할 수 있습니다.

sudo crictl images

사용하지 않는 이미지를 정리하려면 다음 명령어를 사용할 수 있습니다.

sudo crictl rmi --prune

이 명령어는 현재 사용 중이지 않은 이미지를 정리합니다.

Kubernetes의 이미지 GC

Kubernetes 노드에서는 kubelet이 이미지 가비지 컬렉션을 자동으로 수행합니다.

기본적으로 kubelet에는 다음과 같은 이미지 GC 기준이 설정되어 있습니다.

imageGCHighThresholdPercent: 85
imageGCLowThresholdPercent: 80

의미는 다음과 같습니다.

  • 파일 시스템 사용량이 85%를 넘으면 이미지 GC 시작
  • 사용하지 않는 이미지를 정리
  • 사용량이 80% 아래로 내려갈 때까지 정리

즉, Kubernetes 노드에서는 사용하지 않는 이미지가 무한히 쌓이지 않도록 kubelet이 일정 기준에 따라 정리합니다.

다만 이 설정은 kubelet 설정에 따라 달라질 수 있으므로, 실제 운영 환경에서는 노드의 kubelet 설정을 직접 확인하는 것이 좋습니다.

Docker 용량 확인

Docker를 사용하는 환경에서는 다음 명령어로 전체 디스크 사용량을 확인할 수 있습니다.

docker system df

예시는 다음과 같습니다.

TYPE            TOTAL     ACTIVE    SIZE      RECLAIMABLE
Images          6         0         5.308GB   2.472GB (46%)
Containers      0         0         0B        0B
Local Volumes   6         0         143.6MB   143.6MB (100%)
Build Cache     72        0         3.585GB   2.679GB

여기서 주요 항목은 다음과 같습니다.

  • Images: Docker 이미지가 사용하는 용량
  • Containers: 컨테이너 writable layer가 사용하는 용량
  • Local Volumes: Docker volume이 사용하는 용량
  • Build Cache: Docker 빌드 과정에서 생성된 캐시 용량
  • RECLAIMABLE: 정리 가능한 용량

Docker 이미지를 자주 빌드하는 개발 환경에서는 Build Cache가 생각보다 큰 용량을 차지할 수 있습니다.

사용하지 않는 Docker 이미지 정리

사용하지 않는 이미지를 정리하려면 다음 명령어를 사용합니다.

docker image prune -a

-a 옵션을 사용하면 사용 중이지 않은 모든 이미지를 정리합니다.

주의할 점은, 같은 이미지 ID를 가진 이미지가 여러 태그를 가지고 있더라도 실제 레이어는 중복 저장되지 않는다는 것입니다. 즉, 태그가 여러 개라고 해서 이미지 용량이 태그 개수만큼 늘어나는 것은 아닙니다.

이미지를 삭제해도 용량이 줄지 않는 경우

Docker 이미지를 모두 삭제했는데도 docker system df에서 Images의 SIZE가 크게 보이는 경우가 있습니다.

예를 들어 다음과 같은 상황입니다.

TYPE            TOTAL     ACTIVE    SIZE      RECLAIMABLE
Images          0         0         9.033GB   0B (0%)
Containers      0         0         0B        0B
Local Volumes   6         0         143.6MB   143.6MB (100%)
Build Cache     189       0         10.94GB   10.94GB

이 경우에는 이미지 자체는 삭제되었지만, 빌드 캐시에 이미지 레이어가 남아 있을 수 있습니다.

Docker는 빌드 속도를 높이기 위해 이전 빌드에서 사용한 레이어를 캐시로 보관합니다. 그래서 이미지를 삭제하더라도 빌드 캐시가 남아 있으면 실제 디스크 사용량이 크게 줄지 않을 수 있습니다.

Docker Build Cache 정리

빌드 캐시를 정리하려면 다음 명령어를 사용합니다.

docker builder prune

오래된 캐시만 삭제하고 싶다면 until 필터를 사용할 수 있습니다.

docker builder prune --filter until=24h

일정 용량만 남기고 정리하고 싶다면 --keep-storage 옵션을 사용할 수 있습니다.

docker builder prune --keep-storage 10GB

단, 빌드 캐시를 삭제하면 다음 빌드 시 기존 캐시를 사용할 수 없습니다. 따라서 다음 빌드 시간이 길어질 수 있습니다.

개발 환경에서 디스크 용량이 부족할 때는 유용하지만, 자주 빌드하는 프로젝트라면 필요한 캐시까지 모두 삭제하지 않도록 주의하는 것이 좋습니다.

Docker Desktop의 Build Cache GC

Docker Desktop에서 확인해보면 기본적으로 일정 용량 이상이 되었을 때 Build Cache를 정리하는 GC 설정이 존재하는 것으로 보입니다.

예를 들어 환경에 따라 20GB를 기준으로 빌더 캐시를 정리하도록 설정되어 있을 수 있습니다.

다만 이 값은 Docker Desktop 버전이나 설정에 따라 달라질 수 있으므로, 실제 값은 Docker Desktop 설정 또는 현재 사용 중인 Builder 설정을 확인하는 것이 좋습니다.

정리

디스크 용량이 부족할 때는 무작정 파일을 삭제하기보다, 먼저 어떤 경로가 용량을 많이 사용하는지 확인하는 것이 중요합니다.

Kubernetes 노드에서는 주로 다음 경로를 확인합니다.

sudo du -xh / --max-depth=1 | sort -h
sudo du -xh /var --max-depth=1 | sort -h
sudo du -sh /var/log/pods
sudo du -sh /var/log/containers
sudo du -sh /var/lib/containerd

containerd 환경에서는 다음 명령어로 이미지를 확인하고 정리할 수 있습니다.

sudo crictl images
sudo crictl rmi --prune

Docker 환경에서는 다음 명령어를 사용합니다.

docker system df
docker image prune -a
docker builder prune

정리하면, Kubernetes 노드에서는 kubelet이 기본적으로 이미지 GC를 수행하지만, 로그나 빌드 캐시, Docker Desktop의 가상 디스크 사용량 등은 별도로 확인이 필요합니다.

특히 Docker 이미지를 삭제했는데도 용량이 줄지 않는다면, 이미지가 아니라 Build Cache가 남아 있는 상황일 수 있으므로 docker builder prune을 함께 확인하는 것이 좋습니다.

Reference

'환경구성' 카테고리의 다른 글

Slack Incoming Webhook으로 채널에 메시지 보내기  (0) 2026.05.22
Python 개발 환경 세팅하기: venv, Ruff, Black, Mypy, pre-commit 설정 정리  (0) 2026.05.20
VS Code launch.json 으로 FastAPI 디버깅 환경 구성하기  (0) 2026.05.20

티스토리툴바