ORAS を使用して OCI 成果物とサプライチェーン成果物を管理する

[アーティクル]
10/16/2024

Azure Container Registry (ACR) は、Open Container Initiative (OCI) 成果物とサプライチェーン成果物の両方を管理するのに役立ちます。この記事では、ACR を使用して OCI 成果物とサプライチェーン成果物を効果的に管理する方法について説明します。署名、ソフトウェア部品表 (SBOM)、セキュリティスキャン結果、その他の種類を含む、OCI 成果物とサプライチェーン成果物のグラフの両方を格納、管理、取得する方法について説明します。

この記事は、主に次の 2 つのセクションに分かれています。

前提条件

Azure コンテナーレジストリ - コンテナーレジストリは、Azure サブスクリプションに作成します。たとえば、Azure Portal または Azure CLI を使用します。
Azure CLI - バージョン 2.29.1 以降が必要です。インストールまたはアップグレードについては、「Azure CLI のインストール」を参照してください。
ORAS CLI - バージョン v1.1.0 以降のバージョンが必要です。「ORAS のインストール」を参照してください。
Docker (省略可能) - チュートリアルを完了するには、コンテナーイメージを参照します。 oras CLI では資格情報を格納するために Docker デスクトップ資格情報ストアが利用されます。ローカルにインストールされた Docker を使用して、コンテナーイメージをビルドしてプッシュしたり、acr build を使って Azure にリモートでビルドしたりすることができます。

レジストリを構成する

コマンドを実行しやすい環境を構成するには、次の手順に従います。

ACR_NAME 変数をレジストリ名に設定します。
REGISTRY 変数を $ACR_NAME.azurecr.io に設定します。
REPO 変数をリポジトリ名に設定します。
TAG 変数を目的のタグに設定します。
IMAGE 変数を $REGISTRY/${REPO}:$TAG に設定します。

環境変数を設定する

レジストリ名、ログイン資格情報、リポジトリ名、タグを構成して、成果物をプッシュおよびプルします。次の例では、net-monitor リポジトリ名と v1 タグを使用します。ご自身のリポジトリ名とタグに置き換えます。

ACR_NAME=myregistry
REGISTRY=$ACR_NAME.azurecr.io
REPO=net-monitor
TAG=v1
IMAGE=$REGISTRY/${REPO}:$TAG

コンテナーイメージをプルおよびプッシュできるようにするために ACR で認証します。

az login  
az acr login -n $REGISTRY

このセットアップにより、Azure Container Registry との間で成果物をシームレスにプッシュおよびプルできるようになります。これで、oras login コマンドを使用して、追加の認証なしで ACR で ORAS を使用できるようになりました。

Docker が使用できない場合は、提供された AD トークンを認証に使用できます。 AD トークンを使って、お客様の個人の Microsoft Entra ID の認証を受けます。トークンは PASSWORD 変数を介して解析されるため、USER_NAME には常に "000..." を使います。 az acr login で使用されるトークンは 3 時間有効です。

Note

ACR と ORAS では、ユーザーとシステム自動化のための複数の認証オプションがサポートされています。この記事では、デモを使いやすくするために個々の ID を使用します。認証オプションの詳細については、「Azure コンテナーレジストリでの認証」を参照してください。

ORAS を使用して OCI 成果物をプッシュおよびプルする

Azure コンテナーレジストリを使うと、Open Container Initiative (OCI) 成果物に加えて、Docker と OCI のコンテナーイメージを格納して管理することができます。

この機能を示すため、このセクションでは OCI Registry as Storage (ORAS) CLI を使用して、OCI 成果物を Azure コンテナーレジストリとの間でプッシュおよびプルする方法について説明します。各成果物に適したさまざまなコマンドラインツールを使って、Azure コンテナーレジストリ内のさまざまな OCI 成果物を管理できます。

成果物をプッシュする

subject 親を持たない 1 つのファイル成果物には、コンテナーイメージ、Helm チャート、リポジトリの readme ファイルがあります。参照成果物には、署名、ソフトウェアの部品表、スキャンレポート、その他の進化する種類があります。サプライチェーン成果物のアタッチ、プッシュ、プルに関する記事で説明されている参照成果物とは、他の成果物を参照する成果物です。

1 つのファイル成果物をプッシュする

この例では、マークダウンファイルを表すコンテンツを作成します。

echo 'Readme Content' > readme.md

