Docker Buildx Inspect

Docker Buildx Inspect 사용법 완벽 가이드! Buildx Builder 상세 정보 확인하기

작성자:

Docker Buildx를 사용하여 여러 Docker 이미지를 빌드하다 보면 다양한 Builder 환경을 구성하게 됩니다.

예를 들어 개발용 Builder, 운영용 Builder, CI/CD 전용 Builder, 멀티 플랫폼 빌드용 Builder 등 여러 환경을 동시에 관리할 수 있습니다.

하지만 Builder가 많아질수록 현재 Builder가 어떤 설정으로 동작하는지 확인하는 과정이 중요해집니다.

특히 다음과 같은 상황에서는 Builder 상세 정보 확인이 필요합니다.

  • 멀티 플랫폼 빌드 오류 발생
  • BuildKit 실행 상태 확인
  • 지원 플랫폼 확인
  • 원격 Builder 연결 문제 해결
  • CI/CD 빌드 환경 점검

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

Docker Buildx Inspect는 Buildx Builder의 상세 정보를 확인하는 명령어입니다. Builder 이름, Driver, Node 상태, BuildKit 상태, 지원 플랫폼 등을 확인할 수 있어 Docker 빌드 환경 관리에서 매우 중요한 역할을 합니다.

이번 글에서는 Docker Buildx Inspect의 개념부터 기본 사용법, 출력 결과 해석, 실무 활용 방법까지 자세히 알아보겠습니다.

Docker Buildx Inspect란 무엇인가?

Docker Buildx Inspect는 현재 사용 중인 Builder 또는 특정 Builder의 상세 설정 정보를 확인하는 명령어입니다.

docker buildx ls가 Builder 목록을 확인하는 명령어라면, docker buildx inspect는 선택한 Builder 내부 정보를 분석하는 명령어입니다.

확인할 수 있는 정보:

  • Builder 이름
  • Driver 종류
  • Node 정보
  • Endpoint 정보
  • BuildKit 상태
  • 지원 플랫폼

Docker Buildx 환경을 관리할 때 필수적으로 사용하는 명령어입니다.

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

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

Builder 설정 확인

생성한 Builder가 어떤 환경으로 구성되어 있는지 확인합니다.

멀티 플랫폼 빌드 전 확인

ARM64, AMD64 등 지원 플랫폼을 확인합니다.

빌드 오류 분석

BuildKit 상태나 Builder 연결 문제를 확인합니다.

CI/CD 환경 점검

자동 빌드 서버의 Builder 상태를 확인합니다.

Docker Buildx Inspect 기본 사용법

현재 활성화된 Builder 정보를 확인합니다.

docker buildx inspect

특정 Builder를 확인하려면:

docker buildx inspect builder-name

예:

docker buildx inspect production-builder

Docker Buildx Inspect 출력 결과 확인하기

예시 출력:

Name:          production-builder

Driver:
docker-container

Nodes:
Name:          production-builder0
Endpoint:      desktop-linux
Status:        running

Platforms:
linux/amd64
linux/arm64

각 항목을 통해 Builder의 전체 상태를 확인할 수 있습니다.

출력 결과 해석하기

Name

Builder 이름을 표시합니다.

예:

Name: production-builder

현재 확인 중인 Builder 이름입니다.

Driver

Builder가 사용하는 실행 방식을 표시합니다.

예:

Driver:
docker-container

대표적인 Driver:

  • docker
  • docker-container
  • kubernetes
  • remote

멀티 플랫폼 빌드에서는 일반적으로 docker-container Driver를 사용합니다.

Nodes

Builder를 구성하는 Node 정보를 표시합니다.

예:

Nodes:
production-builder0

하나의 Builder가 여러 Node로 구성된 경우 각각 표시됩니다.

Status

현재 Builder 실행 상태입니다.

예:

Status: running

정상적으로 빌드 가능한 상태입니다.

Platforms

지원하는 CPU 플랫폼 정보입니다.

예:

Platforms:
linux/amd64
linux/arm64

멀티 플랫폼 이미지 생성 가능 여부를 확인할 수 있습니다.

Bootstrap 옵션 사용하기

Builder가 정상적으로 실행되지 않거나 BuildKit 상태를 확인할 때 사용합니다.

docker buildx inspect --bootstrap

이 명령은 BuildKit 실행 환경을 준비하고 상태를 확인합니다.

출력:

Status:
running

정상 실행 상태인지 확인할 수 있습니다.

특정 Builder Bootstrap 확인하기

특정 Builder를 지정할 수도 있습니다.

docker buildx inspect production-builder --bootstrap

