원격 드라이버

원격 드라이버 (Remote driver)

Buildx 원격 드라이버는 외부에서 관리되는 BuildKit 인스턴스에 연결해 더 복잡한 커스텀 빌드 워크로드를 처리할 수 있게 해 주는 드라이버예요.

출처: 문서

본문

Buildx 원격 드라이버는 더 복잡한 커스텀 빌드 워크로드를 지원해요. 외부에서 관리되는 BuildKit 인스턴스에 연결할 수 있게 해 주죠. BuildKit 데몬의 수동 관리가 필요한 시나리오나, 다른 소스에서 BuildKit 데몬이 노출되는 경우에 유용해요.

동작 방식 (Synopsis)

$ docker buildx create \
  --name remote \
  --driver remote \
  tcp://localhost:1234

다음 표는 --driver-opt에 넘길 수 있는 드라이버별 옵션을 설명해요:

예시: 유닉스 소켓을 통한 원격 BuildKit (Remote BuildKit over Unix sockets)

이 가이드에서는 유닉스 소켓에서 수신 대기하는 BuildKit 데몬을 만들고, Buildx가 이를 통해 연결하도록 구성하는 방법을 보여줘요.

BuildKit이 설치되어 있는지 확인해요. 예를 들어 다음과 같이 buildkitd 인스턴스를 실행할 수 있어요:
```
$ sudo ./buildkitd --group $( id -gn ) --addr unix://$HOME/buildkitd.sock
```
또는 루트리스(rootless) 모드에서 buildkitd를 실행하는 방법은 루트리스 BuildKit 문서를, systemd 서비스로 실행하는 방법은 BuildKit systemd 예시를 참고하세요.

연결할 수 있는 유닉스 소켓이 있는지 확인해요.

$ ls -lh /home/user/buildkitd.sock
srw-rw---- 1 root user 0 May  5 11:04 /home/user/buildkitd.sock

원격 드라이버로 Buildx를 연결해요:

$ docker buildx create \
  --name remote-unix \
  --driver remote \
  unix://$HOME/buildkitd.sock

docker buildx ls로 사용 가능한 빌더를 나열해요. 목록에 remote-unix가 보일 거예요:

$ docker buildx ls
NAME/NODE           DRIVER/ENDPOINT                        STATUS  PLATFORMS
remote-unix         remote
remote-unix0      unix:///home/.../buildkitd.sock        running linux/amd64, linux/amd64/v2, linux/amd64/v3, linux/386
default *           docker
default           default                                running linux/amd64, linux/386

docker buildx use remote-unix로 이 새 빌더를 기본값으로 전환하거나, --builder로 빌드마다 지정할 수 있어요:

$ docker buildx build --builder=remote-unix -t test --load .

빌드 결과를 Docker 데몬에 로드하려면 --load 플래그를 사용해야 한다는 점을 기억하세요.

예시: Docker 컨테이너의 원격 BuildKit (Remote BuildKit in Docker container)

이 가이드에서는 BuildKit Docker 컨테이너를 직접 부팅하고 Buildx 원격 드라이버로 연결하는, docker-container 드라이버와 유사한 구성을 만드는 방법을 보여줘요. 이 절차는 컨테이너를 수동으로 만들고 노출된 포트로 접근해요. (실제로는 Docker 데몬을 통해 BuildKit에 연결하는 docker-container 드라이버를 쓰는 게 낫겠지만, 설명 목적상 이렇게 해 볼게요.)

BuildKit용 인증서를 생성해요. 시작점으로 다음 bake 정의를 사용할 수 있어요:
```
SAN="localhost 127.0.0.1" docker buildx bake "https://github.com/moby/buildkit.git#master:examples/create-certs"
```
TLS 없이 TCP로 BuildKit을 노출하는 것도 가능하지만 권장하지 않아요. 그렇게 하면 자격 증명 없이 누구나 BuildKit에 접근할 수 있게 되기 때문이에요.

