Docker Buildx Bake JSON 사용법 완벽 가이드! JSON 형식으로 Bake 설정 작성하기

Docker Buildx Bake는 여러 Docker 이미지의 빌드 설정을 파일로 관리하고, 여러 빌드 대상을 한 번에 실행할 수 있도록 도와주는 기능입니다. 복잡한 docker buildx build 명령어를 매번 길게 입력하는 대신 빌드 컨텍스트, Dockerfile, 이미지 태그, 플랫폼, 캐시, 출력 방식 등을 하나의 Bake 설정 파일에 작성할 수 있습니다.

Bake 설정은 HCL뿐만 아니라 JSON과 Docker Compose YAML 형식도 지원합니다. JSON 형식은 문법이 명확하고 다른 프로그램에서 자동으로 생성하거나 수정하기 쉬워 CI/CD 환경과 빌드 자동화 시스템에서 유용하게 사용할 수 있습니다. 이번 글에서는 docker-bake.json 파일의 기본 구조부터 타깃, 그룹, 변수, 멀티 플랫폼 빌드 설정과 실행 방법까지 단계별로 알아보겠습니다.

Docker Buildx Bake란 무엇인가?

Docker Buildx Bake는 Docker Buildx에 포함된 고수준 빌드 명령어입니다. 일반적인 Docker 빌드는 다음과 같이 여러 옵션을 명령줄에 직접 작성합니다.

docker buildx build \
  --file Dockerfile \
  --tag myuser/webapp:latest \
  --platform linux/amd64,linux/arm64 \
  --push \
  .

옵션이 많아질수록 명령어가 길어지고, 개발 환경과 운영 환경에서 서로 다른 설정을 관리하기도 어려워집니다.

Bake를 사용하면 이러한 빌드 설정을 파일에 선언할 수 있습니다.

docker buildx bake

Bake 파일 안에 여러 빌드 타깃을 정의하면 하나의 명령으로 여러 이미지를 실행할 수 있으며, 지정된 여러 타깃은 가능한 경우 병렬로 빌드됩니다.

Docker Buildx Bake에서 지원하는 파일 형식

Docker Buildx Bake는 다음 형식의 설정 파일을 지원합니다.

• HCL
• JSON
• Docker Compose YAML

JSON 형식의 기본 파일명은 다음과 같습니다.

docker-bake.json

설정을 덮어쓰기 위한 JSON 파일은 다음 이름으로 작성할 수 있습니다.

docker-bake.override.json

현재 디렉터리에서 docker buildx bake를 실행하면 Buildx는 지원되는 기본 파일명을 순서대로 검색합니다. 여러 Bake 파일이 존재하면 설정을 하나로 병합하며, 일부 중복 속성은 나중에 불러온 파일의 값으로 덮어씁니다.

특정 JSON 파일을 직접 지정하려면 -f 또는 --file 옵션을 사용합니다.

docker buildx bake -f docker-bake.json

다른 이름의 파일도 사용할 수 있습니다.

docker buildx bake -f bake.production.json

docker-bake.json 기본 구조

가장 기본적인 JSON Bake 파일은 다음과 같이 작성할 수 있습니다.

{
  "target": {
    "webapp": {
      "context": ".",
      "dockerfile": "Dockerfile",
      "tags": [
        "myuser/webapp:latest"
      ]
    }
  }
}

각 항목의 의미는 다음과 같습니다.

• target: 빌드 대상을 정의하는 최상위 객체
• webapp: 사용자가 지정한 타깃 이름
• context: Docker 빌드 컨텍스트
• dockerfile: 사용할 Dockerfile 경로
• tags: 생성할 이미지 태그 목록

Bake의 타깃 하나는 일반적으로 docker build 또는 docker buildx build 명령 한 번에 해당하는 빌드 설정을 나타냅니다.

다음 명령으로 webapp 타깃을 실행할 수 있습니다.

docker buildx bake webapp

