Docker 이미지를 빌드하고 운영하다 보면 단순히 이미지를 생성하는 것뿐만 아니라 빌드 과정에 대한 다양한 정보가 필요해집니다.

예:

이미지 Digest 확인
빌드 결과 기록
Git Commit 정보 저장
이미지 생성 시간 확인
CI/CD 배포 정보 관리
빌드 결과 자동 처리

일반적인 Docker Build에서는 빌드 결과를 확인하기 어렵습니다.

하지만 Docker Buildx Bake에서는 Metadata 관리 기능을 활용하여 빌드 정보를 파일로 저장하고 자동화 과정에 활용할 수 있습니다.

예:

docker buildx bake \
--metadata-file metadata.json

실행 후:

metadata.json

파일에 빌드 관련 정보가 저장됩니다.

이번 글에서는 Docker Buildx Bake Metadata의 개념부터 기본 사용법, Metadata 파일 구조, CI/CD 활용 방법까지 자세히 알아보겠습니다.

Table of Contents

Docker Buildx Bake Metadata란 무엇인가?

Docker Buildx Bake Metadata는 Docker 이미지 빌드 결과 정보를 저장하는 기능입니다.

기본 구조:

빌드 실행

↓

Metadata 생성

↓

JSON 파일 저장

↓

자동화 과정 활용

저장되는 정보:

Image ID
Digest
Build 정보
Export 결과
Provenance 정보

Docker Buildx Bake Metadata가 필요한 이유

일반적인 빌드:

docker buildx bake

결과:

Image 생성 완료

하지만 다음 정보를 자동으로 사용하기 어렵습니다.

생성된 Image Digest
정확한 Image ID
배포 대상 정보
빌드 결과 검증

Metadata 사용:

Build 실행

↓

metadata.json 생성

↓

배포 자동화

장점:

빌드 결과 추적
CI/CD 연결
이미지 검증
자동 배포 가능

Docker Buildx Bake Metadata 기본 사용법

명령어:

docker buildx bake \
--metadata-file build-info.json

실행 결과:

build-info.json

파일 생성

파일 예:

{
  "containerimage.digest": "sha256:xxxxx",
  "containerimage.config.digest": "sha256:xxxxx"
}

빌드 결과 정보를 확인할 수 있습니다.

Docker Buildx Bake Metadata 파일 위치 지정하기

원하는 위치에 저장할 수 있습니다.

예:

docker buildx bake \
--metadata-file ./result/metadata.json

결과:

project/

├── result/

│ └── metadata.json

CI/CD Artifact로 저장할 수 있습니다.

Docker Buildx Bake Metadata 주요 정보

Metadata에는 다양한 정보가 포함됩니다.

Image Digest

예:

{
  "containerimage.digest": "sha256:123456"
}

이미지의 고유 식별 값을 제공합니다.

활용:

배포 이미지 확인
무결성 검증

Image Config Digest

예:

{
  "containerimage.config.digest": "sha256:abcdef"
}

이미지 설정 정보를 확인합니다.

Build Provenance 정보

예:

{
  "buildx.build.provenance": {}
}

빌드 출처와 과정을 확인할 수 있습니다.

Docker Buildx Bake Metadata와 CI/CD 활용

CI/CD 환경에서는 빌드 결과를 다음 단계로 전달할 때 유용합니다.

예:

빌드 단계:

docker buildx bake \
--metadata-file metadata.json

결과:

metadata.json

↓

배포 단계 사용

활용:

배포 이미지 확인
Digest 기반 배포
빌드 결과 저장

Docker Buildx Bake Metadata 실무 활용 예제

이미지 Digest 자동 확인

빌드:

docker buildx bake \
--metadata-file result.json

result.json:

{
  "containerimage.digest": "sha256:xxxx"
}

배포 시:

Digest 기준으로 정확한 이미지를 지정할 수 있습니다.

Docker Buildx Bake Metadata와 Push 활용

Registry Push 환경:

docker buildx bake \
--push \
--metadata-file metadata.json

동작:

이미지 빌드

↓

Registry Push

↓

Metadata 저장

운영 배포 정보를 관리하기 좋습니다.

Docker Buildx Bake Metadata와 SBOM 활용

보안 관리 환경에서는 Metadata와 SBOM을 함께 사용할 수 있습니다.

예:

docker buildx bake \
--sbom=true \
--metadata-file metadata.json

결과:

Software 구성 정보
이미지 정보
빌드 기록

보안 검증에 활용할 수 있습니다.

Docker Buildx Bake Metadata와 Attestation 활용

예:

docker buildx bake \
--attest type=provenance \
--metadata-file metadata.json

생성 정보:

빌드 출처
빌드 환경
이미지 생성 과정

공급망 보안을 강화할 수 있습니다.

Linux 서버 문제 해결

Docker 이미지를 자동 배포하는 과정에서 어떤 이미지가 생성되었는지 확인하기 어려운 문제가 있었습니다.

기존:

docker buildx bake --push

문제:

생성된 Digest 확인 어려움
배포 대상 추적 어려움
빌드 기록 부족

Metadata 적용:

docker buildx bake \
--push \
--metadata-file build.json

결과:

build.json

생성

확인:

Image Digest
Build 정보
배포 대상 정보

자동 배포 시스템에서 정확한 이미지를 관리할 수 있었습니다.

Docker Buildx Bake Metadata 사용 시 주의사항

첫 번째는 Metadata 파일을 Git에 무조건 저장하지 않는 것이 좋습니다.

두 번째는 CI/CD Artifact 관리 정책을 정하는 것이 필요합니다.

세 번째는 Metadata와 실제 Image Tag를 함께 관리해야 합니다.

네 번째는 민감한 정보가 포함되는지 확인해야 합니다.

Best Practice

Docker Buildx Bake Metadata 활용 방법:

CI/CD 빌드 결과 저장
Image Digest 관리
배포 기록 관리
SBOM과 함께 사용
Provenance 정보 활용
Artifact 자동 저장

자주 묻는 질문

Docker Buildx Bake Metadata는 무엇인가요?

Docker 이미지 빌드 결과 정보를 파일로 저장하는 기능입니다.

Metadata 파일 형식은 무엇인가요?

일반적으로 JSON 형식으로 저장됩니다.

Image Digest 확인이 가능한가요?

가능합니다.

Metadata 파일에서 확인할 수 있습니다.

CI/CD에서 사용할 수 있나요?