docker buildx create

docker buildx create는 새 빌더 인스턴스를 만드는 명령이에요. Docker 컨텍스트나 엔드포인트를 가리키는 빌더를 생성할 때 사용해요.

출처: 문서

본문

docker buildx create는 Docker 컨텍스트 또는 엔드포인트를 가리키는 새 빌더 인스턴스를 만들어요. 여기서 컨텍스트는 docker context ls의 컨텍스트 이름이고, 엔드포인트는 Docker 소켓 주소(예: DOCKER_HOST 값)예요.

기본적으로 현재 Docker 구성을 사용해 context/endpoint 값을 결정해요.

빌더 인스턴스는 빌드를 실행할 수 있는 격리된 환경이에요. 모든 Docker 컨텍스트에는 기본 빌더 인스턴스도 함께 있어요.

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

옵션	기본값	설명
`--append`		변경하는 대신 빌더에 노드를 추가해요
`--bootstrap`		검사 전에 빌더를 시작해요
`--buildkitd-config`		BuildKit 데몬 구성 파일
`--buildkitd-flags`		BuildKit 데몬 플래그
`--driver`		사용할 드라이버 (가능한 값: `cloud`, `docker-container`, `kubernetes`, `remote`, `docker`)
`--driver-opt`		드라이버 옵션
`--leave`		변경하는 대신 빌더에서 노드를 제거해요
`--name`		컨테이너에 이름을 지정해요
`--node`		주어진 이름으로 노드를 만들거나 수정해요
`--platform`		서버가 멀티플랫폼을 지원하면 플랫폼을 설정해요
`--timeout`	`20s`	연결 시 또는 이미 실행 중일 때 컨테이너 종료에 쓰는 타임아웃(초)을 정해요
`--use`		현재 빌더 인스턴스를 설정해요

Append a new node to an existing builder (--append)

--append 플래그는 명령 동작을 --name으로 지정한 기존 빌더에 새 노드를 추가하는 것으로 바꿔요. Buildx는 지원하는 플랫폼에 따라 빌드에 적절한 노드를 고를 거예요.

$ docker buildx create mycontext1
eager_beaver

$ docker buildx create --name eager_beaver --append mycontext2
eager_beaver

Specify a configuration file for the BuildKit daemon (--buildkitd-config)

--buildkitd-config FILE

BuildKit 데몬이 사용할 구성 파일을 지정해요. 이 구성은 --buildkitd-flags로 덮어쓸 수 있어요. 예제 BuildKit 데몬 구성 파일을 참고해요.

구성 파일을 지정하지 않으면 Buildx는 기본적으로 다음 위치에서 찾아요.

$BUILDX_CONFIG/buildkitd.default.toml
$DOCKER_CONFIG/buildx/buildkitd.default.toml
~/.docker/buildx/buildkitd.default.toml

docker-container 빌더를 만들면서 buildkitd.toml 구성에 레지스트리 인증서를 지정했다면, 파일이 /etc/buildkit/certs 아래 컨테이너로 복사되고 구성도 그에 맞게 갱신돼요.

Specify options for the BuildKit daemon (--buildkitd-flags)

--buildkitd-flags FLAGS

BuildKit 데몬을 시작할 때 플래그를 추가해요. --buildkitd-config로 지정한 구성 파일보다 우선해요. 사용 가능한 플래그는 buildkitd --help를 참고해요.

--buildkitd-flags '--debug --debugaddr 0.0.0.0:6666'

BuildKit daemon network mode

BuildKit 데몬의 네트워크 모드는 --buildkitd-config 구성 파일의 worker.oci.networkMode 옵션이나 여기의 --oci-worker-net 플래그로 지정할 수 있어요. 기본값은 auto이고 bridge, cni, host 중 하나가 될 수 있어요.

--buildkitd-flags '--oci-worker-net bridge'

[!NOTE] 네트워크 모드 "bridge"는 BuildKit v0.13부터 지원되며 다음 v0.14에서 기본값이 될 예정이에요.

Set the builder driver to use (--driver)

--driver DRIVER

사용할 빌더 드라이버를 설정해요. 드라이버는 BuildKit 백엔드의 구성이에요. Buildx가 지원하는 드라이버는 다음과 같아요.

docker (기본값)
cloud
docker-container
kubernetes
remote

