Docker imageビルド時に付けるラベルの整理

Docker imageをビルドするときは、LABEL を使ってメタデータを付けておくとよい。 参考: https://www.docker.com/ja-jp/blog/docker-best-practices-using-tags-and-labels-to-manage-docker-image-sprawl/

ラベルを付ける目的

• imageの由来を追跡しやすくする（リポジトリ、コミット、バージョン）
• レジストリ上で検索・フィルタしやすくする
• チーム内の運用ルールを機械的にチェックしやすくする

タグとの使い分け:

• タグ（my-app:1.4.0 など）は「どのimageを取得・デプロイするか」を指定するための識別子
• ラベル（org.opencontainers.image.*）は「そのimageが何者か」を説明するメタデータ
• 実運用では、タグで選び、ラベルで追跡・監査する

OCI標準ラベル

独自キーを作る前に、OCI (Open Container Initiative) の推奨キーを優先すると互換性が高くなる。

• org.opencontainers.image.title: image名
• org.opencontainers.image.description: image説明
• org.opencontainers.image.url: プロジェクトURL
• org.opencontainers.image.source: ソースコードURL
• org.opencontainers.image.version: バージョン
• org.opencontainers.image.revision: GitコミットSHA
• org.opencontainers.image.created: ビルド日時（ISO 8601）
• org.opencontainers.image.licenses: SPDX形式のライセンス
• org.opencontainers.image.vendor: 提供元

ラベルの確認方法

docker inspect my-app:1.4.0 --format '{{ json .Config.Labels }}' | jq

AWSのlambdaのイメージではこんな独自キーがついていた

• “com.amazonaws.lambda.platform.kernel”: “k510ga”,
• “com.amazonaws.lambda.platform.version”: “sbxv2ga”

ラベルの付与

ビルド時に --build-arg で値を渡して付与する

docker build \
  --build-arg VERSION="1.4.0" \
  --build-arg VCS_REF="$(git rev-parse --short HEAD)" \
  --build-arg BUILD_DATE="$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
  -t my-app:1.4.0 .

• Dockerfile

FROM node:22-alpine

ARG BUILD_DATE
ARG VCS_REF
ARG VERSION

LABEL org.opencontainers.image.title="my-app" \
      org.opencontainers.image.description="Example web app" \
      org.opencontainers.image.source="https://github.com/kenichikat/my-app" \
      org.opencontainers.image.version="$VERSION" \
      org.opencontainers.image.revision="$VCS_REF" \
      org.opencontainers.image.created="$BUILD_DATE" \
      org.opencontainers.image.licenses="MIT"

WORKDIR /app
COPY . .
RUN npm ci && npm run build
CMD ["node", "dist/index.js"]