Docker のための変更

このドキュメントでは、Docker でコンテナ イメージの認証、push、pull を行う場合の Container Registry と Artifact Registry の違いについて説明します。

このガイドでは、pkg.dev Artifact Registry リポジトリに重点を置いて比較しています。このリポジトリは Container Registry から独立しており、Artifact Registry のすべての機能をサポートしています。

管理者が gcr.io ドメインをサポートするリポジトリを設定している場合は、gcr.io ホスト名へのリクエストは対応する Artifact Registry リポジトリに自動的にリダイレクトされます。Artifact Registry でホストされている gcr.io リポジトリを使用するには、適切な Artifact Registry ロールまたは同等の権限を持つロールが必要です。

Cloud Build でビルドし、Cloud Run または Google Kubernetes Engine にデプロイする際の Container Registry と Artifact Registry の違いについては、Cloud Build、Cloud Run、GKE の変更点をご覧ください。

この情報を使用して、Docker で Container Registry に焦点を当てた既存のコマンド、構成、ドキュメントを適応させることができます。

始める前に

このドキュメントは、以下を前提としています。

  1. プロジェクトで Artifact Registry を有効にしていること。
  2. Docker をインストールしておくこと。 Docker は Cloud Shell に含まれています。

概要

大まかに言えば、Docker を Container Registry または Artifact Registry で使用する場合のワークフローは同じです。

Container Registry Artifact Registry
管理者
  1. Container Registry API を有効にする
  2. 初期イメージをホストに push して、「gcr.io」などのレジストリ ホストを追加します。
  3. レジストリ ホストがイメージにアクセスできるように、ストレージ バケットに対する Cloud Storage ロールを付与します。
 管理者
  1. Artifact Registry API を有効にする
  2. Docker リポジトリを追加します。
  3. Artifact Registry ロールを付与して、イメージへのアクセス権を付与します。
レジストリ ユーザー
  1. 画像を Dockerfile ファイルとして定義します。
  2. イメージを構築する。
  3. レジストリに対して認証します。
  4. イメージにタグを付けてレジストリに push します。
  5. レジストリからイメージを pull するか、Google Cloud ランタイムにデプロイします。
 レジストリ ユーザー
  1. 画像を Dockerfile ファイルとして定義します。
  2. イメージを構築する。
  3. レジストリに対して認証します。
  4. イメージにタグを付けてレジストリに push します。
  5. レジストリからイメージを pull するか、Google Cloud ランタイムにデプロイします。

ただし、Container Registry のショートカットは、管理者ロールとユーザーロールを 1 つのワークフローに統合したものです。このショートカットは、次の場合によく使用されます。

  • 幅広い権限を持つ環境でテストを行うクイックスタートとチュートリアル。
  • 同じ Google Cloud プロジェクトにレジストリ ホストを追加する権限が Cloud Build サービス アカウントにあるため、Cloud Build を使用するワークフロー。

ショートカットのワークフローは次のとおりです。

  1. Container Registry API を有効にします。
  2. Container Registry にアクセスするアカウントに権限を付与します。

  3. レジストリに対して認証します。最も簡単な認証オプションは、Google Cloud CLI で Docker 認証ヘルパーを使用することです。これは初回にのみ必要な手順です。

    gcloud auth configure-docker

  4. イメージをビルドしてタグ付けします。たとえば、次のコマンドはイメージ gcr.io/my-project/my-image:tag1 をビルドしてタグ付けします。

    docker build -t gcr.io/my-project/my-image:tag1

  5. イメージをレジストリに push します。次に例を示します。

    docker push gcr.io/my-project/my-image:tag1

    プロジェクトに gcr.io レジストリ ホストが存在しない場合、Container Registry はイメージをアップロードする前にホストを追加します。

  6. レジストリからイメージを pull するか、Google Cloud ランタイムにデプロイします。次に例を示します。

    docker pull gcr.io/my-project/my-image:tag1