파일 이름이 docker-bake.json이고 현재 디렉터리에 있다면 -f 옵션을 생략할 수 있습니다.

Bake JSON 설정 미리 확인하기

실제 이미지 빌드를 실행하기 전에 --print 옵션으로 최종 설정을 확인하는 것이 좋습니다.

docker buildx bake --print

특정 타깃만 확인하려면 타깃 이름을 함께 입력합니다.

docker buildx bake --print webapp

별도의 JSON 파일을 지정하는 경우에는 다음과 같이 실행합니다.

docker buildx bake -f docker-bake.json --print

--print는 Bake 파일 병합, 변수 적용 및 설정 해석이 끝난 결과를 JSON 형태로 보여줍니다. 실제 빌드 전에 잘못된 경로, 이미지 태그 또는 플랫폼 설정을 점검할 때 유용합니다.

여러 Build Target 작성하기

하나의 JSON 파일에 여러 타깃을 정의할 수 있습니다.

{
  "target": {
    "frontend": {
      "context": "./frontend",
      "dockerfile": "Dockerfile",
      "tags": [
        "myuser/frontend:latest"
      ]
    },
    "backend": {
      "context": "./backend",
      "dockerfile": "Dockerfile",
      "tags": [
        "myuser/backend:latest"
      ]
    }
  }
}

프런트엔드 이미지만 빌드하려면 다음 명령을 사용합니다.

docker buildx bake frontend

백엔드 이미지만 빌드하려면 다음과 같이 실행합니다.

docker buildx bake backend

두 타깃을 함께 지정할 수도 있습니다.

docker buildx bake frontend backend

여러 타깃을 지정하면 Buildx Bake가 빌드 작업을 조정하며, 독립적으로 실행할 수 있는 타깃은 병렬로 처리할 수 있습니다.

Group으로 여러 Target 묶기

여러 타깃을 자주 함께 빌드한다면 group을 사용하는 것이 편리합니다.

{
  "group": {
    "default": {
      "targets": [
        "frontend",
        "backend"
      ]
    }
  },
  "target": {
    "frontend": {
      "context": "./frontend",
      "dockerfile": "Dockerfile",
      "tags": [
        "myuser/frontend:latest"
      ]
    },
    "backend": {
      "context": "./backend",
      "dockerfile": "Dockerfile",
      "tags": [
        "myuser/backend:latest"
      ]
    }
  }
}

default 그룹이 정의되어 있으면 다음 명령으로 그룹에 포함된 타깃을 실행할 수 있습니다.

docker buildx bake

그룹 이름을 직접 지정해도 됩니다.

docker buildx bake default

운영용 그룹을 별도로 만들 수도 있습니다.

{
  "group": {
    "production": {
      "targets": [
        "frontend-prod",
        "backend-prod"
      ]
    }
  },
  "target": {
    "frontend-prod": {
      "context": "./frontend",
      "dockerfile": "Dockerfile",
      "tags": [
        "myuser/frontend:production"
      ]
    },
    "backend-prod": {
      "context": "./backend",
      "dockerfile": "Dockerfile",
      "tags": [
        "myuser/backend:production"
      ]
    }
  }
}

실행 명령은 다음과 같습니다.

docker buildx bake production

JSON Bake 파일에서 변수 사용하기

Bake 파일에는 variable 객체를 정의할 수 있습니다.

{
  "variable": {
    "TAG": {
      "default": "latest"
    }
  },
  "target": {
    "webapp": {
      "context": ".",
      "dockerfile": "Dockerfile",
      "tags": [
        "myuser/webapp:${TAG}"
      ]
    }
  }
}

기본값을 사용하면 다음 이미지 태그가 적용됩니다.

myuser/webapp:latest

환경변수로 기본값을 변경할 수도 있습니다.

Linux 또는 macOS에서는 다음과 같이 실행합니다.

TAG=1.0.0 docker buildx bake webapp

Windows PowerShell에서는 다음과 같이 설정할 수 있습니다.

$env:TAG="1.0.0"
docker buildx bake webapp

