{{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 ===== 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 ===== Installation ===== 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: [[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 ==== 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"] } ==== Inheritance ==== 공통 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 ==== ''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 Build Definition ==== 기존 ''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을 확장할 수 있다. ===== Examples ===== ==== Inspect Before Build ==== # 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 ==== Build Targets ==== # 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 ==== Override Values ==== # 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 ==== Multiple Definition Files ==== # 공통 정의 뒤에 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 ===== 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 | 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") ++++ ===== Security ===== Registry credential, private key, API token을 ''args'', ''tags'', environment variable default 또는 Bake 파일에 평문으로 넣지 않는다. BuildKit ''secret''과 ''ssh'' mount를 사용하고, ''--allow'', ''security.insecure'', ''network.host'', filesystem wildcard 권한은 build에 필요한 최소 범위만 명시한다. ===== 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}}