Docker 이미지를 빌드할 때 단순히 이미지를 생성하는 것뿐 아니라, 빌드 결과물을 원하는 형태로 저장하거나 다른 시스템으로 전달해야 하는 경우가 있습니다.

예:

• Docker Image 로컬 저장
• Registry Push
• 파일 형태로 Export
• Build 결과물 추출
• CI/CD Artifact 생성

기본 Docker Build:

docker buildx build .

하지만 Buildx Bake에서는 output 설정을 통해 빌드 결과를 원하는 위치와 형태로 관리할 수 있습니다.

예:

docker-bake.hcl

target "app" {

  output = [
    "type=docker"
  ]

}

실행:

docker buildx bake app

결과:

Docker Image

↓

Local Docker Engine 저장

이번 글에서는 Docker Buildx Bake Output의 개념부터 output 종류, Docker 저장, Registry Push, Local Export, CI/CD 활용 방법까지 자세히 알아보겠습니다.

Docker Buildx Bake Output이란 무엇인가?

Docker Buildx Bake Output은 Docker Build 결과물을 어디로 보낼지 지정하는 설정입니다.

기본 흐름:

Docker Build

↓

Build Result 생성

↓

Output 지정

↓

저장 또는 전송

Output은 다음과 같은 결과 형태를 지원합니다.

• Docker Image
• Registry Image
• Local File
• Tar Archive
• OCI Image

Docker Buildx Bake Output이 필요한 이유

일반적인 Docker Build:

docker buildx build -t app:v1 .

문제:

• 결과 저장 위치 제한
• 자동화 어려움
• CI Artifact 생성 어려움

Output 사용:

Build

↓

Output 설정

↓

원하는 위치 저장

장점:

• 이미지 관리 편리
• 배포 방식 선택 가능
• CI/CD 자동화 가능
• 테스트 환경 구성 쉬움

Docker Buildx Bake Output 기본 사용법

docker-bake.hcl:

target "app" {

  context = "."

  tags = [
    "company/app:v1"
  ]

  output = [
    "type=docker"
  ]

}

실행:

docker buildx bake app

결과:

Docker Image

↓

Local Docker Engine

Docker Buildx Bake Output 종류

Docker Buildx Bake에서 많이 사용하는 Output은 다음과 같습니다.

type=docker

Docker Engine 이미지로 저장합니다.

예:

output = [
  "type=docker"
]

사용 목적:

• 로컬 테스트
• 개발 환경 실행

확인:

docker images

type=registry 사용법

Registry로 직접 Push합니다.

예:

output = [
  "type=registry"
]

또는:

docker buildx bake --push

흐름:

Build

↓

Registry Push

사용:

• Docker Hub
• Harbor
• ECR
• Private Registry

type=local 사용법

파일 형태로 결과물을 저장합니다.

예:

output = [
  "type=local,dest=./output"
]

결과:

output/

├── 파일1

├── 파일2

└── 결과물

활용:

• Build Artifact 생성
• 테스트 파일 추출

type=tar 사용법

이미지를 Tar 파일로 저장합니다.

예:

output = [
  "type=tar,dest=image.tar"
]

결과:

image.tar

불러오기:

docker load < image.tar

활용:

• Offline 서버 배포
• 폐쇄망 환경

type=oci 사용법

OCI Image 형식으로 저장합니다.

예:

output = [
  "type=oci,dest=image.tar"
]

활용:

• Container Runtime 호환
• 표준 Image Format 저장

Docker Buildx Bake Output Docker 저장 예제

docker-bake.hcl:

target "development" {

  tags = [
    "company/app:dev"
  ]

  output = [
    "type=docker"
  ]

}

실행:

docker buildx bake development

결과:

company/app:dev

↓

Docker Local Image

개발자가 바로 실행할 수 있습니다.

Docker Buildx Bake Output Registry Push 예제

docker-bake.hcl:

target "production" {

  tags = [
    "registry.company.com/app:v1"
  ]

  output = [
    "type=registry"
  ]

}

실행:

docker buildx bake production --push

결과:

Docker Image

↓

Private Registry 저장

Docker Buildx Bake Output과 CI/CD 활용

CI 환경에서는 Output 설정이 매우 중요합니다.

예:

GitHub Actions:

- name: Build

  run: |

    docker buildx bake production --push

흐름:

Code Push

↓

CI 실행

↓

Buildx Bake

↓

Output 설정 적용

↓

Registry 저장

자동 배포 환경을 만들 수 있습니다.

Docker Buildx Bake Output Multi-platform 활용

Multi-platform 빌드는 Output 설정이 중요합니다.

예:

target "app" {

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

  output = [
    "type=registry"
  ]

}

실행:

docker buildx bake app --push

결과:

Image Manifest

├── amd64

└── arm64

여러 서버 환경에서 사용할 수 있습니다.

Docker Buildx Bake Output 실무 예제

프로젝트:

project/

├── Dockerfile

├── docker-bake.hcl

└── output/

docker-bake.hcl:

group "default" {

  targets = [
    "app"
  ]

}


target "app" {

  context = "."

  tags = [
    "company/app:v1"
  ]

  output = [
    "type=docker"
  ]

}

실행:

docker buildx bake

결과:

Docker Image 생성

↓

Local Docker 저장

Docker Buildx Bake Output 문제 해결

Image가 보이지 않는 경우

확인:

docker images

Buildx Driver에 따라 Local 저장이 안 될 수 있습니다.

해결:

output = [
  "type=docker"
]

추가합니다.

Registry Push 실패

확인:

docker login

Registry 인증 상태를 확인합니다.

Multi-platform Build 실패

확인:

docker buildx ls

Builder 설정을 확인합니다.

Docker Buildx Bake Output 사용 시 주의사항

첫 번째는 Output 종류를 목적에 맞게 선택해야 합니다.

두 번째는 Multi-platform Build에서는 type=docker 사용이 제한될 수 있습니다.

세 번째는 운영 환경에서는 Registry Output 사용을 권장합니다.

네 번째는 CI/CD에서는 Artifact 관리 정책이 필요합니다.

Best Practice

Docker Buildx Bake Output 활용 방법:

• 개발 환경은 type=docker 사용
• 운영 배포는 type=registry 사용
• 파일 전달은 type=tar 활용
• CI Artifact는 type=local 활용
• Multi-platform은 Registry 사용
• Output 설정을 Bake File로 관리

자주 묻는 질문

Docker Buildx Bake Output은 무엇인가요?

Docker Build 결과물을 저장하거나 전달하는 방식을 지정하는 기능입니다.

로컬 Docker 이미지로 저장할 수 있나요?

가능합니다.

type=docker Output을 사용하면 됩니다.

Registry Push도 가능한가요?

가능합니다.

type=registry 또는 --push 옵션을 사용합니다.

Tar 파일로 저장할 수 있나요?

가능합니다.

type=tar Output을 사용하면 이미지 파일로 저장할 수 있습니다.

마무리

Docker Buildx Bake Output은 Docker Build 결과물을 원하는 형태와 위치로 관리할 수 있게 해주는 핵심 기능입니다.

개발 환경에서는 Local Image 저장, 운영 환경에서는 Registry Push, 폐쇄망 환경에서는 Tar Export 등 상황에 맞는 Output 방식을 선택할 수 있습니다.

특히 CI/CD, Kubernetes, Multi-platform 환경에서는 Output 설정을 적절하게 구성하면 더욱 효율적인 Docker 이미지 관리 시스템을 구축할 수 있습니다.