コンテナのメタデータを管理する

このページでは、Artifact Registry に保存されているコンテナ イメージに関するメタデータをコンテナ化し、Artifact Registry にアップロードして管理する方法について説明します。アタッチメントとして保存されます。

アタッチメントは OCI アーティファクトであり、Docker 形式のリポジトリにのみ保存できます。

始める前に

1. まだ作成していない場合は、Docker 形式の標準リポジトリを作成します。
2. （省略可）Google Cloud CLI コマンドのデフォルトを構成します。

必要なロール

アタッチメントの管理に必要な権限を取得するには、リポジトリに対する次の IAM ロールの付与を管理者に依頼してください。

• アタッチメントを表示、ダウンロードする: Artifact Registry 読み取り （roles/artifactregistry.reader）
• アタッチメントを作成する: Artifact Registry 書き込み （roles/artifactregistry.writer）
• アタッチメントを削除する: Artifact Registry リポジトリ管理者 （roles/artifactregistry.repoAdmin）

ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。

必要な権限は、カスタムロールや他の事前定義ロールから取得することもできます。

Oras を設定する（省略可）

gcloud CLI の使用に加えて、必要に応じて Oras を使用して添付ファイルを作成、一覧表示、ダウンロードすることもできます。

1. Oras 1.2 以降をインストールします。バージョンを確認するには、oras version コマンドを実行します。

2. Artifact Registry でauthenticateするように Oras を構成します。

アタッチメントを作成する

アタッチメントは、gcloud CLI または Oras を使用して作成できます。

gcloud

後述のコマンドデータを使用する前に、次のように置き換えます。

• ATTACHMENT: アタッチメントの完全修飾名。例: projects/my-project/locations/us-west1/repositories/my-repo/attachments/my-attachment。または、アタッチメント ID のみを指定して、--location フラグと --repository フラグを使用します。
• TARGET: アタッチメントが参照するアーティファクトの完全修飾バージョン名または Artifact Registry URI。ダイジェストまたはタグのいずれかを使用できます。例: us-west1-docker.pkg.dev/my-project/my-repo/my-image:tag1
• TYPE: アタッチメントの type 属性。これは、artifactType プロパティの OCI 仕様に準拠している必要があります。
• ATTACHMENT_NAMESPACE: アタッチメントに固有の変数で、アタッチメントのデータソースを識別します。例: example.com
• FILES: アタッチメントに含めるローカル ファイルのカンマ区切りリスト。

次のコマンドを実行します。

Linux、macOS、Cloud Shell

注: 認証とプロジェクトを使用して Google Cloud CLI を初期化するには、gcloud init、gcloud auth login、または gcloud config set project のいずれかを実行します。

gcloud artifacts attachments create ATTACHMENT \
    --target=TARGET \
    --type=TYPE \
    --attachment-namespace=ATTACHMENT_NAMESPACE \
    --files=FILES

Windows（PowerShell）

注: 認証とプロジェクトを使用して Google Cloud CLI を初期化するには、gcloud init、gcloud auth login、または gcloud config set project のいずれかを実行します。

gcloud artifacts attachments create ATTACHMENT `
    --target=TARGET `
    --type=TYPE `
    --attachment-namespace=ATTACHMENT_NAMESPACE `
    --files=FILES

Windows（cmd.exe）

注: 認証とプロジェクトを使用して Google Cloud CLI を初期化するには、gcloud init、gcloud auth login、または gcloud config set project のいずれかを実行します。

gcloud artifacts attachments create ATTACHMENT ^
    --target=TARGET ^
    --type=TYPE ^
    --attachment-namespace=ATTACHMENT_NAMESPACE ^
    --files=FILES

詳細については、gcloud artifacts attachments create コマンドをご覧ください。

Oras

Oras でアタッチメントを作成するときに、Artifact Registry は、アタッチメント名として使用するランダムな UUID を生成します。

コマンドを実行する前に、次のように置き換えます。

• ARTIFACT_TYPE: アタッチメントの artifactType。

• IMAGE_URI: アタッチメントが参照するイメージ コンテナの URI。

• FILE: アタッチメントのメタデータとして含めるローカル ファイル。

• MEDIA_TYPE: レイヤの mediaType。

  oras attach --artifact-type ARTIFACT_TYPE IMAGE_URI FILE:MEDIA_TYPE

