Docker Bake

Docker Buildx Bake는 HCL, JSON 또는 Compose YAML 정의 파일에서 여러 image build target을 선언하고 병렬 실행하는 고수준 build 명령이다.

• 하나의 Bake 파일에서 build target, target group, variable, 공통 설정 상속과 multi-platform output을 관리한다.
• 반복되는 긴 docker buildx build 명령을 선언형 build workflow로 옮길 때 적합하다.
• 공식 명령은 docker buildx bake이며, 현재 Docker CLI의 docker bake는 같은 Buildx Bake 명령으로 연결된다.

docker buildx bake [OPTIONS] [TARGET...]
docker bake [OPTIONS] [TARGET...]

• docker buildx bake [OPTIONS] [TARGET…]: Bake 정의를 읽어 지정 target 또는 default group을 build
  • -f, –file FILE: HCL, JSON 또는 Compose build 정의 파일 지정. 반복하면 여러 파일을 병합
  • –list targets|variables: target 또는 variable 목록과 설명 출력
  • –print: build 없이 병합·해석된 JSON 정의 출력
  • –call build|check|outline|targets: frontend 평가 방식 선택
    • build: 실제 build 실행
    • check: build check 실행
    • outline: target의 build argument와 default 출력
    • targets: target과 설명 출력
  • –check: –call=check 단축형
  • –set TARGET_PATTERN.KEY=VALUE: target 속성을 CLI에서 override. 반복 가능
  • –var NAME=VALUE: Bake variable 값 지정
  • –load: 조건에 맞는 build 결과를 local Docker image store로 load
  • –push: 조건에 맞는 image output을 registry로 push
  • –no-cache: build cache를 사용하지 않음
  • –pull: 참조 image의 최신 version을 항상 pull 시도
  • –progress auto|none|plain|quiet|rawjson|tty: 진행 출력 형식
  • –builder NAME: 사용할 builder instance 지정
  • -D, –debug: debug logging 활성화
  • –allow ENTITLEMENT[=VALUE]: filesystem, host network 또는 insecure security entitlement 허용
  • –metadata-file FILE: target별 build 결과 metadata를 파일로 기록
  • –policy OPTIONS: global build policy 평가 option
  • –provenance OPTIONS: provenance attestation 설정
  • –sbom OPTIONS: SBOM attestation 설정
• docker bake [OPTIONS] [TARGET…]: 현재 Docker CLI가 제공하는 동일 명령의 단축 진입점
• docker buildx f [OPTIONS] [TARGET…]: Buildx가 제공하는 짧은 alias

Docker Desktop에는 Buildx와 BuildKit이 포함된다. Docker Engine과 Docker CLI를 Docker 공식 repository에서 관리하는 Linux 환경은 docker-buildx-plugin package를 설치한다.

# Debian / Ubuntu
sudo apt-get update
sudo apt-get install docker-buildx-plugin
 
# RHEL / Fedora
sudo dnf install docker-buildx-plugin
 
# 설치 확인
docker buildx version
docker buildx bake --help

• macOS: Docker Desktop for Mac에 Buildx가 포함된다.
• Windows: Docker Desktop for Windows에 Buildx가 포함된다.

Bake 정의는 HCL, JSON, Compose YAML 형식을 지원한다. HCL은 variable, function 등 Bake 전용 기능을 온전히 사용할 수 있는 기본 작성 형식이다.

-f 또는 –file을 생략하면 현재 directory에서 다음 순서로 파일을 찾고, 발견된 파일을 순서대로 병합한다.

1. compose.yaml
2. compose.yml
3. docker-compose.yml
4. docker-compose.yaml
5. docker-bake.json
6. docker-bake.hcl
7. docker-bake.override.json
8. docker-bake.override.hcl

뒤에서 읽은 정의가 앞의 정의를 확장한다. target.tags, target.platforms, target.output, target.dockerfile, target.dockerfile-inline, target.pull, target.target, target.cache-to처럼 교체 대상인 속성은 마지막 정의가 우선한다.

• target "NAME" { … }: 하나의 docker build 실행에 대응하는 build target
  • 자주 쓰는 속성: context, dockerfile, target, args, tags, platforms, output
  • cache와 supply-chain 속성: cache-from, cache-to, attest, secret, ssh
  • 재사용과 변형: inherits, matrix, name
• group "NAME" { targets = […] }: 여러 target을 한 번에 실행하는 group
  • default group은 CLI에서 target을 생략했을 때 실행된다.
  • 같은 이름의 group과 target이 존재하면 group이 우선한다.
• variable "NAME" { … }: default, type, description을 갖는 HCL variable
  • 같은 이름의 environment variable 또는 –var NAME=VALUE로 값을 바꿀 수 있다.
• function "NAME" { … }: HCL expression에서 반복 계산을 재사용하는 custom function

variable "REGISTRY" {
  type        = string
  default     = "registry.example.com/team"
  description = "Image registry and namespace"
}
 
variable "TAG" {
  type        = string
  default     = "dev"
  description = "Image tag"
}
 
target "_common" {
  context    = "."
  dockerfile = "Dockerfile"
  pull       = true
}
 
target "app" {
  inherits  = ["_common"]
  target    = "runtime"
  tags      = [format("%s/app:%s", REGISTRY, TAG)]
  platforms = ["linux/amd64", "linux/arm64"]
}
 
target "worker" {
  inherits = ["_common"]
  target   = "worker"
  tags     = [format("%s/worker:%s", REGISTRY, TAG)]
}
 
group "default" {
  targets = ["app", "worker"]
}

