Docker Compose v5.6.0 적용: jobs와 provider relay 점검

jobs는 실행 방식부터 구분한다

Docker Compose v5.6.0에 jobs 지원이 추가됐지만 예약 실행은 아직 지원하지 않는다. 작업을 jobs로 옮길지 판단할 때 먼저 확인할 것은 실행 시점을 누가 결정하는가다. 수동 트리거로 충분한 작업과 스케줄에 따라 실행해야 하는 작업은 이번 릴리스에서 적용 가능성이 다르다.

이 글의 버전 기준은 docker/compose v5.6.0 (2026-10-02), 직전 v5.5.1이다. 공식 릴리스 노트는 수동으로 트리거한 jobs만 지원하며, 전체 지원은 해당 Docker Engine 지원이 병합된 뒤 제공될 예정이라고 명시한다. 예약 실행의 제공 시점은 이 자료에 없다.

로컬·CI 개발환경에서는 기존 작업의 실행 조건을 먼저 적어 두자. 사람이 필요할 때 시작하는 작업이라면 수동 트리거 지원 범위에서 도입을 검토할 수 있다. 예약 실행 자체가 요구사항이라면 jobs 추가만으로 그 요구가 충족됐다고 판단하면 안 된다. CI에서 사용한다는 이유만으로 예약 jobs가 되는 것도 아니다. 판단 기준은 환경 이름이 아니라 필요한 트리거 방식이다.

다음 그림은 작업의 실행 조건에 따라 이번 릴리스에서 도입을 검토할 수 있는 범위를 나눈다.

⤢✕

릴리스에는 compose-go의 jobs와 container-spec layering 채택도 포함됐다. 다만 제공된 자료에는 jobs 정의나 실행 명령 예제가 없다. 지원 사실을 근거로 설정 구문까지 추정해 기존 Compose 파일에 넣기보다, 먼저 수동 트리거만으로 충분한 작업을 적용 후보로 좁히는 편이 맞다.

provider는 relay와 이미지 경로를 함께 확인한다

provider 서비스를 사용하는 스택은 endpoint 접근과 이미지 처리 양쪽을 검증 대상으로 잡아야 한다. 이번 변경에는 get-service-config provider 요청이 추가됐고, publish-endpoint는 provider 서비스를 위한 network relay를 배포한다. get-relay-info는 provider가 relay를 위해 어디에 바인딩해야 하는지 알려준다. provider relay 연결에는 전용 네트워크도 추가됐다.

여기에 provider 서비스가 이미지 단계에 참여하고, 필요에 따라 이미지가 배포되는 변화가 함께 들어왔다. 따라서 provider를 사용하는 개발환경에서는 endpoint가 접근 가능한지만 확인하고 검증을 끝내기 어렵다. 스택에서 실제로 사용하는 이미지 배포 경로도 확인 대상이다.

아래 도식은 provider 서비스 주변의 변경을 설정 요청, endpoint 연결, 이미지 처리로 나눠 검증 경계를 보여 준다.

⤢✕

새로 추가된 기능과 함께 relay 수명주기 수정도 살펴야 한다. 릴리스에는 경로가 바뀌지 않아도 새 네트워크에 다시 연결하는 수정, 오래된 relay 정리와 이에 대한 start/restart 보호, provider 마이그레이션 시 오래된 서비스 replica를 처리하는 수정이 들어 있다.

기존 provider 스택을 업그레이드한다면 평소 사용 경로에 해당하는 검증을 골라야 한다.

변경 영역	해당하는 환경	확인할 내용
설정 요청	provider 설정을 받는 환경	get-service-config 요청이 필요한 경로의 결과
endpoint relay	provider endpoint를 사용하는 환경	relay 배포와 endpoint 접근 결과
relay 네트워크	네트워크를 새로 연결하는 환경	경로가 동일한 경우에도 새 네트워크 연결이 반영되는지
오래된 relay	start/restart를 반복하는 환경	오래된 relay가 후속 시작이나 재시작을 방해하는지
이미지 단계	provider 이미지 배포를 사용하는 환경	필요한 이미지 배포가 수행되는지
provider 마이그레이션	provider 전환을 수행하는 환경	오래된 서비스 replica의 처리 결과

