docker pull로 이미지를 받을 때 줄마다 'Pull complete', 'Already exists'가 번갈아 표시됩니다. 이게 레이어입니다. 이 구조를 이해하면 왜 같은 Alpine 이미지를 기반으로 한 이미지 10개가 디스크를 중복해서 차지하지 않는지, 컨테이너를 100개 실행해도 이미지가 100배로 늘어나지 않는지 설명됩니다. Dockerfile에서 명령어 순서가 빌드 속도에 영향을 주는 이유도 레이어 캐시 구조에서 나옵니다. 이 ConceptBlock에서는 레이어가 실제 디스크에 어떻게 저장되는지와 Copy-on-Write 전략을 다룹니다.

확대

레이어(Layer)란?

Docker 이미지는 여러 개의 읽기 전용 레이어가 쌓인 구조입니다. 각 레이어는 Dockerfile의 한 명령어(RUN, COPY, ADD 등)가 만들어내는 파일시스템 변경 사항의 스냅샷입니다.

위에서 아래로 쌓인 레이어 구조입니다 (위가 최신).

• 컨테이너 레이어 (읽기/쓰기) ← docker run 시 생성
• 레이어 4: COPY . /app (앱 소스코드) — 읽기 전용
• 레이어 3: RUN pip install -r requirements.txt — 읽기 전용
• 레이어 2: RUN apt-get install python3 — 읽기 전용
• 레이어 1: FROM ubuntu:22.04 (베이스 이미지) — 읽기 전용

각 레이어는 SHA256 해시로 식별되며, Docker는 이 해시를 사용해 레이어를 캐시하고 재사용합니다.

UnionFS와 Copy-on-Write

Docker는 OverlayFS(또는 overlay2)라는 Union 파일시스템을 사용합니다. UnionFS는 여러 디렉토리(레이어)를 하나의 가상 파일시스템으로 병합하여 보여주는 기술입니다.

컨테이너에서 파일 읽기:
  1. 최상위 쓰기 레이어 확인
  2. 없으면 아래 레이어 순서대로 탐색
  3. 처음 발견된 파일 반환

컨테이너에서 파일 수정(Copy-on-Write):
  1. 해당 파일을 하위 읽기 전용 레이어에서 쓰기 레이어로 복사
  2. 쓰기 레이어에서 파일 수정
  3. 이후 읽기 시 쓰기 레이어의 파일이 우선

레이어 공유의 장점

동일한 베이스 이미지를 사용하는 여러 이미지는 하위 레이어를 공유합니다:

ubuntu:22.04 레이어는 디스크에 한 번만 저장되며, 여러 이미지가 이를 공유합니다. 이는 디스크 절약과 pull 속도 향상으로 이어집니다.

OverlayFS 실제 구조 확인

Docker의 레이어는 호스트 파일시스템에서 직접 확인할 수 있습니다. overlay2 드라이버가 각 레이어를 별도 디렉토리로 관리하는 방식을 보면, 왜 동일 베이스 이미지를 쓰는 수십 개의 컨테이너가 디스크를 거의 추가로 차지하지 않는지 이해됩니다.

# 실습 디렉토리 준비
mkdir -p /tmp/docker/part2/exam_6 && cd /tmp/docker/part2/exam_6

# overlay2 드라이버 사용 확인
docker info | grep "Storage Driver"
# Storage Driver: overlay2

# 이미지 레이어 실제 저장 위치
sudo ls /var/lib/docker/overlay2/

# 특정 이미지의 레이어 ID 확인
docker image inspect nginx --format '{{json .RootFS.Layers}}'

docker pull nginx를 실행하면 이미지가 내려옵니다. 그런데 이 nginx 이미지를 누가 관리하는지, 보안 패치는 제때 이루어지는지 확인하셨나요? Docker Hub에는 공식 이미지부터 누구나 올릴 수 있는 커뮤니티 이미지까지 수백만 개가 혼재합니다. 이름만 보고 신뢰하면 악의적으로 패키징된 이미지를 내려받을 수 있고, :latest 태그를 그대로 프로덕션에 사용하면 오늘과 내일의 배포 결과가 달라지는 상황을 만납니다. "어제까지 잘 됐는데 오늘 배포만 실패한다"는 문제의 절반은 태그 관리 부재에서 비롯됩니다. 이 ConceptBlock에서는 Docker Hub 이미지 신뢰 등급과 태그 전략을 다룹니다.

