Docker Buildx Bake를 사용하면 여러 Docker 이미지의 빌드 설정을 하나의 파일에서 관리할 수 있습니다.

하지만 Bake를 제대로 활용하려면 가장 중요한 것이 Bake 파일 작성 방법입니다.

Docker Buildx Bake는 여러 가지 설정 파일 형식을 지원합니다.

대표적으로:

• HCL 형식
• JSON 형식
• YAML 형식

을 사용할 수 있습니다.

가장 많이 사용하는 방식은 HCL(HashiCorp Configuration Language) 형식입니다.

예:

docker-bake.hcl

target "app" {
  context = "."
  dockerfile = "Dockerfile"

  tags = [
    "app:v1"
  ]
}

이 파일 하나로 Docker Build 설정을 관리할 수 있습니다.

이번 글에서는 Docker Buildx Bake 파일의 구조부터 HCL 문법, YAML 설정, Target 관리, 실무 활용 방법까지 자세히 알아보겠습니다.

Docker Buildx Bake 파일이란 무엇인가?

Docker Buildx Bake 파일은 Docker 이미지 빌드 설정을 저장하는 구성 파일입니다.

기존 방식:

docker buildx build
-t app:v1 .

명령어마다 직접 옵션 입력 필요

Bake 방식:

docker buildx bake

설정 파일에 저장된 내용을 자동 실행

구조:

Bake 파일

↓

Target 설정

↓

Docker Build 실행

빌드 옵션을 코드처럼 관리할 수 있습니다.

Docker Buildx Bake 지원 파일 형식

Docker Buildx Bake는 다음 형식을 지원합니다.

HCL

파일명:

docker-bake.hcl

특징:

• 가장 많이 사용
• 가독성이 좋음
• 변수 사용 가능
• 상속 기능 지원

JSON

파일명:

docker-bake.json

특징:

• 프로그램 처리 편리
• 자동 생성 환경 적합

YAML

파일명:

docker-bake.yaml

특징:

• 사람이 읽기 쉬움
• CI/CD 설정과 비슷한 구조

일반적인 Docker 프로젝트에서는 HCL 사용을 많이 권장합니다.

Docker Buildx Bake HCL 기본 구조

기본 형태:

target "이름" {

  설정값

}

예:

target "app" {

  context = "."

  dockerfile = "Dockerfile"

  tags = [
    "app:v1"
  ]

}

구성 요소:

• target
• context
• dockerfile
• tags
• platforms
• args

Target 설정 방법

Target은 빌드 대상을 의미합니다.

예:

target "backend" {

  context = "./backend"

}


target "frontend" {

  context = "./frontend"

}

실행:

docker buildx bake backend frontend

결과:

backend 이미지 빌드

↓

frontend 이미지 빌드

Docker Buildx Bake Group 사용법

Group은 여러 Target을 묶는 기능입니다.

예:

group "default" {

  targets = [
    "backend",
    "frontend"
  ]

}

실행:

docker buildx bake

결과:

backend와 frontend가 함께 빌드됩니다.

Docker Buildx Bake Tag 설정

이미지 이름과 버전을 지정합니다.

예:

target "app" {

  tags = [
    "company/app:v1"
  ]

}

결과:

company/app:v1

여러 Tag 지정도 가능합니다.

tags = [

  "company/app:v1",

  "company/app:latest"

]

Docker Buildx Bake Platform 설정

멀티 플랫폼 빌드도 가능합니다.

예:

target "app" {

  platforms = [
    "linux/amd64",
    "linux/arm64"
  ]

}

결과:

• Intel 서버 지원
• AMD 서버 지원
• ARM 서버 지원

Docker Buildx Bake Build Args 설정

Dockerfile ARG 값을 전달할 수 있습니다.

Dockerfile:

ARG VERSION

RUN echo $VERSION

Bake 파일:

target "app" {

  args = {

    VERSION = "1.0"

  }

}

빌드:

docker buildx bake

자동으로 ARG 값이 전달됩니다.

Docker Buildx Bake YAML 작성 방법

YAML 형식 예제:

docker-bake.yaml

target:

  app:

    context: .

    dockerfile: Dockerfile

    tags:
      - app:v1

