Docker 프로젝트가 커질수록 이미지 버전, 환경 설정, 플랫폼, Registry 주소 등 반복적으로 변경해야 하는 값이 많아집니다.

예:

• 이미지 버전
• Docker 이미지 이름
• 배포 환경
• 빌드 번호
• Git Commit 정보
• 플랫폼 설정

이러한 값을 Dockerfile이나 Bake 파일 내부에 직접 작성하면 관리가 어려워집니다.

예:

target "app" {

  tags = [
    "company/app:v1.0"
  ]

}

버전을 변경하려면 Bake 파일을 직접 수정해야 합니다.

이때 사용하는 기능이 바로 Docker Buildx Bake 변수(variable)입니다.

변수를 사용하면 변경되는 값을 하나의 위치에서 관리하고, 빌드할 때 원하는 값으로 전달할 수 있습니다.

예:

variable "VERSION" {

  default = "latest"

}


target "app" {

  tags = [
    "company/app:${VERSION}"
  ]

}

빌드 시:

docker buildx bake –set *.args.VERSION=1.2

처럼 동적으로 값을 변경할 수 있습니다.

이번 글에서는 Docker Buildx Bake 변수의 개념부터 기본 사용법, 환경별 설정 관리, CI/CD 자동화 활용 방법까지 자세히 알아보겠습니다.

Docker Buildx Bake 변수란 무엇인가?

Docker Buildx Bake 변수는 빌드 설정에서 반복되는 값을 재사용하기 위한 기능입니다.

기본 구조:

variable

↓

값 저장

↓

Target에서 사용

예:

variable "IMAGE_NAME" {

  default = "app"

}


target "default" {

  tags = [
    "${IMAGE_NAME}:latest"
  ]

}

결과:

app:latest

변수를 사용하면 하나의 값을 여러 Target에서 공유할 수 있습니다.

Docker Buildx Bake 변수가 필요한 이유

변수가 없는 경우:

target "backend" {

  tags = [
    "company/backend:v1"
  ]

}


target "frontend" {

  tags = [
    "company/frontend:v1"
  ]

}

문제:

• 버전 변경 시 여러 곳 수정
• 실수 가능성 증가
• CI/CD 자동화 어려움

변수 사용:

variable "VERSION" {

  default = "v1"

}

사용:

tags = [
  "company/app:${VERSION}"
]

장점:

• 설정 중앙 관리
• 환경별 변경 쉬움
• 자동화 편리

Docker Buildx Bake 변수 기본 사용법

docker-bake.hcl

variable "VERSION" {

  default = "latest"

}


target "app" {

  context = "."

  tags = [
    "company/app:${VERSION}"
  ]

}

실행:

docker buildx bake

결과:

company/app:latest

Docker Buildx Bake 변수 값 변경하기

기본값:

default = "latest"

사용자가 변경:

docker buildx bake –set *.tags=company/app:v2

결과:

company/app:v2

빌드마다 다른 값을 사용할 수 있습니다.

Docker Buildx Bake 환경 변수 사용하기

환경 변수와 함께 사용할 수 있습니다.

예:

터미널:

export VERSION=2.0

Bake 파일:

variable "VERSION" {

}

사용:

target "app" {

  tags = [
    "company/app:${VERSION}"
  ]

}

결과:

company/app:2.0

CI/CD 환경에서 많이 사용하는 방식입니다.

Docker Buildx Bake 변수와 Docker ARG 차이

비슷해 보이지만 목적이 다릅니다.

Bake Variable

역할:

• 빌드 설정 관리
• Target 설정 변경
• Tag 관리

예:

tags = [
 "app:${VERSION}"
]

Docker ARG

역할:

• Dockerfile 내부 값 전달

Dockerfile:

ARG VERSION

RUN echo $VERSION

정리:

Bake Variable

= 빌드 설정 변경

Docker ARG

= 이미지 생성 과정 값 전달

Docker Buildx Bake 여러 변수 사용하기

