Docker Image를 Build할 때 최종 결과물을 어떻게 처리할지 결정하는 것은 매우 중요합니다.

예:

• Docker Image Registry Push
• Local Docker 저장
• 파일 형태 Export
• 압축 파일 생성
• OCI Image 저장
• CI/CD Artifact 생성

기본 Build:

Docker Build 실행

↓

Image 생성

↓

결과 저장 방식 결정

하지만 프로젝트 환경에 따라 원하는 결과 형태가 다릅니다.

예:

개발 환경:

Local Docker Image 필요

운영 환경:

Registry Push 필요

CI 환경:

Artifact 파일 저장 필요

Docker Buildx Bake에서는 Output 설정을 사용하여 Build 결과물을 원하는 형태로 관리할 수 있습니다.

예:

docker-bake.hcl

target "app" {

  output = [

    "type=image,push=true"

  ]

}

실행:

docker buildx bake app

결과:

Docker Image Build

↓

Registry Push

↓

배포 가능 Image 생성

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

Docker Buildx Bake Output이란 무엇인가?

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

기본 구조:

Docker Build

↓

Output 설정

↓

결과 저장

대표적인 Output 종류:

• image
• local
• tar
• oci
• docker

Docker Buildx Bake Output이 필요한 이유

Output 설정 없이 Build하면 환경에 따라 원하는 결과를 얻기 어렵습니다.

예:

CI Build

↓

Image 생성

↓

저장 위치 불명확

Output 사용:

Build

↓

Registry Push

또는

↓

파일 저장

장점:

• 배포 자동화
• Artifact 관리
• 환경별 저장 방식 변경
• Build 결과 제어

Docker Buildx Bake Output 기본 사용법

docker-bake.hcl:

target "production" {

  output = [

    "type=image,push=true"

  ]

}

실행:

docker buildx bake production

동작:

Image 생성

↓

Registry Push

Docker Buildx Bake Output Type=image 사용법

가장 많이 사용하는 방식입니다.

설정:

output = [

  "type=image"

]

의미:

Docker Image 생성

Registry Push:

output = [

  "type=image,push=true"

]

Production 환경에서 많이 사용합니다.

Docker Buildx Bake Output Local 저장

Build 결과를 Local 폴더로 저장할 수 있습니다.

설정:

output = [

  "type=local,dest=./output"

]

결과:

project/

├── output/

    ├── files

    └── metadata

활용:

• 정적 파일 생성
• Build 결과 확인
• 테스트 결과 저장

Docker Buildx Bake Output Type=docker 사용법

Local Docker Engine에 Image를 저장합니다.

설정:

output = [

  "type=docker"

]

결과:

Docker Build

↓

Local Docker Image 저장

확인:

docker images

개발 환경에서 많이 사용합니다.

Docker Buildx Bake Output OCI Export 사용법

OCI Image 형식으로 저장할 수 있습니다.

설정:

output = [

  "type=oci,dest=image.tar"

]

결과:

image.tar 생성

활용:

• Image 백업
• 다른 Container 도구 사용
• Offline 배포

Docker Buildx Bake Output Tar Export 사용법

Tar 파일 형태로 저장합니다.

설정:

output = [

  "type=tar,dest=image.tar"

]

결과:

Docker Layer

↓

tar 파일 저장

Docker Buildx Bake Output Registry Push 활용

운영 환경에서는 Registry Push 방식이 가장 일반적입니다.

예:

target "production" {

  tags = [

    "registry.company.com/app:v1"

  ]

  output = [

    "type=image,push=true"

  ]

}

실행:

docker buildx bake production

결과:

Image Build

↓

Registry 저장

↓

배포 가능

Docker Buildx Bake Output Multi-platform 활용

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

예:

target "production" {

  platforms = [

    "linux/amd64",

    "linux/arm64"

  ]

  output = [

    "type=image,push=true"

  ]

}

결과:

Registry

↓

app:v1

├── amd64

└── arm64

Docker Buildx Bake Output CI/CD 활용

CI/CD에서는 Build 결과를 자동 관리할 수 있습니다.

예:

GitHub Actions:

- name: Build Image

  run: |

    docker buildx bake production

Bake:

output = [

  "type=image,push=true"

]

흐름:

Code Push

↓

CI 실행

↓

Image Build

↓

Registry Push

Docker Buildx Bake Output 실무 예제

프로젝트:

project/

├── Dockerfile

├── docker-bake.hcl

└── output/

docker-bake.hcl:

target "production" {

  tags = [

    "registry.company.com/backend:v1.0.0"

  ]

  platforms = [

    "linux/amd64",

    "linux/arm64"

  ]

  output = [

    "type=image,push=true"

  ]

}

실행:

docker buildx bake production

결과:

Multi-platform Image 생성

↓

Registry Push 완료

Docker Buildx Bake Output 확인 방법

Build 결과 확인:

docker buildx imagetools inspect image-name

Local Image 확인:

docker images

Docker Buildx Bake Output 문제 해결

Image가 Local에 보이지 않는 경우

원인:

type=image,push=true

Registry Push 전용 설정일 수 있습니다.

해결:

output = [

"type=docker"

]

Registry Push 실패

확인:

• Docker Login
• Registry 권한
• Image Tag

Export 파일 생성 실패

확인:

• 저장 경로
• 디렉터리 권한
• 파일 이름

Docker Buildx Bake Output 사용 시 주의사항

첫 번째는 Production에서는 일반적으로 Registry Push 방식을 사용합니다.

두 번째는 Local 저장과 Push 방식을 목적에 맞게 구분해야 합니다.

세 번째는 Multi-platform Build에서는 Docker Export보다 Image Push 방식을 권장합니다.

네 번째는 Artifact 저장 시 파일 크기를 관리해야 합니다.

Best Practice

Docker Buildx Bake Output 활용 방법:

• Production → type=image,push=true
• Development → type=docker
• Backup → type=oci
• Artifact → type=local
• CI/CD → Registry Push
• Multi-platform → Image Output

자주 묻는 질문

Docker Buildx Bake Output은 무엇인가요?

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

가장 많이 사용하는 Output은 무엇인가요?

운영 환경에서는 type=image,push=true 방식을 가장 많이 사용합니다.

Local Docker에 저장할 수 있나요?

가능합니다.

type=docker를 사용하면 됩니다.

Multi-platform Image도 Export 가능한가요?

가능하지만 일반적으로 Registry Push 방식이 더 적합합니다.

마무리

Docker Buildx Bake Output은 Docker Build 결과를 원하는 형태로 관리하기 위한 핵심 기능입니다.

개발 환경에서는 Local Image 저장, 운영 환경에서는 Registry Push, 백업 환경에서는 OCI Export 등 목적에 맞는 Output 방식을 선택할 수 있습니다.

특히 CI/CD Pipeline과 Multi-platform Image 환경에서는 Output 설정을 정확하게 구성하면 안정적인 Docker Build 및 배포 시스템을 구축할 수 있습니다.