구조:

target

↓

app

↓

빌드 옵션

YAML은 설정 구조가 단순한 프로젝트에서 사용하기 좋습니다.

Docker Buildx Bake HCL 변수 사용하기

HCL에서는 변수를 사용할 수 있습니다.

예:

variable "VERSION" {

  default = "latest"

}


target "app" {

  tags = [

    "company/app:${VERSION}"

  ]

}

변경 가능한 값을 중앙 관리할 수 있습니다.

Docker Buildx Bake 실무 예제

프로젝트 구조:

project/

├── backend/

│ └── Dockerfile

├── frontend/

│ └── Dockerfile

└── docker-bake.hcl

docker-bake.hcl:

group "default" {

  targets = [

    "backend",

    "frontend"

  ]

}


target "backend" {

  context = "./backend"

  tags = [

    "company/backend:v1"

  ]

}


target "frontend" {

  context = "./frontend"

  tags = [

    "company/frontend:v1"

  ]

}

실행:

docker buildx bake

두 개의 이미지를 자동으로 빌드합니다.

CI/CD에서 Docker Buildx Bake 파일 활용

GitHub Actions:

- name: Build Images

  run: |

    docker buildx bake --push

장점:

• 빌드 설정 통일
• 여러 이미지 자동 처리
• 배포 과정 단순화
• 유지보수 편리

Docker Buildx Bake 설정 확인하기

실제 실행 전에 설정을 확인할 수 있습니다.

명령어:

docker buildx bake –print

확인 가능:

• Target
• Image Tag
• Platform
• Build 옵션

운영 환경에서는 실행 전 검증 용도로 유용합니다.

Linux 서버 문제 해결

여러 Docker 이미지를 운영하는 환경에서 각각 다른 명령어를 관리하고 있었습니다.

기존:

docker buildx build -t backend:v1 ./backend

docker buildx build -t frontend:v1 ./frontend

문제:

• 명령어 관리 어려움
• 옵션 변경 시 여러 곳 수정 필요
• 배포 자동화 복잡

해결:

docker-bake.hcl 작성

target "backend" {

  context="./backend"

}


target "frontend" {

  context="./frontend"

}

실행:

docker buildx bake

결과:

backend 빌드 완료

frontend 빌드 완료

하나의 설정 파일로 여러 Docker 이미지를 관리할 수 있었습니다.

Docker Buildx Bake 사용 시 주의사항

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

두 번째는 Tag 관리 정책이 필요합니다.

세 번째는 운영 환경에서는 Bake 파일 버전을 함께 관리해야 합니다.

네 번째는 빌드 옵션 변경 시 테스트 후 적용하는 것이 좋습니다.

Best Practice

Docker Buildx Bake 파일 작성 방법:

• HCL 형식 우선 사용
• Target 이름 명확하게 작성
• 공통 설정 재사용
• Platform 명확히 지정
• Tag 규칙 통일
• CI/CD와 연결

자주 묻는 질문

Docker Buildx Bake 파일은 무엇인가요?

Docker 이미지 빌드 설정을 파일 형태로 관리하는 구성 파일입니다.

HCL과 YAML 중 어떤 것을 사용하는 것이 좋나요?

대규모 Docker 프로젝트에서는 HCL을 많이 사용합니다.

간단한 설정은 YAML도 사용할 수 있습니다.

Bake 파일 이름은 무엇인가요?

일반적으로:

docker-bake.hcl

파일을 사용합니다.

여러 Docker 이미지를 관리할 수 있나요?

가능합니다.

여러 Target을 정의하여 동시에 빌드할 수 있습니다.

마무리

Docker Buildx Bake 파일은 복잡한 Docker 프로젝트의 빌드 과정을 체계적으로 관리하기 위한 핵심 기능입니다.

HCL 기반 설정을 활용하면 여러 Docker 이미지, 플랫폼, Tag, Build 옵션을 하나의 파일에서 관리할 수 있습니다.

특히 마이크로서비스 환경이나 CI/CD 자동화 환경에서는 Docker Buildx Bake 파일을 활용하면 반복적인 빌드 작업을 줄이고 안정적인 이미지 관리 시스템을 구축할 수 있습니다.