このワークフローは、次のショートカットを利用します。

  • イメージを push するアカウントに、ストレージ管理者ロールまたは、オーナーなどの同じ権限を持つロールが付与されている。このロールの幅広い権限により、Container Registry で使用されていないバケットを含む、プロジェクト内のすべてのストレージ バケットに対する読み取りと書き込みのアクセスが許可されます。
  • 一部の Google Cloud API を有効にすると、Container Registry API が自動的に有効になります。つまり、これらのサービスのユーザーは、同じプロジェクト内の Container Registry に暗黙的にアクセスできます。たとえば、Cloud Build でビルドを実行できるユーザーは、デフォルトでイメージをレジストリに push し、レジストリ ホストを追加できます。

Artifact Registry では、ビルドとデプロイのワークフローを変更する管理者ロールとリポジトリ ユーザー ロールが明確に分離されています。Container Registry ワークフローを Artifact Registry 用に適合させるには、次の変更を行います。各ステップは、ワークフローの変更に関する追加情報にリンクしています。

  1. 新規: Artifact Registry API を有効にする。

    Artifact Registry API を有効にする必要があります。Cloud Build と Cloud Run や GKE などのランタイム環境では、API が自動的に有効になりません。

  2. 新規: ターゲット Docker リポジトリがまだ存在しない場合は、それを作成します。イメージを push する前に宛先のリポジトリを作成する必要があります。イメージを push してもリポジトリの作成をトリガーできず、Cloud Build サービス アカウントにはリポジトリを作成する権限がありません。

  3. Artifact Registry を操作するアカウントに権限を付与します。

  4. 変更後: リポジトリに対する認証を行います。gcloud CLI で認証情報ヘルパーを使用する場合は、Docker クライアント構成に追加するホストを指定する必要があります。たとえば、次のコマンドはホスト us-central1-docker.pkg.dev を追加します。

    gcloud auth configure-docker us-central1-docker.pkg.dev

  5. 変更後: イメージにビルドしてタグ付けします。

    次のコマンド例は Container Registry の例と同じですが、イメージに Artifact Registry リポジトリ パスを使用しています。

    docker build -t us-central1-docker.pkg.dev/my-project/my-repo/my-image:tag1

  6. 変更後: Artifact Registry パスを使用して、リポジトリにイメージを push します。次に例を示します。

    docker push us-central1-docker.pkg.dev/my-project/my-repo/my-image:tag1

  7. 変更: Artifact Registry パスを使用してリポジトリからイメージを pull します。次に例を示します。

    docker pull us-central1-docker.pkg.dev/my-project/my-repo/my-image:tag1

API の有効化

要点:

次の比較は、各サービスの API を有効にする方法を示しています。

Container Registry

Container Registry で Docker や他のサードパーティ クライアントを使用する前に、Container Registry API を有効にする必要があります。

次の Google Cloud APIs を有効にすると、Container Registry API も自動的に有効になります。

  • App Engine フレキシブル環境
  • Cloud Build
  • Cloud Run 関数
  • Cloud Run
  • Artifact Analysis のコンテナ スキャンまたはオンデマンド スキャン
  • Google Kubernetes Engine（GKE）

デフォルトの権限では、レジストリが同じプロジェクトにある場合、Cloud Build でビルドを実行したり、Artifact Analysis を使用してコンテナをスキャンしたり、コンテナを Google Cloud ランタイムにデプロイしたりできるユーザーは、Container Registry 内のイメージに明示的にアクセスできます。

Artifact Registry

Artifact Registry で Docker クライアントや他の Google Cloud サービスを使用するには、Artifact Registry API を有効にする必要があります。

Cloud Build、Cloud Run、GKE などのサービスでは、Artifact Registry API は自動的に有効になりません。

gcloud を使用して、同じプロジェクトで複数の API を有効にできます。たとえば、Cloud Build API と Artifact Registry API を有効にするには、次のコマンドを実行します。

gcloud services enable
    artifactregistry.googleapis.com \
    cloudbuild.googleapis.com

レジストリとリポジトリの追加

要点:

  • イメージを push する前に、Artifact Registry Docker リポジトリを作成する必要があります。

    ストレージ管理者権限を持つアカウントは、レジストリ ホストへの最初の push でプロジェクトにレジストリを追加できるため、Container Registry へのイメージの push を説明するドキュメントでは、レジストリの作成手順が除外されることがよくあります。

  • Container Registry は、すべてのイメージを同じストレージ バケット内の単一のマルチリージョンに保存します。Artifact Registry では、同じリージョンまたはマルチリージョンに、別々のアクセス ポリシーを使用して複数のリポジトリを作成できます。

