Docker Buildx Bake를 사용하다 보면 하나의 프로젝트에서도 다양한 Build 설정이 필요해집니다.

예:

개발 환경 Build 설정
운영 환경 Build 설정
테스트 환경 Build 설정
CI/CD 전용 설정
Multi-platform Build 설정

작은 프로젝트에서는 하나의 docker-bake.hcl 파일만 사용해도 충분합니다.

하지만 프로젝트 규모가 커지면:

docker-bake.hcl

↓

설정 증가

↓

파일 크기 증가

↓

관리 어려움

문제가 발생합니다.

Docker Buildx Bake에서는 여러 개의 Bake 파일을 조합하여 사용할 수 있습니다.

예:

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

결과:

기본 설정 파일

+

운영 설정 파일

↓

최종 Build 설정 생성

이번 글에서는 Docker Buildx Bake File 기능부터 여러 HCL 파일 관리, 환경별 설정 분리, CI/CD 활용, 실무 프로젝트 구조까지 자세히 알아보겠습니다.

Table of Contents

Docker Buildx Bake File이란 무엇인가?

Docker Buildx Bake File은 Docker Build 설정을 저장하는 파일입니다.

대표적인 파일 형식:

docker-bake.hcl

docker-bake.json

docker-bake.override.hcl

파일에는 다음 정보를 저장합니다.

Target
Context
Dockerfile 위치
Tags
Platforms
Cache
Secrets
Build Args

기본 구조:

Bake File

↓

Target 설정

↓

docker buildx bake 실행

↓

Image Build

Docker Buildx Bake File이 필요한 이유

명령어 방식:

docker buildx build \
--platform linux/amd64 \
--tag app:v1 .

문제:

명령어 길어짐
반복 사용 어려움
팀 공유 어려움

Bake File 사용:

target "app" {

  tags = [

    "company/app:v1"

  ]

}

실행:

docker buildx bake app

장점:

Build 설정 관리
팀 공유 가능
자동화 쉬움
환경 분리 가능

Docker Buildx Bake File 기본 구조

docker-bake.hcl:

target "app" {

  context = "."

  dockerfile = "Dockerfile"

  tags = [

    "company/app:latest"

  ]

}

구성:

target

↓

Build 대상


context

↓

Build 위치


dockerfile

↓

Dockerfile 위치


tags

↓

Image 이름

Docker Buildx Bake 여러 파일 사용하기

기본 파일:

docker-bake.hcl

운영 파일:

docker-bake.prod.hcl

실행:

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

동작:

기본 설정 읽기

↓

운영 설정 추가

↓

최종 설정 생성

Docker Buildx Bake File 우선순위

여러 파일을 사용할 경우 뒤에 지정한 파일이 우선 적용됩니다.

예:

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

순서:

base.hcl

↓

production.hcl

↓

production 설정 우선

환경별 변경에 활용할 수 있습니다.

Docker Buildx Bake File 환경별 관리

Docker Buildx Bake File JSON 형식 사용

HCL 외에도 JSON 형식을 사용할 수 있습니다.

docker-bake.json:

{
  "target": {
    "app": {
      "context": ".",
      "dockerfile": "Dockerfile"
    }
  }
}

실행:

docker buildx bake -f docker-bake.json app

자동화 시스템에서 JSON 기반 설정을 사용할 때 유용합니다.

Docker Buildx Bake File와 Inheritance 조합

여러 파일과 Inheritance를 함께 사용할 수 있습니다.

기본:

target "base" {

  cache-from = [

    "type=gha"

  ]

}

Production:

target "production" {

  inherits = [

    "base"

  ]

}

구조:

base 설정

↓

production 적용

공통 설정 관리가 쉬워집니다.

Docker Buildx Bake File CI/CD 활용

CI 환경에서는 환경별 Bake File을 많이 사용합니다.

GitHub Actions:

- name: Build Production

  run: |

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

흐름:

Code Push

↓

CI 실행

↓

Production Bake File 선택

↓

Image Build

↓

Registry Push

Docker Buildx Bake File 실무 프로젝트 구조

예:

application/

├── Dockerfile

├── docker-bake.hcl

├── docker-bake.dev.hcl

├── docker-bake.prod.hcl

├── docker-compose.yml

└── deploy/

docker-bake.hcl:

target "base" {

  context = "."

  dockerfile = "Dockerfile"

}

docker-bake.prod.hcl:

target "production" {

  inherits = [

    "base"

  ]

  tags = [

    "registry.company.com/app:v1"

  ]

  platforms = [

    "linux/amd64",

    "linux/arm64"

  ]

}

실행:

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

Docker Buildx Bake File 확인 방법

최종 설정 확인:

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

확인 가능:

Target
Tag
Platform
Cache
Args

Docker Buildx Bake File 문제 해결

파일을 찾지 못하는 경우

확인:

ls docker-bake.hcl

파일 이름과 위치를 확인합니다.

Target 충돌 발생

확인:

docker buildx bake --list

중복 Target 이름을 확인합니다.

설정이 적용되지 않는 경우

확인:

docker buildx bake --print

최종 병합 결과를 확인합니다.

Docker Buildx Bake File 사용 시 주의사항

첫 번째는 파일 구조를 너무 복잡하게 만들지 않는 것이 좋습니다.

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

세 번째는 Production 설정 변경 전 최종 설정을 확인해야 합니다.

네 번째는 공통 설정과 환경 설정을 분리하는 것이 좋습니다.

Best Practice

Docker Buildx Bake File 활용 방법:

기본 설정 파일 생성
환경별 파일 분리
Inheritance 활용
CI/CD 전용 설정 관리
최종 설정 검증
파일 구조 단순화

자주 묻는 질문

Docker Buildx Bake File은 무엇인가요?

Docker Build 설정을 파일 형태로 관리하는 기능입니다.

여러 Bake File을 함께 사용할 수 있나요?

가능합니다.

여러 파일을 조합하여 최종 Build 설정을 만들 수 있습니다.

HCL과 JSON 중 무엇을 사용하는 것이 좋나요?

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

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