Docker Buildx를 사용하여 여러 이미지를 빌드하다 보면 하나의 Builder만 사용하는 것이 아니라 프로젝트별, 환경별로 여러 Builder를 생성하는 경우가 있습니다.
예를 들어 다음과 같은 환경을 구성할 수 있습니다.
- 개발용 Builder
- 운영 배포용 Builder
- CI/CD 전용 Builder
- 멀티 플랫폼 빌드용 Builder
Builder가 여러 개 생성되면 현재 어떤 Builder가 존재하는지, 어떤 Builder가 활성화되어 있는지, 어떤 플랫폼을 지원하는지 확인해야 합니다.
이때 사용하는 명령어가 바로 docker buildx ls입니다.
Docker Buildx LS는 현재 등록된 Buildx Builder 목록을 확인하는 명령어입니다. Builder 이름, Driver, 상태, 지원 플랫폼 정보를 확인할 수 있어 Buildx 환경 관리에서 가장 기본적으로 사용하는 명령어입니다.
이번 글에서는 Docker Buildx LS의 개념부터 기본 사용법, 출력 결과 해석, Builder 관리 방법, 실무 활용 방법까지 자세히 알아보겠습니다.
Docker Buildx LS란 무엇인가?
Docker Buildx LS는 현재 생성된 Buildx Builder 목록을 출력하는 명령어입니다.
현재 사용 가능한 Builder와 활성화된 Builder를 확인할 수 있으며, 멀티 플랫폼 빌드 환경을 관리할 때 필수적으로 사용됩니다.
Docker Buildx LS는 언제 사용하는가?
다음과 같은 상황에서 사용합니다.
- 생성된 Builder 확인
- 현재 활성 Builder 확인
- 지원 플랫폼 확인
- Buildx 환경 점검
- 빌드 오류 분석
- CI/CD Builder 관리
여러 Builder를 사용하는 환경에서는 작업 전에 항상 확인하는 것이 좋습니다.
Docker Buildx LS 기본 사용법
가장 기본적인 사용 방법입니다.
docker buildx ls실행 결과 예:
NAME/NODE DRIVER/ENDPOINT STATUS PLATFORMS
default docker
default default running linux/amd64
multi-builder * docker-container
multi-builder0 desktop-linux running linux/amd64,linux/arm64현재 등록된 Builder 정보를 확인할 수 있습니다.
출력 결과 이해하기
Docker Buildx LS 결과에서 주요 항목은 다음과 같습니다.
NAME/NODE
Builder 이름과 Node 정보를 의미합니다.
예:
multi-builder *별표(*)가 표시된 Builder가 현재 활성화된 Builder입니다.
DRIVER
Builder가 사용하는 실행 방식을 의미합니다.
대표적인 Driver:
docker
docker-container
kubernetes
remote멀티 플랫폼 빌드에서는 보통 docker-container Driver를 사용합니다.
STATUS
Builder 상태를 표시합니다.
예:
running
inactive정상적으로 사용할 수 있는 Builder는 running 상태입니다.
PLATFORMS
해당 Builder가 지원하는 플랫폼입니다.
예:
linux/amd64
linux/arm64멀티 플랫폼 빌드 가능 여부를 확인할 수 있습니다.
현재 활성 Builder 확인하기
현재 사용 중인 Builder는 별표(*)로 표시됩니다.
예:
multi-builder *다른 Builder를 사용하려면:
docker buildx use builder-name으로 변경할 수 있습니다.
특정 Builder 확인하기
Builder 상세 정보가 필요하면:
docker buildx inspect builder-name을 사용합니다.
LS는 목록 확인용이고 Inspect는 상세 정보 확인용입니다.
Builder 상태 확인하기
Builder가 정상적으로 실행 중인지 확인합니다.
docker buildx ls상태:
running이면 정상적으로 사용할 수 있습니다.
만약 비활성 상태라면:
docker buildx inspect --bootstrap으로 Builder를 시작할 수 있습니다.
여러 Builder 비교하기
예:
NAME DRIVER
default docker
dev-builder docker-container
production-builder docker-container각 환경별 Builder를 비교하여 원하는 빌드 환경을 선택할 수 있습니다.
Docker Buildx LS 실무 활용 예제
Docker Buildx LS는 여러 Builder를 관리하는 환경에서 현재 빌드 환경을 확인하고 올바른 Builder를 선택하기 위해 사용하는 기본 명령어입니다.
특히 멀티 플랫폼 이미지 빌드나 CI/CD 환경에서는 Builder 상태 확인이 매우 중요합니다.
현재 Builder 목록 확인하기
가장 기본적인 사용 방법입니다.
docker buildx ls출력 예:
NAME/NODE DRIVER
default docker
multi-builder * docker-container
ci-builder docker-container현재 multi-builder가 활성화된 상태입니다.
활성 Builder 확인하기
별표(*)가 표시된 Builder가 현재 사용 중인 Builder입니다.
예:
multi-builder *현재 빌드는 해당 Builder 환경에서 실행됩니다.
Builder 변경 후 확인하기
다른 Builder로 변경합니다.
docker buildx use ci-builder확인:
docker buildx ls결과:
ci-builder *새로운 Builder가 활성화된 것을 확인할 수 있습니다.
지원 플랫폼 확인하기
멀티 플랫폼 빌드를 하기 전에 지원 환경을 확인합니다.
docker buildx ls출력:
PLATFORMS
linux/amd64
linux/arm64
linux/arm/v7해당 Builder가 ARM과 AMD64 빌드를 지원하는지 확인할 수 있습니다.
Builder 상태 확인하기
Builder가 정상 실행 중인지 확인합니다.
docker buildx ls상태:
running정상적으로 사용할 수 있는 상태입니다.
비정상 상태라면:
docker buildx inspect --bootstrap으로 Builder를 시작합니다.
CI/CD 전용 Builder 확인하기
자동 빌드 환경에서는 전용 Builder를 구성하는 경우가 많습니다.
예:
NAME DRIVER
development-builder docker-container
ci-builder * docker-container
production-builder docker-container현재 어떤 Builder가 CI 작업에 사용되는지 쉽게 확인할 수 있습니다.
사용하지 않는 Builder 확인하기
오래된 Builder가 남아 있는 경우:
docker buildx ls목록을 확인합니다.
필요 없는 Builder는 삭제할 수 있습니다.
docker buildx rm old-builderLinux 서버 문제 해결
CI/CD 서버에서 Docker 이미지 빌드가 실패하는 문제가 발생했습니다.
관리자는 먼저 현재 Buildx 환경을 확인했습니다.
docker buildx ls확인 결과:
NAME DRIVER
default docker
old-builder docker-container기존 Builder가 오래된 상태였고 필요한 ARM 플랫폼을 지원하지 않았습니다.
새로운 멀티 플랫폼 Builder를 생성했습니다.
docker buildx create \
--name production-builder \
--driver docker-container \
--use다시 확인:
docker buildx ls결과:
production-builder * docker-container지원 플랫폼도 확인했습니다.
linux/amd64
linux/arm64이후 멀티 플랫폼 이미지 빌드가 정상적으로 진행되었습니다.
Docker Buildx LS는 빌드 오류를 해결하거나 현재 빌드 환경을 점검할 때 가장 먼저 확인하는 명령어입니다.
Docker Buildx LS 사용 시 주의사항
Docker Buildx LS를 사용할 때는 다음 사항을 확인해야 합니다.
첫 번째는 현재 활성 Builder를 반드시 확인해야 합니다.
잘못된 Builder를 사용하면 예상하지 못한 플랫폼으로 이미지가 생성될 수 있습니다.
두 번째는 Builder 상태가 running인지 확인해야 합니다.
중지된 Builder는 빌드 작업을 수행할 수 없습니다.
세 번째는 멀티 플랫폼 빌드 전에 지원 플랫폼을 확인해야 합니다.
네 번째는 사용하지 않는 Builder를 정리해야 관리가 쉬워집니다.
Best Practice
Docker Buildx LS를 사용할 때는 다음 방법을 추천합니다.
- 빌드 전 현재 Builder를 확인합니다.
- 프로젝트별 Builder를 구분합니다.
- 멀티 플랫폼 지원 여부를 확인합니다.
- CI/CD Builder 상태를 정기 점검합니다.
- 오래된 Builder는 삭제합니다.
- 중요한 빌드 전 Inspect와 함께 확인합니다.
이러한 방법을 적용하면 Docker Buildx 환경을 안정적으로 관리할 수 있습니다.
자주 묻는 질문
Docker Buildx LS는 무엇을 확인하나요?
현재 등록된 Builder 목록, Driver, 상태, 지원 플랫폼을 확인합니다.
별표(*)는 무엇인가요?
현재 활성화된 Builder를 의미합니다.
Builder가 여러 개 있으면 어떤 것을 사용하나요?
별표(*)가 표시된 활성 Builder가 기본으로 사용됩니다.
Buildx LS는 이미지를 확인하나요?
아닙니다.
Builder 환경 정보만 확인하며 이미지는 docker images로 확인합니다.
마무리
Docker Buildx LS는 현재 등록된 Builder 환경을 확인하는 가장 기본적인 Buildx 관리 명령어입니다.
여러 Builder를 사용하는 환경에서는 현재 활성화된 Builder, 지원 플랫폼, 실행 상태를 확인하는 것이 안정적인 이미지 빌드의 핵심입니다.
특히 멀티 플랫폼 이미지 빌드나 CI/CD 환경에서는 작업 전에 docker buildx ls로 Builder 상태를 확인하고, 필요하면 docker buildx inspect와 함께 활용하면 더욱 안정적인 Docker 빌드 환경을 구축할 수 있습니다.