[IT-정보] 컴포즈 파일 버전 질문 정리 – 설정 오류부터 최신 사양까지 모두 해결해요

컴포즈 파일 버전 때문에 막막했던 경험 있으신가요

도커 컴포즈 파일을 작성해서 실행했는데, 갑자기 빨간색 글씨로 “version is obsolete”라는 경고가 떠서 당황했던 적이 있어요. 분명히 블로그에서 본 대로 version: '3.8'이라고 적었는데 왜 자꾸 문제가 생기는 걸까요? 혹은 버전 숫자를 아예 지워버리면 어떻게 되는 건지, 내가 사용하는 도커 엔진 버전과 컴포즈 파일의 버전이 서로 맞지 않으면 어떤 일이 벌어지는지 궁금할 때가 많아요.

입문 개발자라면 누구나 한 번쯤 겪는 문제입니다. 단순히 숫자 하나를 적는 것 같지만, 이 숫자가 컨테이너가 어떻게 네트워크를 구성하고 볼륨을 연결할지 결정하는 중요한 기준이 되기 때문이에요. 특히 최근에는 도커 컴포즈의 동작 방식이 Compose Specification이라는 새로운 표준으로 통합되면서, 예전 방식대로만 코드를 짜면 예상치 못한 오류를 만날 수 있어요.

이 글을 끝까지 읽고 나면 더 이상 버전 숫자 때문에 머리를 싸매지 않아도 돼요. 현재 여러분의 환경에 가장 적합한 버전 설정법이 무엇인지, 그리고 앞으로 어떤 방향으로 설정을 관리해야 하는지 명확하게 알게 될 거예요.

이 글에서는 다음과 같은 내용들을 다뤄요.

• 도커 컴포즈 버전의 역사와 현재의 변화상
• 버전 지정 방식에 따른 실제 설정 차이점
• 명령어 실행 시 발생하는 버전 관련 오류 해결법
• 실무에서 바로 써먹는 최적의 버전 관리 전략

버전 설정을 시작하기 전 꼭 알아야 할 기초 지식

컴포즈 파일을 작성하기 전에 먼저 이해해야 할 점이 있어요. 우리가 흔히 쓰는 version: '3' 같은 문구는 예전 방식의 유산이라는 사실이에요. 예전에는 도커 컴포즈가 버전별로 지원하는 기능이 엄격하게 나뉘어 있었지만, 지금은 그 경계가 많이 허물어졌어요.

하지만 여전히 기존 프로젝트를 유지보수하거나, 특정 서버 환경에 맞춰 컨테이너를 배포해야 할 때는 버전을 정확히 이해하는 것이 필수예요. 무작정 최신 버전을 쓴다고 좋은 것도 아니고, 너무 낮은 버전을 쓰면 최신 기능을 못 쓸 수도 있거든요.

본격적인 작성에 앞서, 여러분이 선택해야 할 버전의 기준을 표로 정리해 보았어요. 어떤 상황에서 어떤 버전을 지향해야 하는지 확인해 보세요.

가장 중요한 판단 기준은 “내가 사용하는 도커 엔진(Docker Engine)의 버전이 무엇인가”예요. 엔진이 너무 오래되었다면 최신 컴포즈 스펙을 지원하지 못해 오류가 발생할 수 있거든요. 따라서 작업을 시작하기 전에 반드시 터미널에서 docker version 명령어로 엔진 상태를 먼저 확인하는 습관을 가져야 해요.

컴포즈 파일 버전 완벽 가이드: 단계별 실행법

이제 본격적으로 컴포즈 파일을 어떻게 구성하고 관리해야 하는지 단계별로 살펴볼게요. 단순히 코드를 복사하는 것이 아니라, 왜 이렇게 작성해야 하는지 원리를 이해하는 것이 중요해요.

STEP 1. 파일 상단의 버전 선언 이해하기

예전 방식의 컴포즈 파일은 항상 제일 첫 줄에 version: '3.8'처럼 버전을 명시하며 시작했어요. 이 숫자는 “나는 이 파일에서 3.8 버전의 규칙을 따를 거야”라고 도커에게 선언하는 것과 같아요. 만약 3.8 버전에만 있는 특수 기능을 사용하면서 버전을 '2.0'으로 적는다면, 도커는 해당 기능을 인식하지 못하고 에러를 뱉게 돼요.

하지만 최근의 변화를 꼭 기억해야 해요. 최신 도커 컴포즈(V2)를 사용하고 있다면, 사실 이 version 필드는 더 이상 필수가 아니에요. 도커는 이제 Compose Specification이라는 통합 표준을 따르기 때문에, 버전 번호를 적지 않아도 알아서 가장 적절한 방식으로 파일을 해석해요. 그래서 최근에 보이는 “version is obsolete” 경고는 “이제 버전 안 써도 되니까 그냥 써도 돼”라는 친절한 알림이라고 생각하면 마음이 편해요.