예:

variable "IMAGE_NAME" {

  default = "company/app"

}


variable "VERSION" {

  default = "latest"

}


target "app" {

  tags = [
    "${IMAGE_NAME}:${VERSION}"
  ]

}

결과:

company/app:latest

두 값을 동시에 관리할 수 있습니다.

Docker Buildx Bake 변수 실무 활용 예제

개발·운영 환경 분리

변수:

variable "ENV" {

  default = "dev"

}

Target:

target "app" {

  tags = [
    "company/app:${ENV}"
  ]

}

개발:

docker buildx bake –set ENV=dev

결과:

company/app:dev

운영:

docker buildx bake –set ENV=production

결과:

company/app:production

CI/CD에서 Docker Buildx Bake 변수 활용

CI 환경:

docker buildx bake \
--set VERSION=${BUILD_NUMBER}

예:

BUILD_NUMBER:

150

결과:

company/app:150

빌드 번호를 자동으로 이미지 Tag에 적용할 수 있습니다.

Docker Buildx Bake 변수와 플랫폼 관리

변수를 활용하여 플랫폼도 관리할 수 있습니다.

예:

variable "PLATFORM" {

  default = "linux/amd64"

}


target "app" {

  platforms = [
    "${PLATFORM}"
  ]

}

변경:

docker buildx bake –set PLATFORM=linux/arm64

ARM 이미지 빌드로 변경됩니다.

Linux 서버 문제 해결

배포할 때마다 이미지 버전을 직접 수정하고 있었습니다.

기존:

tags = [
 "company/app:v1"
]

문제:

• 매번 파일 수정 필요
• 자동 배포 어려움
• 버전 관리 복잡

변수 적용:

variable "VERSION" {

  default = "latest"

}


target "app" {

  tags = [
    "company/app:${VERSION}"
  ]

}

실행:

docker buildx bake –set VERSION=v2

결과:

company/app:v2

빌드 파일을 수정하지 않고 버전을 변경할 수 있었습니다.

Docker Buildx Bake 변수 사용 시 주의사항

첫 번째는 변수 이름 규칙을 정하는 것이 좋습니다.

두 번째는 기본값(default)을 설정하면 관리가 편리합니다.

세 번째는 민감한 정보는 변수에 직접 저장하지 않는 것이 좋습니다.

네 번째는 CI/CD 환경에서는 환경 변수와 함께 사용하는 것이 좋습니다.

Best Practice

Docker Buildx Bake 변수 활용 방법:

• 이미지 Tag 변수화
• 환경별 설정 분리
• CI/CD Build Number 활용
• 플랫폼 변수 관리
• 공통 설정 재사용
• 버전 관리 자동화

자주 묻는 질문

Docker Buildx Bake 변수는 무엇인가요?

Docker Buildx Bake 설정에서 반복되는 값을 관리하기 위한 기능입니다.

변수와 환경 변수 차이는 무엇인가요?

Bake 변수는 Bake 파일 내부 설정이고, 환경 변수는 외부에서 값을 전달하는 방식입니다.

이미지 버전 관리에 사용할 수 있나요?

가능합니다.

CI/CD 빌드 번호와 연결하여 자동 Tag 생성이 가능합니다.

여러 Target에서 같은 변수를 사용할 수 있나요?

가능합니다.

공통 이미지 이름, 버전, 환경 값을 공유할 수 있습니다.

마무리

Docker Buildx Bake 변수는 복잡한 Docker 빌드 환경을 더욱 유연하게 관리할 수 있도록 도와주는 기능입니다.

이미지 버전, 환경, 플랫폼 등의 변경 값을 변수로 관리하면 Bake 파일을 직접 수정하지 않고도 다양한 빌드 환경을 구성할 수 있습니다.

특히 CI/CD 환경에서는 Build Number, Git Commit, 배포 환경 정보를 변수로 연결하여 자동화된 Docker 이미지 관리 시스템을 구축하는 데 매우 효과적입니다.