このドキュメントでは、Docker でのコンテナ イメージの認証、push、pull に関する Container Registry と Artifact Registry の違いについて説明します。
このガイドでは、標準 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 に焦点を合わせた既存のコマンド、構成、ドキュメントを適応させます。
始める前に
このドキュメントは、次のものがあることを前提としています。
- プロジェクトで Artifact Registry を有効にしている。
- Docker をインストールしておくこと。 Docker は Cloud Shell に含まれています。
概要
大まかに言うと、Container Registry と Artifact Registry で Docker を使用するワークフローは同じです。
Container Registry | Artifact Registry |
---|---|
管理者
|
管理者
|
レジストリ ユーザー
|
レジストリ ユーザー
|
ただし、Container Registry のショートカットは、管理者とユーザーのロールを 1 つのワークフローに統合することです。これは一般的なショートカットです。
- 広範な権限がある環境でテストするクイックスタートとチュートリアル。
- 同じ Google Cloud プロジェクトにレジストリ ホストを追加する権限が Cloud Build サービス アカウントにあるため、Cloud Build を使用するワークフロー。
ショートカットのワークフローは次のようになります。
- Container Registry API を有効にします。
- Container Registry にアクセスするアカウントに権限を付与します。
レジストリに対する認証を行います。最も簡単な認証オプションは、Google Cloud CLI で Docker 認証ヘルパーを使用することです。これは初回にのみ必要な手順です。
gcloud auth configure-docker
イメージをビルドしてタグを付けます。たとえば、次のコマンドは、イメージ
gcr.io/my-project/my-image:tag1
をビルドしてタグを付けます。docker build -t gcr.io/my-project/my-image:tag1
イメージをレジストリに push します。次に例を示します。
docker push gcr.io/my-project/my-image:tag1
gcr.io
レジストリホストがプロジェクトに存在しない場合、Container Registry はイメージをアップロードする前にホストを追加します。イメージをレジストリから 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 に適応させるには、次の変更を行います。各ステップは、ワークフローの変更に関する追加情報にリンクしています。
新規: Artifact Registry API を有効にします。
Artifact Registry API を有効にする必要があります。Cloud Build や、Cloud Run や GKE などのランタイム環境では、API が自動的に有効になりません。
新規: ターゲット Docker リポジトリがまだ存在しない場合は、それを作成します。イメージを push する前に、リポジトリを作成する必要があります。イメージを push してもリポジトリの作成をトリガーできません。Cloud Build サービス アカウントにはリポジトリを作成する権限がありません。
Artifact Registry とやり取りするアカウントに権限を付与します。
変更: リポジトリに対して認証します。gcloud CLI で認証ヘルパーを使用する場合は、Docker クライアント構成に追加するホストを指定する必要があります。たとえば、次のコマンドはホスト
us-central1-docker.pkg.dev
を追加します。gcloud auth configure-docker us-central1-docker.pkg.dev
変更: イメージのビルドとタグ付けを行います。
次のコマンド例は、Container Registry の例と同じですが、イメージに Artifact Registry リポジトリ パスを使用しています。
docker build -t us-central1-docker.pkg.dev/my-project/my-repo/my-image:tag1
変更: Artifact Registry パスを使用してイメージをリポジトリに push します。次に例を示します。
docker push us-central1-docker.pkg.dev/my-project/my-repo/my-image:tag1
変更: Artifact Registry パスを使用してリポジトリからイメージを pull します。次に例を示します。
docker pull us-central1-docker.pkg.dev/my-project/my-repo/my-image:tag1
API の有効化
要点:
- Cloud Build、Cloud Run、GKE などの他の Google Cloud サービスの API に加えて、Artifact Registry API を有効にする必要があります。
次の比較では、各サービスで API を有効にする方法を説明します。
Container Registry
Docker や他のサードパーティ クライアントを Container Registry で使用する前に、Container Registry API を有効にする必要があります。
次の Google Cloud API を有効にすると、Container Registry API も自動的に有効になります。
- App Engine フレキシブル環境
- Cloud Build
- Cloud Functions
- Cloud Run
- Artifact Analysis のコンテナ スキャンまたはオンデマンド スキャン
- Google Kubernetes Engine(GKE)
デフォルトの権限では、レジストリが同じプロジェクトにある場合、Cloud Build でビルドを実行したり、Artifact Analysis を使用してコンテナをスキャンしたり、コンテナを Google Cloud ランタイムにデプロイしたりできるユーザーは、Container Registry 内のイメージに明示的にアクセスできます。
Artifact Registry
Docker クライアントや Google Cloud サービスを Artifact Registry で使用する前に、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 リポジトリを作成する必要があります。
Container Registry への権限を持つイメージは、レジストリ ホストへの最初の push でプロジェクトにレジストリを追加できるため、Container Registry へのイメージの push を説明するドキュメントでは、レジストリ作成手順は除外されます。
Container Registry では、すべてのイメージを同じストレージ バケットの 1 つのマルチリージョンに保存します。Artifact Registry では、同じアクセス ポリシーを使用して、同じリージョンまたはマルチリージョンに複数のリポジトリを作成できます。
次の比較では、各サービスでのリポジトリの設定について説明します。
Container Registry
Container Registry では、プロジェクトに最大 4 つのレジストリホストを追加できます。最初のイメージを push して、レジストリホストを追加します。
gcr.io
などのレジストリをプロジェクトに追加するには、プロジェクト レベルでストレージ管理者のロールを持つアカウントが初期イメージを push します。たとえば、
gcr.io
ホストがプロジェクトmy-project
に存在しない場合は、イメージgcr.io/my-project/my-image:1.0
を push すると次の手順がトリガーされます。gcr.io
ホストをプロジェクトに追加する- プロジェクトで
gcr.io
のストレージ バケットを作成します。 - イメージを
gcr.io/my-project/my-image:1.0
として保存する
最初に push した後、Storage バケットに別のユーザーの権限を付与できます。
プロジェクト内では、レジストリ ホストがすべてのイメージを同じストレージ バケットに保存します。次の例では、プロジェクト my-project
のレジストリ gcr.io
に web-app
という 2 つのイメージがあります。1 つはプロジェクト ID my-project
の直下にあります。もう 1 つのイメージはリポジトリ 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(読み取り)します。
- ストレージ バケットレベルでのストレージのレガシー バケット書き込み
- プロジェクト内の既存のレジストリ ホストのイメージを push(書き込み)および pull(読み取り)します。
- プロジェクト レベルのストレージ管理者
- ホストに初期イメージを push して、レジストリ ホストをプロジェクトに追加します。
最初のイメージをレジストリに push したら、ストレージ バケットへのアクセスが必要な他のアカウントに Cloud Storage のロールを付与します。ストレージ管理者のロールのすべての権限を持つアカウントは、プロジェクト全体でストレージ バケットとストレージ オブジェクトの読み取り、書き込み、削除を行うことができます。
ストレージ バケットに対する権限は、レジストリ内のすべてのリポジトリに適用されます。たとえば、gcr.io/my-project
のバケットに対するストレージ オブジェクト閲覧者権限を持つユーザーは、これらすべてのリポジトリのイメージを読み取ることができます。
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 ランタイムにイメージをデプロイする例については、イメージのデプロイをご覧ください。