Docker Compose jobs 사용법: 예약 작업과 일회성 작업 설정 가이드

Docker Compose 5.8 jobs 사용법: 예약 작업과 일회성 작업 설정의 출발점은 Compose 파일의 최상위 jobs: 요소다. 실행을 마치면 종료되는 컨테이너를 여기에 선언하고, triggers에 manual(수동 실행) 또는 schedule(cron 예약)을 지정한다. 일회성 작업의 실행 명령은 docker compose run <job>이다. 예약 작업은 docker compose up이 엔진에 등록하고, 이후 실행 시점은 엔진이 자체 시계로 정한다.

예약 실행에는 Compose v5.8.0 이상과 jobs 확장을 켠 Docker Engine 29.10.0 이상이 함께 필요하다. 확장은 기본으로 꺼져 있어서, 엔진 설정을 바꾸지 않으면 예약 작업이 있는 프로젝트는 up 단계에서 거부된다. 아래 절차와 설정값은 2026-11-18 기준 Docker 공식 문서와 Compose 릴리스 노트에 근거한다.

목차

Docker Compose 5.8 jobs 적용 대상과 사전 조건

Compose 파일 jobs 레퍼런스는 최상위 jobs를 데이터베이스 마이그레이션이나 백업처럼 완료될 때까지 실행되는 컨테이너를 선언하는 요소로 정의한다. 계속 떠 있는 서비스가 아니라 한 번 돌고 끝나는 작업 단위가 대상이다. 실행 방식은 필요할 때 직접 실행하는 수동 작업과 cron 식에 따라 반복되는 예약 작업으로 나뉜다.

지원 범위는 Compose 버전에 따라 다르다. Compose v5.6.0 릴리스 노트는 jobs를 부분 지원으로 소개했고, 당시에는 수동으로 실행하는 job만 쓸 수 있었다. 예약 job은 Compose v5.8.0 릴리스에서 추가됐다.

시작 전 점검 항목은 네 가지다.

  • Compose 버전: 예약 작업까지 쓰려면 v5.8.0 이상
  • Docker Engine 버전: 29.10.0 이상(API 버전 1.57)
  • 엔진 확장: org.mobyproject.jobs.v0 활성화가 필요하며 기본값은 꺼짐
  • 호스트 권한: dockerd 실행 옵션이나 daemon.json을 고치고 데몬을 재시작할 수 있어야 함
실험적 기능
Docker Engine 문서는 jobs를 실험적 기능으로 분류하고, 릴리스 사이에 동작이 바뀔 수 있다고 경고한다. 엔진이나 Compose를 올린 뒤에는 여기서 쓴 설정 키와 명령 동작을 공식 문서에서 다시 대조해야 한다.
## Engine에서 jobs 확장(org.mobyproject.jobs.v0) 켜기
engine-extension-toggle-blueprint

Docker Engine jobs 관리 문서는 확장을 켜는 경로로 두 가지를 제시한다. 데몬을 직접 띄우는 환경이라면 dockerd --extension-enable org.mobyproject.jobs.v0처럼 플래그를 붙인다. 설정 파일로 관리한다면 daemon.json의 extensions.enable 목록에 확장 이름을 넣는다.

{
  "extensions": {
    "enable": ["org.mobyproject.jobs.v0"]
  }
}

목록을 수정했으면 데몬을 재시작한다. 문서 원문도 "Restart the daemon after you change the list."라고 적고 있다.

엔진 문서가 안내하는 활성화 확인 방법은 예약 job을 선언한 프로젝트에서 docker compose up 또는 docker compose create를 실행해 보는 것이다. 판정 기준은 뒤의 ‘등록과 실행 결과 확인’ 절에 정리했다.

Compose jobs 선언: triggers의 manual과 schedule

triggers-manual-schedule-blueprint

job 이름에는 문자, 숫자, ., _, -만 들어갈 수 있고, 같은 파일의 서비스 이름과 같아서는 안 된다. triggers는 job이 언제 실행되는지 정하는 필수 항목이다. 그 안에 manual이나 schedule 중 하나는 반드시 설정해야 한다.

레퍼런스 문서의 예시는 수동 job과 예약 job을 하나씩 선언한다.

jobs:
  migrate:
    image: example/migrations
    triggers:
      manual: true

  sync:
    image: example/sync
    triggers:
      schedule:
        - cron: "*/5 * * * *"
          concurrency: queue
          missed_fires: skip

migrate는 명령으로 호출할 때만 도는 일회성 job이다. 반면 sync는 5분 간격으로 엔진이 실행하도록 등록되는 예약 job이다.

일회성 작업: manual 트리거

triggers.manual은 docker compose run으로 job을 시작할 수 있는지 정하는 boolean이다. 값을 생략하면 수동 시작이 허용되며, 이것이 기본값이다. 마이그레이션처럼 사람이 시점을 정하는 작업이라면 migrate처럼 manual: true만 두면 된다.