次の手順では、readme.md ファイルを <myregistry>.azurecr.io/samples/artifact:readme にプッシュします。

レジストリは、完全修飾レジストリ名 <myregistry>.azurecr.io (すべて小文字) と、それに続く名前空間とリポジトリ (/samples/artifact) で識別されます。
成果物には :readme というタグが付けられ、リポジトリに登録されている他の成果物 (:latest, :v1, :v1.0.1) から一意に識別されます。
--artifact-type readme/example を設定すると、成果物は、application/vnd.oci.image.config.v1+json を使うコンテナーイメージと区別されます。
./readme.md を使ってアップロードされたファイルを識別します。:application/markdown はそのファイルの IANA mediaType を表します。
詳細については、OCI 成果物作成者向けガイダンスの記事を参照してください。

oras push コマンドを使って、このファイルをレジストリにプッシュします。

Linux、WSL2、または macOS

oras push $REGISTRY/samples/artifact:readme \
    --artifact-type readme/example \
    ./readme.md:application/markdown

Windows

.\oras.exe push $REGISTRY/samples/artifact:readme ^
    --artifact-type readme/example ^
    .\readme.md:application/markdown

プッシュが成功した場合の出力は、次の出力のようになります。

Uploading 2fdeac43552b readme.md
Uploaded  2fdeac43552b readme.md
Pushed <myregistry>.azurecr.io/samples/artifact:readme
Digest: sha256:e2d60d1b171f08bd10e2ed171d56092e39c7bac1

aec5d9dcf7748dd702682d53

複数ファイルの成果物をプッシュする

OCI 成果物が ORAS を使用してレジストリにプッシュされると、各ファイル参照が BLOB としてプッシュされます。個々の BLOB をプッシュするには、ファイルを個別に参照するか、ディレクトリを参照してファイルのコレクションを参照します。
ファイルのコレクションをプッシュする方法の詳細については、「Pushing artifacts with multiple files (複数のファイルを使って成果物をプッシュする)」を参照してください。

リポジトリ用に何らかのドキュメントを作成します。

echo 'Readme Content' > readme.md
mkdir details/
echo 'Detailed Content' > details/readme-details.md
echo 'More detailed Content' > details/readme-more-details.md

複数ファイルの成果物をプッシュします。

Linux、WSL2、または macOS

oras push $REGISTRY/samples/artifact:readme \
    --artifact-type readme/example\
    ./readme.md:application/markdown\
    ./details

Windows

.\oras.exe push $REGISTRY/samples/artifact:readme ^
    --artifact-type readme/example ^
    .\readme.md:application/markdown ^
    .\details

マニフェストを検出する

oras push の結果として作成されたマニフェストを表示するには、oras manifest fetch を使います。

oras manifest fetch --pretty $REGISTRY/samples/artifact:readme

次のように出力されます。

{
  "mediaType": "application/vnd.oci.artifact.manifest.v1+json",
  "artifactType": "readme/example",
  "blobs": [
    {
      "mediaType": "application/markdown",
      "digest": "sha256:2fdeac43552b71eb9db534137714c7bad86b53a93c56ca96d4850c9b41b777fc",
      "size": 15,
      "annotations": {
        "org.opencontainers.image.title": "readme.md"
      }
    },
    {
      "mediaType": "application/vnd.oci.image.layer.v1.tar+gzip",
      "digest": "sha256:0d6c7434a34f6854f971487621426332e6c0fda08040b9e6cc8a93f354cee0b1",
      "size": 189,
      "annotations": {
        "io.deis.oras.content.digest": "sha256:11eceb2e7ac3183ec9109003a7389468ec73ad5ceaec0c4edad0c1b664c5593a",
        "io.deis.oras.content.unpack": "true",
        "org.opencontainers.image.title": "details"
      }
    }
  ],
  "annotations": {
    "org.opencontainers.artifact.created": "2023-01-10T14:44:06Z"
  }
}

成果物をプルする

ダウンロード用のクリーンディレクトリを作成します。

mkdir ./download

oras pull コマンドを実行して、レジストリから成果物をプルします。

oras pull -o ./download $REGISTRY/samples/artifact:readme

プルしたファイルを表示する

tree ./download

成果物を削除する (省略可能)

レジストリから成果物を削除するには、oras manifest delete コマンドを使います。

 oras manifest delete $REGISTRY/samples/artifact:readme