.certs/에 인증서가 생성되면 컨테이너를 시작해요:

$ docker run -d --rm \
  --name=remote-buildkitd \
  --privileged \
  -p 1234:1234 \
  -v $PWD/.certs:/etc/buildkit/certs \
  moby/buildkit:latest \
  --addr tcp://0.0.0.0:1234 \
  --tlscacert /etc/buildkit/certs/daemon/ca.pem \
  --tlscert /etc/buildkit/certs/daemon/cert.pem \
  --tlskey /etc/buildkit/certs/daemon/key.pem

이 명령은 BuildKit 컨테이너를 시작하고 데몬의 1234 포트를 localhost로 노출해요.

Buildx로 이 실행 중인 컨테이너에 연결해요:

$ docker buildx create \
  --name remote-container \
  --driver remote \
  --driver-opt cacert=${PWD}/.certs/client/ca.pem,cert=${PWD}/.certs/client/cert.pem,key=${PWD}/.certs/client/key.pem,servername=<TLS_SERVER_NAME> \
  tcp://localhost:1234

또는 docker-container:// URL 스킴을 사용해 포트를 지정하지 않고 BuildKit 컨테이너에 연결할 수도 있어요:

$ docker buildx create \
  --name remote-container \
  --driver remote \
  docker-container://remote-container

예시: Kubernetes의 원격 BuildKit (Remote BuildKit in Kubernetes)

이 가이드에서는 BuildKit Deployment를 직접 만들어 kubernetes 드라이버와 유사한 구성을 만드는 방법을 보여줘요. kubernetes 드라이버가 내부적으로 이 작업을 해 주지만, BuildKit을 직접 스케일링하고 싶을 때가 있을 수 있어요. 또한 Kubernetes 파드 안에서 빌드를 실행할 때는 각 파드 안에서 Buildx 빌더를 다시 만들거나 파드 사이에 복사해야 해요.

BuildKit 문서의 안내에 따라 buildkitd의 Kubernetes 배포를 만들어요. create-certs.sh 스크립트로 BuildKit 데몬과 클라이언트용 인증서를 만들고, 파드에 연결되는 서비스를 갖춘 BuildKit 파드 배포를 만들어요.

서비스 이름이 buildkitd라고 가정하면, 나열된 인증서 파일이 있는지 확인하고 Buildx에 원격 빌더를 만들어요:

$ docker buildx create \
  --name remote-kubernetes \
  --driver remote \
  --driver-opt cacert=${PWD}/.certs/client/ca.pem,cert=${PWD}/.certs/client/cert.pem,key=${PWD}/.certs/client/key.pem \
  tcp://buildkitd.default.svc:1234

BuildKit 설정 가이드는 ClusterIP 서비스만 만들기 때문에, 이 방식은 클러스터 내부에서만 동작해요. 빌더에 원격으로 접근하려면 ingress를 설정해 사용할 수 있는데, 이 가이드의 범위를 벗어나요.

Kubernetes의 원격 빌더 디버깅하기 (Debug a remote builder in Kubernetes)

Kubernetes에 배포된 원격 빌더에 접근하는 데 문제가 있다면 kube-pod:// URL 스킴을 사용해 Kubernetes API를 통해 BuildKit 파드에 직접 연결할 수 있어요. 이 방법은 배포의 단일 파드에만 연결된다는 점에 주의하세요.

$ kubectl get pods --selector=app=buildkitd -o json | jq -r '.items[].metadata.name'
buildkitd-XXXXXXXXXX-xxxxx
$ docker buildx create \
  --name remote-container \
  --driver remote \
  kube-pod://buildkitd-XXXXXXXXXX-xxxxx

또는 kubectl의 포트 포워딩 메커니즘을 사용할 수 있어요:

$ kubectl port-forward svc/buildkitd 1234:1234

그런 다음 원격 드라이버를 tcp://localhost:1234로 지정하면 돼요.