次の例では、URI とタグで識別されるコンテナ イメージ my-image を参照するファイル hello-world.txt で構成されるアタッチメントを作成します。

  oras attach --artifact-type doc/example \
  us-west1-docker.pkg.dev/my-project/my-repo/my-image:tag1 \
  hello-world.txt:application/vnd.me.hi

ここで

• doc/example は、アタッチメントの artifactType プロパティを定義します。

• us-west1-docker.pkg.dev/my-project/my-repo/my-image:tag1 は、アタッチメントが参照するコンテナ イメージ バージョンのタグを含む URI です。

• hello-world.txt は、アタッチメントがデータとして保持するローカル ファイルです。

• application/vnd.me.hi は、レイヤの mediaType を定義します。

ガイドの全文とその他の例については、oras attach のドキュメントをご覧ください。

リストの添付ファイル

コンテナ イメージには、そのイメージを参照するアタッチメントを任意の数追加できます。アタッチメントを一覧表示するには、Google Cloud コンソール、gcloud CLI、または Oras を使用します。

コンソール

1. Google Cloud コンソールで、[リポジトリ] ページを開きます。

   [リポジトリ] ページを開く

2. リポジトリ名をクリックすると、リポジトリ内のイメージが表示されます。

3. イメージのバージョンを表示するには、イメージ名をクリックします。

4. 該当する画像のバージョンをクリックします。

5. そのバージョンの添付ファイルを表示するには、[添付ファイル] タブをクリックします。

gcloud

後述のコマンドデータを使用する前に、次のように置き換えます。

• TARGET: アタッチメントを一覧表示するアーティファクトの完全修飾バージョン名または Artifact Registry URI。ダイジェストまたはタグのいずれかを使用できます。例: us-west1-docker.pkg.dev/my-project/my-repo/my-image:tag1

次のコマンドを実行します。

Linux、macOS、Cloud Shell

注: 認証とプロジェクトを使用して Google Cloud CLI を初期化するには、gcloud init、gcloud auth login、または gcloud config set project のいずれかを実行します。

gcloud artifacts attachments list \
    --target=TARGET

Windows（PowerShell）

注: 認証とプロジェクトを使用して Google Cloud CLI を初期化するには、gcloud init、gcloud auth login、または gcloud config set project のいずれかを実行します。

gcloud artifacts attachments list `
    --target=TARGET

Windows（cmd.exe）

注: 認証とプロジェクトを使用して Google Cloud CLI を初期化するには、gcloud init、gcloud auth login、または gcloud config set project のいずれかを実行します。

gcloud artifacts attachments list ^
    --target=TARGET

詳細については、gcloud artifacts attachments list コマンドをご覧ください。

Oras

コマンドを実行する前に、次のように置き換えます。

• IMAGE_URI: リスト内のアタッチメントが参照するターゲット イメージの URI。

oras discover --distribution-spec v1.1-referrers-api IMAGE_URI

次の例では、URI とタグで識別されるコンテナ イメージ my-image のアタッチメントを一覧表示します。

oras discover --distribution-spec v1.1-referrers-api \
us-west1-docker.pkg.dev/my-project/my-repo/my-image:tag1

ここで

• v1.1-referrers-api は、使用される Referrer API です。詳細については、ディストリビューション仕様をご覧ください。

• us-west1-docker.pkg.dev/my-project/my-repo/my-image:tag1 は、アタッチメントを一覧表示するコンテナ イメージ バージョンのタグを含む URI です。

ガイドの全文とその他の例については、oras discover のドキュメントをご覧ください。

添付ファイルをダウンロードする

添付ファイルをダウンロードするには、gcloud CLI または Oras を使用します。

gcloud

後述のコマンドデータを使用する前に、次のように置き換えます。

• ATTACHMENT: アタッチメントの完全修飾名。例: projects/my-project/locations/us-west1/repositories/my-repo/attachments/my-attachment。または、アタッチメント ID のみを指定して、--location フラグと --repository フラグを使用することもできます。
• DESTINATION: アタッチメントをダウンロードするローカル ファイル システム内のパス。

次のコマンドを実行します。

Linux、macOS、Cloud Shell

注: 認証とプロジェクトを使用して Google Cloud CLI を初期化するには、gcloud init、gcloud auth login、または gcloud config set project のいずれかを実行します。

gcloud artifacts attachments download ATTACHMENT \
    --destination=DESTINATION

Windows（PowerShell）

注: 認証とプロジェクトを使用して Google Cloud CLI を初期化するには、gcloud init、gcloud auth login、または gcloud config set project のいずれかを実行します。

gcloud artifacts attachments download ATTACHMENT `
    --destination=DESTINATION

