Docker 이미지를 여러 환경에서 운영하다 보면 같은 Dockerfile을 사용하면서도 설정값을 다르게 적용해야 하는 경우가 많습니다.

예:

• 개발 환경(dev)
• 테스트 환경(test)
• 운영 환경(production)
• 서버별 설정
• 버전 변경
• 빌드 옵션 변경

이때 Docker Buildx Bake에서는 Args(Build Arguments) 기능을 사용하여 빌드 과정에 필요한 값을 전달할 수 있습니다.

예:

docker-bake.hcl

target "app" {

  args = {
    APP_VERSION = "1.0.0"
    ENVIRONMENT = "production"
  }

}

Dockerfile:

FROM alpine

ARG APP_VERSION

ARG ENVIRONMENT

RUN echo "Version: $APP_VERSION"

RUN echo "Environment: $ENVIRONMENT"

실행:

docker buildx bake app

결과:

Build Argument 전달

↓

Dockerfile 적용

↓

Image 생성

이번 글에서는 Docker Buildx Bake Args의 개념부터 ARG 설정 방법, 환경별 빌드 관리, CI/CD 활용, Dockerfile 연동까지 자세히 알아보겠습니다.

Docker Buildx Bake Args란 무엇인가?

Docker Buildx Bake Args는 Docker Image를 빌드할 때 Dockerfile에 값을 전달하는 기능입니다.

기본 구조:

Docker Buildx Bake

↓

Build Arguments 전달

↓

Dockerfile ARG 사용

↓

Image 생성

Args는 Build 과정에서만 사용되는 변수입니다.

Docker Buildx Bake Args가 필요한 이유

하나의 Dockerfile을 여러 환경에서 사용하는 경우 설정값 변경이 필요합니다.

기존 방식:

Dockerfile 수정

↓

다시 Build

↓

환경별 파일 관리

문제:

• Dockerfile 중복 증가
• 관리 어려움
• 실수 발생 가능

Args 사용:

하나의 Dockerfile

↓

환경별 Args 전달

↓

다양한 Image 생성

장점:

• Dockerfile 재사용
• 환경별 설정 가능
• Build 자동화
• 관리 편리

Docker Buildx Bake Args 기본 설정

docker-bake.hcl:

target "app" {

  args = {

    NODE_VERSION = "20"

  }

}

Dockerfile:

FROM node:${NODE_VERSION}

ARG NODE_VERSION

빌드:

docker buildx bake app

Build 과정에서 값이 전달됩니다.

Docker Buildx Bake Args와 Dockerfile ARG 사용법

Dockerfile:

FROM ubuntu:22.04

ARG APP_ENV

RUN echo $APP_ENV

Bake 설정:

target "app" {

  args = {

    APP_ENV = "production"

  }

}

결과:

APP_ENV

↓

production

↓

Docker Build 적용

Docker Buildx Bake Args 환경별 관리

개발 환경:

docker-bake-dev.hcl

target "app" {

  args = {

    ENV = "development"

  }

}

운영 환경:

docker-bake-prod.hcl

target "app" {

  args = {

    ENV = "production"

  }

}

실행:

개발:

docker buildx bake -f docker-bake-dev.hcl

운영:

docker buildx bake -f docker-bake-prod.hcl

하나의 Dockerfile로 여러 환경을 관리할 수 있습니다.

Docker Buildx Bake Args 버전 관리 활용

애플리케이션 버전을 전달할 수 있습니다.

docker-bake.hcl:

target "app" {

  args = {

    VERSION = "2.0.0"

  }

}

Dockerfile:

ARG VERSION

LABEL version=$VERSION

결과:

Image

↓

Version Metadata 저장

빌드 버전 관리에 활용할 수 있습니다.

Docker Buildx Bake Args와 Platform 설정

플랫폼별 설정도 가능합니다.

예:

target "app" {

  platforms = [

    "linux/amd64",

    "linux/arm64"

  ]

  args = {

    BUILD_MODE = "release"

  }

}

여러 플랫폼에서 동일한 Build 설정을 유지할 수 있습니다.

