Docker Image를 Build할 때 환경에 따라 다른 값을 사용해야 하는 경우가 많습니다.

예:

• 개발 환경 설정
• 운영 환경 설정
• Application 버전
• API 주소
• Build 옵션
• Package 버전

하지만 이러한 값을 Dockerfile에 직접 고정하면 환경별 관리가 어려워집니다.

예:

FROM node:20

ENV APP_ENV=production

문제:

개발 환경 변경

↓

Dockerfile 수정 필요

↓

재Build 필요

Docker Buildx Bake에서는 Build Args 기능을 사용하여 Build 과정에서 필요한 값을 동적으로 전달할 수 있습니다.

예:

docker-bake.hcl

target "app" {

  args = {

    APP_ENV = "production"

    VERSION = "1.0.0"

  }

}

Dockerfile:

FROM node:20

ARG APP_ENV

ARG VERSION

RUN echo $APP_ENV

RUN echo $VERSION

실행:

docker buildx bake app

결과:

Build Argument 전달

↓

Dockerfile 사용

↓

Image 생성

이번 글에서는 Docker Buildx Bake Build Args의 개념부터 ARG와 ENV 차이, 환경별 설정, CI/CD 활용, 실무 구성 방법까지 자세히 알아보겠습니다.

Docker Buildx Bake Build Args란 무엇인가?

Docker Buildx Bake Build Args는 Docker Build 과정에서 Dockerfile로 값을 전달하는 기능입니다.

기본 구조:

docker-bake.hcl

↓

Build Args 전달

↓

Dockerfile ARG 사용

↓

Image Build

즉, 같은 Dockerfile을 사용하면서 Build 상황에 따라 다른 값을 적용할 수 있습니다.

Docker Buildx Bake Build Args가 필요한 이유

고정된 Dockerfile:

FROM ubuntu

RUN install production-package

문제:

• 개발 환경 적용 어려움
• 테스트 환경 분리 어려움
• 여러 Dockerfile 필요

Build Args 사용:

하나의 Dockerfile

↓

환경별 값 전달

↓

여러 환경 Build 가능

장점:

• Dockerfile 재사용
• 환경별 Build 가능
• CI/CD 자동화 편리
• 설정 관리 단순화

Docker Buildx Bake Build Args 기본 설정

docker-bake.hcl:

target "app" {

  args = {

    NODE_VERSION = "20"

  }

}

Dockerfile:

ARG NODE_VERSION

FROM node:${NODE_VERSION}

실행:

docker buildx bake app

결과:

NODE_VERSION=20

↓

node:20 Image 사용

Docker Buildx Bake Build Args Dockerfile ARG 사용법

Dockerfile:

FROM ubuntu

ARG APP_VERSION

RUN echo "Version: $APP_VERSION"

Bake:

target "app" {

  args = {

    APP_VERSION = "2.0.0"

  }

}

Build 결과:

Version: 2.0.0

Docker Buildx Bake Build Args와 ENV 차이

ARG와 ENV는 비슷하지만 목적이 다릅니다.

ARG

Build 과정에서만 사용합니다.

예:

ARG VERSION

RUN echo $VERSION

특징:

• Build 시 사용
• Image 실행 후 유지되지 않음

ENV

Image 실행 환경에서도 유지됩니다.

예:

ENV APP_ENV=production

특징:

• Container 실행 시 사용
• Image 내부 저장

비교:

기능	ARG	ENV
Build 사용	가능	가능
Container 실행 후 사용	불가능	가능
Image 저장	일부 Metadata	저장됨

Docker Buildx Bake Build Args 여러 개 사용하기

여러 값을 동시에 전달할 수 있습니다.

예:

target "production" {

  args = {

    APP_ENV = "production"

    APP_VERSION = "1.5.0"

    DEBUG = "false"

  }

}

Dockerfile:

ARG APP_ENV

ARG APP_VERSION

ARG DEBUG

환경 설정을 체계적으로 관리할 수 있습니다.

Docker Buildx Bake Build Args 환경별 설정

개발 환경:

target "dev" {

  args = {

    APP_ENV = "development"

  }

}

운영 환경:

target "production" {

  args = {

    APP_ENV = "production"

  }

}

실행:

개발:

docker buildx bake dev

운영:

docker buildx bake production

같은 Dockerfile로 환경을 분리할 수 있습니다.

