📌 설명
docker buildx build는 BuildKit을 사용해 이미지를 빌드합니다.docker build,docker image build등의 명령어와 동일하거나 유사하게 동작하지만, 더 많은 기능을 지원합니다.
🛠️ 기본 사용법
docker buildx build [OPTIONS] PATH | URL | -
PATH: Dockerfile이 있는 디렉터리URL: 원격 Git 리포지토리 등-: 표준 입력
예시:
docker buildx build -t my-image:latest .
⚙️ 주요 옵션 (한글 설명 포함)
| 옵션 | 설명 |
|---|---|
--add-host | 컨테이너 /etc/hosts에 호스트-IP 매핑 추가 |
--allow | 고급 권한 허용 (예: network.host, security.insecure) |
--annotation | 이미지에 주석(Annotation) 추가 |
--attest | SBOM, provenance 등 이미지 검증 정보 포함 |
--build-arg | 빌드 시간에 사용할 인자 변수 설정 |
--cache-from / --cache-to | 빌드 캐시 경로 지정 (성능 최적화) |
--file 또는 -f | 사용할 Dockerfile 지정 (기본값: ./Dockerfile) |
--iidfile | 빌드된 이미지 ID를 파일에 저장 |
--label | 이미지에 메타데이터 라벨 추가 |
--load | 이미지 결과를 로컬 Docker에 바로 로드 (docker image ls에서 바로 보임) |
--push | 이미지 결과를 레지스트리에 푸시 |
--output, -o | 빌드 결과 출력 경로 지정 (type=local, type=docker, type=registry) |
--platform | 대상 플랫폼 지정 (예: linux/amd64, linux/arm64) |
--progress | 빌드 출력 형식 지정 (auto, plain, quiet, 등) |
--pull | 참조된 모든 이미지를 강제로 pull |
--secret | 빌드 중 사용할 보안 정보 전달 |
--ssh | SSH 키 전달 |
--tag, -t | 빌드 결과 이미지에 태그 지정 |
--target | 멀티스테이지 빌드 시 특정 스테이지만 빌드 |
💡 예시: /etc/hosts에 호스트 추가
docker buildx build --add-host my_hostname=8.8.8.8 .
docker buildx build --add-host host.docker.internal=host-gateway .
docker buildx build --add-host my-hostname_v6=[2001:4860:4860::8888] .
✅ 예시: 실전 빌드 명령
- 로컬에서 Dockerfile로 빌드:
docker buildx build -t my-app:latest .
- 멀티 플랫폼 이미지 빌드 후 푸시:
docker buildx build --platform linux/amd64,linux/arm64 -t myrepo/myapp:latest --push .
- 캐시를 사용하여 빠르게 빌드:
docker buildx build --cache-from=type=local,src=./cache --cache-to=type=local,dest=./cache .
📌 요약
buildx는 고급 빌드 기능을 사용하는 도구로, 멀티플랫폼, 캐시, 푸시/로드 등 다양한 기능을 제공합니다.
📌 1. --annotation
이미지에 주석(메타데이터)을 추가합니다.
OCI(Open Container Initiative) 형식으로 추가되며, 사용 위치(레벨)를 지정할 수 있습니다.
✅ 기본 형식
--annotation "key=value"
--annotation "[type:]key=value"
✅ 예시
# 기본 (manifest에 추가됨)
docker buildx build -t myimage --annotation "foo=bar" --push .
# image index에 추가
docker buildx build -t myimage --annotation "index:foo=bar" --push .
# 여러 레벨에 동시에 추가
docker buildx build -t myimage --annotation "index,manifest,manifest-descriptor:foo=bar" --push .
# 특정 플랫폼에만 추가
docker buildx build -t myimage --annotation "manifest[linux/amd64]:foo=bar" --push .
❗주의
manifest[linux/*]와 같은 와일드카드는 지원하지 않습니다.
📌 2. --attest
이미지 빌드 결과에 대한 증명(Attestation)을 생성합니다.
✅ 주요 타입
sbom: Software Bill of Materials (구성 요소 목록)provenance: 빌드 출처/과정 증명 (SLSA Provenance)
✅ 사용 예시
# SBOM 추가
docker buildx build --attest=type=sbom --push .
# Provenance 추가
docker buildx build --attest=type=provenance --push .
# 축약형
docker buildx build --sbom --provenance --push .
📌 Attestation은 이미지를 푸시할 때만 적용됩니다.
📌 3. --allow
BuildKit 실행 권한 확장 (위험한 기능 활성화)
✅ 주요 권한
| 권한 | 설명 |
|---|---|
network.host | 컨테이너가 호스트 네트워크를 사용 가능 |
security.insecure | 샌드박스 없이 실행 허용 (보안에 취약함) |
✅ 사용 예시
# 빌더 생성 시 권한 허용
docker buildx create --name insecure-builder --use --buildkitd-flags '--allow-insecure-entitlement security.insecure'
# 빌드 시 권한 사용
docker buildx build --allow security.insecure .
📌 4. --build-arg
빌드 시 변수 전달 (ARG 명령어와 함께 사용)
✅ 예시
# 직접 값 지정
docker buildx build --build-arg VERSION=1.2.3 .
# 환경 변수에서 값 전달
export API_KEY=abc123
docker buildx build --build-arg API_KEY .
Dockerfile 예시:
ARG VERSION
RUN echo "Version is $VERSION"
✅ 자주 사용하는 내장 인자
| 인자 | 설명 |
|---|---|
BUILDKIT_CONTEXT_KEEP_GIT_DIR=1 | .git 디렉터리 유지 |
BUILDKIT_INLINE_CACHE=1 | 캐시 메타데이터 포함 |
BUILDKIT_MULTI_PLATFORM=1 | 멀티 플랫폼 출력 보장 |
📦 요약
| 옵션 | 용도 |
|---|---|
--annotation | 이미지에 설명/메타데이터 추가 |
--attest | 이미지에 보안/출처 증명 첨부 (SBOM, provenance) |
--allow | 위험한 기능 (host network, sandbox 해제 등) 허용 |
--build-arg | 빌드 시 인자 변수 전달 (Dockerfile의 ARG 사용) |