STEP 2. 환경에 맞는 기능 선택하기

버전을 정할 때 가장 고민되는 부분이 바로 “어떤 기능을 쓸 수 있는가”예요. 예를 들어, 컨테이너의 자원 제한(CPU, 메모리)을 설정하거나 복잡한 네트워크 구성을 하려면 버전 선택이 매우 중요해요.

버전 2와 버전 3의 가장 큰 차이는 Docker Swarm 지원 여부예요. 버전 3는 여러 대의 서버를 묶어서 관리하는 Swarm 모드에서 컨테이너를 배포하기 위해 만들어졌어요. 그래서 개별 컨테이너에 대한 아주 세밀한 설정(예: 일부 네트워크 기능)은 버전 2보다 제한적일 수 있어요. 반대로, 서비스의 확장성(Scale-out)이나 클러스터 환경에서의 운영을 고려한다면 무조건 버전 3 이상의 설정을 따라야 해요.

STEP 3. 최신 Compose Specification으로 전환하기

만약 여러분이 새로운 프로젝트를 시작한다면, 굳이 특정 버전에 얽매이지 말고 최신 표준을 따르는 것을 추천해요. Compose Specification 방식은 버전 번호를 아예 삭제하고 작성하는 방식이에요. 이렇게 하면 도커 엔진이 업데이트될 때마다 여러분의 파일을 일일이 수정할 필요 없이, 엔진이 가진 최신 기능을 자동으로 활용할 수 있어요.

전환 방법은 아주 간단해요. 파일 최상단의 version: 'x.x' 라인을 통째로 삭제하세요. 그리고 사용하려는 기능들이 최신 사양에 맞는지 확인하면 돼요. 이렇게 하면 버전 불일치로 인한 골치 아픈 경고 메시지에서 해방될 수 있어요.

STEP 4. 실행 명령어와 엔진 버전 매칭하기

파일을 잘 썼더라도 실행 도구가 구형이라면 문제가 생겨요. 여기서 많은 분이 헷갈려 하는 것이 docker-compose와 docker compose의 차이예요. 하이픈(-)이 들어간 명령어는 예전 파이썬 기반의 V1 버전이고, 띄어쓰기가 있는 명령어는 최신 Go 언어 기반의 V2 버전이에요.

최신 기능을 제대로 활용하려면 반드시 docker compose(띄어쓰기 포함) 명령어를 사용해야 해요. V1 명령어는 이제 보안 업데이트도 중단되는 추세이므로, 가급적이면 최신 엔진과 V2 명령어를 세트로 맞추는 것이 운영 안정성 측면에서 훨씬 유리해요.

STEP 5. 실제 적용 시나리오 및 예제

이해를 돕기 위해, 버전 관리가 잘 된 모범적인 컴포즈 파일 예시를 하나 만들어 보았어요. 이 예시는 최신 표준을 따르며, 버전 선언 없이도 동작하도록 설계되었어요.

# version: '3.8'  <- 이제 이런 줄은 생략해도 괜찮아요!

services:
  web:
    image: nginx:latest
    ports:
      - "80:80"
    networks:
      - app-network
    deploy:
      resources:
        limits:
          cpus: '0.5'
          memory: 512M

  db:
    image: postgres:15
    environment:
      POSTGRES_PASSWORD: example_password
    networks:
      - app-network
    volumes:
      - db-data:/var/lib/postgresql/data

networks:
  app-network:
    driver: bridge

volumes:
  db-data:

위 예제에서 deploy 섹션을 사용해 CPU와 메모리를 제한하는 부분은 버전 3 이상 혹은 최신 스펙에서 지원하는 기능이에요. 만약 아주 오래된 버전의 컴포즈를 사용한다면 이 부분이 에러를 일으킬 수 있으니, 반드시 자신의 환경을 먼저 체크해야 한다는 점을 잊지 마세요!

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

현장에서 개발자들이 가장 흔하게 저지르는 실수들을 모아봤어요. 비슷한 상황을 겪고 있다면 바로 해결책을 적용해 보세요.

• ❌ 실수: version: 3.9라고 적었는데 엔진 버전이 낮아서 실행이 안 돼요.
  왜 발생하는가: 도커 엔진(Docker Engine)이 너무 구형이라 해당 버전의 문법을 이해하지 못하기 때문이에요.
  ✅ 해결법: 도커 엔진을 최신 버전으로 업데이트하거나, 파일의 버전을 '3.3' 정도로 낮추어 작성하세요.
