[IT-정보] 컴포즈 파일 버전 원리 심화 분석 – 내부 동작 구조부터 실무 설계까지

단순한 숫자 지정 그 이상의 의미를 찾아서

도커 컴포즈 파일을 작성할 때 맨 윗줄에 version: ‘3.8’이라고 적으며 작업을 시작하는 일이 아주 익숙하실 거예요. 아마도 많은 개발자가 이 숫자가 무엇을 의미하는지 깊게 고민하지 않고, 그저 예제 코드에 적힌 숫자를 그대로 복사해서 붙여넣곤 해요. 하지만 서버 운영 환경에서 갑자기 “지원하지 않는 설정 키가 있습니다”라는 에러 메시지를 마주하게 되면 상황은 달라져요.

왜 내가 작성한 설정이 특정 환경에서는 작동하고, 다른 환경에서는 에러를 내뿜는 걸까요? 단순히 도커 엔진의 버전 문제일까요, 아니면 내가 지정한 컴포즈 파일의 버전 때문일까요? 이 질문에 명확히 답하지 못한다면, 컨테이너 오케스트레이션 과정에서 발생하는 미묘한 설정 오류를 해결하기가 매우 어려워져요.

버전 필드는 단순히 파일의 형식을 알리는 표식이 아니에요. 그것은 도커 컴포즈 엔진이 어떤 문법 규칙을 사용할지, 그리고 어떤 API 수준까지 컨테이너 리소스를 생성할 수 있는지를 결정하는 설계도와 같아요. 버전에 따라 사용할 수 있는 네트워크 드라이버의 옵션이 달라지고, 볼륨을 마운트하는 방식이나 컨테이너의 리소스 제한(limits)을 거는 문법 자체가 변하기도 해요.

이 글에서는 단순한 사용법을 넘어, 컴포즈 파일의 버전 필드가 내부적으로 어떻게 해석되고 실제 도커 엔진의 API 호출로 변환되는지 그 심층적인 흐름을 추적해요. 이 과정을 이해하면 단순한 에러 해결을 넘어, 더 안정적인 컨테이너 운영 환경을 설계하는 능력을 갖추게 될 거예요.

오늘 우리가 함께 살펴볼 내용은 다음과 같아요.

• 컴포즈 버전 필드가 엔진 내부에서 해석되는 과정
• 스키마 검증과 API 매핑의 기술적 원리
• 버전 설정에 따른 리소스 생성 방식의 차이
• 실무에서 겪는 버전 관련 문제와 해결 전략

버전 엔진과 스키마의 관계 이해하기

본격적으로 내부 동작을 파헤치기 전에, 우리가 혼동하기 쉬운 두 가지 개념을 명확히 구분해야 해요. 바로 도커 엔진(Docker Engine) 버전과 컴포즈 스키마(Compose Schema) 버전이에요. 많은 개발자가 이 둘을 동일하게 생각하지만, 사실 이들은 서로 다른 계층에서 작동해요.

도커 엔진은 컨테이너를 실제로 실행하는 런타임 환경을 담당하고, 컴포즈는 그 엔진에게 전달할 명령을 정의하는 도구예요. 컴포즈 파일의 버전 필드는 도커 엔진의 버전을 지정하는 것이 아니라, 컴포즈 엔진이 어떤 JSON 스키마를 기준으로 파일을 검증할지를 결정하는 규칙이에요. 즉, 컴포즈 엔진은 이 버전을 보고 “아, 이번에는 3.8 규격에 맞춰서 문법을 체크해야겠구나”라고 판단하는 것이지요.

버전을 선택할 때 고려해야 할 기준은 단순히 “최신이 최고다”가 아니에요. 운영 중인 인프라의 안정성과 호환성을 따져봐야 해요. 아래 표를 통해 버전별 특징과 선택 기준을 비교해 드릴게요.