次の比較は、各サービスのリポジトリの設定を示しています。

Container Registry

Container Registry では、プロジェクトに最大 4 つのレジストリ ホストを追加できます。レジストリ ホストを追加するには、最初のイメージを push します。

  1. gcr.io などのレジストリをプロジェクトに追加するには、プロジェクト レベルでストレージ管理者ロールを持つアカウントが初期イメージを push します。

    たとえば、プロジェクト my-project に gcr.io ホストが存在しない場合、イメージ gcr.io/my-project/my-image:1.0 を push すると、次の手順がトリガーされます。

    1. gcr.io ホストをプロジェクトに追加する
    2. プロジェクトに gcr.io のストレージ バケットを作成します。
    3. イメージを gcr.io/my-project/my-image:1.0 として保存する

  2. この最初の push の後、他のユーザーにストレージ バケットに対する権限を付与できます。

プロジェクト内では、レジストリ ホストがすべてのイメージを同じストレージ バケットに保存します。次の例では、プロジェクト my-project のレジストリ gcr.io 内には、web-app という 2 つのイメージがあります。1 つはプロジェクト ID my-project の直下にあります。もう一方の画像はリポジトリ team1 にあります。

gcr.io/my-project/web-app
gcr.io/my-project/team1/web-app

Artifact Registry

Artifact Registry リポジトリ管理者のロールを持つアカウントは、イメージを push する前にリポジトリを作成する必要があります。その後、他のユーザーにリポジトリに対する権限を付与できます。

Artifact Registry では、各リポジトリは個別のリソースです。したがって、すべてのイメージパスにリポジトリを含める必要があります。

有効な画像パス:

us-central1-docker.pkg.dev/my-project/team1/web-app:1.0
us-central1-docker.pkg.dev/my-project/team2/web-app:1.0

無効なイメージパス（リポジトリが含まれていない）:

us-central1-docker.pkg.dev/my-project/web-app:1.0

次の例は、不明なリポジトリへのイメージの push が失敗する状況を示しています。

  • us-central1-docker.pkg.dev/my-project/team1 が存在しない場合、イメージを us-central1-docker.pkg.dev/my-project/team1 に push します。
  • us-central1-docker.pkg.dev/my-project/team1 は存在するが us-central1-docker.pkg.dev/my-project/team2 が存在しない場合、イメージを us-central1-docker.pkg.dev/my-project/team2 に push します。

権限の付与

要点:

  • Artifact Registry で使用しているアカウントに適切な Artifact Registry ロールを付与します。
  • Google Cloud サービスには、Container Registry と Artifact Registry の両方に対する同等の読み取りまたは書き込みアクセス権があります。ただし、デフォルトの Cloud Build サービス アカウントはリポジトリを作成できません。
  • Container Registry は、ストレージ バケット レベルでのアクセス制御をサポートしています。Artifact Registry は、リポジトリ レベルのアクセス制御をサポートしています。

次の比較は、各サービスで設定されている権限を示しています。

Container Registry

Container Registry では、Cloud Storage のロールを使用してアクセスを制御します。

ストレージ バケット レベルのストレージ オブジェクト閲覧者
プロジェクト内の既存のレジストリ ホストからイメージを pull（読み取り）します。
ストレージ バケット レベルの Storage レガシー バケット書き込み
プロジェクト内の既存のレジストリ ホストのイメージを push（書き込み）および pull（読み取り）します。
プロジェクト レベルのストレージ管理者
ホストに初期イメージを push して、レジストリ ホストをプロジェクトに追加します。

レジストリに最初のイメージの push を行った後は、ストレージ バケットへのアクセスを必要とする他のアカウントに Cloud Storage ロールを付与します。ストレージ管理者のロールのすべての権限を持つアカウントは、プロジェクト全体でストレージ バケットとストレージ オブジェクトの読み取り、書き込み、削除を行うことができます。

ストレージ バケットに対する権限は、レジストリ内のすべてのリポジトリに適用されます。たとえば、gcr.io/my-project のバケットに対する Storage オブジェクト閲覧者権限を持つすべてのユーザーは、次のすべてのリポジトリのイメージを読み取ることができます。