Docker Buildx Bake Args와 CI/CD 활용

CI/CD 환경에서는 환경 변수를 Build Args로 전달할 수 있습니다.

GitHub Actions:

- name: Build

  run: |

    docker buildx bake app

환경 변수:

env:

  VERSION: 1.0.0

Bake:

target "app" {

  args = {

    VERSION = "${VERSION}"

  }

}

흐름:

CI 변수

↓

Build Args 전달

↓

Docker Image 생성

Docker Buildx Bake Args와 Secret 차이

Args와 Secret은 비슷해 보이지만 목적이 다릅니다.

Args

사용 목적:

• 일반 설정값
• 버전 정보
• 환경 이름

예:

VERSION=1.0.0
ENV=production

Secret

사용 목적:

• 비밀번호
• API Key
• Token

예:

PASSWORD

SSH KEY

API TOKEN

비교:

기능	용도
Args	공개 가능한 Build 변수
Secret	보호해야 하는 정보

비밀번호 같은 정보는 Args로 전달하면 안 됩니다.

Docker Buildx Bake Args 실무 예제

프로젝트 구조:

project/

├── Dockerfile

├── docker-bake.hcl

└── app/

Dockerfile:

FROM node:20

ARG APP_VERSION

ARG BUILD_ENV

LABEL version=$APP_VERSION

RUN echo $BUILD_ENV

docker-bake.hcl:

target "production" {

  tags = [

    "company/app:v1"

  ]

  args = {

    APP_VERSION = "1.0.0"

    BUILD_ENV = "production"

  }

}

실행:

docker buildx bake production

결과:

Version 적용

↓

환경 설정 적용

↓

Image 생성

Docker Buildx Bake Args 문제 해결

ARG 값이 전달되지 않는 경우

확인:

Dockerfile:

ARG VERSION
RUN echo $VERSION

Bake:

args = {

 VERSION = "1.0"

}

이름이 동일한지 확인합니다.

환경 변수 적용 오류

확인:

echo $VERSION

환경 변수 존재 여부를 확인합니다.

Image에 값이 남지 않는 경우

ARG는 기본적으로 Build 단계 변수입니다.

필요하면:

ENV VERSION=$VERSION

사용해야 합니다.

Docker Buildx Bake Args 사용 시 주의사항

첫 번째는 비밀번호나 Token을 Args로 전달하지 않아야 합니다.

두 번째는 변경 가능한 값만 Args로 관리하는 것이 좋습니다.

세 번째는 Dockerfile ARG 이름과 Bake Args 이름을 동일하게 유지해야 합니다.

네 번째는 환경별 설정 파일을 분리하면 관리가 편리합니다.

Best Practice

Docker Buildx Bake Args 활용 방법:

• 환경별 설정 관리
• 버전 정보 전달
• Dockerfile 재사용
• CI/CD 변수 연결
• Secret과 구분 사용
• Build 설정 중앙 관리

자주 묻는 질문

Docker Buildx Bake Args는 무엇인가요?

Docker Build 과정에서 Dockerfile에 값을 전달하는 Build 변수 기능입니다.

Args와 ENV 차이는 무엇인가요?

Args는 Build 과정에서 사용되고 ENV는 Image 실행 환경에서도 유지됩니다.

API Key를 Args로 사용할 수 있나요?

권장하지 않습니다.

민감한 정보는 Secret 기능을 사용해야 합니다.

여러 환경을 관리할 수 있나요?

가능합니다.

dev, test, production별 Bake 파일을 만들어 관리할 수 있습니다.

마무리

Docker Buildx Bake Args는 하나의 Dockerfile을 여러 환경에서 효율적으로 재사용하기 위한 중요한 기능입니다.

환경 이름, 버전 정보, Build 옵션 같은 값을 외부에서 전달할 수 있어 개발·테스트·운영 환경을 쉽게 분리할 수 있습니다.

특히 CI/CD Pipeline과 함께 사용하면 자동 빌드 과정에서 필요한 설정값을 관리할 수 있으며, Secret 기능과 함께 활용하면 더욱 안전한 Docker Build 환경을 구축할 수 있습니다.