ORAS を使用してサプライチェーン成果物をアタッチ、プッシュ、プルする

この機能を示すため、この記事では OCI Registry as Storage (ORAS) CLI を使って、サプライチェーン成果物のグラフを Azure コンテナーレジストリに push、discover、および pull する方法について説明します。個々の (サブジェクト) OCI 成果物の格納については、OCI 成果物のプッシュとプルに関する記事を参照してください。

成果物のグラフを格納するために、subject 成果物への参照は、リリース前の OCI 1.1 distribution-spec の一部である OCI イメージマニフェストを使用して定義されます。

コンテナーイメージをプッシュする

Azure CLI を使用して成果物のグラフをコンテナーイメージに関連付けるには、次の手順を実施します。

コンテナーイメージをビルドしてプッシュするか、$IMAGE がレジストリ内の既存のイメージを参照する場合は、この手順をスキップすることもできます。

az acr build -r $ACR_NAME -t $IMAGE https://github.com/wabbit-networks/net-monitor.git#main

署名のアタッチ

echo '{"artifact": "'${IMAGE}'", "signature": "jayden hancock"}' > signature.json

コンテナーイメージへの参照としてレジストリにシグネチャをアタッチする

oras attach コマンドは、ファイル (./signature.json) から $IMAGE への参照を作成します。 --artifact-type は、さまざまなファイルの種類を使用できるようにするファイル拡張子と同様に、成果物を区別するために指定します。 [file]:[mediaType] を指定すると、1 つ以上のファイルをアタッチできます。

oras attach $IMAGE \
    --artifact-type signature/example \
    ./signature.json:application/json

oras attach の詳細については ORAS のドキュメントを参照してください。

参照として複数ファイルの成果物をアタッチする

成果物参照の検出

OCI v1.1 仕様では、subject 成果物への参照を検出するための referrers API が定義されています。 oras discover コマンドでは、コンテナーイメージへの参照の一覧を表示できます。

oras discover を使用して、レジストリに保存されている成果物のグラフを表示します。

oras discover -o tree $IMAGE

出力には、成果物のグラフの先頭が表示されます。ここには、シグネチャとドキュメントがコンテナーイメージの子として表示されます。

myregistry.azurecr.io/net-monitor:v1
├── signature/example
│   └── sha256:555ea91f39e7fb30c06f3b7aa483663f067f2950dcb...
└── readme/example
    └── sha256:1a118663d1085e229ff1b2d4d89b5f6d67911f22e55...

成果物のグラフの作成

OCI v1.1 仕様では、詳細なグラフが可能であり、署名付きソフトウェア部品表 (SBOM) や他の成果物の種類を使用できます。

SBOM を作成してレジストリにアタッチする方法を次に示します。

サンプル SBOM を作成する

echo '{"version": "0.0.0.0", "artifact": "'${IMAGE}'", "contents": "good"}' > sbom.json

レジストリ内のイメージにサンプルの SBOM をアタッチする

Linux、WSL2、または macOS

oras attach $IMAGE \
  --artifact-type sbom/example \
  ./sbom.json:application/json

Windows

.\oras.exe attach $IMAGE ^
    --artifact-type sbom/example ^
    ./sbom.json:application/json

SBOM に署名する

重要

Microsoft では、Notation などのセキュリティで保護された暗号化署名ツールを使用して、イメージに署名し、SBOM に署名するための署名を生成することをお勧めします。

参照としてプッシュされる成果物は、通常、subject 成果物の一部と見なされるため、タグがありません。別の成果物の子である成果物にシグネチャをプッシュするには、ダイジェストを検索するための --artifact-type フィルタリングを付けて、oras discover を使用します。この例では、デモンストレーションのために単純な JSON 署名を使用します。

SBOM_DIGEST=$(oras discover -o json \
                --artifact-type sbom/example \
                $IMAGE | jq -r ".manifests[0].digest")

SBOM のシグネチャを作成します。

echo '{"artifact": "'$IMAGE@$SBOM_DIGEST'", "signature": "jayden hancock"}' > sbom-signature.json

SBOM シグネチャをアタッチする

oras attach $IMAGE@$SBOM_DIGEST \
  --artifact-type 'signature/example' \
  ./sbom-signature.json:application/json

グラフを表示する

oras discover -o tree $IMAGE

次の出力が生成されます。

