Docker Buildx Bake를 제대로 활용하려면 가장 먼저 이해해야 하는 것이 Bake File 구조입니다.

Docker Buildx Bake는 명령어를 직접 입력하는 방식이 아니라 설정 파일에 빌드 정보를 작성하고 이를 기반으로 Docker 이미지를 생성합니다.

기존 방식:

docker buildx build \
-t company/app:v1 .

명령어마다:

• 이미지 이름
• Dockerfile 위치
• Platform
• Cache 설정
• Build Argument

등을 직접 입력해야 합니다.

하지만 Bake File을 사용하면:

docker-bake.hcl

↓

Build 설정 관리

↓

docker buildx bake 실행

하나의 파일에서 모든 빌드 설정을 관리할 수 있습니다.

이번 글에서는 Docker Buildx Bake File의 기본 구조부터 HCL 작성 방법, Target 구성, 변수 활용, 실무 프로젝트 관리 방법까지 자세히 알아보겠습니다.

Docker Buildx Bake File이란 무엇인가?

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

대표적인 파일 형식:

• docker-bake.hcl
• docker-bake.json
• docker-bake.override.hcl

가장 많이 사용하는 형식:

docker-bake.hcl

Bake File 구조:

Bake File

↓

Group

↓

Target

↓

Build Option

↓

Docker Image 생성

즉, Docker Build에 필요한 모든 설정을 코드 형태로 관리할 수 있습니다.

Docker Buildx Bake File을 사용하는 이유

일반적인 Docker Build:

docker buildx build -t app:v1 .

문제:

• 명령어가 길어짐
• 옵션 관리 어려움
• 여러 이미지 관리 불편
• CI/CD 설정 복잡

Bake File 사용:

docker buildx bake

장점:

• 빌드 설정 중앙 관리
• 여러 이미지 자동 관리
• 환경별 설정 분리
• 반복 명령 제거
• CI/CD 자동화 편리

Docker Buildx Bake File 기본 구조

기본 HCL 구조:

target "app" {

  context = "."

  dockerfile = "Dockerfile"

  tags = [
    "company/app:v1"
  ]

}

구성 요소:

Target

= 빌드 대상

Context

= Docker Build 위치

Dockerfile

= 사용할 Dockerfile 지정

Tags

= 생성할 이미지 이름

Docker Buildx Bake File 주요 구성 요소

Docker Buildx Bake File은 여러 블록으로 구성됩니다.

Target

빌드할 이미지를 정의합니다.

예:

target "backend" {

  context = "./backend"

}

Group

여러 Target을 묶습니다.

예:

group "default" {

  targets = [
    "backend",
    "frontend"
  ]

}

Variable

값을 재사용합니다.

예:

variable "VERSION" {

  default = "latest"

}

Function

동적인 설정을 만들 수 있습니다.

Docker Buildx Bake Target 작성 방법

예:

docker-bake.hcl

target "app" {

  context = "./app"

  dockerfile = "Dockerfile"

  tags = [
    "company/app:v1"
  ]

}

실행:

docker buildx bake app

결과:

company/app:v1

이미지가 생성됩니다.

Docker Buildx Bake Group 작성 방법

Group은 여러 이미지를 한번에 빌드할 때 사용합니다.

예:

group "production" {

  targets = [
    "backend",
    "frontend",
    "nginx"
  ]

}

실행:

docker buildx bake production

결과:

Backend Image 생성

Frontend Image 생성

Nginx Image 생성

배포 단위 관리에 유용합니다.

Docker Buildx Bake File과 여러 Dockerfile 관리

프로젝트:

project/

├── backend/

│   └── Dockerfile

├── frontend/

│   └── Dockerfile

└── docker-bake.hcl

Bake File:

target "backend" {

  context = "./backend"

  dockerfile = "Dockerfile"

}


target "frontend" {

  context = "./frontend"

  dockerfile = "Dockerfile"

}

실행:

docker buildx bake backend frontend

각각 다른 Dockerfile을 사용할 수 있습니다.

Docker Buildx Bake File 변수 사용하기

반복되는 값은 변수로 관리할 수 있습니다.

예:

variable "IMAGE_NAME" {

  default = "company/app"

}


variable "VERSION" {

  default = "latest"

}


target "app" {

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

}

결과:

company/app:latest

버전 변경이 쉬워집니다.

Docker Buildx Bake File 상속 사용하기

공통 설정은 Base Target으로 관리할 수 있습니다.

예:

target "base" {

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

}


target "app" {

  inherits = [
    "base"
  ]

}