결국 버전을 결정한다는 것은 우리가 사용할 문법의 한계를 정하는 일과 같아요. 예를 들어, 3.x 버전에서는 2.x에서 사용하던 일부 호스트 기반 네트워크 설정 방식이 제한될 수 있어요. 따라서 개발 환경과 운영 환경의 컴포즈 엔진 버전, 그리고 도커 엔진의 버전을 모두 고려하여 가장 안전한 스키마 버전을 선택하는 것이 실무자의 핵심 역량이에요.

컴포즈 엔진의 내부 데이터 처리 및 리소스 생성 흐름

이제 우리가 작성한 YAML 파일이 어떻게 실제 컨테이너로 변하는지, 그 내부의 복잡한 매커니즘을 단계별로 뜯어볼게요. 컴포즈 엔진은 크게 파싱(Parsing), 검증(Validation), 번역(Translation), 실행(Execution)이라는 네 가지 핵심 단계를 거쳐요.

STEP 1. YAML 파싱과 스키마 식별

사용자가 docker compose up 명령을 내리면, 엔진은 가장 먼저 지정된 경로에서 파일을 찾아 읽기 시작해요. 이때 엔진은 파일의 가장 윗부분에 적힌 version 필드를 최우선적으로 확인해요. 이 숫자는 엔진에게 “이 파일의 구조는 이 규칙을 따르고 있으니, 그에 맞는 파서를 준비하세요”라고 말하는 것과 같아요.

엔진은 이 버전을 보고 내부적으로 준비된 여러 개의 JSON 스키마 중 하나를 선택해요. 만약 버전이 3.8이라면, 3.8 스키마에 정의된 데이터 구조(services, networks, volumes 등)를 바탕으로 YAML의 계층 구조를 메모리상의 객체로 변환해요. 이 과정에서 들여쓰기 오류나 잘못된 키 이름이 있다면 즉시 에러를 발생시켜 실행을 중단하죠.

STEP 2. 스키마 검증과 정책 적용

파싱이 완료되면, 엔진은 읽어 들인 데이터가 선택된 버전의 규칙에 맞는지 아주 꼼꼼하게 검사해요. 이를 스키마 검증이라고 불러요. 예를 들어, 버전 3.x 스키마에서는 deploy 키를 사용하여 컨테이너의 리소스 제한을 설정할 수 있지만, 아주 낮은 버전의 스키마에서는 이 키를 인식하지 못하거나 에러를 낼 수 있어요.

이 단계에서는 단순히 문법만 보는 것이 아니라, 설정된 값들의 유효성도 함께 체크해요. 예를 들어, 포트 매핑 설정에서 숫자가 아닌 문자가 들어갔는지, 혹은 네트워크 이름이 규칙을 준수하는지 등을 확인해요. 이 검증 과정이 통과되어야만 비로소 엔진은 다음 단계인 ‘번역’으로 넘어갈 수 있어요. 만약 여기서 막힌다면, 여러분은 설정을 수정해야 하는 것이지 도커 엔진을 업데이트할 문제가 아닐 확률이 높아요.

STEP 3. 엔진 API로의 명령 번역(Translation)

이 단계가 가장 중요하고 기술적인 핵심이에요. 컴포즈 파일에 적힌 추상적인 설정들을 도커 엔진(Docker Daemon)이 이해할 수 있는 REST API 호출로 변환하는 과정이에요. 컴포즈 파일은 사람이 읽기 좋은(human-readable) 형태이지만, 도커 엔진은 JSON 형태의 API 명령을 원하기 때문이에요.

예를 들어, 컴포즈 파일에 다음과 같은 서비스 설정이 있다고 가정해 봅시다.

이때 버전 필드는 ‘번역 가이드라인’ 역할을 해요. 버전 2.x 스키마를 사용 중이라면 엔진은 호스트의 특정 디렉토리를 직접 마운트하는 상세한 설정을 포함한 API를 호출할 것이고, 3.x 스키마라면 Swarm 모드에서 사용 가능한 클러스터링 관련 옵션들을 포함하도록 명령을 구성할 거예요. 즉, 버전은 컴포즈 엔진이 어떤 API 파라미터를 조합할지를 결정하는 로직의 기준점이 되는 것이지요.