이 표는 검증 후보이지 모든 스택에 필요한 절차는 아니다. provider 마이그레이션을 사용하지 않는 환경이라면 그 경로보다 실제 endpoint 연결과 start/restart 동작을 먼저 확인하면 된다. 릴리스 노트에는 relay의 상세 네트워크 구성이나 요청·응답 형식이 없으므로 그 부분을 임의로 설정 예제로 만들지는 않는다.

미지원 속성 경고를 설정 검토에 연결한다

v5.6.0은 지원하지 않는 Compose 파일 속성에 대한 경고를 추가했다. 기존 파일을 그대로 사용하는 팀도 업그레이드 후 출력에서 이 경고를 확인해야 한다. 파일에 적힌 속성과 현재 Compose가 지원하는 속성을 구분하는 데 쓸 수 있는 신호이기 때문이다.

경고가 나오면 해당 속성이 어떤 요구를 위해 들어갔는지부터 대조하자. 개발환경의 동작이 그 속성에 의존한다면, 경고를 남겨 둔 채 실행 결과만 보고 요구가 충족됐다고 판단하기 어렵다. 제공된 자료는 경고 추가를 설명하며, 각 속성의 처리 방식이나 실행 실패 여부까지 설명하지는 않는다.

x-initialSync를 사용하는 파일도 별도로 확인할 대상이다. 수정 목록에는 compose-go v2.16.1이 x-initialSync를 조용히 승격하는 변화에 대한 대응이 포함돼 있다. 이것이 미지원 속성 경고와 같은 동작이라고 묶어 해석할 근거는 없다. 해당 속성을 쓰는 스택에서 실제 동기화 동작을 확인하는 검증 항목으로 두면 된다.

watch는 파일 변경이 몰릴 때 검증한다

watch 수정의 핵심은 짧은 시간에 파일 변경이 몰려 발생한 재빌드를 병합하는 것이다. 한 파일을 한 번 저장하는 확인만으로는 이 변경이 겨냥한 상황을 재현하기 어렵다.

로컬 개발환경에서 watch를 사용한다면 평소 여러 파일이 함께 바뀌는 작업으로 확인하자. 검증에서는 재빌드 요청이 어떻게 처리되는지와 최종 변경 내용이 반영되는지를 함께 본다. 릴리스 노트에는 병합 시간이나 재빌드 횟수가 없으므로, 특정 시간 안의 변경이 반드시 한 번의 빌드로 끝난다는 기준을 만들면 안 된다.

빌드 출력 문제를 추적하던 환경에는 별도 수정도 있다. 해석되지 않은 auto progress mode를 bake로 넘기는 동작이 수정됐다. watch의 재빌드 병합과 빌드 진행 출력은 확인 대상이 다르므로, 기존 문제가 어느 경로에서 발생했는지에 따라 검증을 나눠야 한다.

CI는 dry-run과 이미지 정리의 결과를 본다

dry-run을 사전 검증에 사용하는 CI라면 실제 부수효과가 남는지 확인해야 한다. 이번 릴리스는 dry-run의 commit이 실제 이미지를 만들지 않도록 수정했다. 성공 메시지만 확인하기보다 해당 경로를 실행한 뒤 실제 이미지 생성 여부를 보는 검증이 이 수정의 목적에 맞는다.

dry-run에서 서비스가 성공적으로 완료되는 경우에 대한 수정도 포함됐다. 다만 자료에는 세부 재현 조건이 없으므로 모든 완료 상태의 처리 방식이 달라졌다고 확대해서 쓰지는 않는다. 기존에 이 경로를 쓰는 CI라면 완료 결과가 기대대로 보고되는지 확인할 대상으로 삼으면 된다.