한 job에 manual: true와 schedule을 함께 쓰면 Compose가 거부한다. 예약 job의 수동 실행을 막고 싶을 때는 반대로 manual: false를 명시한다. 레퍼런스의 rotate-logs 예시가 그 조합으로, schedule에 "0 0 1 * *"를 두고 manual: false를 함께 설정했다. 이런 job에 docker compose run을 실행하면 실패한다.

manual을 생략한 예약 job은 수동 실행도 받는다. 이때의 수동 실행은 일정과 별개인 추가 실행이어서, 다음 예약 시각은 그대로 유지된다.

예약 작업: cron, timezone, concurrency, missed_fires

schedule은 YAML 목록 형식이지만 Compose가 지원하는 항목 수는 job마다 하나다. 짧은 문법은 - "*/10 * * * *"처럼 cron 문자열만 적는다. 긴 문법은 - cron: "*/10 * * * *"처럼 cron 키를 붙이며, 옵션을 함께 지정한 sync 예시도 긴 문법으로 작성됐다.

cron 식은 분, 시, 일, 월, 요일 순서의 5필드로 구성된다. 각 필드에는 숫자, 목록(1,15), 범위(1-5), 간격(*/10, 0-30/10)이 들어갈 수 있다. mon, jan 같은 이름과 @daily 같은 단축 표기는 지원 대상이 아니므로, 매일 한 번 돌리려면 "0 3 * * *"처럼 숫자로 풀어 쓴다.

시간대는 timezone에 IANA 시간대 이름으로 적는다. 생략하면 UTC가 기준이다.

실행이 겹치거나 시각을 놓쳤을 때의 처리는 두 키가 맡는다.

키 값 동작
concurrency forbid (기본값) 새 실행을 건너뛴다
concurrency queue 현재 실행이 끝나기를 기다린다
missed_fires one (기본값) 보충 실행을 한 번 한다
missed_fires skip 놓친 실행을 버린다

sync는 queue와 skip을 골랐다. 앞선 실행이 끝나지 않았으면 기다렸다가 실행하고, 놓친 회차는 보충하지 않는 구성이다.

cron 식 검사 시점
Docker Engine은 `docker compose up`이 job을 등록할 때 cron 식을 해석한다. 그래서 잘못된 식은 등록 단계에서 실패한다. `timezone`을 생략한 `”0 3 * * *”`는 UTC 3시 기준이라는 점도 등록 전에 확인할 대상이다.
## up·run·down으로 jobs 등록·실행·제거하기

v5.8.0 릴리스 노트가 정리한 명령별 역할은 분명하다. up(또는 create)은 예약 job을 엔진에 등록하고, 등록 후 실행은 엔진이 자체 시계에 맞춰 수행한다. run은 job을 즉시 실행하며, down은 등록된 job을 제거한다.

# 예약 job(sync)을 엔진에 등록한다. create도 같은 등록을 수행한다
docker compose up

# 수동 job(migrate)을 즉시 실행한다. 의존 대상이 먼저 시작된다
docker compose run migrate

# 엔진에 등록된 예약 job을 제거한다
docker compose down

docker compose run migrate는 job이 의존하는 서비스와 job을 먼저 시작한 다음 migrate를 실행한다. 로그는 터미널로 스트리밍되고, 컨테이너의 종료 코드가 명령의 결과로 돌아온다. 배포 스크립트에서 마이그레이션 성패를 가를 때 이 종료 코드가 판단 기준이 된다.

이미 등록된 job의 정의를 바꾸는 경우, 엔진 문서는 기존 job을 제거한 뒤 다시 등록하라고 안내한다. Compose 명령에 대응시키면 제거는 down, 재등록은 up이 담당한다.

down 동작의 근거 범위
확장이 켜진 엔진에서 `down`이 예약 job을 제거한다는 설명은 v5.8.0 릴리스 노트에 있다. Engine 문서에서 확인되는 것은 확장이 꺼져 있을 때 `docker compose down`이 jobs를 무시한다는 문장이다.
## 등록과 실행 결과 확인

확장 활성화 여부. 예약 job을 선언한 프로젝트에서 docker compose up 또는 docker compose create를 실행한다. 확장이 꺼져 있으면 예약 job에는 jobs 확장이 필요하다는 오류가 나면서 명령이 실패한다. 이 오류 없이 등록이 끝났다면 엔진 쪽 준비는 된 상태로 본다.

job 컨테이너 조회. job 실행으로 생성된 컨테이너에는 com.docker.job.id와 com.docker.job.run-id 라벨이 붙는다. 종료된 컨테이너까지 포함해 찾으려면 docker ps --all --filter label=com.docker.job.id를 쓴다. 5분 주기 sync처럼 짧은 간격의 job은 등록 후 첫 주기가 지난 시점에 이 명령으로 컨테이너가 생겼는지 보면 된다.