확대

Docker Hub 이미지 종류

Docker Hub(hub.docker.com)는 세계 최대의 컨테이너 이미지 레지스트리입니다. 이미지는 신뢰 수준에 따라 구분됩니다.

공식 이미지 (Official Images)

Docker Inc.와 해당 소프트웨어 커뮤니티가 직접 관리합니다. 이미지 이름에 슬래시(/)가 없으며 Docker Hub에서 파란 "Official Image" 배지를 확인할 수 있습니다.

# 공식 이미지 예시 (사용자명 없음)
docker pull nginx          # Nginx 공식 이미지
docker pull postgres        # PostgreSQL 공식 이미지
docker pull python          # Python 공식 이미지
docker pull node            # Node.js 공식 이미지
docker pull ubuntu          # Ubuntu 공식 이미지
docker pull alpine          # Alpine Linux 공식 이미지

검증된 퍼블리셔 이미지 (Verified Publisher)

Docker가 신원을 확인한 기업/조직이 제공합니다.

# 검증된 퍼블리셔 이미지 (조직명/이미지명)
docker pull elastic/elasticsearch:8.11.0
docker pull bitnami/postgresql:15

커뮤니티 이미지

누구나 올릴 수 있는 이미지입니다. 사용 전 반드시 Dockerfile과 관리 상태를 검토해야 합니다.

# 커뮤니티 이미지 (사용자명/이미지명)
docker pull myusername/myapp:latest

태그(Tag) 관리의 중요성

태그는 이미지의 특정 버전을 식별하는 레이블입니다. 이미지 전체 참조 형식은 다음과 같습니다:

[레지스트리호스트:포트/][사용자명/]이미지명[:태그]

예시:
  nginx                              # Docker Hub 공식, latest 태그
  nginx:1.25.3                       # Docker Hub 공식, 특정 버전
  myuser/myapp:v2.1                  # Docker Hub 커뮤니티
  registry.example.com/myapp:1.0.0  # 프라이빗 레지스트리
  gcr.io/google-containers/pause:3.9 # Google Container Registry

:latest 태그의 위험성

:latest는 고정된 버전이 아닙니다. 누군가 새 이미지를 push할 때마다 가리키는 대상이 바뀝니다.

# 위험한 패턴 — 언제 이미지가 바뀔지 모름
FROM python:latest  # ❌ 프로덕션에서 절대 금지

# 안전한 패턴 — 정확한 버전 고정
FROM python:3.11.7-slim-bookworm  # ✅ 재현 가능한 빌드

:latest는 단순히 "가장 최근에 push된 이미지"를 가리키는 일반 태그입니다. 특별한 의미가 없으며, 이미지 관리자가 새 버전을 push할 때마다 변경될 수 있습니다.

태그 전략 예시

CI/CD 파이프라인에서 이미지를 빌드할 때는 버전 번호, Git SHA, 환경명을 조합해 태그를 붙입니다.

# 시맨틱 버저닝 기반 태그 전략
docker tag myapp:latest myapp:2.1.3      # 정확한 버전
docker tag myapp:latest myapp:2.1        # 마이너 버전
docker tag myapp:latest myapp:2          # 메이저 버전
docker tag myapp:latest myapp:stable     # 안정화 채널
docker tag myapp:latest myapp:latest     # 최신 (개발용)

# Git 커밋 해시 기반 태그 (CI/CD에서 많이 사용)
GIT_SHA=$(git rev-parse --short HEAD)
docker tag myapp:latest myapp:$GIT_SHA

Alpine vs slim vs 기본 이미지

공식 이미지는 보통 여러 변형(variant)을 제공합니다:

Alpine은 크기가 작지만 musl libc 사용으로 일부 Python 패키지 빌드에 문제가 생길 수 있습니다. 일반적으로 slim 변형이 크기와 호환성의 균형이 좋습니다.