이제 실제 이미지 태그는 다음과 같이 해석됩니다.

myuser/webapp:1.0.0

Bake 변수에는 기본값과 설명을 지정할 수 있으며, 환경변수를 사용해 파일을 직접 수정하지 않고 값을 덮어쓸 수 있습니다.

Dockerfile Build Argument 설정하기

Dockerfile에 다음과 같은 ARG가 있다고 가정해 보겠습니다.

FROM node:22-alpine

ARG NODE_ENV=production

WORKDIR /app

COPY . .

RUN echo "Build environment: ${NODE_ENV}"

CMD ["node", "server.js"]

JSON Bake 파일에서는 args를 사용해 값을 전달합니다.

{
  "target": {
    "webapp": {
      "context": ".",
      "dockerfile": "Dockerfile",
      "args": {
        "NODE_ENV": "production"
      },
      "tags": [
        "myuser/webapp:latest"
      ]
    }
  }
}

여러 Build Argument도 함께 지정할 수 있습니다.

{
  "target": {
    "webapp": {
      "context": ".",
      "dockerfile": "Dockerfile",
      "args": {
        "NODE_ENV": "production",
        "APP_VERSION": "1.0.0",
        "API_URL": "https://api.example.com"
      },
      "tags": [
        "myuser/webapp:1.0.0"
      ]
    }
  }
}

일반 명령어의 다음 옵션을 Bake 파일로 옮긴 것과 비슷합니다.

docker buildx build \
  --build-arg NODE_ENV=production \
  --build-arg APP_VERSION=1.0.0 \
  .

멀티 플랫폼 이미지 설정하기

platforms 속성을 사용하면 여러 CPU 아키텍처용 이미지를 빌드할 수 있습니다.

{
  "target": {
    "webapp": {
      "context": ".",
      "dockerfile": "Dockerfile",
      "platforms": [
        "linux/amd64",
        "linux/arm64"
      ],
      "tags": [
        "myuser/webapp:latest"
      ]
    }
  }
}

멀티 플랫폼 빌드는 하나의 빌드 실행에서 서로 다른 운영체제 또는 CPU 아키텍처를 대상으로 이미지를 생성하는 방식입니다. 대표적으로 linux/amd64와 linux/arm64 조합을 사용할 수 있습니다.

레지스트리로 바로 푸시하려면 output 또는 outputs 설정을 추가합니다.

{
  "target": {
    "webapp": {
      "context": ".",
      "dockerfile": "Dockerfile",
      "platforms": [
        "linux/amd64",
        "linux/arm64"
      ],
      "tags": [
        "myuser/webapp:latest"
      ],
      "output": [
        "type=registry"
      ]
    }
  }
}

환경에 따라 속성 표현과 지원 여부가 달라질 수 있으므로 실제 실행 전 다음 명령으로 최종 설정을 확인합니다.

docker buildx bake --print webapp

로컬 Docker 이미지로 불러오기

단일 플랫폼 이미지를 빌드한 뒤 현재 Docker Engine 이미지 저장소로 불러오려면 Docker 출력 방식을 지정할 수 있습니다.

{
  "target": {
    "webapp": {
      "context": ".",
      "dockerfile": "Dockerfile",
      "platforms": [
        "linux/amd64"
      ],
      "tags": [
        "myuser/webapp:local"
      ],
      "output": [
        "type=docker"
      ]
    }
  }
}

빌드를 실행합니다.

docker buildx bake webapp

완료 후 이미지를 확인합니다.

docker image ls

type=docker 출력은 일반적으로 로컬 Docker 이미지 저장소로 결과물을 불러올 때 사용합니다. 여러 플랫폼을 동시에 로컬 Docker 이미지로 불러오는 방식에는 제약이 있을 수 있으므로, 멀티 플랫폼 결과는 레지스트리 푸시나 OCI 출력 방식을 사용하는 것이 일반적입니다.

캐시 설정 추가하기

