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

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

예를 들어 다음과 같은 환경을 구성할 수 있습니다.

• 개발용 Builder
• 운영용 Builder
• CI/CD 전용 Builder
• 멀티 플랫폼 빌드용 Builder

여러 Builder가 존재하면 현재 어떤 Builder가 활성화되어 있는지, 어떤 Builder를 사용하여 이미지가 빌드되는지 확인하고 전환해야 합니다.

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

Docker Buildx Use는 현재 사용할 Buildx Builder를 변경하는 명령어입니다. 원하는 Builder를 활성화하면 이후 실행하는 docker buildx build 명령은 선택한 Builder 환경에서 실행됩니다.

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

Docker Buildx Use란 무엇인가?

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

Docker Buildx는 여러 개의 Builder를 동시에 관리할 수 있으며, 별표(*)가 표시된 Builder가 현재 사용 중인 Builder입니다.

예:

NAME

default

multi-builder *

현재 multi-builder가 활성화되어 있다는 의미입니다.

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

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

• 다른 Builder로 전환
• 프로젝트별 빌드 환경 변경
• CI/CD Builder 선택
• 멀티 플랫폼 Builder 사용
• 빌드 오류 해결

여러 빌드 환경을 관리하는 경우 반드시 필요한 기능입니다.

Docker Buildx Builder 목록 확인하기

Builder를 변경하기 전에 현재 목록을 확인합니다.

docker buildx ls

출력 예:

NAME                 DRIVER

default              docker

multi-builder *      docker-container

ci-builder           docker-container

현재 multi-builder가 활성 상태입니다.

Docker Buildx Use 기본 사용법

Builder 변경 방법입니다.

docker buildx use ci-builder

이제 ci-builder가 현재 활성 Builder가 됩니다.

확인:

docker buildx ls

결과:

ci-builder *

특정 Builder로 전환 후 빌드하기

Builder 변경 후 이미지를 빌드합니다.

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

현재 활성화된 Builder를 사용하여 빌드됩니다.

현재 Builder 확인하기

현재 사용 중인 Builder는 목록에서 확인할 수 있습니다.

docker buildx ls

또는:

docker buildx inspect

현재 Builder 상세 정보를 확인할 수 있습니다.

일회성 Builder 지정하기

현재 Builder를 변경하지 않고 특정 Builder를 사용할 수도 있습니다.

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

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

Docker Buildx Use와 Create 차이

두 명령어는 목적이 다릅니다.

Docker Buildx Create

역할:

• 새로운 Builder 생성

예:

docker buildx create --name new-builder

Docker Buildx Use

역할:

• 기존 Builder 전환

예:

docker buildx use new-builder

Create는 생성, Use는 선택이라고 이해하면 됩니다.

Docker Buildx Use와 LS 관계

Builder 변경 후에는 LS로 확인하는 것이 좋습니다.

변경:

docker buildx use production-builder

확인:

docker buildx ls

별표(*)가 이동하면 정상적으로 변경된 것입니다.

Docker Buildx Use 실무 활용 예제

Docker Buildx Use는 여러 Builder 환경을 운영할 때 원하는 빌드 환경으로 빠르게 전환하기 위해 사용합니다.

특히 개발 환경과 운영 환경의 Builder를 분리하거나, ARM·AMD64 멀티 플랫폼 빌드를 위한 Builder를 변경할 때 매우 유용합니다.

멀티 플랫폼 Builder로 전환하기

현재 Builder 확인:

docker buildx ls

출력:

NAME                  DRIVER

default               docker

multi-builder *       docker-container
production-builder    docker-container

운영용 Builder로 변경:

docker buildx use production-builder

확인:

docker buildx ls

결과:

production-builder *

이제 이후 Buildx 빌드는 운영용 Builder에서 실행됩니다.

CI/CD 전용 Builder 사용하기

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

현재:

docker buildx use ci-builder

확인:

docker buildx inspect

