docker buildx build
docker buildx build
docker buildx build는 BuildKit으로 Dockerfile을 빌드하는 명령이에요. 여러 플랫폼 빌드, 캐시, attestation(증명)을 비롯해 docker build보다 폭넓은 기능을 제공해요.
출처: 문서
본문
docker buildx build는 지정한 빌드 컨텍스트(PATH | URL | -)에서 Dockerfile을 빌드해요. --platform으로 여러 플랫폼을 대상으로 하고, --load·--push·--output으로 결과를 다양한 방식으로 내보낼 수 있어요. 빌드 캐시(--cache-from/--cache-to)와 attestation(--provenance, --sbom, --attest)도 지원해요.
지원하는 옵션은 다음과 같아요.
| 옵션 | 기본값 | 설명 |
|---|---|---|
--add-host |
커스텀 host-to-IP 매핑을 추가해요 (host:ip) |
|
--allow |
추가 권한(entitlement)을 명시적으로 허용해요 (예: network.host, security.insecure) |
|
--annotation |
컨테이너에 주석(annotation)을 추가해요 (OCI 런타임으로 전달돼요) | |
--attest |
증명(attestation) 파라미터 (형식: type=sbom,generator=image) |
|
--build-arg |
빌드 시 변수를 설정해요 | |
--build-context |
추가 빌드 컨텍스트 (예: name=path, name=docker-image://image) |
|
--cache-from |
외부 캐시 소스 (예: user/app:cache, type=local,dest=path) |
|
--cache-to |
캐시 내보내기 대상 (예: user/app:cache, type=local,dest=path) |
|
--call |
build |
빌드를 평가하는 메서드를 설정해요 (check, outline, targets) |
--cgroup-parent |
컨테이너의 상위 cgroup을 정해요 | |
--check |
--call=check의 축약형이에요 |
|
-f, --file |
빌드 정의 파일 | |
--iidfile |
이미지 ID를 파일에 기록해요 | |
--label |
컨테이너에 메타데이터를 설정해요 | |
--load |
--output=type=docker의 축약형이에요 |
|
--metadata-file |
빌드 결과 메타데이터를 파일에 기록해요 | |
--network |
컨테이너를 네트워크에 연결해요 | |
--no-cache |
이미지를 빌드할 때 캐시를 사용하지 않아요 | |
--no-cache-filter |
지정한 단계만 캐시하지 않아요 | |
-o, --output |
파일로 저장해요 (기본은 stdout) | |
--platform |
서버가 멀티플랫폼을 지원하면 플랫폼을 설정해요 | |
--policy |
정책 구성 (형식: filename=path[,filename=path]...) |
|
--progress |
auto |
진행 출력 유형을 설정해요 (auto, none, plain, quiet, rawjson, tty) |
--provenance |
--attest=type=provenance의 축약형이에요 |
|
--pull |
생성 전에 이미지를 가져올지 정해요 (always, missing, never) |
|
--push |
--output=type=registry,unpack=false의 축약형이에요 |
|
-q, --quiet |
구성만 검증하고 아무것도 출력하지 않아요 | |
--resource |
빌드 컨테이너 리소스 제한 (형식: memory=2g, cpus=4) |
|
--sbom |
--attest=type=sbom의 축약형이에요 |
|
--secret |
빌드에 노출할 비밀값 (형식: id=mysecret[,src=/local/file]) |
|
--shm-size |
/dev/shm 크기를 정해요 |
|
--ssh |
빌드에 노출할 SSH 에이전트 소켓·키 (형식: default 또는 id=path) |
|
-t, --tag |
새 이미지 참조를 설정해요 (형식: [registry/]repository[:tag]) |
|
--target |
빌드할 target build stage를 설정해요 | |
--ulimit |
ulimit 옵션을 정해요 |
Add entries to container hosts file (--add-host)
--add-host 플래그를 하나 이상 사용해 빌드 컨테이너의 /etc/hosts 파일에 호스트를 추가할 수 있어요. 이 예제는 my-hostname과 my_hostname_v6 호스트에 정적 주소를 추가해요.\n\nconsole\n$ docker buildx build --add-host my_hostname=8.8.8.8 --add-host my_hostname_v6=2001:4860:4860::8888 .\n\n\n호스트에서 실행 중인 서비스에 빌드가 연결돼야 한다면 --add-host에 특별한 host-gateway 값을 쓸 수 있어요. 다음 예제에서는 빌드 컨테이너가 host.docker.internal을 호스트의 게이트웨이 IP로 해석해요.\n\nconsole\n$ docker buildx build --add-host host.docker.internal=host-gateway .\n\n\nIPv6 주소는 대괄호로 감쌀 수 있어요. =와 : 둘 다 유효한 구분자이며 다음 예제의 두 형식 모두 유효해요.\n\nconsole\n$ docker buildx build --add-host my-hostname:10.180.0.1 --add-host my_hostname_v6=[2001:4860:4860::8888] .\n
Create annotations (--annotation)
text\n--annotation=\"key=value\"\n--annotation=\"[type:]key=value\"\n\n\n이미지 인덱스·매니페스트·디스크립터에 OCI 주석을 추가해요. 다음 예제는 이미지 매니페스트에 foo=bar 주석을 추가해요.\n\nconsole\n$ docker buildx build -t TAG --annotation \"foo=bar\" --push .\n
Create attestations (--attest)
--attest 플래그로 빌드 결과에 증명(attestation)을 추가해요. --attest=type=sbom은 SBOM, --attest=type=provenance는 provenance(출처) 증명을 추가해요. 자세한 내용은 docker buildx build --attest 문서를 참고해요.\n\nconsole\n$ docker buildx build --attest=type=sbom,generator=docker.io/docker/buildkit-syft-scanner:stable -t TAG --push .\n
Allow extra privileged entitlement (--allow)
--allow 플래그로 추가 권한(entitlement)을 명시적으로 허용해요. 기본적으로 Buildx와 BuildKit은 제한된 권한으로 동작해요. network.host(호스트 네트워크)와 security.insecure(비보안 실행) entitlement를 허용할 수 있어요.\n\nconsole\n$ docker buildx build --allow network.host --allow security.insecure .\n\n\n빌드 컨테이너가 호스트 네트워크를 사용하려면 --allow network.host가 필요하고, 루트로 실행되는 빌드 단계가 필요하면 --allow security.insecure를 써요.
Set build-time variables (--build-arg)
--build-arg로 빌드 시 변수를 설정해요. Dockerfile의 ARG 지시문에 전달되는 값이에요.\n\nconsole\n$ docker buildx build --build-arg HTTPS_PROXY=https://myproxy.example.com --build-arg VERSION=1.0 .\n
Additional build contexts (--build-context)
--build-context로 Dockerfile의 FROM이 사용할 추가 빌드 컨텍스트를 지정해요. 로컬 디렉터리, 원격 URL, OCI 이미지 등의 컨텍스트를 이름으로 참조할 수 있어요.\n\nconsole\n$ docker buildx build --build-context project=../project --build-context alpine=docker-image://alpine:3.19 .\n
Override the configured builder instance (--builder)
buildx --builder와 동일해요.
Use an external cache source for a build (--cache-from)
--cache-from으로 외부 캐시 소스를 사용해요. 빌드에서 기존 캐시를 재사용해 빌드를 빠르게 만들 수 있어요.\n\nconsole\n$ docker buildx build --cache-from=type=registry,ref=user/app:cache .\n
Export build cache to an external cache destination (--cache-to)
--cache-to로 빌드 캐시를 외부 캐시 대상으로 내보내요. 레지스트리나 로컬 캐시로 캐시를 저장해서 이후 빌드에서 재사용할 수 있어요.\n\nconsole\n$ docker buildx build --cache-to=type=registry,ref=user/app:cache,mode=max .\n
Invoke a frontend method (--call)
--call로 프론트엔드 메서드를 호출해요. build(기본), check, outline, targets 중에서 선택할 수 있어요.\n\nconsole\n$ docker buildx build --call=check .\n$ docker buildx build --call=outline .\n
Use a custom parent cgroup (--cgroup-parent)
--cgroup-parent로 빌드 컨테이너가 사용할 상위 cgroup을 지정해요.\n\nconsole\n$ docker buildx build --cgroup-parent $(docker inspect --format '{{.Id}}' $(docker ps -q) | head -1) .\n
Specify a Dockerfile (-f, --file)
-f / --file로 사용할 Dockerfile을 지정해요. 기본값은 컨텍스트 루트의 Dockerfile이에요.\n\nconsole\n$ docker buildx build -f ./Dockerfile.debug .\n
Load the single-platform build result to docker images (--load)
--load를 쓰면 단일 플랫폼 빌드 결과를 docker images에 로드해요. docker 드라이버는 기본적으로 적용되고, 다른 드라이버에서는 명시해야 해요.\n\nconsole\n$ docker buildx build --load -t myimage .\n
Write build result metadata to a file (--metadata-file)
--metadata-file로 빌드 결과 메타데이터를 파일에 기록해요. 이후 단계에서 빌드 결과를 참조할 때 유용해요.\n\nconsole\n$ docker buildx build --metadata-file metadata.json .\n
Set the networking mode for the RUN instructions during build (--network)
--network로 빌드 중 RUN 지시문의 네트워킹 모드를 설정해요. 기본값은 default고, 호스트 네트워크는 host(네트워크에 따라 다름)를 써요.\n\nconsole\n$ docker buildx build --network=host .\n
Ignore build cache for specific stages (--no-cache-filter)
--no-cache-filter로 특정 빌드 단계(stage)의 캐시를 무시해요. --no-cache가 전체 캐시를 끄는 것과 달리, 이 옵션은 지정한 단계만 캐시를 끄고 싶을 때 사용해요.\n\nconsole\n$ docker buildx build --no-cache-filter=stage1 .\n
Set the export action for the build result (-o, --output)
-o / --output으로 빌드 결과의 내보내기 동작을 지정해요. type=docker(이미지 로드), type=registry(레지스트리 푸시), type=local(파일시스템) 등을 지원해요.\n\nconsole\n$ docker buildx build -o type=docker .\n$ docker buildx build -o type=local,dest=./out .\n
Set the target platforms for the build (--platform)
--platform으로 빌드 대상 플랫폼을 지정해요. linux/amd64,linux/arm64처럼 여러 플랫폼을 쉼표로 구분해 지정하면 멀티플랫폼 이미지를 빌드할 수 있어요.\n\nconsole\n$ docker buildx build --platform linux/amd64,linux/arm64,linux/arm/v7 -t multiarch:latest .\n
Set type of progress output (--progress)
--progress로 진행 출력 유형을 설정해요. auto, plain, tty, rawjson 등을 지원해요. 컨테이너 출력을 그대로 보려면 plain을 써요.\n\nconsole\n$ docker buildx build --progress=plain .\n
Create provenance attestations (--provenance)
--provenance로 provenance(출처) attestation을 생성·설정해요. 기본적으로 활성화되며 mode=min/mode=max로 포함 수준을 조절할 수 있어요.\n\nconsole\n$ docker buildx build --provenance=true -t TAG --push .\n
Push the build result to a registry (--push)
--push로 빌드 결과를 레지스트리로 푸시해요. -t로 지정한 태그로 이미지를 올려요.\n\nconsole\n$ docker buildx build --push -t user/app:latest .\n
Create SBOM attestations (--sbom)
--sbom으로 SBOM(소프트웨어 구성 목록) attestation을 생성·설정해요.\n\nconsole\n$ docker buildx build --sbom=true -t TAG --push .\n
Secret to expose to the build (--secret)
--secret으로 빌드에 노출할 비밀값을 지정해요. id=mysecret,src=./secret.txt처럼 값을 전달할 수 있어요.\n\nconsole\n$ docker buildx build --secret id=mysecret,src=./secret.txt .\n
Shared memory size for build containers (--shm-size)
--shm-size로 빌드 컨테이너의 공유 메모리 크기를 지정해요.\n\nconsole\n$ docker buildx build --shm-size 2g .\n
SSH agent socket or keys to expose to the build (--ssh)
--ssh로 빌드에 노출할 SSH 에이전트 소켓 또는 키를 지정해요. buildkit이 SSH 에이전트 포워딩으로 접근할 수 있게 해요.\n\nconsole\n$ docker buildx build --ssh default .\n
Tag an image (-t, --tag)
-t / --tag로 이미지에 이름과 태그를 지정해요. name:tag 형식이며 여러 번 지정해 여러 태그를 붙일 수 있어요.\n\nconsole\n$ docker buildx build -t myimage:latest -t myimage:v1 .\n
Specifying target build stage (--target)
--target으로 빌드할 특정 build stage를 지정해요. 다단계 Dockerfile에서 특정 단계까지만 빌드하고 싶을 때 사용해요.\n\nconsole\n$ docker buildx build --target app .\n
Set ulimits (--ulimit)
--ulimit로 빌드 컨테이너의 ulimit을 설정해요.\n\nconsole\n$ docker buildx build --ulimit nofile=1024:1024 .\n
Set CPU and memory limits for build containers (--resource)
--resource로 빌드 컨테이너의 CPU·메모리 제한을 설정해요. --resource memory=2g --resource cpus=4처럼 값을 지정할 수 있어요.\n\nconsole\n$ docker buildx build --resource memory=2g,cpus=4 .\n