STEP 4. 리소스 생성 순서 및 의존성 해결

모든 명령이 번역되면, 엔진은 리소스들을 어떤 순서로 만들지 결정해요. 모든 것을 한꺼번에 만드는 것이 아니라, 의존 관계를 계산하여 순차적으로 실행해요. 일반적으로 네트워크와 볼륨이 먼저 생성되고, 그 다음에 서비스(컨테이너)들이 생성되는 흐름을 가져요.

여기서 컴포즈 파일의 버전이 미치는 영향이 다시 한번 드러나요. 특정 버전에서는 네트워크 생성 시 driver_opts를 통해 매우 세밀한 설정을 지원하지만, 하위 버전에서는 이러한 옵션이 무시되거나 에러를 발생시킬 수 있어요. 엔진은 번역된 명령을 바탕으로 도커 엔진에게 요청을 보내고, 엔진은 실제로 컨테이너, 네트워크, 볼륨을 하나씩 생성해 나갑니다.

STEP 5. 설정 반영의 최종 확인

마지막으로, 생성된 리소스들이 실제 운영 체제의 커널 수준에서 제대로 작동하는지 확인하는 단계예요. 예를 들어, 컴포즈 파일에서 설정한 메모리 제한(Memory Limit) 설정이 실제 컨테이너의 Cgroups 설정에 정확히 반영되었는지 엔진은 도커 데몬으로부터 응답을 받아 최종적으로 확정해요. 만약 버전 설정 오류로 인해 잘못된 API 호출이 전달되었다면, 이 단계에서 리소스 생성 실패가 발생하게 됩니다.

이 모든 과정은 찰나의 순간에 일어나지만, 그 내부에는 버전이라는 기준점을 중심으로 한 정교한 논리 구조가 숨어 있어요. 우리가 버전 필드를 신중하게 선택해야 하는 이유가 바로 여기에 있는 것이지요.

자주 하는 실수와 해결법 및 FAQ

자주 하는 실수와 해결법

❌ 실수: 도커 엔진 버전은 최신인데, 컴포즈 파일 버전만 높게 적는 경우
왜 발생하는가: 컴포즈 엔진이 지원하는 스키마 버전과 실제 도커 엔진이 처리할 수 있는 API 기능이 일치하지 않을 때 발생해요. 파일에는 최신 기능을 적었지만, 정작 엔진이 그 기능을 수행할 API를 가지고 있지 않은 상황이에요.
✅ 해결법: 사용하는 도커 엔진의 버전을 확인하고, 해당 엔진이 지원하는 가장 높은 스키마 버전을 확인하여 일치시켜 주세요.

❌ 실수: 3.x 버전에서 2.x 전용 네트워크 설정을 사용하는 경우
왜 발생하는가: 버전 3.x는 클러스터 환경에 최적화되어 있어, 호스트의 물리적 경로를 직접 제어하는 일부 상세한 네트워크 옵션이 제한될 수 있어요.
✅ 해결법: 3.x 스키마의 문법 가이드를 준수하거나, 호스트 기반의 정밀한 제어가 꼭 필요하다면 2.x 스키마를 사용하는 것을 검토해 보세요.

❌ 실수: 환경 변수(Environment Variables)를 사용하면서 버전 형식을 무시하는 경우
왜 발생하는가: .env 파일 등에서 가져오는 값이 숫자가 아닌 문자열로 인식되어, 버전을 판단하는 파싱 단계에서 오류가 생길 수 있어요.
✅ 해법: 환경 변수가 버전 필드나 숫자형 설정값에 영향을 주지 않도록 데이터 타입을 명확히 관리해야 해요.