gcr.io/my-project/team1
gcr.io/my-project/team2
gcr.io/my-project/test
gcr.io/my-project/production

Artifact Registry

Artifact Registry には、アクセスを制御する独自のロールがあります。これらのロールは、管理者とリポジトリのユーザーロールを明確に区別します。

Artifact Registry リポジトリ管理者ロールまたは Artifact Registry 管理者ロールは、リポジトリを管理するアカウントにのみ付与する必要があります。

Artifact Registry 読み取り
アーティファクトとリポジトリを一覧表示します。アーティファクトをダウンロードします。
Artifact Registry 書き込み
アーティファクトとリポジトリを一覧表示します。アーティファクトをダウンロードし、新しいアーティファクト バージョンをアップロードして、タグを追加または更新します。
Artifact Registry リポジトリ管理者
Artifact Registry 書き込みの権限と、アーティファクトとタグを削除する権限。
Artifact Registry 管理者
Artifact Registry リポジトリ管理者の権限と、リポジトリの作成、更新、削除、リポジトリに対する権限付与のための権限。

これらの権限はリポジトリ レベルで適用できます。次に例を示します。

  • us-central1-docker.pkg.dev/my-project/team1 のチーム 1 にアクセス権を付与します。
  • us-central1-docker.pkg.dev/my-project/team2 のチーム 2 にアクセス権を付与します。

Artifact Registry の権限を付与する方法については、アクセス制御のドキュメントをご覧ください。

レジストリに対する認証

要点:

  • Artifact Registry は、Container Registry と同じ認証方法をサポートしています。
  • Docker 認証情報ヘルパーの場合、Docker クライアント構成に追加するホストを指定する必要があります。
  • docker login を使用した認証では、Container Registry ホストの代わりに Artifact Registry ホストを使用します。

認証情報ヘルパーの使用

コマンド gcloud auth configure-docker とスタンドアロン認証ヘルパーは、デフォルトでは *.gcr.io ホスト名用にのみ Docker を構成します。Artifact Registry の場合は、Docker クライアント構成に追加する Artifact Registry ホストのリストを指定する必要があります。

たとえば、リージョン us-central1 の Docker リポジトリの認証を設定するには、次のコマンドを実行します。

gcloud auth configure-docker us-central1-docker.pkg.dev

後で us-east1 と asia-east1 にリポジトリを追加する場合は、コマンドを再度実行して、対応するリージョン ホスト名を Docker 構成に追加する必要があります。

gcloud auth configure-docker us-east-docker.pkg.dev,asia-east1-docker.pkg.dev

Artifact Registry の認証方法の詳細については、Docker の認証の設定をご覧ください。

パスワード認証の使用

Docker にログインするときは、*.gcr.io ホスト名ではなく Artifact Registry ホスト名を使用します。次の例は、ホスト us-central1-docker.pkg.dev に対する base64 でエンコードされたサービス アカウント キーによる認証を示しています。

cat key.json | docker login -u _json_key_base64 --password-stdin \
https://us-central1-docker.pkg.dev

イメージのビルドとタグ付け

重要なポイント: - Artifact Registry では、リポジトリに別のホスト名を使用します。

イメージにタグを付けるときは、Container Registry パスではなく Artifact Registry パスを使用します。次に例を示します。

docker tag my-image us-central1-docker.pkg.dev/my-project/my-repo/my-image:1.0

イメージをレジストリに push する

主なポイント: - Artifact Registry では、イメージを push する前にターゲット リポジトリが存在している必要があります。- Artifact Registry では、リポジトリに別のホスト名を使用します。

イメージを push するときは、Container Registry パスではなく Artifact Registry パスを使用します。次に例を示します。

docker push us-central1-docker.pkg.dev/my-project/my-repo/my-image:1.0

レジストリからイメージを pull する

キーポイント:

  • Artifact Registry のホスト名は Container Registry のホスト名とは異なります。

イメージを pull する場合は、Container Registry パスではなく Artifact Registry パスを使用します。次に例を示します。

docker pull us-central1-docker.pkg.dev/my-project/my-repo/my-image:1.0

Cloud Run や GKE などの Google Cloud ランタイムにイメージをデプロイする例については、イメージのデプロイをご覧ください。