BuildKit 캐시를 사용하면 이전 빌드 결과를 재사용해 반복 빌드 시간을 단축할 수 있습니다.

로컬 캐시를 사용하는 JSON 예시는 다음과 같습니다.

{
  "target": {
    "webapp": {
      "context": ".",
      "dockerfile": "Dockerfile",
      "tags": [
        "myuser/webapp:latest"
      ],
      "cache-from": [
        "type=local,src=.buildx-cache"
      ],
      "cache-to": [
        "type=local,dest=.buildx-cache,mode=max"
      ]
    }
  }
}

레지스트리 캐시를 사용할 수도 있습니다.

{
  "target": {
    "webapp": {
      "context": ".",
      "dockerfile": "Dockerfile",
      "tags": [
        "myuser/webapp:latest"
      ],
      "cache-from": [
        "type=registry,ref=myuser/webapp:buildcache"
      ],
      "cache-to": [
        "type=registry,ref=myuser/webapp:buildcache,mode=max"
      ]
    }
  }
}

CI/CD 환경에서는 빌드 실행 환경이 매번 새로 만들어질 수 있으므로 로컬 캐시보다 레지스트리 또는 CI 전용 원격 캐시가 유용할 수 있습니다.

Target 상속 설정하기

여러 타깃에 공통 설정이 있다면 inherits를 사용할 수 있습니다.

{
  "target": {
    "base": {
      "context": ".",
      "dockerfile": "Dockerfile",
      "platforms": [
        "linux/amd64",
        "linux/arm64"
      ]
    },
    "development": {
      "inherits": [
        "base"
      ],
      "args": {
        "NODE_ENV": "development"
      },
      "tags": [
        "myuser/webapp:dev"
      ]
    },
    "production": {
      "inherits": [
        "base"
      ],
      "args": {
        "NODE_ENV": "production"
      },
      "tags": [
        "myuser/webapp:latest"
      ],
      "output": [
        "type=registry"
      ]
    }
  }
}

개발 이미지를 빌드합니다.

docker buildx bake development

운영 이미지를 빌드하고 레지스트리로 내보냅니다.

docker buildx bake production

공통 설정을 base 타깃에 모으면 Dockerfile 경로, 컨텍스트, 플랫폼 등의 반복을 줄일 수 있습니다.

완성된 docker-bake.json 예제

다음은 변수, 그룹, 공통 타깃, 개발용 타깃과 운영용 타깃을 포함한 예제입니다.

{
  "variable": {
    "REGISTRY": {
      "default": "docker.io"
    },
    "IMAGE_NAME": {
      "default": "myuser/webapp"
    },
    "TAG": {
      "default": "latest"
    }
  },
  "group": {
    "default": {
      "targets": [
        "development"
      ]
    },
    "release": {
      "targets": [
        "production"
      ]
    }
  },
  "target": {
    "base": {
      "context": ".",
      "dockerfile": "Dockerfile"
    },
    "development": {
      "inherits": [
        "base"
      ],
      "args": {
        "NODE_ENV": "development"
      },
      "platforms": [
        "linux/amd64"
      ],
      "tags": [
        "${REGISTRY}/${IMAGE_NAME}:dev"
      ],
      "output": [
        "type=docker"
      ]
    },
    "production": {
      "inherits": [
        "base"
      ],
      "args": {
        "NODE_ENV": "production"
      },
      "platforms": [
        "linux/amd64",
        "linux/arm64"
      ],
      "tags": [
        "${REGISTRY}/${IMAGE_NAME}:${TAG}"
      ],
      "cache-from": [
        "type=registry,ref=${REGISTRY}/${IMAGE_NAME}:buildcache"
      ],
      "cache-to": [
        "type=registry,ref=${REGISTRY}/${IMAGE_NAME}:buildcache,mode=max"
      ],
      "output": [
        "type=registry"
      ]
    }
  }
}

개발용 기본 타깃을 실행합니다.

docker buildx bake

운영용 release 그룹을 실행합니다.

