단일 도커 컨테이너에서 쿠버네티스 오케스트레이션 전환 시 네트워크·스토리지 오류 해결법

단일 서버에서 Docker 실행만으로 깔끔하게 돌아가던 웹 서비스가 트래픽 급증으로 다운되었을 때, 무작정 쿠버네티스를 도입했다가 Pod가 무한 재시작 상태에 빠져 주말 내내 밤을 새운 경험이 있습니다. 인터넷을 검색해 봐도 단순히 Docker Compose 파일을 K8s YAML로 변환하라는 일반론만 나올 뿐, 막상 배포하면 왜 로컬 이미지를 못 찾고 스토리지 연결이 터지는지 명확한 원인을 찾기 어렵습니다. 찾아보니 컨테이너 런타임과 오케스트레이션 엔진이 작동하는 레이어 자체가 달라서 발생하는 지점이 바로 여기인데요, 이 글에서는 Docker v29와 Kubernetes v1.36 최신 스펙을 기준으로 두 기술의 차이점과 마이그레이션 도중 발생하는 실무 오류 해결법을 확실히 정리해 드립니다.

단일 컨테이너(Docker)와 클러스터 오케스트레이션(Kubernetes)의 역할 차이

많은 개발자가 도커와 쿠버네티스를 하나를 선택하면 다른 하나를 버려야 하는 경쟁 관계처럼 오해하곤 합니다. 하지만 실무 측면에서 도커는 애플리케이션과 그 의존성을 하나의 이미지로 패키징하고 단일 호스트 노드에서 '컨테이너를 실행'하는 런타임 및 이미지 빌드 도구입니다. 반면 쿠버네티스는 수십~수천 대의 서버(노드 클러스터)를 하나의 거대한 컴퓨팅 자원으로 묶어, 그 위에서 실행되는 수백 개의 컨테이너를 배치하고, 노드 장애 시 자동 복구(Self-healing)하며, 트래픽에 맞춰 수평 확장(Auto-scaling)을 지휘하는 '오케스트레이터'입니다. 결국 두 기술은 대립하는 것이 아니라 쿠버네티스라는 지휘자가 도커 방식으로 만들어진 컨테이너라는 연주자들을 통제하는 상호 보완 구조입니다.

• Docker: 단일 서버 중심의 컨테이너 패키징, 빌드, 로컬 테스트, 이미지 표준 제공
• Kubernetes: 다중 서버(클러스터) 환경에서의 자동 배포, 롤링 업데이트, 자가 치유, 로드밸런싱 전담
• 컨테이너 런타임 변화: 최신 쿠버네티스는 Docker Engine을 직접 호출하지 않고 CRI(Container Runtime Interface) 표준인 containerd를 직접 사용하지만, 이미지 빌드와 CLI 규격은 여전히 Docker 표준을 따릅니다.

공식 최신 스펙 비교: Docker Engine v29 vs Kubernetes v1.36

최근 아키텍처를 구성할 때 오래된 구버전 가이드를 그대로 적용하면 API 버전 호환성 문제로 deployment 생성이 실패할 수 있습니다. 각 시스템의 현재 정식 지원 버전과 사양 기준을 명확히 대조해 파악해야 합니다.

구분 항목	Docker Engine v29.7.2 (2026년, Docker 8월 공식 발표)	Kubernetes v1.36.4 (2026년, CNCF 8월 공식 발표)
핵심 역할	단일 호스트 컨테이너 생명주기 관리 및 이미지 빌드	멀티 노드 클러스터 통합 오케스트레이션 및 상태 보장
최소 운용 단위	Container (컨테이너)	Pod (1개 이상의 컨테이너와 공유 파이프라인)
기본 네트워크	Bridge, Host, Overlay (Docker Swarm 전용)	CNI (Flannel, Calico, Cilium 등) 기반 Pod-to-Pod 통신
스토리지 연동	Volume, Bind Mount (단일 파일시스템 지정)	PV, PVC, StorageClass (동적 프로비저닝 추상화)
상태 점검 및 복구	restart policy (always, on-failure 등 기본 지원)	livenessProbe, readinessProbe, startupProbe 세분화 제어

도커에서 쿠버네티스 전환 시 가장 자주 막히는 지점 2가지와 해결법