myregistry.azurecr.io/net-monitor:v1
├── sbom/example
│   └── sha256:4f1843833c029ecf0524bc214a0df9a5787409fd27bed2160d83f8cc39fedef5
│       └── signature/example
│           └── sha256:3c43b8cb0c941ec165c9f33f197d7f75980a292400d340f1a51c6b325764aa93
├── readme/example
│   └── sha256:5fafd40589e2c980e2864a78818bff51ee641119cf96ebb0d5be83f42aa215af
└── signature/example
    └── sha256:00da2c1c3ceea087b16e70c3f4e80dbce6f5b7625d6c8308ad095f7d3f6107b5

成果物のグラフの昇格

一般的な DevOps ワークフローでは、開発環境からステージング環境を経て成果物を運用環境に昇格させます。セキュリティで保護されたサプライチェーンワークフローは、パブリックコンテンツをプライベートにセキュリティで保護された環境に昇格させます。いずれの場合も、シグネチャ、SBOM、スキャン結果、およびサブジェクト成果物に関連付けられているその他の成果物を昇格させて、依存関係の完全なグラフを作成します。

oras copy コマンドを使用すると、レジストリ間で成果物のフィルター処理されたグラフを昇格させることができます。

net-monitor:v1 イメージをコピーすると、成果物は sample-staging/net-monitor:v1 に関連付けられます。

TARGET_REPO=$REGISTRY/sample-staging/$REPO
oras copy -r $IMAGE $TARGET_REPO:$TAG

oras copy の出力:

Copying 6bdea3cdc730 sbom-signature.json
Copying 78e159e81c6b sbom.json
Copied  6bdea3cdc730 sbom-signature.json
Copied  78e159e81c6b sbom.json
Copying 7cf1385c7f4d signature.json
Copied  7cf1385c7f4d signature.json
Copying 3e797ecd0697 details
Copying 2fdeac43552b readme.md
Copied  3e797ecd0697 details
Copied  2fdeac43552b readme.md
Copied demo42.myregistry.io/net-monitor:v1 => myregistry.azurecr.io/sample-staging/net-monitor:v1
Digest: sha256:ff858b2ea3cdf4373cba65d2ca6bcede4da1d620503a547cab5916614080c763

昇格された成果物グラフを検出する

oras discover -o tree $TARGET_REPO:$TAG

oras discover の出力:

myregistry.azurecr.io/sample-staging/net-monitor:v1
├── sbom/example
│   └── sha256:4f1843833c029ecf0524bc214a0df9a5787409fd27bed2160d83f8cc39fedef5
│       └── signature/example
│           └── sha256:3c43b8cb0c941ec165c9f33f197d7f75980a292400d340f1a51c6b325764aa93
├── readme/example
│   └── sha256:5fafd40589e2c980e2864a78818bff51ee641119cf96ebb0d5be83f42aa215af
└── signature/example
    └── sha256:00da2c1c3ceea087b16e70c3f4e80dbce6f5b7625d6c8308ad095f7d3f6107b5

参照される成果物のプル

特定の参照された成果物をプルするために、oras discover コマンドによって参照のダイジェストが検出されます。

DOC_DIGEST=$(oras discover -o json \
              --artifact-type 'readme/example' \
              $TARGET_REPO:$TAG | jq -r ".manifests[0].digest")

ダウンロード用のクリーンディレクトリを作成する

mkdir ./download

ダウンロードディレクトリにドキュメントをプルする

oras pull -o ./download $TARGET_REPO@$DOC_DIGEST

ドキュメントを表示する

tree ./download

tree の出力:

./download
├── details
│   ├── readme-details.md
│   └── readme-more-details.md
└── readme.md

リポジトリとタグの一覧を表示する

ORAS により、タグを割り当てなくても、成果物グラフをプッシュ、検出、プル、コピーできます。また、これにより、コンテナーイメージ、Helm チャート、およびその他の成果物に関連付けられているシグネチャや SBoM とは対照的に、ユーザーが考える成果物に焦点を当てたタグの一覧表示も可能になります。

タグの一覧を表示する

oras repo tags $REGISTRY/$REPO

グラフのすべての成果物の削除

OCI v1.1 仕様のサポートにより、サブジェクト成果物に関連付けられている成果物のグラフを削除できます。 oras manifest delete コマンドを使用して、成果物のグラフ (シグネチャ、SBOM、および SBOM のシグネチャ) を削除します。

