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

Docker Buildx Bake는 여러 Docker 빌드 작업을 하나의 설정 파일로 관리할 수 있는 자동화 기능입니다.

Bake 설정 파일은 다양한 형식을 지원하며 대표적으로 다음 두 가지 방식이 사용됩니다.

HCL(HashiCorp Configuration Language)
JSON(JavaScript Object Notation)

HCL은 사람이 직접 작성하기 편한 형식이고, JSON은 프로그램이나 자동화 시스템에서 생성하고 관리하기 좋은 형식입니다.

특히 CI/CD 환경에서는 설정 파일을 자동 생성하거나 다른 시스템과 연동하는 경우가 많기 때문에 JSON 형식의 Bake 파일이 유용하게 활용됩니다.

Docker Buildx Bake JSON을 사용하면 다음과 같은 빌드 정보를 구조화된 데이터 형태로 관리할 수 있습니다.

Target
Group
Image Tag
Dockerfile
Build Context
Platform
Cache
Output 설정

이번 글에서는 Docker Buildx Bake JSON의 개념부터 기본 구조, 작성 방법, 실무 활용 방법까지 자세히 알아보겠습니다.

Docker Buildx Bake JSON이란 무엇인가?

Docker Buildx Bake JSON은 Bake 빌드 설정을 JSON 형식으로 작성하는 방법입니다.

기본 파일명:

docker-bake.json

JSON 구조를 사용하여 Docker 빌드 작업을 정의합니다.

예:

{
  "target": {
    "app": {
      "dockerfile": "Dockerfile",
      "tags": [
        "my-app:latest"
      ]
    }
  }
}

하나의 Target 빌드 설정을 관리할 수 있습니다.

Docker Buildx Bake JSON은 언제 사용하는가?

다음과 같은 환경에서 사용합니다.

CI/CD 자동화
설정 파일 자동 생성
빌드 시스템 연동
대규모 프로젝트 관리
프로그램 기반 Docker 빌드 관리

특히 Jenkins, GitHub Actions 같은 자동화 환경에서 활용하기 좋습니다.

Docker Buildx Bake JSON 기본 구조

기본 구조:

{
  "group": {
    "default": {
      "targets": [
        "app"
      ]
    }
  },

  "target": {
    "app": {
      "context": ".",
      "dockerfile": "Dockerfile",
      "tags": [
        "app:latest"
      ]
    }
  }
}

구성 요소:

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

Docker Bake JSON Target 설정하기

Target은 하나의 이미지 빌드 작업입니다.

예:

{
  "target": {
    "backend": {
      "context": "./backend",
      "tags": [
        "company/backend:v1"
      ]
    }
  }
}

Backend 이미지 빌드 설정을 정의합니다.

Docker Bake JSON Group 설정하기

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

예:

{
  "group": {
    "default": {
      "targets": [
        "backend",
        "frontend"
      ]
    }
  }
}

실행:

docker buildx bake

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

Docker Bake JSON 플랫폼 설정하기

멀티 플랫폼 빌드 설정:

{
  "target": {
    "app": {
      "platforms": [
        "linux/amd64",
        "linux/arm64"
      ]
    }
  }
}

AMD64와 ARM64 이미지를 생성할 수 있습니다.

Docker Bake JSON Cache 설정하기

Cache 설정도 JSON으로 관리할 수 있습니다.

예:

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

CI/CD 빌드 속도를 개선할 수 있습니다.

Docker Bake JSON Push 설정하기

Registry Push 설정:

{
  "target": {
    "app": {
      "output": [
        "type=image,push=true"
      ]
    }
  }
}

빌드 후 자동 Push가 가능합니다.

Docker Buildx Bake JSON 실행 방법

JSON 파일을 지정하여 실행합니다.

docker buildx bake \
-f docker-bake.json

기본 파일명을 사용하는 경우:

docker buildx bake

자동으로 설정 파일을 읽습니다.

Docker Buildx Bake JSON 실무 활용 예제

프로젝트 구조:

project/

├── docker-bake.json

├── api/

│   └── Dockerfile

└── web/

    └── Dockerfile

docker-bake.json:

{
  "group": {
    "default": {
      "targets": [
        "api",
        "web"
      ]
    }
  },

  "target": {
    "api": {
      "context": "./api",
      "tags": [
        "company/api:latest"
      ]
    },

    "web": {
      "context": "./web",
      "tags": [
        "company/web:latest"
      ]
    }
  }
}

실행:

docker buildx bake

API와 Web 이미지가 자동으로 빌드됩니다.

Linux 서버 문제 해결

CI/CD 환경에서 여러 Docker 이미지 빌드 설정을 관리하고 있었습니다.

기존 방식:

docker buildx build api

docker buildx build web

docker buildx build worker

빌드 명령이 많아지면서 관리가 어려워졌습니다.

JSON Bake 파일을 작성했습니다.

{
  "group": {
    "default": {
      "targets": [
        "api",
        "web",
        "worker"
      ]
    }
  }
}

이후 실행:

docker buildx bake \
-f docker-bake.json

모든 이미지 빌드가 자동화되었습니다.

Docker Buildx Bake JSON을 활용하면 프로그램과 연동 가능한 구조적인 Docker 빌드 환경을 만들 수 있습니다.

Docker Buildx Bake JSON 사용 시 주의사항

첫 번째는 JSON은 HCL보다 작성량이 많을 수 있습니다.

두 번째는 괄호와 쉼표 오류가 발생하기 쉬우므로 검증이 필요합니다.

세 번째는 사람이 직접 관리하는 경우 HCL이 더 편리할 수 있습니다.

네 번째는 자동 생성 환경에서는 JSON이 더 적합합니다.

Best Practice

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

CI/CD 자동화 환경에서 활용합니다.
JSON Schema 검증을 사용합니다.
환경별 파일을 분리합니다.
Git으로 버전 관리합니다.
Target 구조를 명확하게 작성합니다.
HCL과 목적에 따라 선택합니다.

자주 묻는 질문

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

일반적으로 docker-bake.json을 사용합니다.

HCL과 JSON 중 어떤 것이 더 좋은가요?

직접 작성은 HCL, 자동 생성은 JSON이 편리합니다.

JSON으로 멀티 플랫폼 빌드가 가능한가요?

가능합니다.

Platform 옵션을 사용하면 됩니다.

Dockerfile 대신 JSON을 사용하나요?

아닙니다.

Dockerfile은 이미지 생성 과정, JSON은 빌드 설정 관리 역할입니다.

마무리

Docker Buildx Bake JSON은 Docker 빌드 설정을 구조화된 데이터 형태로 관리할 수 있는 강력한 방법입니다.

특히 CI/CD 환경이나 자동화 시스템에서는 JSON 형식이 다른 도구와 연동하기 쉬워 효율적인 빌드 파이프라인 구축에 도움이 됩니다.

Docker Buildx Bake HCL과 JSON을 상황에 맞게 활용하면 여러 Docker 이미지와 플랫폼을 더욱 안정적으로 관리할 수 있습니다.