Docker Compose 5.7.0 업그레이드: 단일 실행 계획과 API 대응

Docker Compose 5.7.0의 단일 실행 계획이 바꾸는 실패 시점과 라이브러리 API 호환성을 점검하고 신규 CLI 옵션의 적용 범위를 판단한다.

2026-11-12

CLI 사용자와 라이브러리 사용자의 점검 범위가 다르다

api.Compose.Up을 직접 호출하는 프로그램은 업그레이드 후 기존 옵션 조합에서 오류를 받을 수 있다. 이전에는 조용히 무시되던 조합을 이제 실행 전에 검증하기 때문이다.

이 글의 기준은 **Docker Compose 5.7.0 (2026-11-02)**이다. 공식 릴리스노트는 CLI가 이전처럼 동작한다고 명시하면서, Compose를 라이브러리로 사용하는 코드에는 별도의 변경 안내를 제공한다.

핵심은 Up의 Create와 Start가 하나의 daemon 스냅샷을 사용하는 단일 실행 계획으로 묶였다는 점이다. 이 변경은 분리 모드의 up -d와 대화형 up에 적용됐다. scale, watch 재빌드, start도 통합된 실행 계획을 사용하며, start는 시작 작업만 담은 계획을 만든다.

아래 흐름은 Up에서 계획 수립과 실제 컨테이너 생성의 경계가 어디에 놓이는지 보여 준다.

⤢✕있음없음Up 호출옵션 검증단일 daemon 스냅샷Create와 Start의 단일 실행계획Start 계획 오류컨테이너 생성 전 실패Create 실행Start 실행

CLI만 사용하는 환경이라면 신규 옵션과 관련 수정 사항을 중심으로 확인하면 된다. 라이브러리를 내장한 배포 도구라면 여기에 호출 인자, 오류 처리, 메뉴 구현, 공개 심벌 사용 여부까지 점검 범위를 넓혀야 한다.

실행 계획이 만들어진 뒤의 상태 변화로 검증한다

Create와 Start 사이에서 daemon을 다시 관찰하지 않는다는 점은 라이브러리 호출 테스트에 직접 영향을 준다. 단계 사이에 컨테이너 상태가 바뀌더라도 새 상태를 조회해 계획을 다시 정하는 동작을 기대해서는 안 된다.

릴리스노트가 명시한 동작은 다음과 같다.

상황 5.7.0의 동작 호출 코드에서 확인할 것
계획 수립 후 컨테이너가 종료됨 해당 컨테이너를 다시 시작하지 않음 종료 후 재시작을 기대하는 테스트가 있는지
단계 사이에 컨테이너가 제거됨 건너뛰지 않고 해당 컨테이너의 시작이 실패함 시작 실패를 호출자가 어떻게 처리하는지
Start 단계의 계획 수립에 오류가 있음 컨테이너를 만들기 전에 실패함 오류를 생성 이후의 실패로 가정하고 있는지

특히 컨테이너 제거 사례는 “대상이 없어졌으니 건너뛴다”는 기대와 다르다. 아래 순서는 계획에 포함된 대상이 실행 전에 사라졌을 때의 실패 지점을 보여 준다.

⤢✕외부 작업daemonUp외부 작업daemonUp단일 실행 계획 수립Create와 Start 사이 재조회 없음스냅샷 조회컨테이너 상태컨테이너 제거계획에 따른 컨테이너 시작시작 실패

라이브러리 래퍼의 검증은 정상적인 기동 성공에만 머물러서는 부족하다. 위 상태 변화에 대해 반환 결과와 후속 처리를 확인해야 한다. Start 계획 오류에서는 컨테이너 생성 전 실패를 기대하도록 테스트를 맞춘다.

프로젝트 전달 경로도 함께 확인한다. Up은 직접 전달받은 프로젝트를 사용하며 StartOptions.Project는 무시한다. 프로젝트를 후자에만 넣거나 서로 다른 프로젝트를 전달하던 코드는 실제로 어느 프로젝트를 실행하려 했는지부터 정리해야 한다.

무시되던 옵션 조합을 오류 처리 대상으로 옮긴다