공통 target을 먼저 정의하고 inherits로 재사용한다. 여러 parent를 지정하면 목록에서 뒤에 있는 parent의 충돌 값이 우선한다.

target "_release" {
  pull = true
  attest = [
    "type=provenance,mode=max",
    "type=sbom"
  ]
}
 
target "app-release" {
  inherits  = ["app", "_release"]
  tags      = ["registry.example.com/team/app:latest"]
  platforms = ["linux/amd64", "linux/arm64"]
}

matrix는 하나의 target 정의에서 여러 variant를 만든다. 생성되는 각 target의 이름은 name으로 고유하게 지정한다.

target "app" {
  name = "app-${platform}"
 
  matrix = {
    platform = ["amd64", "arm64"]
  }
 
  platforms = ["linux/${platform}"]
  tags      = ["registry.example.com/team/app:${platform}"]
}

기존 compose.yaml의 service build 속성도 Bake target으로 사용할 수 있다.

services:
  app:
    image: registry.example.com/team/app:dev
    build:
      context: .
      dockerfile: Dockerfile
      target: runtime
      platforms:
        - linux/amd64
        - linux/arm64

Compose 파일과 docker-bake.hcl이 함께 있으면 둘을 병합한다. Compose의 service build 정의를 기본값으로 두고 HCL에서 tag, output, cache, attestation을 확장할 수 있다.

# target과 설명 확인
docker buildx bake --list=targets
 
# variable, type, default, 설명 확인
docker buildx bake --list=variables
 
# 병합 후 실제 build definition 확인
docker buildx bake --print
 
# Dockerfile build check 실행
docker buildx bake --check

# default group build
docker buildx bake
 
# app target만 build
docker buildx bake app
 
# 여러 target 병렬 build
docker buildx bake app worker
 
# 결과를 local Docker image store로 load
docker buildx bake --load app
 
# release target을 registry로 push
docker buildx bake --push app-release

# Bake variable override
docker buildx bake --var TAG=2026.08.17 app
 
# environment variable로 같은 이름의 variable override
TAG=2026.08.17 docker buildx bake app
 
# 모든 target의 platform 교체
docker buildx bake --set "*.platform=linux/amd64"
 
# app 계열 target에 tag 추가
docker buildx bake --set "app*.tags+=registry.example.com/team/app:stable"
 
# 특정 target의 build argument override
docker buildx bake --set app.args.BUILD_MODE=release app

# 공통 정의 뒤에 release override 병합
docker buildx bake \
  -f docker-bake.hcl \
  -f docker-bake.release.hcl \
  --print
 
# 병합된 release target build 및 push
docker buildx bake \
  -f docker-bake.hcl \
  -f docker-bake.release.hcl \
  --push app-release

• target 이름을 찾지 못하면 docker buildx bake –list=targets와 –print로 실제 병합 결과를 확인한다.
• variable override가 적용되지 않으면 –list=variables로 이름과 type을 확인하고, shell environment의 같은 이름 변수가 default를 덮는지 점검한다.
• multi-platform 결과를 local image store에 load할 수 없으면 단일 platform으로 제한하거나 registry/OCI output과 –push를 사용한다.
• local context 또는 output이 Bake 파일 기준 directory 밖에 있으면 필요한 경로만 –allow fs.read=PATH 또는 –allow fs.write=PATH로 허용한다.
• CI 로그가 읽기 어려우면 –progress=plain을 사용한다.

• 공식 문서와 자동화에서는 docker buildx bake를 기본형으로 사용한다.
• docker bake는 현재 Docker CLI에서 같은 Buildx Bake 명령으로 동작하지만, 환경별 호환성을 위해 script에서는 공식 명령형을 우선한다.
• HCL과 JSON은 Bake 전용 속성을 지원한다. Compose YAML은 Compose build model에서 표현 가능한 속성을 중심으로 사용한다.

docker buildx bake --help

Usage:  docker buildx bake [OPTIONS] [TARGET...]
 
Build from a file
 
Aliases:
  docker buildx bake, docker buildx f
 
Options:
      --allow stringArray      Allow build to access specified resources
      --builder string         Override the configured builder instance
                               (default "default")
      --call string            Set method for evaluating build ("check",
                               "outline", "targets") (default "build")
      --check                  Shorthand for "--call=check"
  -D, --debug                  Enable debug logging
  -f, --file stringArray       Build definition file
      --list string            List targets or variables
      --load                   Shorthand for
                               "--set=*.output=type=docker". Conditional.
      --metadata-file string   Write build result metadata to a file
      --no-cache               Do not use cache when building the image
      --policy stringArray     Global policy evaluation options (format:
                               "[disabled=true|false][,strict=true|false][,log-level=level]")
      --print                  Print the options without building
      --progress string        Set type of progress output ("auto",
                               "none",  "plain", "quiet", "rawjson",
                               "tty"). Use plain to show container output
                               (default "auto")
      --provenance string      Shorthand for "--set=*.attest=type=provenance"
      --pull                   Always attempt to pull all referenced images
      --push                   Shorthand for
                               "--set=*.output=type=registry". Conditional.
      --sbom string            Shorthand for "--set=*.attest=type=sbom"
      --set stringArray        Override target value (e.g.,
                               "targetpattern.key=value")
      --var stringArray        Set a variable value (e.g., "name=value")

• docker
• buildx
• builder
• compose
• Docker Docs: Bake
• Docker Docs: Bake file reference
• Docker Docs: docker buildx bake

• codex:: 2026-08-17 Added Docker Bake CLI usage, HCL and Compose authoring, target hierarchy, variable overrides, matrix builds, validation, output, and security guidance.