Docker Compose로 작성된 서비스를 쿠버네티스 Manifest로 옮기는 도중 가장 빈번하게 터지는 문제는 로컬 이미지 참조 불가와 디렉터리 바인딩 실패입니다. 이 두 가지를 사전에 차단하지 않으면 배포 명령 직후 Pod가 생성되지 않거나 수초 만에 다운되는 현상을 겪게 됩니다.

1. ErrImagePull / ImagePullBackOff 오류: Docker Desktop 로컬 데몬에서 빌드한 이미지(예: my-app:v1)를 K8s deployment에 지정하면, K8s Worker Node의 containerd 런타임이 로컬 Docker daemon 이미지 저장소에 접근하지 못해 원격 레지스트리를 찾다가 실패합니다. 해결책: 이미지를 Docker Hub나 Private Registry(ECR 등)에 push한 뒤 imagePullSecrets와 명확한 Tag 경로를 Manifest에 기술하거나, Minikube/Kind 사용 시 eval $(minikube docker-env) 명령으로 로컬 데몬 환경을 직접 동기화해야 합니다.
2. VolumeBinding/PersistentVolumeClaim 실패 및 데이터 유실: Docker Compose의 './data:/app/data' 식의 바인딩 마운트를 K8s의 hostPath로 단순 전환하면, Pod가 다른 워커 노드로 스케줄링되어 이동했을 때 데이터가 공유되지 않거나 권한 문제로 'Pending' 상태에 갇히게 됩니다. 해결책: Cloud Vendor의 StorageClass(gp3, EBS, NFS 등)를 정의하고 PersistentVolumeClaim(PVC)을 작성하여 Pod가 어떤 노드로 이동하더라도 동적으로 영속 볼륨이 바인딩되도록 설계해야 합니다.

운영 규모별 리소스 및 관리 비용 비교

서비스 초기 단계부터 무조건 쿠버네티스를 적용하는 것은 오버엔지니어링이 될 수 있습니다. 인프라 운영 규모 및 전담 인력 유무에 따른 실질적인 리소스 비용과 엔지니어링 공수를 비교하여 결정해야 합니다.

규모 및 서비스 형태	권장 인프라 구성	초기 구축 공수	월 예상 인프라 비용 및 관리 포인트
소규모 (컨테이너 1~5개, 단일 서버)	Docker Engine + Docker Compose	낮음 (1~2일 내 구축)	서버 1대 비용 (약 $20~$50/월). 단순 호스트 리소스 모니터링만 필요.
중규모 (컨테이너 6~20개, 무중단 배포 필요)	Managed K8s (EKS/GKE) 노드 2~3대	보통 (1~2주 소요)	클러스터 제어면(Control Plane) 비용 + 노드 3대 ($150~$300/월). Ingress 및 PVC 관리 필요.
대규모 (컨테이너 50개 이상, HPA/Microservices)	Multi-AZ Kubernetes + CNI + Service Mesh	높음 (전담 DevOps 팀 필요)	노드 수에 비례 ($1,000/월 이상). Auto-scaling, GitOps 배포 파이프라인, 세밀한 RBAC 체계 운영.

Docker Compose 환경에서 K8s Manifest로 안전하게 이관하는 5단계 절차

기존에 운영 중인 Docker Compose 환경을 서비스 중단 없이 쿠버네티스 클러스터로 전환하기 위한 차근차근한 적용 절차입니다.

1. 컨테이너 이미지 외부 레지스트리 이관: 로컬에서 빌드하던 Dockerfile을 CI/CD 파이프라인(GitHub Actions 등)과 연동하여 원격 Container Registry에 자동 빌드·Push 되도록 세팅합니다.
2. Kompose 도구를 활용한 기본 Manifest 생성: 'kompose convert -f docker-compose.yml' 명령을 수행하여 기본적인 Deployment, Service YAML 파일 뼈대를 추출합니다.
3. K8s 객체 명세 정제 및 리소스 제한 설정: 추출된 YAML 파일에 cpu/memory 'requests' 및 'limits'를 명시하고, 단순 hostPath 볼륨을 PersistentVolumeClaim(PVC) 스펙으로 교체합니다.
4. Health Check(Liveness/Readiness Probe) 추가: K8s가 트래픽을 안전하게 유입시킬 수 있도록 컨테이너별 HTTP GET 또는 Exec 기반의 상태 검사 경로를 Manifest에 추가합니다.
5. Ingress Controller 및 TLS 라우팅 연결: NGINX Ingress Controller 등을 설치하여 기존 Docker의 포트 바인딩(-p 80:80) 구조를 도메인 기반의 L7 트래픽 분산 구조로 완벽히 전환합니다.