docker push myuser/app:1.0 한 줄에도 Layer already exists가 섞여 나오고, 마지막에 digest: sha256:...가 찍힙니다. docker pull은 이 대화를 거의 반대로 진행합니다. push/pull이 레지스트리와 어떤 단계로 주고받는지 알면 401과 403이 무엇이 다른지, 왜 코드 한 줄만 바꾼 재배포는 작은 레이어만 오가는지, 태그와 다이제스트가 어디서 갈리는지를 단계로 짚을 수 있습니다.

[내 PC]  docker push myuser/app:1.0
   │
   ① 로그인·토큰 획득           (docker login → 레지스트리가 저장소 push 토큰 발급)
   │
   ② 준비: 매니페스트·레이어 목록  (로컬 이미지의 config + 레이어 digest 목록 산출)
   │
   ③ 레이어 존재 확인           (각 레이어 digest를 레지스트리에 질의)
   │    → 이미 있음: "Layer already exists" (업로드 생략)
   │    → 없음: 다음 단계로
   │
   ④ 없는 레이어만 업로드        (blob 업로드 → 레지스트리가 digest 재계산·검증)
   │
   ⑤ 매니페스트 커밋           (config + 레이어 목록을 태그 이름으로 등록 → 매니페스트 digest 확정)
   ▼
[레지스트리]  myuser/app:1.0 태그가 방금 만든 매니페스트 digest 를 가리킴

   ※ pull은 역방향: ⑤ 매니페스트 조회 → ③ 로컬에 없는 레이어 판별 → ④ 다운로드

각 단계에서 무슨 일이 일어나고, 막히면 어떤 증상인가:

핵심은 401과 403의 갈림입니다 — 401은 "누구인지 모름"(①의 로그인·토큰 문제), 403은 "누구인지는 알지만 이 저장소에 쓸 권한이 없음"(④의 권한 문제)입니다. 로그인부터 다시 할지, 권한을 받을지가 여기서 갈립니다. 태그 vs 다이제스트도 ⑤에서 갈립니다 — 태그(:1.0)는 매니페스트에 붙이는 가변 이름이라 같은 태그를 다시 push하면 새 매니페스트 digest를 가리키도록 바뀌지만, @sha256:... 다이제스트는 매니페스트 내용 그 자체의 해시라 언제나 같은 실체를 가리킵니다. 재배포가 빠른 이유는 ③에서 안 바뀐 레이어를 전부 건너뛰고 바뀐 상위 레이어와 작은 매니페스트만 오가기 때문이고, pull이 manifest unknown으로 실패하면 대칭적으로 ⑤(그 태그의 매니페스트가 레지스트리에 없음)를 의심하면 됩니다.

docker pull nginx가 하는 일을 '이미지 파일 하나를 통째로 내려받는 것'으로 이해하면, 아키텍처 불일치 같은 함정 앞에서 막힙니다. 레지스트리가 이미지를 어떻게 쪼개 보관하는지 보면 태그 뒤에 숨은 구조가 드러납니다.

• 이미지 = 매니페스트 + blob: 레지스트리는 콘텐츠 주소(content-addressable) 저장소입니다. 이미지는 매니페스트(설정과 레이어 다이제스트 목록)와 blob(실제 레이어 데이터)으로 나뉘어 저장됩니다. pull은 매니페스트를 먼저 받고, 로컬에 없는 레이어 blob만 내려받습니다. push도 마찬가지라, 레지스트리에 이미 있는 레이어는 Layer already exists로 건너뜁니다 — 그래서 코드 한 줄만 바꾼 재배포는 작은 상위 레이어만 오갑니다.
• 태그는 매니페스트 리스트일 수 있다: nginx 같은 태그는 흔히 단일 이미지가 아니라 매니페스트 리스트(멀티아치 index) 를 가리킵니다. 그 안에 linux/amd64, linux/arm64 등 아키텍처별 이미지가 묶여 있고, pull하는 클라이언트가 자기 아키텍처에 맞는 매니페스트를 골라 받습니다. 그래서 같은 태그라도 x86 서버와 Apple Silicon 맥에서 다른 실체가 내려옵니다.
• 다이제스트는 그 실체를 불변으로 고정한다: 태그는 사람이 붙인 가변 이름이라 같은 태그에 다른 이미지가 다시 push될 수 있지만, @sha256:... 다이제스트는 매니페스트 내용을 해시한 값이라 항상 정확히 그 실체를 가리킵니다. 멀티아치 태그를 다이제스트로 핀하면 특정 아키텍처의 특정 이미지까지 못 박을 수 있습니다.