효과:

• Platform 설정 공유
• Cache 설정 공유
• Build 옵션 재사용

Docker Buildx Bake File Override 관리

환경별 설정을 분리할 수 있습니다.

기본:

docker-bake.hcl

개발:

docker-bake.override.hcl

운영:

docker-bake.production.hcl

실행:

docker buildx bake \
-f docker-bake.hcl \
-f docker-bake.production.hcl

환경에 맞는 Build 설정을 적용할 수 있습니다.

Docker Buildx Bake File Platform 설정

멀티 플랫폼 이미지도 설정할 수 있습니다.

예:

target "app" {

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

}

결과:

Intel 서버 이미지

+

ARM 서버 이미지

다양한 환경에서 실행 가능한 이미지를 만들 수 있습니다.

Docker Buildx Bake File Cache 설정

빌드 속도를 높이기 위해 Cache를 추가할 수 있습니다.

예:

target "app" {

  cache-from = [
    "type=registry,ref=company/cache"
  ]

  cache-to = [
    "type=registry,ref=company/cache"
  ]

}

효과:

• Layer 재사용
• 빌드 시간 감소
• CI 비용 절감

Docker Buildx Bake File 실무 활용 예제

서비스 구조:

company-project/

├── backend/

├── frontend/

├── nginx/

└── docker-bake.hcl

docker-bake.hcl:

group "default" {

  targets = [
    "backend",
    "frontend",
    "nginx"
  ]

}


target "backend" {

  context = "./backend"

  tags = [
    "company/backend:v1"
  ]

}


target "frontend" {

  context = "./frontend"

  tags = [
    "company/frontend:v1"
  ]

}


target "nginx" {

  context = "./nginx"

  tags = [
    "company/nginx:v1"
  ]

}

실행:

docker buildx bake

결과:

Backend 빌드

Frontend 빌드

Nginx 빌드

CI/CD에서 Docker Buildx Bake File 활용

GitHub Actions 예:

- name: Build Docker Images

  run: |

    docker buildx bake \
    --push

활용:

• 자동 이미지 빌드
• Registry Push
• 배포 자동화
• 동일한 Build 환경 유지

Linux 서버 문제 해결

여러 Docker 이미지를 운영하면서 각각 다른 Build 명령어를 사용하고 있었습니다.

기존:

docker buildx build -t backend:v1 ./backend

docker buildx build -t frontend:v1 ./frontend

문제:

• 명령어 반복
• 옵션 관리 어려움
• 배포 자동화 복잡

Bake File 적용:

target "backend" {

  context="./backend"

}


target "frontend" {

  context="./frontend"

}

실행:

docker buildx bake

결과:

모든 이미지를 하나의 설정 파일에서 관리할 수 있었습니다.

Docker Buildx Bake File 사용 시 주의사항

첫 번째는 Bake File 이름 규칙을 통일하는 것이 좋습니다.

두 번째는 Target 이름을 명확하게 작성해야 합니다.

세 번째는 민감한 정보는 Secret 기능을 사용하는 것이 좋습니다.

네 번째는 운영 환경에서는 Override 파일을 분리하는 것이 좋습니다.

Best Practice

Docker Buildx Bake File 활용 방법:

• docker-bake.hcl 중앙 관리
• 서비스별 Target 구성
• 공통 설정 상속 사용
• 환경별 Override 관리
• Cache 적용
• CI/CD 자동화 연결

자주 묻는 질문

Docker Buildx Bake File은 무엇인가요?

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

가장 많이 사용하는 파일 형식은 무엇인가요?

일반적으로 docker-bake.hcl 파일을 가장 많이 사용합니다.

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

가능합니다.

Target을 여러 개 생성하여 Backend, Frontend, Nginx 등을 관리할 수 있습니다.

JSON이나 YAML도 사용할 수 있나요?

가능합니다.

하지만 HCL 형식이 가장 많이 사용됩니다.

마무리

Docker Buildx Bake File은 Docker 이미지 빌드를 체계적으로 관리하기 위한 핵심 기능입니다.

명령어 중심의 Docker Build 방식에서 벗어나 설정 파일 기반으로 빌드를 관리할 수 있으며, 여러 이미지와 환경을 하나의 구조 안에서 효율적으로 운영할 수 있습니다.

특히 대규모 프로젝트, 마이크로서비스 환경, CI/CD 자동화 환경에서는 Docker Buildx Bake File을 활용하면 더욱 안정적이고 관리하기 쉬운 Docker 빌드 시스템을 구축할 수 있습니다.