실행 상태 값. 엔진이 job 실행에 부여하는 상태는 pending, running, succeeded, failed, timed_out, cancelled 중 하나다. 엔진은 기본적으로 job마다 실행 기록을 최대 10 000개까지 보관한다.

수동 실행 결과. docker compose run은 로그를 스트리밍하고 종료 코드를 반환하므로, 수동 job은 터미널 출력과 종료 코드만으로 성공 여부를 가린다. 예외가 하나 있다. 다른 job의 의존 대상으로 함께 실행된 job은 일반 컨테이너로 돌기 때문에 실행 기록이 남지 않는다.

예약 실행의 제약: depends_on, 지원하지 않는 속성, profiles

depends_on은 예약 실행에서 평가되지 않는다

v5.8.0 릴리스 노트의 백업 예시는 서비스 db와 예약 job backup을 함께 선언한다.

services:
  db:
    image: postgres
jobs:
  backup:
    image: backup-tool
    depends_on: [db]
    triggers:
      schedule:
        - cron: "0 3 * * *"

backup에는 depends_on: [db]가 있지만, Docker Engine은 예약 job을 시작할 때 depends_on을 평가하지 않는다. 의존 대상을 먼저 시작하는 동작은 docker compose run backup처럼 Compose가 직접 실행할 때만 일어난다. 따라서 수동 실행으로 테스트했을 때 정상이었다고 해서 예약 실행에서도 같은 순서가 보장되지는 않는다.

예약 job의 의존 관계
예약 실행 경로에서는 `depends_on`이 쓰이지 않으므로, 예약 job이 접근하는 서비스의 기동 상태는 `depends_on`과 별도로 관리해야 한다. 수동 실행 테스트 결과를 그대로 예약 실행의 근거로 삼으면 안 된다.
의존 관계 규칙은 이 밖에도 있다. job은 서비스와 다른 job 모두에 `depends_on`을 걸 수 있다. 반면 서비스는 job에 `depends_on`을 걸 수 없다.

쓸 수 없는 속성과 profiles 동작

job에서 지원하지 않는 속성은 deploy, scale, restart, post_start, pre_start, pre_stop, container_name, attach, develop, extends, provider, links, external_links다. 서비스 정의를 job으로 옮겨 올 때 이 키가 남아 있지 않은지 먼저 확인한다.

profiles가 지정된 job은 해당 profile 중 하나가 활성일 때만 동작한다. 다만 docker compose run으로 그 job을 직접 지정하면 Compose가 profile을 활성화해 실행한다.

Docker Compose jobs를 지원하지 않는 엔진에서의 동작

확장이 꺼져 있거나 jobs를 지원하지 않는 엔진에서도 모든 명령이 막히지는 않는다. docker compose up, create, start가 거부하는 대상은 예약 job을 선언한 프로젝트뿐이다. 릴리스 노트에 따르면 이 거부는 리소스를 하나도 만들기 전에 일어난다.

docker compose run <job>은 경고를 출력한 뒤 해당 job을 일회성 서비스로 대신 실행한다. 이 경우 job 실행 기록이 아니라 일반 일회성 컨테이너로 처리된다는 차이가 있다. docker compose down은 jobs를 무시한다.

수동 job과 예약 job 설정 요약과 이어서 볼 주제

일회성 작업만 필요하다면 구성은 단순하다. triggers.manual: true로 선언하고 docker compose run <job>으로 실행한 뒤, 스트리밍된 로그와 종료 코드로 결과를 판단한다. jobs 확장이 꺼진 엔진에서도 run은 경고와 함께 일회성 서비스로 실행되므로 동작 자체는 막히지 않는다.

예약 작업은 준비 조건이 더 많다. Compose v5.8.0 이상, Docker Engine 29.10.0 이상, org.mobyproject.jobs.v0 확장 활성화와 데몬 재시작이 모두 갖춰져야 up이 job을 등록한다. YAML에서는 job당 schedule 항목 하나, 숫자로 쓴 5필드 cron, UTC 기본 시간대, forbid·one 기본값을 전제로 설정을 짠다. 그리고 예약 실행에서는 depends_on이 평가되지 않는다는 점을 설계 단계에서 반영해야 한다.

docker compose cron 구성을 운영에 올린 뒤 이어지는 주제는 세 갈래다. docker compose 마이그레이션 job을 배포 파이프라인의 종료 코드 판정에 연결하는 방법, daemon.json으로 docker engine 29.10 jobs 확장을 호스트별로 관리하고 재시작 시점을 정하는 절차, 그리고 profiles로 compose triggers schedule job의 활성 범위를 환경별로 나누는 구성이 그것이다. jobs가 실험적 기능인 만큼, 각 주제를 적용하기 전에 Compose 파일 jobs 레퍼런스의 변경 여부를 함께 확인하는 것이 전제다.

관련 글

이 글 공유하기