이 구조를 알면 "push가 왜 빠른가", "같은 태그인데 왜 서버마다 다른 게 받아지나"가 한 번에 설명됩니다.

로컬에서 docker build -t myapp:1.0 .으로 이미지를 만든 뒤 docker push myapp:1.0을 실행하면 "denied: access forbidden" 에러가 납니다. 회사 ECR이나 사설 레지스트리에 올리려면 이미지 이름 앞에 레지스트리 주소가 포함되어야 하는데, myapp:1.0은 Docker Hub의 개인 계정을 가정하기 때문입니다. 또 nginx라는 이름은 실제로는 docker.io/library/nginx:latest가 생략된 형태이고, AWS ECR 이미지는 123456.dkr.ecr.ap-northeast-2.amazonaws.com/myapp:latest처럼 보입니다. 이 규칙을 모르면 push 실패, pull 실패, 이미지 이름 혼동이 반복됩니다. 이 ConceptBlock에서는 이미지 이름의 전체 구성과 다이제스트로 불변성을 보장하는 방법을 다룹니다.

확대

이미지 이름의 전체 형식

Docker 이미지 이름은 여러 부분으로 구성되며, 생략 시 기본값이 채워집니다.

전체 형식:
[레지스트리호스트[:포트]/][네임스페이스/]저장소[:태그][@다이제스트]

예시:
docker.io/library/nginx:1.25@sha256:abc123...def456
    ↑          ↑       ↑      ↑          ↑
 레지스트리  네임스페이스 저장소  태그     다이제스트

# 생략 시 기본값 채우기
nginx                = docker.io/library/nginx:latest
nginx:alpine         = docker.io/library/nginx:alpine
myuser/myapp         = docker.io/myuser/myapp:latest
myuser/myapp:v1.0    = docker.io/myuser/myapp:v1.0

# 다른 레지스트리 사용
ghcr.io/myorg/myapp:latest          # GitHub Container Registry
123456.dkr.ecr.ap-northeast-2.amazonaws.com/myapp:latest  # AWS ECR
asia-northeast1-docker.pkg.dev/project/repo/myapp:latest  # GCP Artifact Registry
myregistry.internal:5000/myapp:v2   # 사설 레지스트리

태그 vs 다이제스트 — 가변 vs 불변

태그는 편하지만 언제든 덮어쓸 수 있어 재현성이 깨질 수 있습니다. 다이제스트는 SHA256 해시이므로 항상 동일한 이미지를 가리킵니다.

# 태그: 가변 (같은 태그가 언제든 다른 이미지를 가리킬 수 있음)
docker pull nginx:latest
# 오늘의 latest와 내일의 latest가 다를 수 있음!

# 다이제스트: 불변 (SHA256 해시, 항상 동일한 이미지 보장)
docker pull nginx@sha256:a0bcfe...8d12c
# 언제 어디서 pull해도 완전히 동일한 이미지

# 현재 이미지의 다이제스트 확인
docker image inspect nginx:latest --format '{{.RepoDigests}}'
# [nginx@sha256:a0bcfe...8d12c]

# 다이제스트로 pull (프로덕션 환경 권장)
docker pull nginx@sha256:a0bcfe...8d12c

사설 레지스트리 이미지 관리

로컬에서 빌드한 이미지를 사설 레지스트리에 push할 때는 이미지 이름에 레지스트리 주소를 포함한 태그를 먼저 추가합니다.

# 로컬에서 빌드한 이미지를 사설 레지스트리에 push
# 1. 이미지에 레지스트리 주소 포함한 태그 추가
docker tag myapp:latest myregistry.example.com:5000/myapp:latest
docker tag myapp:latest myregistry.example.com:5000/myapp:v1.2.3

