운영 환경마다 다른 컴포즈 파일 버전, 왜 문제가 될까요
로컬 환경에서는 아무 문제 없이 잘 돌아가던 컨테이너가 정작 운영 서버에 배포하는 순간 에러를 뱉으며 멈춰버리는 경험을 해보셨나요? “version” 필드에 정의된 숫자가 현재 설치된 도커 엔진 버전과 맞지 않거나, 특정 버전에서만 지원하는 기능을 사용했을 때 발생하는 이 문제는 의외로 많은 팀이 겪는 골칫거리예요.
개발팀은 최신 기능을 쓰고 싶어 하고, 인프라 팀은 검증된 안정적인 환경을 유지하고 싶어 하죠. 이 간극 사이에서 적절한 컴포즈 파일 버전 비교 기준이 없다면, 배포 자동화 파이프라인은 언제든 깨질 수 있는 시한폭탄이 돼요. 단순히 숫자를 높게 적는다고 해결되는 문제도 아니에요.
지금 이 글을 읽고 계신 분들은 아마도 현재 팀의 컨테이너 운영 방식을 점검하거나, 새로운 프로젝트의 표준 설정값을 정해야 하는 위치에 계실 거예요. 어떤 버전을 선택해야 나중에 후회하지 않을지, 그리고 현재 사용 중인 설정이 최선인지 판단할 근거가 필요하죠.
이 글을 끝까지 읽으시면 다음과 같은 내용을 명확히 알 수 있어요.
- 도커 컴포즈 버전별 핵심 차이점과 기술적 특징
- 현재 팀의 운영 규모에 딱 맞는 버전 선택 기준
- 버전 지정 방식에 따른 컨테이너 배포 시 주의사항
- 최신 컴포즈 사양(Compose Specification)으로의 전환 전략
버전 선택 전 반드시 점검해야 할 기술적 배경
무작정 버전을 올리기 전에 우리가 사용하는 도구의 정체를 정확히 파악해야 해요. 도커 컴포즈는 크게 두 가지 흐름으로 나뉘어 발전해 왔어요. 과거 Python 기반의 docker-compose와 현재 표준이 된 Go 언어 기반의 docker compose(명령어 사이에 하이픈이 없음)예요. 이 차이를 모르면 아무리 좋은 버전 설정을 해도 실행 자체가 안 될 수 있어요.
또한, 컴포즈 파일 내의 version 필드가 가지는 의미가 예전과는 달라졌다는 점을 이해해야 해요. 과거에는 이 숫자가 파일의 문법(Schema)을 결정하는 절대적인 기준이었지만, 최근에는 이 필드 자체가 선택 사항으로 변하고 있거든요.
도커 엔진의 버전과 도커 컴포즈의 버전은 서로 별개예요. 도커 엔진이 최신이라고 해서 컴포즈의 모든 최신 기능을 바로 쓸 수 있는 건 아니니, 반드시 두 도구의 버전을 함께 체크해 보세요.
본격적인 비교에 앞서, 여러분의 환경이 어떤 기준을 우선시하는지 아래 표를 통해 자가 진단해 보세요.
| 판단 기준 | 안정성 우선형 | 기능 확장형 | 클라우드/Swarm형 |
|---|---|---|---|
| 주요 목적 | 레거시 서버 유지 | 최신 개발 환경 구축 | 오케스트레이션 활용 |
| 권장 버전 | v2.x 또는 v3.x 초기 | Compose Spec (No version) | v3.8 이상 |
| 핵심 가치 | 예측 가능한 동작 | 최신 라이브러리 연동 | 확장성 및 스케일링 |
이 표를 기준으로 팀의 현재 상황을 정의해 보세요. 만약 운영 서버가 매우 오래된 OS 위에서 돌아가고 있다면, 최신 기능이 포함된 버전 3.8을 고집하는 것이 오히려 독이 될 수 있어요. 반대로 모든 것을 클라우드 네이티브하게 가져가고 싶다면, 버전 번호에 얽매이지 않는 최신 표준을 따라야 하죠.
상황별 컴포즈 버전 분석 및 최적의 선택 전략
이제 구체적으로 어떤 버전들이 존재하고, 각각의 특성이 무엇인지 깊이 있게 파헤쳐 볼게요. 단순히 숫자를 나열하는 게 아니라, 실무에서 마주하게 될 기술적 한계와 가능성을 중심으로 설명해 드릴게요.
STEP 1. 과거의 유산, 버전 1과 2의 특징
버전 1은 version 필드 자체가 아예 없던 시절의 방식이에요. 파일 전체가 하나의 거대한 설정 덩어리였고, 네트워크나 볼륨을 세밀하게 제어하는 능력이 매우 부족했죠. 지금 시점에서 버전 1을 사용하는 것은 권장하지 않아요. 거의 모든 현대적 컨테이너 환경에서는 탈락한 방식이라고 봐도 무방해요.
반면 버전 2는 컨테이너 운영의 기반을 닦은 중요한 버전이에요. 네트워크(Networks)와 볼륨(Volumes)을 독립적인 자원으로 정의할 수 있게 되면서, 컨테이너 간의 연결성이 비약적으로 발전했죠. 단일 서버 내에서 여러 서비스를 띄우고 서로 통신하게 만드는 환경에서는 버전 2가 매우 안정적이었어요. 하지만 도커 스웜(Docker Swarm) 같은 클러스터 환경을 지원하지 않는다는 치명적인 한계가 있었어요.
STEP 2. 표준의 시대, 버전 3의 진화와 한계
버전 3는 도커의 방향성이 ‘단일 호스트’에서 ‘클러스터(Swarm)’로 이동하면서 등장했어요. 가장 큰 변화는 deploy 키의 도입이에요. 이를 통해 컨테이너의 복제본 개수(replicas), 업데이트 전략, 리소스 제한(CPU/Memory) 등을 설정할 수 있게 되었죠.
버전 3.x 시리즈 중에서도 3.8 버전은 가장 널리 쓰이는 표준 중 하나예요. 하지만 여기서 주의할 점이 있어요. 버전 3는 스웜 모드에 최적화되어 설계되었기 때문에, 일반적인 단일 호스트 운영 환경에서는 오히려 버전 2에서 가능했던 일부 세밀한 네트워크 설정이 제한될 수 있다는 점이에요. 즉, ‘스웜을 쓸 것인가, 말 것인가’가 버전 3를 선택하는 결정적 기준이 돼요.
STEP 3. 새로운 패러다임, Compose Specification
최근 도커는 ‘버전 번호’라는 개념 자체를 폐지하려는 움직임을 보이고 있어요. 이것이 바로 Compose Specification이에요. 이제는 파일 최상단에 version: '3.8' 같은 문구를 적지 않아도 돼요. 대신 도커 엔진이 설치된 컴포즈 도구의 최신 사양을 자동으로 인식하여 실행하죠.
이 방식의 가장 큰 장점은 하위 호환성과 상위 호환성을 동시에 잡을 수 있다는 것이에요. 개발자는 버전 숫자를 고민할 필요 없이 최신 문법을 사용할 수 있고, 실행 환경(CI/CD 서버나 운영 서버)의 도커 컴포즈 버전이 높다면 알아서 최적의 기능을 사용하게 돼요. 만약 팀이 최신 버전의 도커 엔진을 사용 중이라면, 이 사양으로 전환하는 것이 가장 미래 지향적인 선택이에요.
STEP 4. 기능 중심의 상세 비교 분석
실무에서 가장 많이 갈리는 부분은 네트워크와 보안 설정이에요. 아래는 주요 기능별로 버전 간 차이를 정리한 내용이에요.
- 네트워크 제어: 버전 2는 단일 호스트 내의 복잡한 브리지 네트워크 설정에 강점이 있지만, 버전 3는 클러스터 전체를 아우르는 오버레이(Overlay) 네트워크를 지향해요.
- 보안(Secrets/Configs): 버전 3 이상부터는 환경 변수 대신 보안이 강화된 Secrets와 Configs 기능을 본격적으로 지원해요. 보안이 중요한 금융이나 개인정보 처리 서비스라면 반드시 버전 3.x 이상이나 Compose Spec을 써야 해요.
- 리소스 제한: 버전 2는 호스트의 자원을 직접 제어하는 느낌이라면, 버전 3는 스웜의 스케줄러에게 자원 할당을 요청하는 방식이에요.
만약 운영 서버의 도커 컴포즈 버전이 너무 낮다면, 파일에
version: '3.8'이라고 명시해도 에러가 날 수 있어요. 버전 명시는 ‘이 기능을 쓰겠다’는 선언이 아니라, ‘이 문법 규칙을 따르겠다’는 약속이기 때문이에요.STEP 5. 실무 적용 시나리오 가이드
이해를 돕기 위해 두 가지 극단적인 운영 시나리오를 가정해 볼게요.
시나리오 A: 소규모 스타트업의 단일 서버 운영
서버 1대에서 웹 서버, DB, 캐시 서버를 모두 띄우는 구조라면? 버전 3.8을 쓰되, 스웜 관련 설정인 deploy 키는 최소한으로 사용하는 것이 좋아요. 만약 도커 엔진이 최신이라면 아예 버전 명시를 생략하고 Compose Spec을 따르는 것이 관리 포인트가 가장 적어요.
시나리오 B: 대규모 엔터프라이즈의 클러스터 환경
수십 대의 노드로 구성된 도커 스웜 환경이라면? 무조건 버전 3.8 이상을 사용해야 해요. 특히 컨테이너의 가용성(Availability)을 보장하기 위해 update_config나 rollback_config 같은 설정이 필수적이기 때문이에요. 이때는 버전 번호를 명확히 기재하여 모든 노드가 동일한 문법으로 해석하도록 강제하는 것이 안전해요.
자주 하는 실수와 해결법 및 FAQ
현장에서 개발자들이 가장 자주 범하는 실수들을 정리했어요. 이 패턴만 피해도 배포 실패의 절반은 막을 수 있어요.
❌ 실수: 최신 문법을 쓰면서 버전은 ‘2.x’로 지정하기
→ 왜 발생하는가: 예전에 작성된 템플릿을 복사해서 쓰다가 새로운 기능(Secrets 등)만 추가하는 경우예요.
✅ 해결법: 추가한 기능이 지원되는 최소 버전을 확인하고, 가능하면 버전 명시를 생략하는 Compose Spec 방식을 고려하세요.
❌ 실수: 단일 서버 환경에서 버전 3.x의 ‘deploy’ 설정만 믿고 배포하기
→ 왜 발생하는가: 스웜 모드가 아닌 일반 도커 엔진에서는 deploy 설정이 무시될 수 있다는 사실을 간과하기 때문이에요.
✅ 해결법: 단일 호스트라면 리소스 제한을 위해 mem_limit 같은 버전 2 스타일의 설정을 병행하거나, 도커 엔진의 기본 설정값을 확인하세요.
❌ 실수: CI/CD 환경과 운영 서버의 도커 컴포즈 버전 불일치
→ 왜 발생하는가: 로컬에서는 최신 도커를 쓰지만, 배포 서버는 몇 년 전 이미지를 그대로 쓰고 있는 경우예요.
✅ 해결법: 배포 파이프라인 단계에서 반드시 도커 컴포즈 버전을 체크하는 스크립트를 넣으세요.
❌ 실수: 환경 변수(.env) 파일 위치와 버전 간의 충돌
→ 왜 발생하는가: 특정 버전에서는 환경 변수 주입 방식이 까다로울 수 있어요.
✅ 해결법: 컴포즈 파일 내에서 ${VARIABLE} 형식을 사용하고, 반드시 버전 3 이상의 사양을 준수하세요.
버전을 올리는 것은 단순히 숫자를 바꾸는 게 아니라, 컨테이너가 자원을 사용하는 방식과 네트워크를 구성하는 철학을 바꾸는 작업이라는 점을 명심해야 해요.
자주 묻는 질문
Q. 이제 컴포즈 파일에 version 필드를 아예 안 써도 되나요?
네, 최신 도커 엔진과 도커 컴포즈(V2)를 사용하고 있다면 생략해도 무방해요. 생략하면 자동으로 최신 Compose Specification을 따르게 되어 편리해요. 하지만 팀 내 컨벤션이 확고하거나 구형 환경과의 호환성이 중요하다면 명시하는 것이 더 안전할 수 있어요.
Q. 버전 3.8이 가장 좋다는 뜻인가요?
꼭 그렇지는 않아요. 3.8은 기능이 풍부한 아주 좋은 버전이지만, 아주 가벼운 테스트용 환경이라면 굳이 무거운 설정을 가져갈 필요가 없죠. 상황에 따라 ‘가장 최신’이 아닌 ‘가장 적합한’ 버전을 찾는 것이 핵심이에요.
Q. 도커 컴포즈 V1에서 V2로 넘어갈 때 버전 설정이 바뀌나요?
명령어 자체가 docker-compose에서 docker compose로 바뀌는 큰 변화가 있어요. V2는 Compose Specification을 기반으로 하므로, 기존 버전 명시 방식보다 훨씬 유연하게 동작해요. 가급적 V2로 마이그레이션하는 것을 강력히 추천해요.
Q. 스웜(Swarm)을 안 쓰는데 왜 버전 3를 써야 하나요?
스웜을 안 쓰더라도 최신 보안 기능(Secrets)이나 향상된 리소스 관리 기능을 쓰려면 버전 3 이상이 필요해요. 다만, 스웜 전용 기능인 deploy 옵션이 단일 호스트에서 어떻게 동작하는지는 반드시 테스트해 봐야 해요.
Q. 버전 충돌 에러가 나면 어떻게 확인하나요?
가장 먼저 docker compose version 명령어로 실행 환경의 버전을 확인하세요. 그 다음 사용 중인 YAML 파일의 키(Key)들이 해당 버전에서 지원되는지 공식 문서를 대조해 보는 것이 가장 빠른 방법이에요.
성공적인 컨테이너 운영을 위한 마지막 점검
컴포즈 파일 버전 결정은 단순한 문법 선택이 아니라, 우리 서비스의 운영 안정성과 확장성을 결정하는 중요한 설계 작업이에요. 기술의 흐름을 따라가되, 현재 우리 인프라의 한계를 객관적으로 바라보는 태도가 필요해요.
- 단일 서버 위주의 가벼운 운영이라면 버전 2나 3 초기 버전을 고려하세요.
- 클러스터링이나 보안(Secrets)이 중요하다면 버전 3.8 이상을 선택하세요.
- 최신 도커 환경이라면 버전 명시를 생략하는 Compose Spec이 가장 효율적이에요.
- 운영 서버와 개발 환경의 도커 엔진 버전을 반드시 일치시키거나 호환성을 체크하세요.
- 배포 전 반드시 CI/CD 단계에서 버전 호환성 테스트를 자동화하세요.
이제 무엇을 해야 할까요? 지금 바로 팀에서 사용하는 컴포즈 파일들을 한 번 모아서 확인해 보세요. 버전이 제각각이거나, 사용하지 않는 구형 문법이 섞여 있지는 않은가요?
우선순위 기준 세 가지를 정해 두면 선택이 훨씬 쉬워집니다. 첫째는 보안, 둘째는 호환성, 셋째는 운영 편의성이에요. 이 기준을 바탕으로 팀의 표준 가이드를 만들어 보세요.
이번 주 안에 현재 운영 중인 서비스 중 가장 작은 규모의 프로젝트 하나를 골라, 버전 명시를 제거하거나 최신 사양으로 전환하는 실험을 진행해 보시는 건 어떨까요? 작은 실험이 큰 사고를 막는 밑거름이 될 거예요.
더 자세한 도커 활용법이 궁금하시다면 도커 컴포즈 기본 개념 완벽 정리 — 개념부터 실무 활용까지 한눈에 보는 가이드 글을 함께 읽어보시는 것을 추천해요.
