Docker Buildx Bake HCL 사용법 완벽 가이드! HCL 설정 파일 작성하기

Docker Buildx Bake를 활용하려면 여러 빌드 설정을 저장할 수 있는 설정 파일이 필요합니다.

Docker Bake는 다양한 형식의 설정 파일을 지원하지만, 가장 많이 사용하는 방식이 바로 HCL(HashiCorp Configuration Language) 형식입니다.

HCL은 사람이 읽기 쉬운 구조로 Docker 빌드 설정을 작성할 수 있도록 만들어진 설정 언어입니다.

docker-bake.hcl 파일을 사용하면 다음과 같은 빌드 정보를 코드 형태로 관리할 수 있습니다.

이미지 이름
Dockerfile 위치
Build Context
플랫폼
Cache 설정
환경 변수
Push 설정

복잡한 Docker 빌드 명령어를 하나의 설정 파일로 관리할 수 있어 대규모 프로젝트와 CI/CD 환경에서 많이 사용됩니다.

이번 글에서는 Docker Buildx Bake HCL의 개념부터 기본 문법, Target 설정, Variable 활용, 실무 적용 방법까지 자세히 알아보겠습니다.

Docker Bake HCL이란 무엇인가?

Docker Bake HCL은 Docker Buildx Bake에서 사용하는 설정 파일 형식입니다.

기본 파일명:

docker-bake.hcl

HCL 문법을 사용하여 Docker 빌드 작업을 정의합니다.

예:

target "app" {
  dockerfile = "Dockerfile"

  tags = [
    "my-app:latest"
  ]
}

하나의 Target에 필요한 빌드 정보를 저장할 수 있습니다.

HCL(HashiCorp Configuration Language)이란?

HCL은 HashiCorp에서 만든 설정 언어입니다.

주요 특징:

사람이 읽기 쉬움
JSON보다 간결한 구조
변수 사용 가능
재사용 가능한 설정 가능

Terraform 같은 인프라 관리 도구에서도 사용됩니다.

Docker Buildx Bake HCL 기본 구조

기본 구조:

group "default" {
  targets = [
    "app"
  ]
}

target "app" {
  context = "."

  dockerfile = "Dockerfile"

  tags = [
    "app:latest"
  ]
}

구성 요소:

group : 여러 Target 관리
target : 빌드 작업 정의
variable : 변수 정의

Docker Bake HCL Target 작성하기

Target은 하나의 Docker 이미지 빌드를 의미합니다.

예:

target "backend" {

  context = "./backend"

  dockerfile = "Dockerfile"

  tags = [
    "company/backend:v1"
  ]
}

설정 내용:

빌드 위치
Dockerfile
이미지 Tag

를 관리합니다.

Docker Bake HCL Group 설정하기

여러 Target을 한 번에 실행하려면 Group을 사용합니다.

예:

group "default" {

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

실행:

docker buildx bake

두 이미지를 동시에 빌드합니다.

Docker Bake HCL 플랫폼 설정하기

멀티 플랫폼 빌드 설정:

target "app" {

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

하나의 설정으로 여러 CPU 환경용 이미지를 생성할 수 있습니다.

Docker Bake HCL Tag 변수 사용하기

변수를 활용하면 반복 설정을 줄일 수 있습니다.

예:

variable "TAG" {

  default = "latest"
}


target "app" {

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

실행 시 변경:

TAG=v2 docker buildx bake

버전별 빌드 관리가 쉬워집니다.

Docker Bake HCL Cache 설정하기

Cache 옵션도 HCL에서 관리할 수 있습니다.

예:

target "app" {

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

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

CI/CD 빌드 속도를 향상시킬 수 있습니다.

Docker Bake HCL Push 설정하기

Registry Push 설정:

target "app" {

  output = [
    "type=image,push=true"
  ]
}

빌드 후 자동으로 이미지를 Registry에 업로드합니다.

Docker Bake HCL 실무 활용 예제

프로젝트 구조:

project/

├── docker-bake.hcl

├── api/

│   └── Dockerfile

└── web/

    └── Dockerfile

docker-bake.hcl:

group "default" {

  targets = [
    "api",
    "web"
  ]
}


target "api" {

  context = "./api"

  tags = [
    "company/api:latest"
  ]
}


target "web" {

  context = "./web"

  tags = [
    "company/web:latest"
  ]
}

실행:

docker buildx bake

두 서비스를 자동으로 빌드합니다.

Linux 서버 문제 해결

CI/CD 서버에서 Docker 빌드 명령이 계속 증가했습니다.

기존 방식:

docker buildx build api

docker buildx build web

docker buildx build worker

관리하기 어려운 상태였습니다.

HCL 설정 파일을 작성했습니다.

group "default" {

  targets = [
    "api",
    "web",
    "worker"
  ]
}

이후 실행:

docker buildx bake

모든 이미지가 설정에 따라 자동 빌드되었습니다.

Docker Buildx Bake HCL은 복잡한 Docker 빌드 환경을 코드 형태로 관리하는 효과적인 방법입니다.

Docker Bake HCL 사용 시 주의사항

첫 번째는 HCL 파일을 Git으로 관리하는 것이 좋습니다.

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

세 번째는 운영 환경과 개발 환경 설정을 분리하는 것이 좋습니다.

네 번째는 중요한 Tag와 Push 설정을 검토해야 합니다.

Best Practice

Docker Bake HCL을 사용할 때는 다음 방법을 추천합니다.

환경별 HCL 파일을 분리합니다.
변수로 반복 설정을 줄입니다.
Target 이름을 명확하게 관리합니다.
CI/CD와 연동합니다.
Cache 설정을 활용합니다.
Git으로 버전 관리합니다.

자주 묻는 질문

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

기본 이름은 docker-bake.hcl입니다.

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

사람이 직접 작성하고 관리한다면 HCL이 더 편리합니다.

HCL에서 변수를 사용할 수 있나요?

가능합니다.

Variable 기능으로 재사용 가능한 설정을 만들 수 있습니다.

Bake HCL은 Dockerfile을 대체하나요?

아닙니다.

Dockerfile은 이미지 생성 과정, HCL은 빌드 설정 관리를 담당합니다.

마무리

Docker Buildx Bake HCL은 Docker 빌드 환경을 체계적으로 관리하기 위한 핵심 설정 방식입니다.

복잡한 빌드 명령어를 하나의 파일로 관리하고, 여러 이미지와 플랫폼을 자동화할 수 있어 대규모 Docker 프로젝트에서 매우 유용합니다.

특히 CI/CD 환경에서는 HCL 기반 Bake 설정을 활용하면 반복 작업을 줄이고 안정적인 이미지 빌드 파이프라인을 구축할 수 있습니다.