Docker Image를 Build할 때 최종 결과물을 어디에 저장할지 결정하는 것은 매우 중요합니다.

기본적인 Docker Build:

Docker Build

↓

Docker Image 생성

↓

Local Docker Engine 저장

하지만 실제 운영 환경에서는 다양한 저장 방식이 필요합니다.

예:

• Docker Image 저장
• Registry Push
• Local 파일 저장
• OCI Image 저장
• Docker Archive 생성
• CI/CD Artifact 저장

Docker Buildx Bake에서는 Output 옵션(output) 을 사용하여 Build 결과의 저장 위치와 형식을 지정할 수 있습니다.

예:

docker-bake.hcl

target "app" {

  output = [
    "type=image,name=company/app:latest,push=true"
  ]

}

실행:

docker buildx bake app

결과:

Docker Build

↓

Image 생성

↓

Registry Push

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

Docker Buildx Bake Output이란 무엇인가?

Docker Buildx Bake Output은 Build 결과물을 저장할 위치와 방식을 지정하는 기능입니다.

기본 구조:

Dockerfile

↓

Build 실행

↓

Output 설정

↓

결과 저장

Output을 통해 Build 결과가 어디로 이동할지 결정할 수 있습니다.

Docker Buildx Bake Output이 필요한 이유

일반 Docker Build:

docker build

↓

Local Image 저장

문제:

• Registry Push 자동화 어려움
• CI 환경 활용 어려움
• Artifact 관리 어려움

Output 사용:

Docker Build

↓

원하는 저장 위치 선택

↓

자동 관리

장점:

• Registry 자동 Push
• 파일 저장 가능
• CI/CD 활용 가능
• 배포 자동화 가능

Docker Buildx Bake Output 기본 설정

docker-bake.hcl:

target "app" {

  output = [

    "type=docker"

  ]

}

실행:

docker buildx bake app

결과:

Docker Image

↓

Local Docker Engine 저장

Docker Buildx Bake Output 타입 종류

Docker Buildx에서는 여러 Output 타입을 제공합니다.

type=docker

Docker Engine에 Image 저장

예:

output = [

  "type=docker"

]

특징:

• docker images 확인 가능
• Local 테스트 적합

확인:

docker images

---

type=image

Image 형태로 출력

예:

output = [

  "type=image"

]

특징:

• Registry Push 가능
• Image Metadata 유지

예:

output = [

  "type=image,push=true"

]

---

type=registry

Registry 저장 방식

예:

output = [

  "type=image,push=true"

]

결과:

Build

↓

Image 생성

↓

Registry Push

운영 환경에서 가장 많이 사용합니다.

---

type=local

Local 파일 저장

예:

output = [

  "type=local,dest=./output"

]

결과:

output/

├── image

└── metadata

테스트와 Artifact 저장에 사용됩니다.

---

type=oci

OCI Image Format 저장

예:

output = [

  "type=oci,dest=image.tar"

]

활용:

• Image 백업
• 다른 시스템 이동

Docker Buildx Bake Output Registry Push 설정

운영 환경에서는 Build 후 Registry Push를 많이 사용합니다.

docker-bake.hcl:

target "production" {

  tags = [

    "registry.company.com/app:v1"

  ]

  output = [

    "type=image,push=true"

  ]

}

실행:

docker buildx bake production

결과:

Image Build

↓

Tag 적용

↓

Registry Push

Docker Buildx Bake Output과 Tags 함께 사용하기

Output은 Tag와 함께 사용하는 경우가 많습니다.

예:

target "app" {

  tags = [

    "company/app:v1.0.0"

  ]

  output = [

    "type=image,push=true"

  ]

}

흐름:

Build

↓

Tag 생성

↓

Push

Docker Buildx Bake Output Local 저장 활용

개발 환경에서는 Local 저장이 편리합니다.

설정:

target "test" {

  output = [

    "type=docker"

  ]

}

결과:

Build 완료

↓

docker images 확인 가능

테스트 목적에 적합합니다.

Docker Buildx Bake Output CI/CD 활용

CI 환경에서는 Registry 또는 Artifact 저장이 중요합니다.

GitHub Actions 예:

- name: Build Image

  run: |

    docker buildx bake production

Bake:

target "production" {

  output = [

    "type=image,push=true"

  ]

}

흐름:

Code Push

↓

Build

↓

Image 생성

↓

Registry 저장

Docker Buildx Bake Output Multi-platform 활용

Multi-platform Build에서는 Image Output을 사용해야 합니다.

예:

target "app" {

  platforms = [

    "linux/amd64",

    "linux/arm64"

  ]


  output = [

    "type=image,push=true"

  ]

}

결과:

Image Manifest

├── amd64

└── arm64

Docker Buildx Bake Output 실무 예제

프로젝트:

project/

├── Dockerfile

├── docker-bake.hcl

└── deployment.yaml

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

결과:

Docker Image 생성

↓

Multi-platform Manifest 생성

↓

Registry Push

Docker Buildx Bake Output 문제 해결

Image가 Local에 보이지 않는 경우

원인:

type=image 사용

확인:

docker images

Local 저장 필요 시:

output = [

"type=docker"

]

Registry Push 실패

확인:

docker login

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

Multi-platform 오류

확인:

output = [

"type=image,push=true"

]

Multi-platform은 Registry 저장 방식이 필요합니다.

Docker Buildx Bake Output 사용 시 주의사항

첫 번째는 목적에 맞는 Output 타입을 선택해야 합니다.

두 번째는 Multi-platform Build에서는 Registry Push 방식을 권장합니다.

세 번째는 Local 저장과 Registry 저장 방식을 구분해야 합니다.

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

Best Practice

Docker Buildx Bake Output 활용 방법:

• 운영은 type=image 사용
• Registry Push 자동화
• 개발은 type=docker 활용
• Artifact는 type=local 활용
• Multi-platform은 Registry 저장
• CI/CD Pipeline 연결

자주 묻는 질문

Docker Buildx Bake Output은 무엇인가요?

Docker Build 결과물을 어디에 저장할지 지정하는 기능입니다.

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

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

Local Docker에 저장할 수 있나요?

가능합니다.

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

Multi-platform Image도 저장할 수 있나요?

가능합니다.

Registry Push 방식으로 관리하는 것이 일반적입니다.

마무리

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

Local 테스트부터 Registry 배포, CI/CD Artifact 저장까지 다양한 환경에 맞게 Output 방식을 선택할 수 있습니다.

특히 운영 환경에서는 Image Push 설정과 Multi-platform Output 구성을 활용하면 안정적인 Docker 배포 시스템을 구축할 수 있습니다.