Docker Buildx Bake Build Args와 Target 상속 활용

공통 설정:

target "base" {

  args = {

    NODE_VERSION = "20"

  }

}

개발:

target "dev" {

  inherits = [

    "base"

  ]

  args = {

    APP_ENV = "dev"

  }

}

운영:

target "production" {

  inherits = [

    "base"

  ]

  args = {

    APP_ENV = "prod"

  }

}

공통 값과 환경별 값을 분리할 수 있습니다.

Docker Buildx Bake Build Args CI/CD 활용

CI/CD에서는 Build 정보를 동적으로 전달할 수 있습니다.

예:

- name: Build Image

  run: |

    docker buildx bake production

Bake:

target "production" {

  args = {

    BUILD_NUMBER = "123"

  }

}

활용:

• Build 번호
• Commit ID
• Release 버전
• 환경 정보

Docker Buildx Bake Build Args Git 정보 활용

Git Commit 정보를 Build Args로 전달할 수 있습니다.

예:

git rev-parse HEAD

결과:

a82fd91

Bake:

args = {

  GIT_COMMIT = "a82fd91"

}

Dockerfile:

ARG GIT_COMMIT

RUN echo $GIT_COMMIT

Image 생성 정보를 추적할 수 있습니다.

Docker Buildx Bake Build Args 실무 예제

프로젝트:

project/

├── Dockerfile

├── docker-bake.hcl

└── app/

docker-bake.hcl:

target "production" {

  tags = [

    "registry.company.com/app:v1"

  ]

  args = {

    APP_ENV = "production"

    APP_VERSION = "1.0.0"

    BUILD_NUMBER = "100"

  }

}

Dockerfile:

FROM node:20

ARG APP_ENV

ARG APP_VERSION

ARG BUILD_NUMBER

RUN echo $APP_ENV

RUN echo $APP_VERSION

RUN echo $BUILD_NUMBER

실행:

docker buildx bake production

결과:

환경 정보 전달

↓

Application Build

↓

Docker Image 생성

Docker Buildx Bake Build Args 문제 해결

ARG 값이 전달되지 않는 경우

확인:

ARG VERSION
RUN echo $VERSION

Bake 설정:

args = {

 VERSION = "1.0"

}

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

값 변경이 적용되지 않는 경우

확인:

• Docker Build Cache
• ARG 위치
• Dockerfile 순서

필요 시:

docker buildx bake app --no-cache

Secret 정보를 ARG로 전달하는 경우

주의:

ARG TOKEN

↓

Image History 노출 가능

Secret은 Build Secret 기능을 사용하는 것이 좋습니다.

Docker Buildx Bake Build Args 사용 시 주의사항

첫 번째는 비밀번호와 API Key 같은 민감 정보는 ARG로 전달하지 않는 것이 좋습니다.

두 번째는 환경별 ARG 이름 규칙을 통일하는 것이 좋습니다.

세 번째는 Build Cache 영향을 고려해야 합니다.

네 번째는 CI/CD에서는 자동 값 주입 방식을 사용하는 것이 좋습니다.

Best Practice

Docker Buildx Bake Build Args 활용 방법:

• 환경별 설정 분리
• Version 정보 전달
• CI/CD 자동 주입
• Git 정보 기록
• Target별 관리
• Secret과 구분 사용

자주 묻는 질문

Docker Buildx Bake Build Args는 무엇인가요?

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

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

ARG는 Build 전용이고 ENV는 Container 실행 환경에서도 유지됩니다.

API Key를 ARG로 전달해도 되나요?

권장하지 않습니다.

민감 정보는 Secret 기능을 사용하는 것이 안전합니다.

CI/CD에서도 사용할 수 있나요?

가능합니다.

Build 번호, Version, Commit 정보를 전달하는 용도로 많이 사용합니다.

마무리

Docker Buildx Bake Build Args는 하나의 Dockerfile을 다양한 환경에서 활용하기 위한 핵심 기능입니다.

개발, 테스트, 운영 환경마다 다른 값을 전달할 수 있어 Dockerfile 중복을 줄이고 Build 자동화를 쉽게 만들 수 있습니다.

특히 CI/CD 환경에서는 Version, Commit 정보, Build 번호 등을 자동으로 전달하여 체계적인 Image 관리가 가능합니다.