# 2. 레지스트리에 push
docker push myregistry.example.com:5000/myapp:latest
docker push myregistry.example.com:5000/myapp:v1.2.3

# 3. 다른 서버에서 pull
docker pull myregistry.example.com:5000/myapp:v1.2.3

# 4. 이미지 목록 API 확인
curl http://myregistry.example.com:5000/v2/_catalog
# {"repositories":["myapp","nginx","redis"]}
curl http://myregistry.example.com:5000/v2/myapp/tags/list
# {"name":"myapp","tags":["latest","v1.2.3","v1.2.2"]}

CI 빌드 서버를 3개월째 운영하다 보면 어느 날 아침 파이프라인 전체가 멈춥니다. docker build 도중 "no space left on device" 에러가 납니다. 원인은 매번 빌드할 때마다 생성되는 dangling 이미지가 아무도 정리하지 않은 채 쌓인 것입니다. 개발 노트북에서도 Docker를 몇 달 쓰면 디스크 수 GB가 Docker 이미지와 빌드 캐시로 채워집니다. docker system df를 처음 실행했을 때 "회수 가능 공간 3.1GB"가 표시되면 당황하기 마련입니다. 정리 명령어는 여러 종류가 있고 영향 범위가 다르므로, 순서와 범위를 알고 써야 실수로 운영 데이터를 지우는 사고를 막을 수 있습니다. 이 ConceptBlock에서는 Docker 디스크 사용량을 파악하고 안전하게 정리하는 방법을 다룹니다.

확대

디스크 사용량 파악

Docker를 오래 사용하면 이미지, 컨테이너, 볼륨, 빌드 캐시가 쌓여 디스크를 차지합니다.

# Docker 전체 디스크 사용량 확인
docker system df
# TYPE            TOTAL   ACTIVE  SIZE      RECLAIMABLE
# Images          12      3       4.2GB     3.1GB (73%)  ← 회수 가능
# Containers      5       2       12MB      1kB (0%)
# Local Volumes   8       3       2.1GB     800MB (38%)
# Build Cache     23      0       1.5GB     1.5GB        ← 전부 회수 가능

# 상세 목록
docker system df -v

dangling 이미지가 생기는 이유

# 같은 태그로 재빌드하면 이전 이미지가 <none>:<none> 으로 남음
docker build -t myapp:latest .   # 첫 번째 빌드 → abc123
docker build -t myapp:latest .   # 재빌드 → def456 (새 이미지)
                                  # abc123은 태그를 잃고 <none>:<none>으로 전락

docker images
# REPOSITORY   TAG       IMAGE ID       SIZE
# myapp        latest    def456         200MB  ← 현재 이미지
# <none>       <none>    abc123         200MB  ← dangling 이미지!

단계별 정리 방법

영향 범위가 작은 것부터 순서대로 실행합니다. 운영 환경에서는 prune -a나 --volumes 사용 전에 반드시 어떤 데이터가 삭제되는지 확인해야 합니다.

# 1. dangling 이미지만 삭제 (가장 안전)
docker image prune
# WARNING! This will remove all dangling images.
# 삭제할 공간: 1.2GB

# 2. 사용 중이지 않은 이미지 전체 삭제
docker image prune -a
# 실행 중인 컨테이너에서 사용 중인 이미지는 삭제 안 됨

# 3. 미사용 컨테이너 삭제
docker container prune

# 4. 미사용 볼륨 삭제 (주의: 데이터 영구 삭제!)

# 5. 한 번에 전체 정리

자동 정리 설정

--filter 옵션으로 기간이나 라벨을 지정하면 원하는 범위만 정리할 수 있습니다. CI 빌드 서버에는 cron으로 등록해 두면 디스크가 차는 것을 예방할 수 있습니다.

# 특정 날짜 이전 이미지만 삭제
docker image prune -a --filter "until=72h"  # 72시간 이상 미사용

# 특정 라벨이 있는 이미지만 삭제
docker image prune --filter "label=stage=dev"

# cron으로 주기적 자동 정리 (매주 일요일 새벽 3시)