Docker Buildx Bake는 여러 Docker 이미지 빌드 작업을 하나의 설정 파일로 관리할 수 있는 강력한 자동화 기능입니다.
하지만 Bake를 제대로 활용하려면 빌드 정보를 저장하는 설정 파일 구조를 이해해야 합니다.
이때 사용하는 것이 바로 Docker Bake File입니다.
Docker Bake File은 Docker Buildx Bake에서 사용할 빌드 설정을 정의하는 파일입니다.
빌드 대상(Target), 그룹(Group), 이미지 이름(Tag), Dockerfile 위치, 플랫폼, Cache 설정 등 다양한 빌드 옵션을 코드 형태로 관리할 수 있습니다.
기존에는 여러 개의 긴 Docker 명령어를 직접 입력해야 했지만 Bake File을 사용하면 하나의 설정 파일로 반복적인 빌드 작업을 자동화할 수 있습니다.
이번 글에서는 Docker Buildx Bake File의 개념부터 기본 구조, HCL 작성 방법, Target 설정, 실무 활용 방법까지 자세히 알아보겠습니다.
Docker Bake File이란 무엇인가?
Docker Bake File은 Docker Buildx Bake 명령이 읽는 빌드 설정 파일입니다.
기본 파일명:
docker-bake.hcl이 파일 안에 Docker 이미지 생성에 필요한 모든 설정을 작성합니다.
관리 가능한 항목:
- 빌드 대상(Target)
- 빌드 그룹(Group)
- 이미지 Tag
- Dockerfile 경로
- Build Context
- 플랫폼 설정
- Cache 설정
- Push 설정
Docker Bake File은 언제 사용하는가?
다음과 같은 환경에서 활용합니다.
- 여러 Docker 이미지 관리
- 마이크로서비스 환경
- CI/CD 자동화
- 반복적인 이미지 빌드
- 멀티 플랫폼 배포
- 팀 단위 개발 환경
서비스가 많아질수록 Bake File의 효과가 커집니다.
Docker Bake File 기본 구조
기본적인 구조입니다.
group "default" {
targets = [
"app"
]
}
target "app" {
dockerfile = "Dockerfile"
tags = [
"my-app:latest"
]
}구성 요소:
- group : 여러 Target 관리
- target : 하나의 빌드 작업 정의
Docker Bake File Target 이해하기
Target은 하나의 Docker 이미지 빌드 작업입니다.
예:
target "backend" {
dockerfile = "Dockerfile"
tags = [
"backend:v1"
]
}하나의 Target은 하나의 이미지 생성 작업을 의미합니다.
Docker Bake File Group 사용하기
Group은 여러 Target을 묶어 한 번에 실행하기 위한 기능입니다.
예:
group "default" {
targets = [
"frontend",
"backend"
]
}실행:
docker buildx bake결과:
frontend 빌드
backend 빌드여러 이미지를 동시에 관리할 수 있습니다.
Docker Bake File 이미지 Tag 설정하기
이미지 이름과 버전을 지정할 수 있습니다.
예:
target "app" {
tags = [
"company/app:v1.0"
]
}생성 결과:
company/app:v1.0운영 환경에서는 버전 Tag 사용을 권장합니다.
Docker Bake File 플랫폼 설정하기
멀티 플랫폼 이미지도 설정할 수 있습니다.
예:
target "app" {
platforms = [
"linux/amd64",
"linux/arm64"
]
}AMD64와 ARM64 이미지를 동시에 생성할 수 있습니다.
Docker Bake File Dockerfile 지정하기
기본 Dockerfile이 아닌 다른 파일을 사용할 수 있습니다.
예:
target "production" {
dockerfile = "Dockerfile.prod"
}개발용과 운영용 Dockerfile을 분리할 때 사용합니다.
Docker Bake File Context 설정하기
빌드 경로를 지정합니다.
예:
target "frontend" {
context = "./frontend"
}프로젝트 구조:
project/
├── frontend/
├── backend/
└── docker-bake.hcl각 서비스별 빌드 환경을 구성할 수 있습니다.
Docker Bake File 실행 방법
기본 실행:
docker buildx bake특정 Target 실행:
docker buildx bake backend특정 설정 파일 사용:
docker buildx bake -f custom-bake.hclDocker Bake File 실무 활용 예제
프로젝트 구조:
project/
├── docker-bake.hcl
├── api/
│ └── Dockerfile
└── web/
└── Dockerfiledocker-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 bakeAPI와 Web 이미지를 한 번에 빌드할 수 있습니다.
Linux 서버 문제 해결
서비스가 증가하면서 배포 서버에서 Docker 빌드 명령 관리 문제가 발생했습니다.
기존 방식:
docker buildx build -t api .
docker buildx build -t web .
docker buildx build -t worker .서비스가 늘어나면서 명령어 관리가 어려워졌습니다.
관리자는 Bake File을 생성했습니다.
group "default" {
targets = [
"api",
"web",
"worker"
]
}이후 실행:
docker buildx bake모든 서비스 이미지가 자동으로 빌드되었습니다.
Docker Bake File을 활용하면 복잡한 Docker 빌드 과정을 코드처럼 관리할 수 있습니다.
Docker Bake File 사용 시 주의사항
첫 번째는 설정 파일 변경 시 빌드 결과가 달라질 수 있으므로 Git으로 관리하는 것이 좋습니다.
두 번째는 Target 이름을 명확하게 작성해야 합니다.
세 번째는 운영 환경에서는 Tag 관리가 중요합니다.
네 번째는 CI/CD 환경에서는 Push와 Cache 옵션을 함께 사용하는 것이 좋습니다.
Best Practice
Docker Bake File을 사용할 때는 다음 방법을 추천합니다.
- Bake File을 Git으로 관리합니다.
- Target 이름을 역할별로 구분합니다.
- 운영 이미지는 버전 Tag를 사용합니다.
- 멀티 플랫폼 설정을 명확히 관리합니다.
- CI/CD 환경과 연동합니다.
- Cache 설정을 활용합니다.
자주 묻는 질문
Docker Bake File 기본 파일명은 무엇인가요?
기본 파일명은 docker-bake.hcl입니다.
Bake File 없이 사용할 수 있나요?
가능하지만 여러 빌드를 관리하려면 Bake File 사용을 권장합니다.
HCL이란 무엇인가요?
HashiCorp Configuration Language의 약자로 설정 파일 작성에 사용하는 문법입니다.
Target과 Group 차이는 무엇인가요?
Target은 하나의 빌드 작업이고 Group은 여러 Target을 묶는 역할입니다.
마무리
Docker Buildx Bake File은 Docker 이미지 빌드 설정을 코드 형태로 관리할 수 있게 해주는 핵심 기능입니다.
여러 이미지, 멀티 플랫폼 빌드, CI/CD 자동화를 하나의 설정 파일에서 관리할 수 있어 대규모 프로젝트에서 매우 유용합니다.
특히 서비스가 많아질수록 Docker 명령어를 직접 관리하는 방식보다 Bake File을 활용하는 방식이 더욱 효율적이며 안정적인 빌드 환경을 구축할 수 있습니다.