include로 Compose 파일 모듈화하기

include로 Compose 파일 모듈화하기 (Use include to modularize Compose files)

Docker Compose의 include 최상위 요소는 다른 Compose 파일을 포함해 Compose 구성을 재사용하고 모듈화해요.

출처: 문서

본문

요구 사항: Docker Compose 2.20.0 이상

다른 Compose 파일을 포함해서 Docker Compose 구성을 재사용하고 모듈화할 수 있어요. 이는 다음과 같은 경우에 유용해요:

다른 Compose 파일을 재사용하고 싶을 때.
애플리케이션 모델의 일부를 별도의 Compose 파일로 분리해 따로 관리하거나 다른 사람과 공유해야 할 때.
팀이 더 큰 배포 안에서 자신의 하위 도메인에 대해 선언해야 하는 제한된 리소스 수에 필요한 복잡성만 담은 Compose 파일을 유지해야 할 때.

include 최상위 섹션은 다른 Compose 애플리케이션 또는 하위 도메인에 대한 의존성을 정의하는 데 사용돼요. include 섹션에 나열된 각 경로는 상대 경로를 해석하기 위해 자체 프로젝트 디렉토리를 가진 개별 Compose 애플리케이션 모델로 로드돼요.

포함된 Compose 애플리케이션이 로드되면 모든 리소스 정의가 현재 Compose 애플리케이션 모델에 복사돼요. 리소스 이름이 충돌하면 Compose는 경고를 표시하고 병합하려 시도하지 않아요. 이를 강제하기 위해 include는 Compose 애플리케이션 모델을 정의하도록 선택된 Compose 파일들이 파싱·병합된 후에 평가돼, Compose 파일 간 충돌이 감지돼요.

include는 재귀적으로 적용돼, 자체 include 섹션을 선언하는 포함된 Compose 파일이 다른 파일들도 포함하게 돼요.

포함된 Compose 파일에서 끌어온 볼륨·네트워크·기타 리소스는 현재 Compose 애플리케이션이 서비스 간 참조에 사용할 수 있어요. 예:

include:
  - my-compose-include.yaml  #serviceB 선언됨
services:
  serviceA:
    build: .
    depends_on:
      - serviceB # 이 Compose 파일에 선언된 것처럼 serviceB를 직접 사용

Compose는 include와 함께 보간된 변수도 지원해요. 필수 변수를 지정하는 것이 좋아요. 예:

include:
  - ${INCLUDE_PATH:?FOO}/compose.yaml

짧은 문법 (Short syntax)

짧은 문법은 다른 Compose 파일의 경로만 정의해요. 파일은 부모 폴더를 프로젝트 디렉토리로, 보간으로 변수 기본값을 정의하려고 선택적 .env 파일을 로드해요. 로컬 프로젝트의 환경은 그 값을 오버라이드할 수 있어요.

include:
  - ../commons/compose.yaml
  - ../another_domain/compose.yaml

services:
  webapp:
    depends_on:
      - included-service # another_domain이 정의

위 예제에서 ../commons/compose.yaml과 ../another_domain/compose.yaml 둘 다 개별 Compose 프로젝트로 로드돼요. include가 참조하는 Compose 파일의 상대 경로는 로컬 프로젝트 디렉토리가 아니라 자체 Compose 파일 경로를 기준으로 해석돼요. 변수는 같은 폴더의 선택적 .env 파일에 설정된 값으로 보간되고 로컬 프로젝트의 환경으로 오버라이드돼요.

긴 문법 (Long syntax)

긴 문법은 하위 프로젝트 파싱에 대한 더 많은 제어를 제공해요:

include:
   - path: ../commons/compose.yaml
     project_directory: ..
     env_file: ../another/.env

path

path는 필수이며 로컬 Compose 모델로 파싱·포함될 Compose 파일의 위치를 정의해요.

path는 다음과 같이 설정할 수 있어요:

문자열(단일 Compose 파일) 일 때.
문자열 목록(로컬 애플리케이션의 Compose 모델 정의를 위해 여러 Compose 파일을 병합해야 할 때).

include:
   - path:
       - ../commons/compose.yaml
       - ./commons-override.yaml

project_directory

project_directory는 Compose 파일에 설정된 상대 경로를 해석할 기본 경로를 정의해요. 기본값은 포함된 Compose 파일의 디렉토리예요.

env_file

env_file은 파싱 중인 Compose 파일에서 변수를 보간할 때 기본값을 정의할 환경 파일을 정의해요. 기본값은 파싱 중인 Compose 파일의 project_directory에 있는 .env 파일이에요.

env_file은 프로젝트 환경을 정의하기 위해 여러 환경 파일을 병합해야 할 때 문자열 또는 문자열 목록으로 설정할 수 있어요.

include:
   - path: ../another/compose.yaml
     env_file:
       - ../another/.env
       - ../another/dev.env

로컬 프로젝트의 환경은 Compose 파일이 설정한 값보다 우선하므로, 로컬 프로젝트가 커스터마이징을 위해 값을 오버라이드할 수 있어요.

추가 리소스 (Additional resources)

include 사용에 대한 자세한 내용은 "Working with multiple Compose files" 를 참고해요.

더 알아보기 (Learn more)

여러 Compose 파일 작업 가이드를 참고해요.