Docker 이미지를 생성할 때 환경에 따라 다른 값을 사용해야 하는 경우가 있습니다.
예:
- 개발 버전과 운영 버전 구분
- 애플리케이션 버전 변경
- 빌드 환경 설정 변경
- 패키지 버전 지정
- 이미지 생성 정보 추가
이런 값을 Dockerfile 내부에 직접 작성하면 관리가 어려워집니다.
이때 사용하는 기능이 바로 Docker Buildx Build –build-arg입니다.
--build-arg 옵션은 Dockerfile의 ARG 변수에 외부 값을 전달하는 기능입니다.
예:
docker buildx build \
--build-arg VERSION=1.0.0 \
-t app:v1 .Dockerfile에서 전달받은 값을 빌드 과정에 사용할 수 있습니다.
이번 글에서는 Docker Buildx Build –build-arg의 개념부터 ARG 사용법, 환경별 빌드 설정, CI/CD 활용 방법까지 자세히 알아보겠습니다.
Docker Buildx Build –build-arg란 무엇인가?
--build-arg는 Docker 이미지 빌드 과정에서 사용할 변수를 전달하는 옵션입니다.
기본 형식:
docker buildx build \
--build-arg 변수명=값 .Dockerfile:
ARG VERSION
RUN echo $VERSION빌드:
docker buildx build \
--build-arg VERSION=1.0 .결과:
1.0값이 전달됩니다.
Dockerfile ARG란 무엇인가?
ARG는 Docker 이미지 빌드 과정에서만 사용하는 변수입니다.
예:
ARG APP_VERSION
RUN echo $APP_VERSION특징:
- 빌드 시 사용
- 컨테이너 실행 후에는 기본적으로 존재하지 않음
- 이미지 생성 과정 제어 가능
ARG와 ENV 차이
비슷하지만 목적이 다릅니다.
ARG
빌드 전용 변수:
ARG VERSION사용:
--build-arg VERSION=1.0ENV
컨테이너 실행 환경 변수:
ENV VERSION=1.0컨테이너 내부에서도 사용할 수 있습니다.
정리:
ARG = 빌드 과정
ENV = 실행 환경Docker Buildx Build –build-arg 기본 사용법
Dockerfile:
FROM ubuntu
ARG MESSAGE
RUN echo $MESSAGE빌드:
docker buildx build \
--build-arg MESSAGE="Hello Docker" \
-t test:v1 .빌드 과정에서 값이 적용됩니다.
여러 Build Argument 전달하기
여러 변수를 사용할 수 있습니다.
Dockerfile:
ARG VERSION
ARG ENVIRONMENT빌드:
docker buildx build \
--build-arg VERSION=1.0 \
--build-arg ENVIRONMENT=production \
-t app:v1 .여러 설정을 동시에 전달할 수 있습니다.
기본값 지정하기
Dockerfile에서 기본값을 설정할 수 있습니다.
예:
ARG VERSION=latest
RUN echo $VERSION빌드 시 값을 전달하지 않으면:
latest가 사용됩니다.
전달하면:
docker buildx build \
--build-arg VERSION=1.2 .1.2가 적용됩니다.
Docker Buildx Build –build-arg 실무 활용 예제
애플리케이션 버전 관리
Dockerfile:
ARG APP_VERSION
LABEL version=$APP_VERSION빌드:
docker buildx build \
--build-arg APP_VERSION=2.0.0 \
-t app:v2 .이미지 버전 정보를 관리할 수 있습니다.
운영·개발 환경 분리
Dockerfile:
ARG ENV
RUN if [ "$ENV" = "production" ]; then \
echo production; \
fi개발:
docker buildx build \
--build-arg ENV=development .운영:
docker buildx build \
--build-arg ENV=production .환경별 빌드가 가능합니다.
CI/CD 환경 활용
CI 파이프라인에서:
docker buildx build \
--build-arg BUILD_NUMBER=${BUILD_NUMBER} \
-t company/app:${BUILD_NUMBER} \
--push .자동 빌드 번호를 이미지에 전달할 수 있습니다.
Linux 서버 문제 해결
CI/CD 환경에서 빌드 버전을 자동으로 넣어야 했습니다.
기존 Dockerfile:
RUN echo version문제:
모든 빌드가 같은 버전 사용ARG 추가:
ARG VERSION
RUN echo $VERSION빌드:
docker buildx build \
--build-arg VERSION=2026.07.28 \
-t app:v1 .결과:
VERSION=2026.07.28CI/CD에서 자동으로 버전 관리가 가능해졌습니다.
Docker Buildx Build –build-arg 사용 시 주의사항
첫 번째는 민감한 정보를 전달하는 용도로 사용하면 안 됩니다.
예:
- 비밀번호
- API Key
- Secret Token
이런 정보는 --secret 기능을 사용하는 것이 좋습니다.
두 번째는 ARG 값은 이미지 History에 남을 수 있습니다.
세 번째는 기본값을 신중하게 설정해야 합니다.
네 번째는 빌드 목적과 실행 환경 변수를 구분해야 합니다.
Best Practice
Docker Buildx Build –build-arg 활용 방법:
- 버전 정보 전달에 활용
- 환경별 빌드 설정 관리
- CI/CD 변수 연동
- 민감 정보는 사용하지 않기
- ARG와 ENV 목적 구분
- 기본값 설정 활용
자주 묻는 질문
Docker Buildx Build –build-arg는 무엇인가요?
Dockerfile ARG 변수에 값을 전달하는 옵션입니다.
ARG와 ENV 차이는 무엇인가요?
ARG는 빌드 과정, ENV는 컨테이너 실행 환경에서 사용합니다.
비밀번호를 –build-arg로 전달해도 되나요?
권장하지 않습니다.
민감 정보는 Build Secret 기능을 사용하는 것이 좋습니다.
여러 값을 전달할 수 있나요?
가능합니다.
여러 개의 --build-arg 옵션을 사용할 수 있습니다.
마무리
Docker Buildx Build –build-arg는 Docker 이미지 빌드 과정을 유연하게 관리할 수 있도록 해주는 중요한 기능입니다.
버전 정보, 환경 설정, 빌드 옵션 등을 외부에서 전달할 수 있어 하나의 Dockerfile로 다양한 환경을 지원할 수 있습니다.
특히 CI/CD 환경에서는 자동 버전 관리와 환경별 이미지 생성을 위해 자주 활용되며, ARG와 ENV의 차이를 이해하고 올바르게 사용하는 것이 중요합니다.