이미지 정리에서는 down --rmi의 dangling 이미지 관련 수정이 들어왔다. 이 옵션으로 정리하는 CI는 명령의 종료 여부와 함께 정리 후 이미지 상태를 확인해야 한다. 릴리스 노트만으로 모든 이미지가 삭제된다거나 특정 옵션 값의 동작까지 바뀌었다고 단정할 수는 없다.

병렬 처리와 이미지 publish 경로도 사용하는 경우에만 검증 범위에 넣자.

CI 경로	릴리스에 명시된 변화	검증 관점
dry-run의 commit	실제 이미지를 만들지 않도록 수정	실행 후 실제 이미지 생성 여부
dry-run의 서비스 완료	성공적으로 완료되는 서비스 관련 수정	기존 완료 경로의 결과 보고
down --rmi	dangling 이미지 관련 수정	정리 후 이미지 상태
bulk Engine 호출	모든 fan-out에서 --parallel 준수	기존 병렬 제한을 쓰는 호출 경로
이미지 publish	OCI 1.1에서 OCI 1.0으로 push가 폴백할 때 경고	해당 경고의 출력 여부

OCI 폴백 경고는 CI 로그를 읽을 때 구분해 둘 신호다. 이번 변경은 폴백 시 경고를 추가한다는 내용이며, 폴백 자체를 제거한다는 내용은 아니다.

포트 조회와 실행 관찰 경로를 점검한다

포트 조회에는 PRIVATE_PORT가 선택 사항이 되는 변경이 있다. 자료에 명시된 명령은 다음과 같다.

docker compose port

이 명령을 사용하는 스크립트가 있다면 PRIVATE_PORT 지정 여부에 따라 사용하는 경로의 출력과 후속 처리를 확인하자. 제공된 자료에는 전체 호출 예제나 생략 시 출력 형식이 없으므로, 새 출력 구조를 가정해 스크립트를 바꾸는 것은 피해야 한다.

dual-stack port publisher의 동률 순서를 유지하는 수정도 포함됐다. 포트 출력의 순서를 소비하는 코드가 있다면 결과를 비교할 이유가 있다. 다만 이 수정이 모든 포트 출력에 새로운 정렬 규칙을 부여한다는 뜻은 아니다.

실행 상태를 관찰하는 경로에는 서로 다른 수정이 들어왔다.

• up monitor가 외부에서 중지되거나 제거된 컨테이너를 감지하도록 수정됐다.
• 빠르게 실행이 끝나는 경우 재시작 후 로그 재연결에서 출력을 잃는 문제가 수정됐다.
• up의 최종 보고에서 무해한 context.Canceled 잡음이 제거됐다.

외부 컨테이너 조작을 사용하는 환경은 monitor의 감지를, 짧게 실행되는 작업의 로그를 읽는 환경은 출력 누락 여부를 확인하면 된다. 최종 보고의 잡음 제거는 로그 재연결 수정과 별개의 변화다. 오류 문자열이 줄었다는 사실만으로 로그 수집까지 검증됐다고 판단하면 안 된다.

업그레이드 검증은 사용하는 기능에 맞춘다

v5.6.0 적용 범위는 스택이 어떤 기능을 쓰는지에 따라 정하면 된다. jobs 도입 후보는 수동 트리거로 충분한 작업으로 좁히고, provider 스택은 relay 연결과 이미지 경로를 확인한다. 기존 파일은 미지원 속성 경고를 검토하며, watch와 CI는 각각 파일 변경 집중 상황과 dry-run·이미지 정리 결과를 검증한다.

service config-hash의 바이트 레이아웃을 compose-go 구조체 리팩터링과 분리해 고정하는 수정도 포함됐다. 자료만으로 특정 서비스의 재생성 여부를 예측할 수는 없다. 구성 해시 변화와 관련된 문제를 추적하던 환경이라면 실제 결과를 비교할 근거로 사용하자.

검증 기록에는 사용한 기능, 재현한 상황, 관찰한 결과를 남기면 된다. 릴리스 노트에 적힌 수정 목록을 모두 실행하는 것보다, 자신의 스택이 의존하는 경로에서 기대한 결과가 나오는지 확인하는 편이 적용 여부를 판단하는 데 직접적이다.