• ❌ 실수: 버전을 삭제했더니 갑자기 네트워크 설정이 작동하지 않아요.
  왜 발생하는가: 버전을 삭제하면 Compose Specification 모드로 동작하는데, 이때 기본 네트워크 드라이버 설정이 달라질 수 있어요.
  ✅ 해결법: networks 섹션에서 드라이버(bridge 등)를 명확하게 명시해 주세요.
• ❌ 실수: docker-compose up 명령어를 썼는데 명령어를 찾을 수 없다고 나와요.
  왜 발생하는가: 최신 도커 설치 방식에서는 하이픈이 포함된 구형 명령어가 포함되지 않을 수 있어요.
  ✅ 해결법: docker compose up(띄어쓰기) 명령어를 사용하세요.
• ❌ 실수: 파일 맨 위에 version: 3라고 따옴표 없이 적었어요.
  왜 발생하는가: YAML 문법에서 숫자는 문자열과 다르게 취급될 수 있어 파싱 오류가 생길 수 있어요.
  ✅ 해결법: 반드시 '3' 또는 '3.8'처럼 따옴표로 감싸서 문자열로 입력하세요.
• ❌ 실수: Swarm 모드에서 쓰던 설정을 일반 로컬 환경에서 돌리려다 에러가 나요.
  왜 발생하는가: deploy 섹션의 일부 설정은 Swarm 환경 전용이기 때문이에요.
  ✅ 해결법: 로컬 테스트 시에는 deploy 설정을 제외하거나, 최신 스펙을 지원하는 엔진을 사용하세요.

실무에서 자주 묻는 질문들을 정리했습니다.

Q. 버전 숫자를 아예 안 적으면 어떻게 되나요?

최신 도커 컴포즈(V2)를 사용 중이라면 아무런 문제 없이 아주 잘 작동해요. 오히려 버전 번호를 적지 않는 것이 현재의 표준(Compose Specification)에 더 부합하는 깔끔한 방식이에요.

Q. "version is obsolete"라는 경고가 계속 뜨는데 무시해도 될까요?

네, 무시해도 컨테이너 실행에는 지장이 없어요. 하지만 경고를 없애고 싶다면 파일 상단의 version: '...' 줄을 삭제하는 것이 가장 깔끔한 해결책이에요.

Q. 버전 2와 3 중 무엇을 쓰는 게 무조건 유리한가요?

그렇지 않아요. 현재는 버전 2와 3의 경계가 사라지고 하나의 통합된 스펙으로 합쳐지고 있어요. 따라서 특정 버전을 고집하기보다는 최신 도커 엔진을 설치하고 버전을 명시하지 않는 방식을 지향하는 것이 가장 좋습니다.

Q. 제 컴포즈 버전은 어떻게 확인하나요?

터미널에 docker compose version을 입력해 보세요. 만약 명령어가 작동하지 않는다면 docker-compose --version을 입력하여 설치 여부를 확인할 수 있어요.

Q. 특정 기능을 쓰려면 반드시 버전을 높여야 하나요?

네, 맞아요. 예를 들어 특정 볼륨 드라이버 기능이나 복잡한 보안 설정을 사용하려면, 그 기능을 지원하는 최소 버전 이상의 스펙이 필요해요. 사용하려는 기능의 공식 문서를 먼저 확인하는 습관이 중요해요.

컴포즈 버전 관리를 위한 최종 요약

오늘 살펴본 내용을 바탕으로, 앞으로 컴포즈 파일을 작성할 때 이것만은 꼭 기억해 주세요. 복잡한 설정 속에서도 중심을 잡을 수 있도록 정리해 두었습니다.

이제 이론적인 부분은 모두 마스터하셨어요! 당장 실행에 옮겨볼 차례예요.

🚀 이번 주 할 일:
현재 운영 중인 프로젝트의 docker-compose.yml 파일을 열어보세요. 그리고 상단의 버전 선언을 지웠을 때 정상적으로 작동하는지 테스트해 보세요. 만약 경고가 사라지고 서비스가 잘 돌아간다면, 여러분은 이미 최신 표준을 따르고 있는 거예요!

혹시 작업을 하다가 도저히 해결되지 않는 특이한 에러 메시지를 만났나요? 혼자 고민하며 시간을 보내기보다는 댓글로 남겨 주세요. 제가 아는 선에서 최대한 상세히 답변을 정리해 드릴게요. 여러분의 시행착오를 줄여드리는 것이 제 목표니까요!

함께 읽으면 도움이 되는 글:
도커 컴포즈 기본 개념 완벽 정리 — 개념부터 실무 활용까지 한눈에 보는 가이드