빌드 드라이버에 대한 자세한 내용은 여기를 참고해요.

`docker` driver

Docker 데몬에 내장된 빌더를 사용해요. 이 드라이버에서는 buildx build에 기본적으로 --load 플래그가 적용돼요. 다만 멀티플랫폼 이미지 빌드나 캐시 내보내기는 현재 지원되지 않아요.

`cloud` driver

Docker Build Cloud 빌더를 사용해요. Docker Build Cloud 접근·설정은 Docker Build Cloud setup을, 빌드 예제는 Building with Docker Build Cloud를 참고해요.

--driver cloud와 <account>/<builder> 또는 cloud://<account>/<builder> 형식의 빌더 이름으로 기존 cloud 빌더에 Buildx를 연결할 수 있어요. docker login으로 로그인하고 빌더 접근 권한이 있어야 해요.

$ docker buildx create --driver cloud --name cloud-builder --use org/builder
$ docker buildx create --driver cloud --name cloud-builder --use cloud://org/builder

출력을 지정하지 않으면 태그 없는 결과가 cloud 빌드 캐시에 남아요. --tag를 쓰면 Buildx가 단일 플랫폼을 대상으로 build가 한 cloud 노드에서 실행될 때 이미지를 자동으로 로드해요. 로딩 동작·Docker 컨텍스트·기타 출력 구성은 Load results from Docker Build Cloud를 참고해요.

buildx create가 Build Cloud 빌더 그룹을 해석하면 각 서비스 인스턴스가 Buildx 노드가 돼요. --append는 해석된 인스턴스 이름이 Buildx 빌더 안에서 고유해야 해요. 해석된 cloud 노드는 생성 시점의 스냅샷이므로, Build Cloud 멤버십이나 배치가 바뀐 뒤 topology를 갱신하려면 Buildx 빌더를 다시 만들어야 해요.

Set additional driver-specific options (--driver-opt)

--driver-opt OPTIONS

드라이버별 추가 옵션을 전달해요. 사용 가능한 드라이버 옵션에 대한 자세한 내용은 특정 드라이버 문서를 참고해요.

BUILDX_DEFAULT_POLICY=1을 설정하면 docker-container 드라이버가 빌더를 만들기 전에 서명된 moby/buildkit 빌더 이미지 태그를 검증해요. 검증을 명시적으로 건너뛰려면 allow-untrusted-image=true를 설정해요. 예를 들어:

$ BUILDX_DEFAULT_POLICY=1 docker buildx create --driver docker-container \
    --driver-opt allow-untrusted-image=true

신뢰하는 이미지에만 이 옵션을 사용해요. 새 빌더 노드의 빌더 이미지 검증을 비활성화해요.

Remove a node from a builder (--leave)

--leave 플래그는 명령 동작을 빌더에서 노드를 제거하는 것으로 바꿔요. 빌더는 --name으로, 제거할 노드는 --node로 지정해요.

$ docker buildx create --name mybuilder --node mybuilder0 --leave

Specify the name of the builder (--name)

--name NAME

--name 플래그는 만들거나 수정할 빌더의 이름을 지정해요. 지정하지 않으면 자동으로 생성돼요.

Specify the name of the node (--node)

--node NODE

--node 플래그는 만들거나 수정할 노드의 이름을 지정해요. 이름을 지정하지 않으면 노드 이름은 기본적으로 속한 빌더의 이름에 인덱스 번호 접미사가 붙은 값이 돼요.

Set the platforms supported by the node (--platform)

--platform PLATFORMS

--platform 플래그는 노드가 지원하는 플랫폼을 설정해요. OS/아키텍처/변형 형식의 플랫폼을 쉼표로 구분한 목록을 받아요. 노드는 지원하는 플랫폼을 자동으로 감지하기도 하지만, 수동 값이 감지된 값보다 우선하며 여러 노드가 같은 플랫폼 빌드를 지원할 때 사용할 수 있어요.

$ docker buildx create --platform linux/amd64
$ docker buildx create --platform linux/arm64,linux/arm/v7

Automatically switch to the newly created builder (--use)

--use 플래그는 현재 빌더를 새로 만든 빌더로 자동 전환해요. docker buildx use $(docker buildx create ...)를 실행하는 것과 같아요.

docker buildx create