소개
Docker Buildx 는 표준 Docker build 명령을 확장하여 멀티 아키텍처 이미지를 생성하기 위한 향상된 기능을 제공합니다. 그러나 사용자는 이 도구를 사용할 때 종종 "docker buildx build requires exactly 1 argument" 오류를 겪게 됩니다. 이 포괄적인 튜토리얼은 Docker Buildx 를 이해하고, 이 일반적인 오류를 진단하며, 효과적인 솔루션을 구현하는 과정을 안내합니다.
이 랩을 마치면 Docker Buildx 를 설정하고, Docker 이미지를 생성하며, "requires exactly 1 argument" 오류를 해결하고, 여러 아키텍처용 이미지를 빌드하는 실질적인 경험을 얻게 될 것입니다. 이러한 기술은 현대 컨테이너화된 애플리케이션 개발 및 배포에 필수적입니다.
Docker Buildx 설정
Docker Buildx 는 Docker 와 함께 사전 설치되어 있지만 사용하기 전에 제대로 설정해야 합니다. 이 단계에서는 Docker 가 설치되었는지 확인하고, Docker Buildx 를 활성화하며, 첫 번째 빌더 인스턴스를 생성합니다.
Docker 설치 확인
먼저 Docker 가 시스템에 설치되어 실행 중인지 확인해 보겠습니다.
docker --version
다음과 유사한 출력을 볼 수 있습니다.
Docker version 20.10.21, build baeda1f
이는 Docker 가 설치되어 사용할 준비가 되었음을 확인합니다.
Docker Buildx 이해
Docker Buildx 는 BuildKit 을 사용하여 Docker 의 기능을 확장하는 CLI 플러그인입니다. 다음을 가능하게 합니다.
- 여러 플랫폼 (예: AMD64, ARM64) 용 이미지를 동시에 빌드
- 보다 효율적인 레이어 캐싱
- 향상된 빌드 성능
- 고급 빌드 기능
Docker Buildx 빌더 생성
새로운 Docker Buildx 빌더를 생성하고 사용해 보겠습니다.
docker buildx create --name mybuilder --use
출력은 다음과 유사해야 합니다.
mybuilder
이제 빌더가 생성되었고 기본값으로 설정되었는지 확인해 보겠습니다.
docker buildx ls
다음과 유사한 출력을 볼 수 있습니다.
NAME/NODE DRIVER/ENDPOINT STATUS PLATFORMS
mybuilder * docker-container
mybuilder0 unix:///var/run/docker.sock inactive
default docker
default default running linux/amd64, linux/386
mybuilder 옆의 별표 (*) 는 현재 활성 빌더임을 나타냅니다.
빌더 검사
빌더의 세부 정보를 살펴보겠습니다.
docker buildx inspect mybuilder
이렇게 하면 지원되는 플랫폼 및 현재 상태를 포함하여 빌더의 구성을 볼 수 있습니다.
이제 Docker Buildx 를 성공적으로 설정했으므로 빌더와 함께 사용할 Dockerfile 을 생성할 준비가 되었습니다.
테스트를 위한 간단한 Dockerfile 생성
Docker Buildx 를 사용하여 이미지를 빌드하기 전에 간단한 Dockerfile 을 생성해야 합니다. 이는 "requires exactly 1 argument" 오류를 이해하기 위한 테스트 케이스 역할을 합니다.
Dockerfile 이해
Dockerfile 은 Docker 이미지를 빌드하기 위한 지침이 포함된 텍스트 문서입니다. 특정 구성으로 컨테이너를 생성하는 프로세스를 자동화합니다.
프로젝트용 디렉토리를 생성해 보겠습니다.
mkdir -p ~/project/buildx-test
cd ~/project/buildx-test
기본 Dockerfile 생성
이제 nano 텍스트 편집기를 사용하여 간단한 Dockerfile 을 생성해 보겠습니다.
nano Dockerfile
다음 내용을 Dockerfile 에 복사하여 붙여넣습니다.
FROM ubuntu:22.04
RUN apt-get update && apt-get install -y \
curl \
nginx \
&& rm -rf /var/lib/apt/lists/*
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]
Ctrl+O를 누른 다음 Enter를 눌러 저장하고, Ctrl+X를 눌러 nano 를 종료합니다.
이 Dockerfile 을 분석해 보겠습니다.
FROM ubuntu:22.04- Ubuntu 22.04 를 기본 이미지로 사용합니다.RUN apt-get update...- 패키지 목록을 업데이트하고 curl 및 nginx 를 설치합니다.EXPOSE 80- 컨테이너가 포트 80 에서 수신 대기함을 나타냅니다.CMD ["nginx", "-g", "daemon off;"]- 컨테이너가 시작될 때 nginx 를 포그라운드에서 실행합니다.
.dockerignore 파일 생성
.dockerignore 파일은 빌드 컨텍스트에 필요하지 않은 파일 및 디렉토리를 제외하여 빌드를 더 빠르고 효율적으로 만드는 데 도움이 됩니다.
nano .dockerignore
다음 내용을 추가합니다.
.git
.gitignore
*.md
Ctrl+O를 누른 다음 Enter를 눌러 저장하고, Ctrl+X를 눌러 nano 를 종료합니다.
프로젝트 구조 확인
파일이 올바르게 생성되었는지 확인해 보겠습니다.
ls -la
다음과 유사한 출력을 볼 수 있습니다.
total 16
drwxrwxr-x 2 labex labex 4096 Jan 1 00:00 .
drwxr-xr-x 3 labex labex 4096 Jan 1 00:00 ..
-rw-rw-r-- 1 labex labex 21 Jan 1 00:00 .dockerignore
-rw-rw-r-- 1 labex labex 159 Jan 1 00:00 Dockerfile
이제 기본 Dockerfile 이 있으므로 다음 단계에서 Docker Buildx 를 테스트하고 "requires exactly 1 argument" 오류를 탐색할 준비가 되었습니다.
"Requires Exactly 1 Argument" 오류 이해 및 해결
이 단계에서는 "requires exactly 1 argument" 오류를 의도적으로 발생시켜 그 원인을 이해한 다음, 해결 방법을 배우겠습니다.
오류 발생시키기
먼저, 아직 해당 디렉토리에 있지 않다면 프로젝트 디렉토리로 이동합니다.
cd ~/project/buildx-test
이제 빌드 컨텍스트를 지정하지 않고 Docker Buildx 를 사용하여 이미지를 빌드해 보겠습니다.
docker buildx build
다음과 유사한 오류 메시지가 표시됩니다.
"docker buildx build" requires exactly 1 argument.
See 'docker buildx build --help'.
Usage: docker buildx build [OPTIONS] PATH | URL | -
이 오류는 docker buildx build 명령이 빌드 컨텍스트 (Dockerfile 이 포함된 디렉토리) 를 인수로 필요로 하기 때문에 발생합니다.
오류 이해
"requires exactly 1 argument" 오류는 Docker Buildx 가 이미지를 빌드하는 데 필요한 파일을 어디에서 찾아야 하는지 알아야 함을 의미합니다. 이 인수는 일반적으로 Dockerfile(빌드 컨텍스트) 이 포함된 디렉토리의 경로입니다.
이 오류를 유발하는 일반적인 시나리오는 다음과 같습니다.
- 빌드 컨텍스트를 지정하는 것을 잊은 경우
- 잘못된 명령 구문을 사용한 경우
- 옵션을 잘못된 순서로 배치한 경우
오류 수정
빌드 컨텍스트를 추가하여 명령을 수정해 보겠습니다. 가장 간단한 방법은 현재 디렉토리를 나타내기 위해 .을 사용하는 것입니다.
docker buildx build .
이번에는 Docker 가 빌드 프로세스를 시작하지만, 이미지를 태그하지 않아 나중에 참조하기 어려울 것입니다.
실행 중인 경우 Ctrl+C로 빌드를 중지하고, 적절한 태그를 사용하여 다시 시도해 보겠습니다.
docker buildx build -t nginx-test:latest .
빌드 진행 상황을 보여주는 출력을 볼 수 있습니다.
[+] Building 12.8s (7/7) FINISHED
=> [internal] load build definition from Dockerfile 0.0s
=> => transferring dockerfile: 203B 0.0s
=> [internal] load .dockerignore 0.0s
=> => transferring context: 34B 0.0s
=> [internal] load metadata for docker.io/library/ubuntu:22.04 0.5s
=> [1/3] FROM docker.io/library/ubuntu:22.04@sha256:... 0.0s
=> CACHED [2/3] RUN apt-get update && apt-get install -y curl nginx 0.0s
=> CACHED [3/3] EXPOSE 80 0.0s
=> exporting to image 0.0s
=> => exporting layers 0.0s
=> => writing image sha256:... 0.0s
=> => naming to docker.io/library/nginx-test:latest 0.0s
다양한 Buildx 옵션 사용
Docker Buildx 와 함께 몇 가지 추가 옵션을 살펴보겠습니다.
- 이미지를 빌드하여 Docker 의 로컬 이미지 저장소에 로드합니다.
docker buildx build --load -t nginx-test:local .
- 빌드 캐시를 사용하지 않고 빌드합니다 (새 빌드 강제).
docker buildx build --no-cache -t nginx-test:nocache .
- 최종 이미지 ID 만 빌드하고 출력합니다.
docker buildx build -q -t nginx-test:quiet .
빌드된 이미지 확인
빌드한 이미지를 확인해 보겠습니다.
docker images | grep nginx-test
다음과 유사한 출력을 볼 수 있습니다.
nginx-test quiet abcdef123456 5 minutes ago 123MB
nginx-test nocache fedcba654321 5 minutes ago 123MB
nginx-test local 123456abcdef 5 minutes ago 123MB
nginx-test latest abcdef123456 5 minutes ago 123MB
이제 Docker Buildx 에서 발생하는 일반적인 "requires exactly 1 argument" 오류를 이해하고 다양한 옵션으로 이미지를 올바르게 빌드하는 방법을 알게 되었습니다.
Docker Buildx 를 사용하여 멀티 아키텍처 이미지 빌드
Docker Buildx 의 가장 강력한 기능 중 하나는 여러 아키텍처에 대한 이미지를 동시에 빌드하는 기능입니다. 이 단계에서는 멀티 아키텍처 이미지를 만드는 방법을 배우겠습니다.
멀티 아키텍처 이미지 이해
멀티 아키텍처 이미지를 사용하면 동일한 이미지 이름이 서로 다른 플랫폼 (AMD64, ARM64 등) 에서 작동할 수 있습니다. 이미지를 가져올 때 Docker 는 호스트 아키텍처에 적합한 버전을 자동으로 선택합니다.
이는 특히 다음과 같은 경우에 유용합니다.
- x86 및 ARM 기반 장치 모두 지원
- 애플리케이션이 다양한 클라우드 제공업체에서 실행되도록 보장
- 서로 다른 아키텍처를 가진 IoT 장치용 빌드
멀티 아키텍처 빌드 설정
Docker Buildx 는 멀티 아키텍처 빌드를 위해 구성되어야 합니다. 먼저, 빌더가 이 기능을 지원하는지 확인해 보겠습니다.
docker buildx inspect --bootstrap mybuilder
빌더를 사용할 수 없다는 오류가 표시되면, 올바른 구성으로 다시 생성해 보겠습니다.
docker buildx rm mybuilder
docker buildx create --name mybuilder --driver docker-container --bootstrap --use
멀티 아키텍처 이미지 생성
이제 여러 아키텍처에 대해 Nginx 이미지를 빌드해 보겠습니다.
docker buildx build --platform linux/amd64,linux/arm64 -t nginx-test:multi .
다음과 유사한 오류 메시지가 표시될 수 있습니다.
error: multiple platforms feature is currently not supported for docker driver. Please switch to a different driver (eg. "docker buildx create --use")
이것은 기본 Docker 드라이버가 멀티 아키텍처 빌드를 지원하지 않기 때문에 발생합니다. 접근 방식을 수정해 보겠습니다.
데모 목적으로, 특정 플랫폼에 대해 별도로 빌드합니다.
docker buildx build --platform linux/amd64 -t nginx-test:amd64 --load .
이렇게 하면 AMD64 아키텍처에 대해 이미지를 특별히 빌드하고 Docker 의 로컬 이미지 저장소에 로드합니다.
빌드 인수 사용
Docker Buildx 를 사용하면 빌드 인수를 사용하여 빌드를 사용자 정의할 수 있습니다. 빌드 인수를 사용하도록 Dockerfile 을 수정해 보겠습니다.
nano Dockerfile
Dockerfile 내용을 다음과 같이 업데이트합니다.
FROM ubuntu:22.04
ARG PACKAGE=nginx
RUN apt-get update && apt-get install -y \
curl \
${PACKAGE} \
&& rm -rf /var/lib/apt/lists/*
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]
Ctrl+O를 누른 다음 Enter를 눌러 저장하고, Ctrl+X를 눌러 nano 를 종료합니다.
이제 사용자 지정 패키지로 이미지를 빌드할 수 있습니다.
docker buildx build --build-arg PACKAGE=nginx-extras -t nginx-extras:latest .
레지스트리에 푸시 (선택 사항)
멀티 아키텍처 이미지를 완전히 활용하려면 일반적으로 레지스트리에 푸시해야 합니다. 이 작업에는 Docker Hub 자격 증명 또는 개인 레지스트리가 필요합니다. 실제 시나리오에서는 명령이 다음과 같습니다.
## Example only - not required for this lab
## docker buildx build --platform linux/amd64,linux/arm64 -t username/nginx-test:multi --push .
이미지 검사
생성한 이미지를 검사해 보겠습니다.
docker images | grep nginx
다음과 유사한 출력을 볼 수 있습니다.
nginx-extras latest abcdef123456 1 minute ago 130MB
nginx-test amd64 123456abcdef 2 minutes ago 123MB
nginx-test latest fedcba654321 10 minutes ago 123MB
이미지 테스트
마지막으로, 이미지를 사용하여 컨테이너를 실행하여 작동하는지 확인해 보겠습니다.
docker run -d --name test-nginx -p 8080:80 nginx-test:latest
컨테이너가 실행 중인지 확인합니다.
docker ps
컨테이너가 실행 중임을 나타내는 출력을 볼 수 있습니다.
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
abcdef123456 nginx-test:latest "nginx -g 'daemon of…" 10 seconds ago Up 10 seconds 0.0.0.0:8080->80/tcp test-nginx
nginx 서버가 응답하는지 확인하기 위해 curl 을 사용해 보겠습니다.
curl http://localhost:8080
기본 Nginx 환영 페이지 HTML 을 볼 수 있습니다.
작업이 완료되면 컨테이너를 정리합니다.
docker stop test-nginx
docker rm test-nginx
축하합니다! Docker Buildx 로 성공적으로 작업하고, "requires exactly 1 argument" 오류를 이해하고 해결했으며, 서로 다른 아키텍처에 대한 특수 빌드를 만드는 방법을 배웠습니다.
요약
이 Lab 에서는 Docker Buildx 를 실질적으로 경험하고, 일반적인 "requires exactly 1 argument" 오류를 해결하는 방법을 배웠습니다. 다음은 수행한 작업입니다.
- Docker Buildx 를 설정하고 빌더 인스턴스를 생성했습니다.
- 테스트를 위한 기본 Dockerfile 을 생성했습니다.
- "requires exactly 1 argument" 오류를 겪고, 이해하고, 해결했습니다.
- 다양한 옵션과 구성으로 Docker 이미지를 빌드했습니다.
- 멀티 아키텍처 이미지 빌드의 기본 사항을 배웠습니다.
이러한 기술은 애플리케이션이 다양한 하드웨어 플랫폼에서 실행되어야 하는 현대 개발 환경에서 Docker 를 사용하는 데 탄탄한 기반을 제공합니다. 이제 일반적인 오류를 피하면서 효율적이고 플랫폼별 컨테이너 이미지를 만들기 위해 Docker Buildx 를 자신 있게 사용할 수 있습니다.
Docker 여정을 계속 진행하면서, 더 발전된 Buildx 기능 탐색, CI/CD 파이프라인에 통합, 그리고 어디에서나 실행될 수 있는 진정한 휴대용 애플리케이션을 빌드하는 데 활용하는 것을 고려해 보십시오.
