docker buildx bake

docker buildx bake는 빌드 정의 파일(bake 파일)을 바탕으로 고수준 빌드를 수행하는 명령이에요. 지정한 각 target이 빌드의 일부로 병렬 실행돼요.

출처: 문서

본문

[!NOTE] buildx bake 명령은 필요에 따라 향후 이전 버전과 호환되지 않는 기능이 추가될 수 있어요. 명령 개선과 기능 확장에 대한 피드백을 찾고 있어요.

Bake는 고수준 빌드 명령이에요. 지정한 target이 각각 병렬로 실행돼요. bake 파일 작성에 대한 소개는 High-level build options with Bake 가이드를 참고해요.

지원하는 옵션은 다음과 같아요.

옵션	기본값	설명
`--allow`		추가 권한(entitlement)을 명시적으로 허용해요 (예: `network.host`, `security.insecure`)
`--call`	`build`	빌드를 평가하는 메서드를 설정해요 (`check`, `outline`, `targets`)
`--check`		`--call=check`의 축약형이에요
`-f`, `--file`		빌드 정의 파일
`--list`		target 또는 변수 목록을 보여줘요
`--load`		`--output=type=docker`의 축약형이에요
`--metadata-file`		빌드 결과 메타데이터를 파일에 기록해요
`--no-cache`		이미지를 빌드할 때 캐시를 사용하지 않아요
`--policy`		정책 구성 (형식: `filename=path[,filename=path]...`)
`--print`		빌드하지 않고 옵션만 출력해요
`--progress`	`auto`	진행 출력 유형을 설정해요 (`auto`, `none`, `plain`, `quiet`, `rawjson`, `tty`)
`--provenance`		`--attest=type=provenance`의 축약형이에요
`--pull`		생성 전에 이미지를 가져올지 정해요 (`always`, `missing`, `never`)
`--push`		`--output=type=registry,unpack=false`의 축약형이에요
`--sbom`		`--attest=type=sbom`의 축약형이에요
`--set`		target 값을 덮어써요 (예: `targetpattern.key=value`)
`--var`		변수 값을 설정해요 (예: `name=value`)

Allow extra privileged entitlement (--allow)

Entitlement는 권한이 필요한 작업에 통제된 접근을 제공하기 위한 것이에요. 기본적으로 Buildx와 BuildKit은 제한된 권한으로 동작해서 사용자와 시스템을 의도하지 않은 부작용이나 보안 위험으로부터 보호해요. --allow 플래그는 추가 entitlement에 대한 접근을 명시적으로 허용해, 빌드나 bake 작업에 높은 권한이 필요할 때 이를 분명히 드러내요.

BuildKit의 network.host, security.insecure entitlement 외에도 Bake는 파일시스템 entitlement를 지원해서 파일시스템 접근을 세밀하게 제어할 수 있어요. 특히 기본 작업 디렉터리 밖 파일에 접근해야 하는 빌드에서 유용해요.

Bake가 지원하는 파일시스템 entitlement는 다음과 같아요.

--allow fs=<path|*> - 작업 디렉터리 밖 파일에 읽기·쓰기 접근을 부여해요.
--allow fs.read=<path|*> - 작업 디렉터리 밖 파일에 읽기 접근을 부여해요.
--allow fs.write=<path|*> - 작업 디렉터리 밖 파일에 쓰기 접근을 부여해요.

fs entitlement는 파일시스템의 디렉터리 경로(상대 또는 절대)를 값으로 받아요. 또는 와일드카드(*)를 넘겨 Bake가 전체 파일시스템에 접근하도록 허용할 수 있어요.

Bake는 --allow=buildx.local.delete도 지원해서 mode=delete가 설정됐을 때 로컬 출력이 오래된 파일을 삭제할 권한을 부여해요.

Example: fs.read

다음 Bake 구성이 있다고 할게요. Bake는 bake 파일 기준 상위 디렉터리에 접근해야 해요.

target "app" {
  context = "../src"
}

docker-bake.hcl 파일이 있는 디렉터리에서 docker buildx bake app을 실행한다면, ../src 디렉터리를 읽는 것을 명시적으로 허용해야 해요. 이 경우 다음 호출이 모두 동작해요.

$ docker buildx bake --allow fs.read=* app
$ docker buildx bake --allow fs.read=../src app
$ docker buildx bake --allow fs=* app

Example: fs.write

다음 docker-bake.hcl 파일은 /tmp 디렉터리에 쓰기 접근이 필요해요.

target "app" {
  output = "/tmp"
}

/tmp 디렉터리 밖에서 docker buildx bake app을 실행한다면, 경로를 지정하거나 와일드카드를 써서 fs.write entitlement를 허용해야 해요.

$ docker buildx bake --allow fs=/tmp app
$ docker buildx bake --allow fs.write=/tmp app
$ docker buildx bake --allow fs.write=* app

Override the configured builder instance (--builder)

buildx --builder와 동일해요.

Invoke a frontend method (--call)

build --call과 동일해요.

Call: check (--check)

build --check과 동일해요.

Specify a build definition file (-f, --file)

-f / --file 옵션으로 사용할 빌드 정의 파일을 지정해요. 파일은 HCL, JSON 또는 Compose 파일일 수 있어요. 파일을 여러 개 지정하면 모두 읽고 빌드 구성을 결합해요.

docker buildx bake