TAG=1.0.0 docker buildx bake release

최종 설정만 확인하려면 다음 명령을 사용합니다.

TAG=1.0.0 docker buildx bake release --print

JSON 문법 오류 확인하기

JSON은 쉼표와 큰따옴표 규칙이 엄격합니다. 다음과 같은 실수가 자주 발생합니다.

잘못된 예시는 다음과 같습니다.

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

"dockerfile": "Dockerfile" 뒤에 불필요한 쉼표가 있으므로 올바른 JSON이 아닙니다.

수정된 예시는 다음과 같습니다.

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

JSON에서는 일반적으로 다음 규칙을 지켜야 합니다.

• 문자열과 속성 이름은 큰따옴표로 작성합니다.
• 마지막 속성 뒤에는 쉼표를 넣지 않습니다.
• 주석을 직접 작성하지 않습니다.
• 중괄호와 대괄호의 개수를 맞춥니다.
• 객체에는 {}를 사용하고 배열에는 []를 사용합니다.

파일 자체의 JSON 문법을 검사하려면 jq를 사용할 수 있습니다.

jq . docker-bake.json

Python을 이용해 검사할 수도 있습니다.

python -m json.tool docker-bake.json

JSON 문법이 정상이어도 Bake 속성 이름이나 값이 잘못되면 실행 단계에서 오류가 발생할 수 있습니다. 따라서 JSON 검사 후 Bake 설정도 확인하는 것이 좋습니다.

docker buildx bake -f docker-bake.json --print

Docker Buildx Bake JSON 실행 오류 해결하기

docker-bake.json 파일을 찾지 못하는 경우

다음과 같은 오류가 발생할 수 있습니다.

failed to find target

또는 현재 디렉터리의 설정 파일을 불러오지 못할 수 있습니다.

파일 위치를 확인합니다.

ls -l docker-bake.json

파일을 직접 지정합니다.

docker buildx bake -f ./docker-bake.json

지정한 Target이 없는 경우

다음 명령을 실행했다고 가정해 보겠습니다.

docker buildx bake app

JSON 파일에 app 타깃이 없으면 실행할 수 없습니다.

{
  "target": {
    "webapp": {
      "context": "."
    }
  }
}

이 경우 실제 타깃 이름인 webapp을 사용해야 합니다.

docker buildx bake webapp

Dockerfile 경로가 잘못된 경우

{
  "target": {
    "webapp": {
      "context": ".",
      "dockerfile": "docker/Dockerfile"
    }
  }
}

Dockerfile이 실제 경로에 존재하는지 확인합니다.

ls -l docker/Dockerfile

dockerfile 경로는 빌드 컨텍스트와 파일 위치를 고려해 정확하게 지정해야 합니다.

변수가 적용되지 않는 경우

변수 이름의 대소문자가 일치하는지 확인합니다.

{
  "variable": {
    "TAG": {
      "default": "latest"
    }
  },
  "target": {
    "webapp": {
      "tags": [
        "myuser/webapp:${TAG}"
      ]
    }
  }
}

환경변수도 같은 이름으로 설정합니다.

TAG=2.0.0 docker buildx bake webapp --print

JSON 형식과 HCL 형식의 차이

JSON 형식은 다음과 같은 장점이 있습니다.

• 문법 구조가 명확합니다.
• 다양한 프로그래밍 언어에서 쉽게 생성할 수 있습니다.
• API나 자동화 도구에서 수정하기 편리합니다.
• JSON 검증 도구를 사용할 수 있습니다.

반면 다음과 같은 단점도 있습니다.

• 주석을 작성하기 어렵습니다.
• 쉼표와 큰따옴표 규칙이 엄격합니다.
• 복잡한 표현식과 조건 로직은 HCL이 더 편리할 수 있습니다.
• 설정이 길어지면 중괄호와 대괄호가 많아져 가독성이 떨어질 수 있습니다.

