docker:bake:ko [Command Line Interface Helper]

이 문서는 읽기 전용입니다. 원본을 볼 수는 있지만 바꿀 수는 없습니다. 문제가 있다고 생각하면 관리자에게 문의하세요.
{{tag>[docker cli buildx buildkit bake hcl]}}

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

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

===== Usage =====
<code bash>
docker buildx bake [OPTIONS] [TARGET...]
docker bake [OPTIONS] [TARGET...]
</code>

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

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

<code bash>
# 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
</code>

  * macOS: [[https://docs.docker.com/desktop/setup/install/mac-install/|Docker Desktop for Mac]]에 Buildx가 포함된다.
  * Windows: [[https://docs.docker.com/desktop/setup/install/windows-install/|Docker Desktop for Windows]]에 Buildx가 포함된다.

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

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

  - ''compose.yaml''
  - ''compose.yml''
  - ''docker-compose.yml''
  - ''docker-compose.yaml''
  - ''docker-bake.json''
  - ''docker-bake.hcl''
  - ''docker-bake.override.json''
  - ''docker-bake.override.hcl''

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

==== HCL Building Blocks ====
  * ''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

==== Minimal HCL Example ====
<code hcl>
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"]
}
</code>

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

<code hcl>
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"]
}
</code>

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

<code hcl>
target "app" {
  name = "app-${platform}"

  matrix = {
    platform = ["amd64", "arm64"]
  }

  platforms = ["linux/${platform}"]
  tags      = ["registry.example.com/team/app:${platform}"]
}
</code>

==== Compose YAML Build Definition ====
기존 ''compose.yaml''의 service ''build'' 속성도 Bake target으로 사용할 수 있다.

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

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

===== Examples =====
==== Inspect Before Build ====
<code bash>
# 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
</code>

==== Build Targets ====
<code bash>
# 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
</code>

==== Override Values ====
<code bash>
# 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
</code>

==== Multiple Definition Files ====
<code bash>
# 공통 정의 뒤에 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
</code>

===== Troubleshooting =====
  * 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''을 사용한다.

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

===== Help =====
++++ docker buildx bake --help |
<code text>
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")
</code>
++++

===== Security =====
<note important>
Registry credential, private key, API token을 ''args'', ''tags'', environment variable default 또는 Bake 파일에 평문으로 넣지 않는다. BuildKit ''secret''과 ''ssh'' mount를 사용하고, ''--allow'', ''security.insecure'', ''network.host'', filesystem wildcard 권한은 build에 필요한 최소 범위만 명시한다.
</note>

===== See Also =====
  * [[:docker:ko]]
  * [[:docker:buildx]]
  * [[:docker:builder]]
  * [[:docker:compose]]
  * [[https://docs.docker.com/build/bake/|Docker Docs: Bake]]
  * [[https://docs.docker.com/build/bake/reference/|Docker Docs: Bake file reference]]
  * [[https://docs.docker.com/reference/cli/docker/buildx/bake/|Docker Docs: docker buildx bake]]

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

{{indexmenu>.#1|js}}