Windows（cmd.exe）

注: 認証とプロジェクトを使用して Google Cloud CLI を初期化するには、gcloud init、gcloud auth login、または gcloud config set project のいずれかを実行します。

gcloud artifacts attachments download ATTACHMENT ^
    --destination=DESTINATION

ATTACHMENT を指定する代わりに、--oci-version-name フラグに続けてアタッチメントの完全なバージョン名または Artifact Registry URI を指定できます。ダイジェストまたはタグのいずれかを使用できます。例: projects/my-project/locations/us-west1/repositories/my-repo/packages/my-package/versions/sha256:abc123

詳細については、gcloud artifacts attachments download コマンドをご覧ください。

Oras

コマンドを実行する前に、次のように置き換えます。

• DESTINATION: アタッチメントの宛先ディレクトリ。

• ATTACHMENT_URI: ダウンロードするアタッチメントの URI。これは、アタッチメントが参照するイメージ コンテナの URI で、アタッチメントの一意の SHA が続きます。

oras pull -o DESTINATION ATTACHMENT_URI

次の例では、URI とダイジェストで識別されるアタッチメントをダウンロードします。

oras pull -o . us-west1-docker.pkg.dev/my-project/my-repo/my-image@sha256:xxxx

ここで

• -o . は、現在のディレクトリをダウンロード先として指定します。

• us-west1-docker.pkg.dev/my-project/my-repo/my-image@sha256:xxxx は、ダウンロードするアタッチメントのダイジェストを含む画像 URI です。

ガイドの全文とその他の例については、oras pull のドキュメントをご覧ください。

添付ファイルを削除する

添付ファイルは、Google Cloud コンソールまたは gcloud CLI を使用して直接削除できます。アタッチメントを間接的に削除するには、参照しているコンテナ イメージを削除します。

添付ファイルを直接削除する

添付ファイルを直接削除するには、次のいずれかの方法を使用します。

コンソール

1. Google Cloud コンソールで、[リポジトリ] ページを開きます。

   [リポジトリ] ページを開く

2. リポジトリ名をクリックして、リポジトリ内のイメージを表示します。

3. イメージ名をクリックすると、そのイメージのバージョンが表示されます。

4. アタッチメントを表示するイメージのバージョンをクリックします。

5. [添付ファイル] タブをクリックすると、そのバージョンの添付ファイルが表示されます。

6. 削除する添付ファイルのダイジェストをクリックします。

7. [削除] をクリックします。

8. 確認ダイアログで [削除] をクリックします。

gcloud

後述のコマンドデータを使用する前に、次のように置き換えます。

• ATTACHMENT: アタッチメントの完全修飾名。例: projects/my-project/locations/us-west1/repositories/my-repo/attachments/my-attachment。または、アタッチメント ID のみを指定して、--location フラグと --repository フラグを使用することもできます。

次のコマンドを実行します。

Linux、macOS、Cloud Shell

注: 認証とプロジェクトを使用して Google Cloud CLI を初期化するには、gcloud init、gcloud auth login、または gcloud config set project のいずれかを実行します。

gcloud artifacts attachments delete ATTACHMENT

Windows（PowerShell）

注: 認証とプロジェクトを使用して Google Cloud CLI を初期化するには、gcloud init、gcloud auth login、または gcloud config set project のいずれかを実行します。

gcloud artifacts attachments delete ATTACHMENT

Windows（cmd.exe）

注: 認証とプロジェクトを使用して Google Cloud CLI を初期化するには、gcloud init、gcloud auth login、または gcloud config set project のいずれかを実行します。

gcloud artifacts attachments delete ATTACHMENT

詳細については、gcloud artifacts attachments list コマンドをご覧ください。

添付ファイルを間接的に削除する

コンテナ イメージが削除されると、参照しているアタッチメントもすべて削除されます。これは、コンテナ イメージの手動削除とクリーンアップ ポリシーによる削除の両方に適用されます。

注: クリーンアップ ポリシーは添付ファイルには直接適用されません。ただし、クリーンアップ ポリシーでコンテナ イメージが削除されると、そのコンテナ イメージを参照するすべてのアタッチメントが削除されます。