oras manifest delete -f $REGISTRY/$REPO:$TAG

oras manifest delete -f $REGISTRY/sample-staging/$REPO:$TAG

マニフェストの一覧を表示して、対象の成果物および関連するすべての成果物が削除され、クリーンな環境になったことを確認できます。

az acr manifest list-metadata \
  --name $REPO \
  --registry $ACR_NAME -o jsonc

出力:

2023-01-10 18:38:45.366387 Error: repository "net-monitor" is not found.

まとめ

この記事では、Azure Container Registry を使用して、OCI 成果物とサプライチェーン成果物の両方を格納、管理、および取得する方法について学びました。 ORAS CLI を使用して、Azure Container Registry との間で成果物をプッシュおよびプルしました。また、プッシュされた成果物のマニフェストを検出し、コンテナーイメージにアタッチされている成果物のグラフを表示しました。

次のステップ

署名、ソフトウェアの部品表、その他の参照型に関連する成果物の参照についてご確認ください。
成果物のマニフェストを構成する方法など、ORAS プロジェクトの詳細についての詳細をご確認ください。
OCI 成果物リポジトリを参照して、新しい成果物の型に関するリファレンス情報をご確認ください。

次の方法で共有

ORAS を使用して OCI 成果物とサプライチェーン成果物を管理する

前提条件

レジストリを構成する

環境変数を設定する

ORAS を使用して OCI 成果物をプッシュおよびプルする

成果物をプッシュする

1 つのファイル成果物をプッシュする

複数ファイルの成果物をプッシュする

マニフェストを検出する

成果物をプルする

プルしたファイルを表示する

成果物を削除する (省略可能)

ORAS を使用してサプライチェーン成果物をアタッチ、プッシュ、プルする

コンテナーイメージをプッシュする

署名のアタッチ

コンテナーイメージへの参照としてレジストリにシグネチャをアタッチする

参照として複数ファイルの成果物をアタッチする

成果物参照の検出

成果物のグラフの作成

サンプル SBOM を作成する

レジストリ内のイメージにサンプルの SBOM をアタッチする

SBOM に署名する

SBOM シグネチャをアタッチする

グラフを表示する

成果物のグラフの昇格

昇格された成果物グラフを検出する

参照される成果物のプル

ダウンロード用のクリーンディレクトリを作成する

ダウンロードディレクトリにドキュメントをプルする

ドキュメントを表示する

リポジトリとタグの一覧を表示する

タグの一覧を表示する

グラフのすべての成果物の削除

まとめ

次のステップ

フィードバック

その他のリソース

次の方法で共有

ORAS を使用して OCI 成果物とサプライ チェーン成果物を管理する

前提条件

レジストリを構成する

環境変数を設定する

レジストリにサインインする

ORAS を使用して OCI 成果物をプッシュおよびプルする

成果物をプッシュする

1 つのファイル成果物をプッシュする

複数ファイルの成果物をプッシュする

マニフェストを検出する

成果物をプルする

プルしたファイルを表示する

成果物を削除する (省略可能)

ORAS を使用してサプライ チェーン成果物をアタッチ、プッシュ、プルする

コンテナー イメージをプッシュする

署名のアタッチ

コンテナー イメージへの参照としてレジストリにシグネチャをアタッチする

参照として複数ファイルの成果物をアタッチする

成果物参照の検出

成果物のグラフの作成

サンプル SBOM を作成する

レジストリ内のイメージにサンプルの SBOM をアタッチする

SBOM に署名する

SBOM シグネチャをアタッチする

グラフを表示する

成果物のグラフの昇格

昇格された成果物グラフを検出する

参照される成果物のプル

ダウンロード用のクリーン ディレクトリを作成する

ダウンロード ディレクトリにドキュメントをプルする

ドキュメントを表示する

リポジトリとタグの一覧を表示する

タグの一覧を表示する

グラフのすべての成果物の削除

まとめ

次のステップ

フィードバック

その他のリソース

ORAS を使用して OCI 成果物とサプライチェーン成果物を管理する

ORAS を使用してサプライチェーン成果物をアタッチ、プッシュ、プルする

コンテナーイメージをプッシュする

コンテナーイメージへの参照としてレジストリにシグネチャをアタッチする

ダウンロード用のクリーンディレクトリを作成する

ダウンロードディレクトリにドキュメントをプルする