❌ 실수: Compose V2로 넘어오면서 버전 필드를 생략하고 방치하는 경우
왜 발생하는가: V2에서는 버전 생략이 가능하지만, 프로젝트가 복잡해지면 의도치 않게 기본 스키마가 적용되어 특정 옵션이 동작하지 않을 수 있어요.
✅ 해결법: 명시적인 제어를 위해 가급적 프로젝트의 요구 사항에 맞는 버전을 명시하는 습관을 갖는 것이 좋아요.

❌ 실수: 볼륨(Volume) 경로 설정 시 버전별 차이를 간과하는 경우
왜 발생하는가: 버전마다 상대 경로를 해석하거나 마운트하는 방식의 미묘한 정책 차이가 있을 수 있어요.
✅ 해결법: 반드시 공식 문서를 통해 해당 버전의 Volume Syntax를 재확인하세요.

자주 묻는 질문

Q. 컴포즈 파일의 버전 숫자를 무조건 높게 적는 게 유리한가요?

아니요, 그렇지 않아요. 버전 숫자가 높다는 것은 더 많은 최신 기능을 사용할 수 있다는 뜻이지만, 동시에 구형 도커 엔진과의 호환성이 떨어진다는 것을 의미해요. 운영 환경의 엔진 버전을 먼저 확인하는 것이 순서예요.

Q. 버전 필드를 아예 삭제하면 어떻게 되나요?
도커 컴포즈 V2를 사용 중이라면 기본적으로 최신 스키마를 기준으로 동작하려고 시도해요. 하지만 프로젝트의 의존성이 명확하지 않다면 예기치 못한 문법 오류가 발생할 수 있으니 주의가 필요해요.

Q. 도커 엔진 업데이트 없이 컴포즈 파일 버전만 올려도 되나요?
안 돼요. 컴포즈 파일 버전은 엔진이 이해할 API의 범위를 정하는 것이므로, 엔진이 지원하지 않는 API를 호출하는 설정은 반드시 에러를 발생시켜요.

Q. 특정 버전에서만 작동하는 특수 기능이 정말 있나요?
네, 있어요. 예를 들어 Swarm 모드에서의 서비스 배포 설정인 deploy 키는 3.x 버전 이상의 스키마에서만 유효하게 동작해요.

Q. 에러 메시지에 ‘Unsupported configuration key’가 뜨면 어떻게 하나요?
가장 먼저 현재 지정한 버전 필드가 해당 키를 지원하는지 확인하세요. 지원하지 않는다면 버전을 높이거나, 해당 키를 대신할 구형 버전의 문법을 찾아야 해요.

원리를 알면 안정적인 인프라가 보입니다

지금까지 컴포즈 파일의 버전 필드가 단순한 숫자를 넘어, 엔진 내부에서 어떻게 스키마를 결정하고 API 명령으로 변환되는지 깊이 있게 살펴보았어요. 버전 설정은 컨테이너의 생명주기와 리소스의 구조를 결정하는 매우 중요한 설계 결정이에요.

오늘 배운 내용을 바탕으로 지금 바로 여러분의 프로젝트를 점검해 보세요. 단순히 복사해 온 버전이 현재 서버 환경에 적절한지, 혹은 불필요하게 복잡한 문법을 쓰고 있지는 않은지 확인하는 것만으로도 운영의 안정성이 크게 향상될 거예요.

🚀 지금 바로 실행해 보세요!

• 사용 중인 서버에서 docker version 명령어로 엔진 버전을 확인하세요.
• 현재 컴포즈 파일의 버전이 엔진이 지원하는 범위 내에 있는지 대조해 보세요.
• 가능하다면 버전 필드를 명시적으로 작성하여 설정의 의도를 분명히 하세요.

더 깊이 있는 컨테이너 운영 지식이 필요하다면, 아래의 가이드를 함께 읽어보시는 것을 추천해요.

도커 컴포즈 기본 개념 완벽 정리 — 개념부터 실무 활용까지 한눈에 보는 가이드