CI용 BuildKit 환경에서 이미지가 생성됩니다.

특정 Builder를 지정하여 빌드하기

Builder를 변경하지 않고 일회성으로 사용할 수 있습니다.

docker buildx build \
--builder multi-builder \
--platform linux/amd64,linux/arm64 \
-t my-app:v1 .

현재 활성 Builder는 유지하면서 원하는 Builder만 사용할 수 있습니다.

프로젝트별 Builder 전환하기

프로젝트마다 Builder를 분리하는 경우:

프로젝트 A

↓

app-builder


프로젝트 B

↓

api-builder


운영 배포

↓

production-builder

작업 시작 전에 필요한 Builder로 변경합니다.

예:

docker buildx use api-builder

프로젝트별 빌드 환경을 명확하게 관리할 수 있습니다.

Builder 변경 후 상태 확인하기

전환 후에는 반드시 확인하는 것이 좋습니다.

docker buildx ls

또는:

docker buildx inspect

현재 사용 중인 Builder와 플랫폼 정보를 확인할 수 있습니다.

Linux 서버 문제 해결

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

기존에는 기본 Builder를 사용하고 있었습니다.

확인:

docker buildx ls

결과:

NAME
default *

기본 Builder는 필요한 ARM 플랫폼 빌드를 지원하지 않았습니다.

멀티 플랫폼 Builder로 변경했습니다.

docker buildx use multi-builder

확인:

docker buildx inspect

결과:

Platforms:
linux/amd64
linux/arm64

이후 이미지 빌드:

docker buildx build \
--platform linux/amd64,linux/arm64 \
-t company/app:v1 \
--push .

ARM과 AMD64 환경 모두 지원하는 이미지가 정상적으로 생성되었습니다.

Docker Buildx Use를 활용하면 상황에 맞는 Builder를 선택하여 효율적인 이미지 빌드 환경을 운영할 수 있습니다.

Docker Buildx Use 사용 시 주의사항

Docker Buildx Use를 사용할 때는 다음 사항을 확인해야 합니다.

첫 번째는 현재 활성 Builder를 항상 확인해야 합니다.

잘못된 Builder를 사용하면 원하는 플랫폼으로 이미지가 생성되지 않을 수 있습니다.

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

전환 후:

docker buildx inspect

으로 확인하는 것이 좋습니다.

세 번째는 운영 환경에서는 빌드 전용 Builder와 테스트용 Builder를 구분하는 것이 안전합니다.

네 번째는 자동화 환경에서는 전역 변경보다 --builder 옵션 사용이 더 안전할 수 있습니다.

Best Practice

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

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

이러한 방법을 적용하면 Docker Buildx 환경을 더욱 안정적으로 운영할 수 있습니다.

자주 묻는 질문

Docker Buildx Use는 Builder를 새로 만드나요?

아닙니다.

이미 생성된 Builder를 선택하는 기능입니다.

현재 활성 Builder는 어떻게 확인하나요?

다음 명령으로 확인할 수 있습니다.

docker buildx ls

별표(*)가 현재 Builder입니다.

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

아닙니다.

빌드 작업을 수행할 Builder만 변경됩니다.

Docker Buildx Use와 –builder 옵션 차이는 무엇인가요?

use는 기본 Builder를 변경하고, --builder는 특정 명령에서만 Builder를 지정합니다.

마무리

Docker Buildx Use는 여러 Builder 환경을 관리할 때 원하는 빌드 환경으로 전환하는 핵심 명령어입니다.

멀티 플랫폼 이미지 빌드, CI/CD 자동화, 프로젝트별 빌드 환경 분리 등 다양한 상황에서 활용할 수 있으며, 올바른 Builder를 선택하면 더욱 안정적인 Docker 이미지 생성 환경을 구축할 수 있습니다.

특히 빌드 전 docker buildx ls로 현재 Builder를 확인하고, 필요하면 docker buildx inspect로 상세 설정을 검증하는 습관이 중요합니다.