Docker Buildx Use 사용법 완벽 가이드! Buildx Builder 전환하기

Docker Buildx를 사용하다 보면 하나의 Builder만 사용하는 것이 아니라 여러 개의 Builder를 생성하여 관리하는 경우가 많습니다.

예를 들어 개발 환경에서는 기본 Builder를 사용하고, 운영 배포에서는 멀티 플랫폼 전용 Builder를 사용할 수 있습니다.

또한 CI/CD 환경에서는 별도의 빌드 전용 Builder를 구성하여 자동화 작업을 수행하기도 합니다.

이처럼 여러 Builder가 존재하는 환경에서는 현재 어떤 Builder가 활성화되어 있는지 관리하는 것이 중요합니다.

이때 사용하는 명령어가 바로 docker buildx use입니다.

Docker Buildx Use는 사용할 Builder를 변경하는 명령어입니다. 지정한 Builder를 활성화하면 이후 실행하는 Buildx 빌드 작업은 해당 Builder 환경에서 실행됩니다.

이번 글에서는 Docker Buildx Use의 개념부터 기본 사용법, Builder 전환 방법, 실무 활용 방법까지 자세히 알아보겠습니다.

Docker Buildx Use란 무엇인가?

Docker Buildx Use는 현재 활성화할 Builder를 변경하는 명령어입니다.

Docker Buildx는 여러 Builder를 동시에 생성하고 관리할 수 있으며, 현재 선택된 Builder가 이미지 빌드 작업을 담당합니다.

현재 활성 Builder는 다음과 같이 확인할 수 있습니다.

docker buildx ls

출력:

NAME                  DRIVER

default               docker

multi-builder *       docker-container

별표(*)가 표시된 Builder가 현재 사용 중인 Builder입니다.

Docker Buildx Use는 언제 사용하는가?

다음과 같은 상황에서 사용합니다.

멀티 플랫폼 Builder 전환
CI/CD 전용 Builder 사용
프로젝트별 빌드 환경 변경
원격 Build 서버 사용
빌드 오류 해결

여러 빌드 환경을 운영하는 경우 필수적으로 사용하는 기능입니다.

Docker Buildx Builder 목록 확인하기

Builder 변경 전 현재 상태를 확인합니다.

docker buildx ls

예:

NAME                 DRIVER

default              docker

production-builder   docker-container

ci-builder *         docker-container

현재 ci-builder가 활성화되어 있는 상태입니다.

Docker Buildx Use 기본 사용법

기존 Builder를 선택하는 방법입니다.

docker buildx use production-builder

변경 후 확인:

docker buildx ls

결과:

NAME                    DRIVER

production-builder *    docker-container

ci-builder              docker-container

이제 production-builder가 기본 Builder로 설정됩니다.

현재 Builder 확인하기

현재 활성화된 Builder 정보는 다음 명령으로 확인할 수 있습니다.

docker buildx inspect

또는:

docker buildx ls

별표(*)가 표시된 Builder가 현재 사용 중입니다.

특정 Builder로 빌드하기

Builder를 변경하지 않고 특정 빌드에서만 사용할 수도 있습니다.

docker buildx build \
--builder production-builder \
-t my-app:v1 .

현재 설정은 유지하면서 원하는 Builder만 선택할 수 있습니다.

Docker Buildx Use와 Create 차이

두 명령어는 역할이 다릅니다.

Docker Buildx Create

새로운 Builder 생성

docker buildx create --name my-builder

Docker Buildx Use

기존 Builder 선택

docker buildx use my-builder

정리하면:

Create = Builder 만들기

Use = Builder 사용하기

입니다.

Docker Buildx Use 실무 활용 예제

멀티 플랫폼 Builder 전환

ARM64와 AMD64 이미지를 만들어야 하는 경우 멀티 플랫폼 Builder를 선택합니다.

docker buildx use multi-builder

확인:

docker buildx inspect

출력:

Platforms:
linux/amd64
linux/arm64

이제 멀티 플랫폼 빌드가 가능합니다.

CI/CD Builder 사용

자동 빌드 환경에서는 CI 전용 Builder를 사용할 수 있습니다.

docker buildx use ci-builder

이후:

docker buildx build \
-t my-app:v1 .

CI Builder 환경에서 빌드됩니다.

프로젝트별 Builder 관리

프로젝트마다 Builder를 분리할 수 있습니다.

예:

프로젝트 A
 └─ app-builder

프로젝트 B
 └─ api-builder

운영 배포
 └─ production-builder

작업 전 필요한 Builder를 선택합니다.

Linux 서버 문제 해결

개발팀에서 ARM 서버용 Docker 이미지를 빌드해야 하는 문제가 발생했습니다.

기존 Builder 확인:

docker buildx ls

결과:

NAME

default *

기본 Builder는 ARM64 플랫폼을 지원하지 않았습니다.

관리자는 멀티 플랫폼 Builder로 변경했습니다.

docker buildx use multi-builder

확인:

docker buildx inspect

결과:

Platforms:

linux/amd64

linux/arm64

이후 정상적으로 멀티 플랫폼 이미지를 생성할 수 있었습니다.

Docker Buildx Use 사용 시 주의사항

첫 번째는 Builder 변경 후 반드시 현재 상태를 확인하는 것이 좋습니다.

잘못된 Builder를 사용하면 예상하지 못한 환경에서 이미지가 생성될 수 있습니다.

두 번째는 Builder마다 지원 플랫폼이 다를 수 있습니다.

변경 후:

docker buildx inspect

으로 확인해야 합니다.

세 번째는 자동화 환경에서는 use보다 --builder 옵션이 더 안전할 수 있습니다.

네 번째는 Builder 이름을 명확하게 관리해야 합니다.

Best Practice

Docker Buildx Use를 사용할 때는 다음 방법을 추천합니다.

Builder 이름을 역할별로 관리합니다.
빌드 전 현재 Builder를 확인합니다.
멀티 플랫폼 작업 전 플랫폼을 확인합니다.
CI/CD 전용 Builder를 분리합니다.
중요한 빌드는 --builder 옵션을 활용합니다.
사용하지 않는 Builder는 정리합니다.

자주 묻는 질문

Docker Buildx Use는 Builder를 생성하나요?

아닙니다.

기존에 생성된 Builder를 선택하는 기능입니다.

Builder를 변경하면 이미지가 이동하나요?