Up은 실행에 앞서 CLI 플래그와 같은 규칙으로 옵션을 검증한다. UpOptions.Validate()는 호환되지 않는 조합에 *api.IncompatibleOptionsError를 반환한다.

대상은 Start.Wait와 Start.Attach의 조합, 그리고 Start.Attach가 없는 분리 실행에 OnExit, ExitCodeFrom, Watch를 결합한 경우다. 이 조합들은 이전에는 조용히 무시됐다.

아래 판단 흐름은 호출자가 실행 전에 걸러야 할 조합의 범위를 나타낸다.

⤢✕예아니요아니요예예아니요Up 옵션Start.Wait와 Start.Attach결합IncompatibleOptionsErrorStart.Attach 없음해당 비호환 조합에 해당하지않음OnExit 또는 ExitCodeFrom또는 Watch 지정

호출 코드에서 옵션을 조립하는 지점과 오류를 처리하는 지점을 함께 수정한다. 분리 실행을 선택한 뒤에도 종료 관련 옵션이나 Watch를 그대로 남겨 두는 코드라면, 이전에 문제가 드러나지 않았다는 이유로 유효한 조합이라고 판단할 수 없다.

오류 종류를 식별할 때 릴리스노트가 제시한 판별식은 다음과 같다.

errors.Is(err, api.ErrIncompatibleOptions)

이 판별 결과를 옵션 구성 오류 처리로 연결하고, 호환되지 않는 조합을 넣은 테스트에서 오류가 실제로 전달되는지 확인한다. 정상 조합의 성공 테스트만으로는 이번 변경을 검증할 수 없다.

메뉴와 공개 API는 컴파일 점검에서 함께 다룬다

대화형 up의 키보드 메뉴는 이제 라이브러리가 직접 구성하지 않는다. 라이브러리 사용자가 메뉴를 제공하려면 NavigationMenu: true를 설정하고, compose.WithNavigationMenu(...)로 구현도 전달해야 한다. 요구 조건이 충족되지 않으면 메뉴가 표시되지 않고 경고가 나온다.

기존 호출 코드가 메뉴 표시를 라이브러리 기본 동작으로 기대했다면, 옵션 설정과 구현 주입을 함께 확인한다. 컴파일이 통과해도 화면 동작은 별도로 검증해야 하는 지점이다.

다른 API 변경은 다음처럼 점검할 수 있다.

변경 대상 바뀐 계약 적용할 점검
DownOptions.Images api.ImagePruneMode 타입 사용 string 변수를 전달하는 곳에 타입 변환이 필요한지 확인
Down의 이미지 정리 값 잘못된 값은 제거 작업 전에 거부 잘못된 입력에서 제거 작업이 시작되지 않는지 검증
compose.ServiceHash, compose.NetworkHash, compose.VolumeHash 더 이상 공개되지 않음 해당 공개 함수에 의존하는 코드 검색
api.Compose 더 작은 인터페이스들로 구성되며 메서드 집합은 동일 메서드 집합 변경과 공개 심벌 제거를 구분해 오류 확인
PushOptions.IgnoreMissing 새 옵션 추가 로컬에 없는 이미지를 건너뛰려는 호출에 적용 검토

DownOptions.Images에 타입 없는 상수를 넣는 코드는 계속 컴파일되지만, string 변수에는 변환이 필요하다. 따라서 상수를 사용하는 테스트만 통과했다고 실제 설정값 전달 경로까지 검증됐다고 볼 수 없다.

공개 해시 헬퍼는 내부 패키지로 이동했다. 릴리스노트에는 외부 사용자를 위한 대체 공개 API가 제시돼 있지 않으므로, 여기서 임의의 대체 호출법을 정할 수는 없다. 해당 심벌을 사용하는 코드는 업그레이드 작업의 별도 호환성 항목으로 남겨 처리해야 한다.

신규 CLI 옵션은 자동화의 의도에 맞춰 적용한다

신규 옵션은 사용 중인 명령이 무엇을 허용해야 하는지 정한 뒤 적용한다. 기존 의존성을 그대로 재사용하려는 경우와 로컬 이미지가 없어도 push를 진행하려는 경우는 서로 다른 요구다.

