[Kubernetes] 도커 이미지가 삭제될 때(Image Garbage Collection)

도커 이미지가 자동으로 삭제되는 이유

Kubernetes 노드에서는
디스크 공간이 부족해지는 상황을 방지하기 위해
Kubelet이 자동으로 사용하지 않는 도커 이미지를 정리(Image Garbage Collection) 합니다.

이 동작은 버그가 아니라
노드 안정성을 유지하기 위한 정상적인 메커니즘입니다.

---

Kubelet Image Garbage Collection(Image GC)

Kubelet은 다음 조건을 기준으로
이미지 정리(Image GC)를 수행합니다.

• 디스크 사용률이 특정 임계치를 초과하면
• 사용되지 않는 이미지부터 순차적으로 삭제

이 동작은 KubeletConfiguration을 통해 제어할 수 있습니다.

---

KubeletConfiguration 설정 예시

kind: KubeletConfiguration
apiVersion: kubelet.config.k8s.io/v1beta1
cgroupDriver: cgroupfs
evictionHard:
  imagefs.available: "5%"
  nodefs.available: "10%"
imageGCHighThresholdPercent: 90
imageGCLowThresholdPercent: 85

---

주요 설정 값 설명

imageGCHighThresholdPercent

imageGCHighThresholdPercent: 90

• 디스크 사용률이 90% 이하인 경우
• Image Garbage Collection을 실행하지 않음
• 즉, 이 값은 GC 시작 기준 상한선

---

imageGCLowThresholdPercent

imageGCLowThresholdPercent: 85

• 디스크 사용률이 85% 이상이면
• Image Garbage Collection을 항상 수행
• GC가 동작하여 사용률을 이 값 이하로 낮추는 것이 목표

---

동작 흐름 정리

• 디스크 사용률 < 85%
  → Image GC 동작하지 않음

• 디스크 사용률 85% ~ 90%
  → Image GC 동작 가능 상태

• 디스크 사용률 > 90%
  → Image GC 강제 실행

---

EKS Kubelet의 Image GC 기본 설정

EKS에서 사용하는 EKS Optimized AMI에는
기본 Kubelet Image GC 파라미터가 이미 설정되어 있습니다.

기본값

• --image-gc-low-threshold
  • 기본값: 80%
• --image-gc-high-threshold
  • 기본값: 85%

즉, EKS에서는
디스크 사용률이 80%를 넘기면
이미지 정리가 시작되고,
85%를 초과하면 적극적으로 GC가 수행됩니다.

---

실무에서 자주 겪는 상황

• 특정 이미지가 갑자기 노드에서 사라짐
• Pod 재시작 시 이미지 재다운로드 발생
• 디스크 사용률 급증 후 이미지 정리 로그 확인

이 경우 대부분
Image Garbage Collection에 의해 자동 삭제된 상황입니다.

---

마무리하며

Kubernetes에서 도커 이미지가 삭제되는 현상은
대부분 Kubelet Image GC 설정에 따른 정상 동작입니다.

운영 환경에서는 다음을 고려해야 합니다.

• 노드 디스크 용량 충분히 확보
• Image GC 임계치 이해
• 빈번한 이미지 재다운로드 발생 여부 모니터링

이 개념을 알고 있으면
갑작스러운 이미지 삭제로 인한 혼란을 크게 줄일 수 있습니다.