Docker Image를 Build하면 다양한 정보가 생성됩니다.

예:

Image ID
Digest
Build 결과
Tag 정보
Platform 정보
Manifest 정보
Build 시간 정보

일반적인 Build 과정에서는 이러한 정보를 화면 출력으로만 확인할 수 있습니다.

하지만 CI/CD 환경이나 자동 배포 시스템에서는 Build 결과 데이터를 파일로 저장하고 다음 단계에서 활용해야 하는 경우가 많습니다.

Docker Buildx Bake에서는 metadata-file 옵션을 사용하여 Build 결과 정보를 JSON 파일 형태로 저장할 수 있습니다.

예:

docker-bake.hcl

target "app" {

  tags = [
    "company/app:v1.0.0"
  ]

}

실행:

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

결과:

Docker Build 실행

↓

Build Metadata 생성

↓

metadata.json 저장

생성된 파일:

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

이번 글에서는 Docker Buildx Bake Metadata-file의 개념부터 사용 방법, JSON Metadata 분석, CI/CD 자동화, 배포 정보 관리까지 자세히 알아보겠습니다.

Table of Contents

Docker Buildx Bake Metadata-file이란 무엇인가?

Docker Buildx Bake Metadata-file은 Build 결과 정보를 파일로 저장하는 기능입니다.

기본 구조:

Docker Build

↓

Build 결과 생성

↓

Metadata 추출

↓

JSON 파일 저장

저장되는 정보:

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

즉, Build 결과를 자동화 시스템에서 사용할 수 있도록 저장하는 기능입니다.

Docker Buildx Bake Metadata-file이 필요한 이유

일반적인 Build:

docker build

↓

화면 출력

↓

정보 사라짐

문제:

자동화 어려움
배포 단계 연결 어려움
Image 정보 관리 어려움

Metadata-file 사용:

Build

↓

metadata.json 생성

↓

CI/CD 다음 단계 사용

장점:

Build 결과 저장
자동 배포 연결
Image 추적 가능
Digest 관리 가능

Docker Buildx Bake Metadata-file 기본 사용법

명령어:

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

결과:

Build 완료

↓

metadata.json 생성

파일 확인:

cat metadata.json

출력 예:

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

Docker Buildx Bake Metadata-file JSON 구조

Metadata 파일은 JSON 형식으로 저장됩니다.

예:

{
  "buildx.build.ref": "builder-name",
  "containerimage.config.digest": "sha256:abcd",
  "containerimage.digest": "sha256:efgh"
}

주요 항목:

containerimage.digest

Image Manifest Digest 정보입니다.

예:

sha256:abcdef123456

활용:

Image 검증
배포 추적

containerimage.config.digest

Image Configuration Digest입니다.

활용:

Image Metadata 확인
보안 분석

buildx.build.ref

Build 참조 정보입니다.

활용:

Build 추적
CI 로그 연결

Docker Buildx Bake Metadata-file과 CI/CD 활용

CI/CD에서는 Build 결과를 다음 단계로 전달해야 합니다.

예:

Build

↓

Metadata 저장

↓

배포 단계 실행

GitHub Actions 예:

- name: Build Image

  run: |

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

다음 단계:

- name: Deploy

  run: |

    cat metadata.json

Build 결과를 자동으로 활용할 수 있습니다.

Docker Buildx Bake Metadata-file과 Image Digest 관리

운영 환경에서는 Tag보다 Digest 기반 배포를 사용하는 경우가 많습니다.

Tag:

company/app:latest

문제:

Image 변경 가능
정확한 버전 확인 어려움

Digest:

company/app@sha256:abcdef

장점:

동일 Image 보장
안정적인 배포
Rollback 관리

Metadata-file을 사용하면 Digest 정보를 자동 저장할 수 있습니다.

Docker Buildx Bake Metadata-file Registry 활용

Registry Push와 함께 사용할 수 있습니다.

예:

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

흐름:

Image Build

↓

Registry Push

↓

Digest 저장

↓

배포 사용

Docker Buildx Bake Metadata-file Multi-platform 활용

Multi-platform Image에서도 Metadata를 저장할 수 있습니다.

예:

target "production" {

  platforms = [

    "linux/amd64",

    "linux/arm64"

  ]

}

실행:

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

결과:

metadata.json

↓

Multi-platform Manifest 정보 저장

여러 Architecture Image 정보를 관리할 수 있습니다.

Docker Buildx Bake Metadata-file 실무 예제

프로젝트:

project/

├── Dockerfile

├── docker-bake.hcl

└── deploy.sh

docker-bake.hcl:

target "production" {

  tags = [

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

  ]

  platforms = [

    "linux/amd64",

    "linux/arm64"

  ]

}

Build:

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

생성:

build-info.json

배포:

cat build-info.json

Image 정보를 확인 후 배포할 수 있습니다.

Docker Buildx Bake Metadata-file 문제 해결

Metadata 파일이 생성되지 않는 경우

확인:

ls

파일 경로를 확인합니다.

잘못된 예:

--metadata-file

올바른 예:

--metadata-file metadata.json

JSON 파일 내용이 부족한 경우

확인:

Build 옵션
Push 여부
Output 설정

CI 환경에서 파일 전달 실패

확인:

Artifact 저장 설정
파일 경로
권한 설정

Docker Buildx Bake Metadata-file 사용 시 주의사항

첫 번째는 Metadata 파일에 민감한 정보가 포함되지 않는지 확인해야 합니다.

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

세 번째는 Digest 기반 배포 시 Metadata 파일 보관이 중요합니다.

네 번째는 Build 결과 파일 이름 규칙을 정하는 것이 좋습니다.

Best Practice

Docker Buildx Bake Metadata-file 활용 방법:

CI/CD Build 결과 저장
Image Digest 관리
Multi-platform 정보 기록
배포 자동화 연결
Artifact 보관
Release 추적

자주 묻는 질문

Docker Buildx Bake Metadata-file은 무엇인가요?

Docker Build 결과 정보를 JSON 파일로 저장하는 기능입니다.

어디에 활용하나요?

CI/CD, 자동 배포, Image Digest 관리 등에 활용합니다.

Tag 대신 Digest를 사용할 수 있나요?

가능합니다.

Metadata-file에서 Digest 정보를 확인할 수 있습니다.

Multi-platform Image도 지원하나요?