명령·설정 릴리스노트에 명시된 변경 실무 적용 지점
run --no-recreate 기존 의존성을 그대로 재사용 의존성 재생성을 원하지 않는 실행
push --ignore-missing 로컬에 없는 이미지 건너뛰기 이미지 누락을 허용하는 push 작업
push --ignore-push-failures --ignore-missing을 권장하며 폐기 예정 처리 기존 스크립트의 실패 허용 의도 재검토
stats --all-projects, stats --aggregate 통계 조회 플래그 추가 통계 수집 명령의 조회 요구 검토
서비스의 umask 속성 서비스 속성 지원 추가 umask 설정이 필요한 서비스
--parallel과 bake 병렬 제한을 bake의 --jobs로 전달 bake를 사용하는 빌드의 병렬 제한 확인

특히 push 스크립트에서는 플래그 이름만 치환하지 않는다. 새 옵션에서 명시적으로 허용하는 것은 로컬에 없는 이미지의 건너뛰기다. 기존 스크립트가 어떤 실패를 허용하려 했는지 먼저 확인한 뒤 변경해야 한다.

자료에 제시된 명령·옵션 표기는 다음과 같다.

run --no-recreate
push --ignore-missing
stats --all-projects
stats --aggregate

stats의 출력 형식이나 집계 계산 방식, umask의 구체적인 설정 예시는 제공된 릴리스노트만으로 확정할 수 없다. 적용 검토 항목에는 넣되, 이 자료를 근거로 설정값이나 출력 파서를 새로 작성하지는 않는다.

서비스 설정에 해당하는 수정 사항을 회귀 검증에 넣는다

use_api_socket을 사용하는 서비스는 실행 경로에 따라 확인한다. 포그라운드 Up도 이제 up -d처럼 /run/secrets/docker/config.json을 제공하며, start로 시작한 서비스에 설정 파일을 제공하는 수정도 포함됐다. 별도로 서비스에 전달하는 자격증명 강화가 명시돼 있지만, 구체적인 강화 방식은 이 자료에 없다.

따라서 검증 항목은 사용하는 실행 경로에서 설정 파일이 제공되는지 확인하는 수준으로 잡는다. 릴리스노트의 “강화”라는 표현만으로 특정 유출 경로나 공격 방어 효과를 단정하지 않는다.

훅을 사용하는 서비스라면 pre_start도 확인한다. 이번 릴리스에서는 훅이 서비스의 env_file과 environment를 전달받도록 수정됐고, 포그라운드 Up에서 훅 출력이 표시된다. 훅이 이 환경값을 사용하거나 출력으로 실행 결과를 확인하는 구성이라면 검증 대상이다.

그 밖에는 실제 사용 기능에 맞춰 회귀 검증을 고른다.

  • watch 사용 환경: bind mount 경로에서 sync+exec 트리거를 건너뛰는 수정과 감시 경로 안의 모든 깊이에서 .git을 무시하는 변경을 확인한다.
  • 로그 수집 환경: 재시작된 컨테이너의 각 로그 줄을 정확히 한 번 전달하는 수정에 맞춰 중복 전달 여부를 확인한다.
  • 볼륨을 다루는 환경: run이 재생성한 의존성의 익명 볼륨을 유지하는지, down -v가 프로젝트 소유가 아닌 볼륨을 남기는지 확인한다.
  • 붙여서 실행하는 up 환경: 애플리케이션을 중지할 때 -t가 반영되는지 확인한다.

업그레이드 완료 기준은 사용 방식에 맞춰 잡는다. CLI 사용자는 실제 명령과 서비스 설정에 해당하는 동작을 검증한다. 라이브러리 사용자는 여기에 비호환 옵션 오류, 계획 이후 상태 변화, 프로젝트 전달, 메뉴 표시, 타입 변경과 제거된 공개 심벌까지 확인해야 한다. 컴파일 검사와 실행 검증이 각각 다른 변경 지점을 잡아내는 릴리스다.

DockerDocker Compose라이브러리 API배포호환성