자주 막히는 지점

• ErrImagePull 및 ImagePullBackOff 오류: 로컬 Docker Engine 빌드 이미지를 K8s Pod에서 image: my-service:latest 형식으로 호출할 때 containment 런타임 간 상호작용 불일치로 외부 레지스트리를 조회하다 실패하는 현상
• PersistentVolumeClaim 바인딩 실패(Pending 상태 유지): Docker Compose의 상대 경로 디렉터리 마운트 방식을 K8s hostPath로 단순 변경 후 멀티 노드 환경에서 노드 이동 시 스토리지를 찾지 못해 Pod 실행이 차단되는 문제

체크리스트

• 사용 중인 모든 컨테이너 이미지가 외부 Private/Public 레지스트리에 태깅되어 Push 되었는지 확인
• Kubernetes Pod Manifest 내에 livenessProbe 및 readinessProbe 설정이 포함되어 있는지 확인
• 로컬 bind mount 디렉터리가 PVC(PersistentVolumeClaim) 동적 프로비저닝 구조로 변경되었는지 확인
• Pod의 CPU/Memory limits 값이 클러스터 노드 단일 용량을 초과하지 않는지 확인
• Service 타입이 내부 통신용(ClusterIP)과 외부 노출용(Ingress/LoadBalancer)으로 적절히 분리되었는지 확인

오해하기 쉬운 정보

• Kubernetes가 Docker를 대체하므로 Docker는 사용할 필요가 없다는 오해: 거짓입니다. Kubernetes는 클러스터 오케스트레이터이며, 컨테이너 이미지를 빌드하고 로컬 개발 환경을 가동할 때는 여전히 Docker CLI와 Dockerfile 규격을 가장 널리 사용합니다.
• Docker Compose 파일을 K8s Manifest로 자동 변환(Kompose)하면 즉시 운영 환경 배포가 가능하다는 생각: 거짓입니다. 자동 변환 도구는 뼈대만 제공할 뿐, Auto-scaling(HPA), Ingress TLS 설정, Secret 암호화, PVC 스토리지 클래스 지정 등의 실무 설정은 사람이 직접 정제해야 합니다.
• Docker Swarm과 Kubernetes의 기능적 차이가 없다는 착각: 거짓입니다. Docker Swarm은 설정이 간편하지만 복잡한 서비스 메시, 고급 트래픽 분산, 세밀한 RBAC 접근 제어 및 자동 수평 확장은 Kubernetes 환경에서만 완벽히 지원됩니다.

처음 도커 환경에서 쿠버네티스로 서비스를 이관하던 날, 스토리지 바인딩 에러와 이미지 풀 실패로 밤새 설정 파일을 몇 번이고 다시 수정했던 답답함이 떠오릅니다. 오케스트레이션 엔진의 작동 원리를 정확히 이해하고 스펙 요구사항에 맞춰 스토리지와 이미지 레지스트리 경로를 정제해 나가면, 비로소 무중단 배포와 자동 스케일링이 주는 안도감을 경험할 수 있습니다. 오늘 공유해 드린 오류 예방법과 전환 가이드를 바탕으로 한 단계 더 견고한 클라우드 네이티브 인프라를 완성해 보시기 바랍니다.

핵심 요약

• Docker는 컨테이너 빌드 및 단일 실행을 전담하고, Kubernetes는 멀티 노드 클러스터 오케스트레이션을 담당한다.
• 2026년 8월 최신 공식 발표 기준 Docker Engine v29.7.2와 Kubernetes v1.36.4 스펙을 기준으로 인프라를 구성해야 최신 API 호환성이 유지된다.
• K8s 전환 시 로컬 Docker 이미지를 불러오지 못하는 ImagePullBackOff 문제는 원격 레지스트리 Push 및 Secret 설정으로 해결한다.
• Docker Compose의 단순 디렉터리 마운트는 K8s에서 PVC 기반 StorageClass 동적 프로비저닝으로 교체해야 데이터 유실을 막는다.
• 컨테이너 수가 적고 단일 서버 운용 시에는 Docker Compose가 효율적이며, 무중단 배포 및 자동 확장이 필요한 대규모 환경은 Kubernetes 적용이 필수적이다.

#Docker #Kubernetes #DevOps #컨테이너오케스트레이션 #Kubernetes이관 #클라우드네이티브