특히 Bake의 연산, 조건식 및 표현식 기능은 HCL 형식에서 제공되는 기능이 중심이므로 복잡한 동적 설정에는 HCL이 더 적합할 수 있습니다.

설정 파일을 프로그램에서 자동 생성하거나 기존 JSON 기반 시스템과 연동해야 한다면 JSON 형식이 적합합니다. 사람이 직접 관리하고 변수와 조건을 다양하게 활용해야 한다면 HCL 형식도 함께 검토할 수 있습니다.

자주 묻는 질문

docker-bake.json 파일명은 반드시 고정해야 하나요?

아닙니다. 기본 파일명을 사용하면 docker buildx bake가 자동으로 검색하지만, 다른 파일명을 사용할 때는 -f 또는 --file 옵션으로 경로를 지정하면 됩니다.

docker buildx bake -f bake.dev.json

JSON Bake 파일에 주석을 작성할 수 있나요?

표준 JSON은 주석 문법을 지원하지 않습니다. 설명이 많이 필요한 설정이라면 별도의 문서에 기록하거나 HCL 형식을 사용하는 방법을 고려할 수 있습니다.

여러 JSON Bake 파일을 함께 사용할 수 있나요?

가능합니다. -f 옵션을 여러 번 사용해 설정 파일을 순서대로 불러올 수 있습니다.

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

뒤에 지정된 파일의 설정이 앞 파일의 값을 병합하거나 일부 속성을 덮어쓸 수 있습니다.

Bake JSON 파일에서 환경변수를 사용할 수 있나요?

가능합니다. variable에 기본값을 정의하고 같은 이름의 환경변수를 설정하면 실행 시 값을 변경할 수 있습니다.

TAG=3.0.0 docker buildx bake production

모든 Target을 한 번에 빌드하려면 어떻게 하나요?

함께 실행할 타깃을 하나의 그룹으로 묶는 것이 좋습니다.

{
  "group": {
    "all": {
      "targets": [
        "frontend",
        "backend",
        "worker"
      ]
    }
  }
}

다음 명령으로 실행합니다.

docker buildx bake all

빌드하지 않고 설정만 검사할 수 있나요?

--print 옵션을 사용하면 됩니다.

docker buildx bake -f docker-bake.json --print

이 명령으로 변수와 타깃이 적용된 최종 빌드 정의를 확인할 수 있습니다.

마무리

Docker Buildx Bake의 JSON 형식을 사용하면 여러 Docker 이미지의 빌드 설정을 구조적인 파일로 관리할 수 있습니다. target으로 개별 빌드를 정의하고, group으로 여러 타깃을 묶으며, variable을 이용해 이미지 태그와 환경별 값을 유연하게 변경할 수 있습니다.

처음에는 간단한 context, dockerfile, tags 설정부터 시작한 뒤 필요에 따라 platforms, args, cache-from, cache-to, output을 추가하는 것이 좋습니다. 실제 빌드를 실행하기 전에는 반드시 docker buildx bake --print로 최종 설정을 확인하면 경로와 변수, 타깃 이름에서 발생하는 오류를 줄일 수 있습니다.

JSON은 자동화 도구와 연동하기 쉽다는 장점이 있지만 문법이 엄격하므로 jq, python -m json.tool과 같은 도구로 JSON 문법을 검사하고, 이어서 Bake의 --print 옵션으로 빌드 정의까지 검증하는 방식이 안전합니다.

함께 보면 좋은 Docker Buildx Bake 글

• Docker Buildx Bake File 사용법 완벽 가이드
• Docker Buildx Bake Target 사용법 완벽 가이드
• Docker Buildx Bake Group 사용법 완벽 가이드
• Docker Buildx Bake Variable 사용법 완벽 가이드
• Docker Buildx Bake Override 사용법 완벽 가이드
• Docker Buildx Bake Platform 사용법 완벽 가이드
• Docker Buildx Bake Cache 사용법 완벽 가이드
• Docker Buildx Bake Output 사용법 완벽 가이드

docker-buildx-bake-json