운영용 Builder 상태를 점검할 때 활용합니다.

Docker Buildx LS와 Inspect 차이

두 명령어는 비슷해 보이지만 용도가 다릅니다.

Docker Buildx LS

확인 내용:

  • Builder 목록
  • 활성 Builder
  • Driver
  • 지원 플랫폼

명령어:

docker buildx ls

Docker Buildx Inspect

확인 내용:

  • Builder 상세 설정
  • Node 정보
  • BuildKit 상태
  • Endpoint 정보

명령어:

docker buildx inspect

간단히 정리하면:

LS = 목록 확인

Inspect = 상세 분석

입니다.

Docker Buildx Inspect 실무 활용 예제

멀티 플랫폼 지원 확인

빌드 전에 플랫폼을 확인합니다.

docker buildx inspect

결과:

Platforms:
linux/amd64
linux/arm64

ARM과 AMD64 빌드가 가능한 것을 확인할 수 있습니다.

원격 Builder 연결 확인

원격 빌드 서버를 사용하는 경우:

docker buildx inspect remote-builder

확인:

  • Endpoint
  • Node 상태
  • Driver

원격 연결 오류 분석에 활용합니다.

CI/CD Builder 상태 확인

자동 빌드 환경에서는:

docker buildx inspect ci-builder --bootstrap

BuildKit 실행 상태를 확인합니다.

Linux 서버 문제 해결

CI/CD 환경에서 ARM64 이미지 빌드가 실패하는 문제가 발생했습니다.

먼저 Builder 목록을 확인했습니다.

docker buildx ls

활성 Builder를 확인한 후 상세 정보를 확인했습니다.

docker buildx inspect production-builder

결과:

Platforms:
linux/amd64

확인 결과 ARM64 플랫폼이 지원되지 않는 Builder였습니다.

새로운 멀티 플랫폼 Builder를 생성했습니다.

docker buildx create \
--name multi-builder \
--driver docker-container \
--use

다시 확인:

docker buildx inspect --bootstrap

결과:

Platforms:
linux/amd64
linux/arm64

이후 ARM64와 AMD64 이미지를 정상적으로 빌드할 수 있었습니다.

Docker Buildx Inspect 사용 시 주의사항

첫 번째는 Inspect는 설정 확인 명령어라는 점입니다.

이미지를 빌드하거나 Builder 설정을 변경하지 않습니다.

두 번째는 --bootstrap 사용 시 BuildKit 컨테이너가 실행될 수 있습니다.

서버 리소스를 사용할 수 있으므로 필요할 때 사용하는 것이 좋습니다.

세 번째는 멀티 플랫폼 빌드 전 반드시 지원 플랫폼을 확인해야 합니다.

네 번째는 Builder가 여러 개인 경우 이름을 명확하게 관리해야 합니다.

Best Practice

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

  • 빌드 전 Builder 상태를 확인합니다.
  • 멀티 플랫폼 작업 전 지원 플랫폼을 확인합니다.
  • 오류 발생 시 Inspect로 원인을 분석합니다.
  • CI/CD Builder 상태를 정기 점검합니다.
  • Builder 이름을 환경별로 구분합니다.
  • 사용하지 않는 Builder는 정리합니다.

자주 묻는 질문

Docker Buildx Inspect는 무엇을 확인하나요?

Builder 이름, Driver, Node 상태, BuildKit 정보, 지원 플랫폼 등을 확인합니다.

Inspect와 LS 중 어떤 것을 사용해야 하나요?

전체 Builder 확인은 LS, 특정 Builder 상세 확인은 Inspect를 사용합니다.

Inspect를 실행하면 이미지가 생성되나요?

아닙니다.

Builder 설정 정보만 확인합니다.

–bootstrap은 언제 사용하나요?

Builder가 정상 실행되지 않거나 BuildKit 상태를 확인할 때 사용합니다.

마무리

Docker Buildx Inspect는 Buildx Builder의 상세 정보를 확인하는 핵심 관리 명령어입니다.

Builder의 Driver, Node 상태, 지원 플랫폼, BuildKit 실행 상태를 확인할 수 있어 멀티 플랫폼 빌드와 CI/CD 환경 관리에서 매우 중요한 역할을 합니다.

특히 Docker 이미지 빌드 오류가 발생했을 때 docker buildx ls로 Builder 목록을 확인한 후 docker buildx inspect를 활용하면 문제 원인을 빠르게 파악할 수 있습니다.

안정적인 Docker 빌드 환경을 운영하기 위해서는 Builder 상태 확인과 정기적인 점검이 필수입니다.

댓글 남기기