Docker Image를 여러 플랫폼에서 운영하거나 Container Registry에서 관리하다 보면 단순한 Image Tag와 Label만으로는 부족한 경우가 있습니다.

특히 Multi-platform Image 환경에서는 다음과 같은 정보 관리가 필요합니다.

Image Manifest 설명
Platform별 Metadata
Registry 표시 정보
OCI Image 정보
배포 관련 추가 데이터

Docker Buildx에서는 Annotations(주석 메타데이터) 기능을 사용하여 Image Manifest와 OCI 구조에 추가 정보를 기록할 수 있습니다.

Docker Buildx Bake에서는 annotations 옵션으로 이러한 정보를 자동 추가할 수 있습니다.

예:

docker-bake.hcl

target "app" {

  tags = [
    "company/app:v1"
  ]

  annotations = [
    "index:org.opencontainers.image.title=Company Application",
    "index:org.opencontainers.image.version=1.0.0"
  ]

}

실행:

docker buildx bake app --push

결과:

Docker Image 생성

↓

Manifest Metadata 추가

↓

Registry 저장

이번 글에서는 Docker Buildx Bake Annotations의 개념부터 Label과 차이점, OCI Manifest 관리, Multi-platform 활용, CI/CD 적용 방법까지 자세히 알아보겠습니다.

Table of Contents

Docker Buildx Bake Annotations란 무엇인가?

Docker Buildx Bake Annotations는 Docker Image 또는 Image Manifest에 추가 Metadata를 기록하는 기능입니다.

쉽게 설명하면:

Label

= Image 내부 정보

Annotation

= Image Manifest 정보

구조:

Docker Image

↓

Manifest

↓

Annotations Metadata

Container Registry에서 Image 정보를 표현하거나 관리할 때 활용됩니다.

Docker Buildx Bake Annotations가 필요한 이유

기본 Docker Image:

company/app:v1

정보:

Image 이름
Tag
Layer

정도만 확인할 수 있습니다.

하지만 대규모 환경에서는 추가 정보가 필요합니다.

예:

Image

├── Application 이름

├── Version

├── Build 정보

├── Platform 정보

└── 설명 Metadata

Annotations를 사용하면 Image 구조에 추가 정보를 저장할 수 있습니다.

Docker Buildx Bake Annotations와 Labels 차이

둘은 비슷하지만 저장 위치가 다릅니다.

Labels

저장 위치:

Image Config

용도:

Image 설명
제작자 정보
버전 정보

예:

labels = {

  "version" = "1.0"

}

Annotations

저장 위치:

OCI Manifest

또는

Manifest Index

용도:

Multi-platform Image Metadata
Registry 표시 정보
Image Artifact 정보

비교:

기능	저장 위치	목적
Labels	Image Config	Image 정보
Annotations	Manifest	배포 Metadata

Docker Buildx Bake Annotations 기본 설정

docker-bake.hcl:

target "app" {

  tags = [
    "company/app:v1"
  ]

  annotations = [
    "index:org.opencontainers.image.title=My App"
  ]

}

실행:

docker buildx bake app --push

결과:

Docker Image

↓

OCI Manifest

↓

Annotation 저장

Docker Buildx Bake OCI Annotation 사용하기

Docker에서는 OCI 표준 Annotation 사용을 권장합니다.

대표적인 Annotation:

Image 제목

org.opencontainers.image.title

설명

org.opencontainers.image.description

버전

org.opencontainers.image.version

Source 주소

org.opencontainers.image.source

예:

annotations = [

  "index:org.opencontainers.image.title=Backend API",

  "index:org.opencontainers.image.version=2.0.0"

]

표준 방식으로 Image Metadata를 관리할 수 있습니다.

Docker Buildx Bake Annotations Multi-platform 활용

Annotations는 Multi-platform Image에서 특히 유용합니다.

예:

target "app" {

  platforms = [

    "linux/amd64",

    "linux/arm64"

  ]

  annotations = [

    "index:org.opencontainers.image.description=Multi Platform Application"

  ]

}

결과:

Image Manifest

├── linux/amd64

├── linux/arm64

└── Annotation

하나의 Image Tag에 플랫폼 정보를 함께 관리할 수 있습니다.

Docker Buildx Bake Annotations 확인 방법

Image Manifest 정보를 확인합니다.

명령:

docker buildx imagetools inspect company/app:v1

확인:

Name

MediaType

Platform

Annotations

Registry에 저장된 Metadata를 확인할 수 있습니다.

Docker Buildx Bake Annotations와 Registry 활용

Container Registry에서는 Manifest 정보를 기반으로 Image를 관리합니다.

구조:

Registry

↓

Image Manifest

↓

Annotations

↓

Platform 정보

활용:

Docker Hub
Harbor
ECR
ACR
Private Registry

Docker Buildx Bake Annotations CI/CD 활용

CI/CD Pipeline에서 자동 Metadata 추가가 가능합니다.

예:

target "production" {

  annotations = [

    "index:build.number=123",

    "index:environment=production"

  ]

}

결과:

CI Build

↓

Annotation 추가

↓

Registry Push

Build 정보를 자동으로 기록할 수 있습니다.

Docker Buildx Bake Annotations와 Git 정보 연결

Git Commit 정보를 Annotation으로 저장할 수 있습니다.

예:

Commit:

a82fd91

Bake:

annotations = [

  "index:git.commit=a82fd91"

]

활용:

배포 추적
Rollback 관리
장애 분석

Docker Buildx Bake Annotations 실무 예제

프로젝트 구조:

project/

├── Dockerfile

├── docker-bake.hcl

└── deployment.yaml

docker-bake.hcl:

target "production" {

  tags = [

    "registry.company.com/app:v1"

  ]


  platforms = [

    "linux/amd64",

    "linux/arm64"

  ]


  labels = {

    "org.opencontainers.image.version" = "1.0.0"

  }


  annotations = [

    "index:org.opencontainers.image.title=Company API",

    "index:org.opencontainers.image.description=Production Service"

  ]

}

실행:

docker buildx bake production --push

결과:

Docker Image

+

Label Metadata

+

Manifest Annotation

↓

운영 관리 가능

Docker Buildx Bake Annotations 문제 해결

Annotation이 보이지 않는 경우

확인:

docker buildx imagetools inspect image-name

Manifest 정보를 확인합니다.

Multi-platform에서 적용되지 않는 경우

확인:

Image Push 여부
Registry 지원 여부
Annotation 대상(index 또는 manifest)

Build Cache 문제

Cache 삭제:

docker buildx prune

다시 Build합니다.

Docker Buildx Bake Annotations 사용 시 주의사항

첫 번째는 Annotation과 Label의 저장 위치 차이를 이해해야 합니다.

두 번째는 Registry가 OCI Metadata를 지원해야 합니다.

세 번째는 민감한 정보를 Annotation에 저장하면 안 됩니다.

네 번째는 표준 OCI Annotation 사용을 권장합니다.

Best Practice

Docker Buildx Bake Annotations 활용 방법:

OCI 표준 Metadata 사용
Multi-platform Image 관리
CI Build 정보 기록
Git Commit 저장
Registry Metadata 관리
Label과 함께 활용

자주 묻는 질문

Docker Buildx Bake Annotations는 무엇인가요?

Docker Image Manifest에 추가 Metadata를 기록하는 기능입니다.

Labels와 어떤 차이가 있나요?

Labels는 Image 내부 정보이고 Annotations는 Manifest Metadata입니다.

Multi-platform Image에서 사용할 수 있나요?

가능합니다.

특히 Manifest Index 관리에 유용합니다.

CI/CD 정보를 저장할 수 있나요?