Artifact Registry の「gcr.io」リポジトリへの手動移行

このドキュメントでは、Artifact Registry で gcr.io リポジトリを手動で設定する方法について説明します。

自動移行化ツールを使用して、Artifact Registry の gcr.io リポジトリに移行することをおすすめします。

顧客管理の暗号鍵（CMEK）を使用して Artifact Registry に gcr.io リポジトリを作成する場合は、始める前にの手順を完了してから、リポジトリの手動作成の手順に沿って操作します。

始める前に

1. Google Cloud CLI をまだインストールしていない場合は、インストールします。すでにインストールしている場合は、次のコマンドを実行してコンポーネントを最新バージョンに更新します。

   gcloud components update
   

2. Artifact Registry API と Resource Manager API を有効にします。gcloud CLI は、Resource Manager API を使用して、必要な権限のいずれかを確認します。

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

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

3. 移行を開始する前に、Artifact Registry の料金をご覧ください。

必要なロール

gcr.io リポジトリの設定に必要な権限を取得するには、次の IAM ロールを付与するよう管理者に依頼してください。

• Artifact Registry リポジトリを作成して、個々のリポジトリへのアクセス権を付与する場合: Google Cloud プロジェクトの Artifact Registry 管理者（roles/artifactregistry.admin）
• Cloud Storage ストレージ バケットに適用される既存の Container Registry 構成を表示して管理する場合: Google Cloud プロジェクトのストレージ管理者（roles/storage.admin）
• 初めてイメージを gcr.io ホスト名に push したときに gcr.io リポジトリを作成する場合: Google Cloud プロジェクトの Artifact Registry の Create-on-push Writer （roles/artifactregistry.createOnPushWriter)
• プロジェクト レベルでリポジトリへのアクセス権を付与する場合: Google Cloud プロジェクトのプロジェクト IAM 管理者（roles/resourcemanager.projectIamAdmin）
• 組織内の有効なサービスを一覧表示する場合: 組織の Cloud Asset 閲覧者（roles/cloudasset.viewer）

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

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

制限事項

Artifact Registry gcr.io リポジトリには、次の制限が適用されます。

• Container Registry から移行する場合、Container Registry ホストを別のプロジェクトの Artifact Registry リポジトリにマッピングすることはできません。
• 各 Container Registry ホスト名は、同じマルチリージョン内の対応する Artifact Registry gcr.io リポジトリにのみマッピングされます。
• gcr.io リポジトリの名前は事前定義されており、変更できません。

リポジトリの場所をより詳細に制御するには、Artifact Registry pkg.dev ドメインの標準リポジトリに移行できます。標準リポジトリは gcr.io ドメインをサポートしていないため、この移行アプローチでは既存の自動化とワークフローに対してより多くの変更が必要になります。機能の違いについては、[移行オプションを選択する] をご覧ください。

リポジトリの作成

gcr.io リポジトリを作成して、リダイレクトを有効にする前に、ユーザーのアクセス権を構成し、既存の Container Registry イメージを Artifact Registry にコピーできるようにします。

手動によるリポジトリの作成

顧客管理の暗号鍵（CMEK）を使用してリポジトリのコンテンツを暗号化する場合、またはロケーションの制約が存在し、Google Cloud 組織で特定のロケーションでの新しいリソース作成がブロックされている場合は、gcr.io リポジトリを手動で作成します。

gcr.io リポジトリを手動で作成するには、以下の手順を行います。

1. CMEK を使用している場合は、このリポジトリで使用する鍵を作成し、その鍵を使用する権限を付与します。顧客管理の暗号鍵の有効化を参照してください。

2. リポジトリを追加します。

   コンソール

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

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

   2. [リポジトリを作成] をクリックします。

   3. リポジトリ名を指定します。

      Container Registry ホスト名	Artifact Registry リポジトリ名
      gcr.io	gcr.io
      asia.gcr.io	asia.gcr.io
      eu.gcr.io	eu.gcr.io
      us.gcr.io	us.gcr.io

   4. Docker をリポジトリ形式として指定します。

   5. ロケーション タイプ で、リポジトリのマルチ リージョンを指定します。

      Container Registry ホスト名	Artifact Registry リポジトリのロケーション	Artifact Registry リポジトリ名
      gcr.io	us	gcr.io
      asia.gcr.io	asia	asia.gcr.io
      eu.gcr.io	europe	eu.gcr.io
      us.gcr.io	us	us.gcr.io

   6. リポジトリの説明を追加します。リポジトリの説明は暗号化されないため、機密データは含めないでください。

   7. [暗号化] セクションで、リポジトリの暗号化方式を選択します。

      • Google が管理する鍵 - Google が管理する暗号鍵を使用してリポジトリのコンテンツを暗号化します。
      • 顧客管理の暗号鍵 - Cloud Key Management Service で管理する鍵を使用してリポジトリのコンテンツを暗号化します。鍵の設定手順については、リポジトリの CMEK の設定をご覧ください。

   8. [作成] をクリックします。

   gcloud

   次のコマンドを実行して新しいリポジトリを作成します。

   gcloud artifacts repositories create REPOSITORY \
       --repository-format=docker \
       --location=LOCATION \
       --description=DESCRIPTION \
       --kms-key=KMS-KEY
   

   次の値を置き換えます。

   • REPOSITORY はリポジトリの名前です。

     Container Registry ホスト名	Artifact Registry リポジトリ名
     gcr.io	gcr.io
     asia.gcr.io	asia.gcr.io
     eu.gcr.io	eu.gcr.io
     us.gcr.io	us.gcr.io

   • LOCATION は、リポジトリのマルチリージョンです。

     Container Registry ホスト名	Artifact Registry リポジトリのロケーション	Artifact Registry リポジトリ名
     gcr.io	us	gcr.io
     asia.gcr.io	asia	asia.gcr.io
     eu.gcr.io	europe	eu.gcr.io
     us.gcr.io	us	us.gcr.io

   • DESCRIPTION はリポジトリの説明です。リポジトリの説明は暗号化されないため、機密データは含めないでください。

   • KMS-KEY は、リポジトリのコンテンツを暗号化するために顧客管理の暗号鍵を使用する場合、Cloud KMS 暗号鍵のフルパスです。パスの形式は次のとおりです。

     projects/KMS-PROJECT/locations/KMS-LOCATION/keyRings/KEY-RING/cryptoKeys/KEY

     次の値を置き換えます。

     • KMS-PROJECT は鍵が保管されているプロジェクトです。
     • KMS-LOCATION は鍵の場所です。
     • KEY-RING はキーリングの名前です。
     • KEY は、鍵の名前です。

   次のコマンドでリポジトリを一覧表示することで、リポジトリが作成されていることを確認できます。

   gcloud artifacts repositories list
   

トラフィックを新しいリポジトリにリダイレクトする前に、既存の自動化でリポジトリにアクセスできることを確認する必要があります。次のステップでは、リポジトリへのアクセス権を付与する権限を構成します。

リポジトリに権限を付与する

Container Registry は、Cloud Storage ロールを使用してアクセスを制御します。Artifact Registry には独自の IAM ロールがあり、これらのロールは読み込み、書き込み、リポジトリの管理ロールを Container Registry よりも明確に分離しています。

ストレージ バケットに付与されている既存の権限を、素早く推奨される Artifact Registry ロールにマッピングするには、ロール マッピング ツールを使用します。

また、Google Cloud コンソールを使用して、ストレージ バケットにアクセスできるプリンシパルのリストを表示することもできます。

1. Google Cloud コンソールで、Cloud Storage の [バケット] ページに移動します。
   

   [バケット] に移動

2. 表示するレジストリ ホストのストレージ バケットをクリックします。バケット名では、Google Cloud のプロジェクト IDは PROJECT-ID です。

   • gcr.io: artifacts.PROJECT-ID.appspot.com
   • asia.gcr.io: asia.artifacts.PROJECT-ID.appspot.com
   • eu.gcr.io: eu.artifacts.PROJECT-ID.appspot.com
   • us.gcr.io: us.artifacts.PROJECT-ID.appspot.com

3. [権限] タブをクリックします。

4. [Permissions] タブで、[View by role] サブタブをクリックします。

5. ロールを開いて、そのロールを持つプリンシパルを表示します。

このリストには、バケットに直接付与された IAM ロールと、親プロジェクトから継承したロールが含まれます。このロールに基づいて、最適な Artifact Registry ロールを選択して付与できます。

Cloud Storage と基本ロール

現在 Container Registry にアクセスしているユーザーとサービス アカウント にArtifact Registry リポジトリを付与します。親プロジェクトから継承した Cloud Storage ロールについては、プリンシパルが 現在 Container Registry を使用していることを確認する必要があります一部のプリンシパルは、Container Registry に関係のない他の Cloud Storage バケットにのみアクセスできる場合があります。

IAM の導入前から存在する基本ロールのオーナー、編集者、閲覧者は、ストレージ バケットへのアクセスが制限されています。それらのロールは本質的に名前が示すように Cloud Storage リソースに対するすべてのアクセス権を付与するものではなく、その他の Google Cloud サービスに対する追加の権限を付与します。Artifact Registry にアクセスする必要があるユーザーとサービス アカウントを確認します。ロールのマッピングの表を使用して、Artifact Registry へのアクセスが妥当である場合に、適切なロールを付与できます。

次の表は、事前定義された Cloud Storage ロールによって Container Registry アクセスに付与される権限に基づいて、Artifact Registry ロールのマッピングを示します。

必要なアクセス権	現在のロール	Artifact Registry ロール	ロールを付与する場所
イメージの pull のみ（読み取り専用）	Storage オブジェクト閲覧者 （roles/storage.objectViewer）	Artifact Registry 読み取り （roles/artifactregistry.reader)）	Artifact Registry リポジトリまたは Google Cloud プロジェクト
イメージの push と pull（読み込みと書き込み） 画像の削除	Storage レガシー バケット書き込み （roles/storage.legacyBucketWriter）	Artifact Registry リポジトリ管理者 （roles/artifactregistry.repoAdmin)）	Artifact Registry リポジトリまたは Google Cloud プロジェクト
プロジェクトでイメージが gcr.io ホスト名に初めて push されたときに、Artifact Registry で gcr.io リポジトリを作成する。	ストレージ管理者 （roles/storage.admin）	Artifact Registry の Create-on-push リポジトリ管理者 (roles/artifactregistry.createOnPushRepoAdmin)	Google Cloud プロジェクト
リポジトリの作成、管理、削除	ストレージ管理者 （roles/storage.admin）	Artifact Registry 管理者 (roles/artifactregistry.Admin)	Google Cloud プロジェクト

プロジェクトから継承されたサービス エージェントのロール

Google Cloud サービスのデフォルトのサービス アカウントには、プロジェクト レベルで独自のロールが付与されています。たとえば、Cloud Run のサービス エージェントには Cloud Run サービス エージェントのロールがあります。

ほとんどの場合、これらのサービス エージェントのロールには Container Registry と Artifact Registry に対する同等のデフォルト権限が含まれています。既存の Container Registry サービスと同じプロジェクトで Artifact Registry を実行している場合は、追加の変更は必要ありません。

サービス エージェントのロールの権限について詳しくは、サービス エージェントのロールのリファレンスをご覧ください。

カスタムロール

ロール マッピングの表を使用して、必要なアクセスレベルに基づいてユーザーまたはサービス アカウントに付与するロールを決定します。

Artifact Registry のロールを付与する手順については、ロールと権限を構成するをご覧ください。

Container Registry からコンテナをコピーする

自動移行ツールを使用して、Container Registry から Artifact Registry にイメージをコピーすることをおすすめします。

他のツールを使用してイメージをコピーする場合は、Container Registry からイメージをコピーするをご覧ください。

その他の機能を設定する

このセクションでは、Container Registry で設定されているその他の機能の構成について説明します。

Artifact Analysis

Artifact Analysis は、Container Registry と Artifact Registry の両方をサポートしています。どちらのプロダクトも、イメージ メタデータと脆弱性スキャンに同じ Artifact Analysis API を使用し、Artifact Analysis 通知に同じ Pub/Sub トピックを使用します。

ただし、次の操作はリダイレクトが有効な場合にのみ行うことができます。

• Artifact Registry での gcr.io リポジトリの自動スキャン
• Pub/Sub 通知に gcr.io リポジトリのアクティビティを含める。

引き続き gcloud container images コマンドを使用して、gcr.io イメージパスに関連付けられたメモとオカレンスを一覧表示できます。

Pub/Sub 通知

Artifact Registry は、Container Registry と同じ　gcr　トピックへの変更を公開します。すでに Artifact Registry と同じプロジェクトで Pub/Sub と Container Registry を併用している場合は、追加の構成は必要ありません。ですが、リダイレクトを有効にするまで、Artifact Registry は gcr.io リポジトリのメッセージを公開しません

別のプロジェクトで Artifact Registry を設定した場合は、gcr トピックが存在しない可能性があります設定手順については、Pub/Sub 通知の構成をご覧ください。

gcr.io トラフィックのリダイレクトを有効にする

gcr.io リポジトリを作成し、サードパーティ クライアントの権限と認証を構成したら、gcr.io トラフィックのリダイレクトを有効にできます。

リダイレクトを有効にした後に問題が発生した場合は、gcloud artifacts settings disable-upgrade-redirection コマンドを実行してトラフィックを Container Registry にルーティングし直すことができます。問題への対処が完了したら、リダイレクトを再びオンにします。

リダイレクトを有効にする権限を確認する

リダイレクトを有効にするには、プロジェクト レベルで次の権限が必要です。

• artifactregistry.projectsettings.update - Artifact Registry のプロジェクト設定を更新する権限。この権限は、Artifact Registry の管理者ロールに含まれています（roles/artifactregistry.admin）。
• storage.buckets.update - 全プロジェクトのストレージ バケットを更新する権限。ストレージの管理者ロールに含まれています（roles/storage.admin）。

これらの権限がない場合は、管理者にプロジェクト レベルで付与するよう依頼してください。

次のコマンドは、プロジェクトに Artifact Registry 管理者およびストレージ管理者のロールを付与します。

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member='user:PRINCIPAL' \
    --role='roles/artifactregistry.admin'

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member='user:PRINCIPAL' \
    --role='roles/storage.admin'

次の値を置き換えます。

• PROJECT_ID は、Google Cloud プロジェクト ID です。
• PRINCIPAL は、更新するアカウントのメールアドレスです。例: my-user@example.com

プロジェクトの設定を検証する

プロジェクトの設定を検証するには、次のコマンドを実行します。

gcloud artifacts settings enable-upgrade-redirection \
    --project=PROJECT_ID --dry-run

PROJECT_ID は、実際の Google Cloud プロジェクト ID に置き換えます。

Artifact Registry は、Container Registry ホスト名にマッピングされているリポジトリを確認します。

リダイレクトを有効にすると、Artifact Registry によって不足している gcr.io リポジトリが作成されるようにできますが、リダイレクトを有効にする前に確認できるように、最初に gcr.io リポジトリを作成することをおすすめします。

• リポジトリ レベルの権限を構成します。
• 引き続き使用する Container Registry からイメージをコピーします。
• 追加の構成を行います。

リダイレクトを有効にする

gcr.io トラフィックでリダイレクトを有効にするには:

リダイレクトを有効にするには、次のコマンドを実行します。

gcloud artifacts settings enable-upgrade-redirection \
    --project=PROJECT_ID

PROJECT_ID は、実際の Google Cloud プロジェクト ID に置き換えます。

Artifact Registry でリダイレクトの有効化が開始されます。

リダイレクトの現在のステータスを確認するには、次のコマンドを実行します。

gcloud artifacts settings describe

リダイレクトを有効にすると、結果は次のようになります。

legacyRedirectionState: REDIRECTION_FROM_GCR_IO_ENABLED

すべての Container Registry ホスト名に対して gcr.io リポジトリを作成していない場合でも、gcr.io、asia.gcr.io、eu.gcr.io、us.gcr.io へのすべてのトラフィックがリダイレクトされます。対応する Artifact Registry リポジトリがないホスト名にイメージを push すると、artifactregistry.repositories.createOnPush 権限を持つロールがユーザーに付与されている場合に、Artifact Registry はリポジトリを作成します。事前定義ロールの Create-on-push Writer（artifactregistry.createOnPushWriter）と Create-on-push リポジトリ管理者（artifactregistry.createOnPushRepoAdmin）には、この権限が付与されています。

リダイレクトを有効にすると、新しい gcr.io リポジトリを使用して自動化をテストし、イメージを push および pull できるかどうかを確認できます。

リダイレクトを確認する

gcr.io ホスト名への pull リクエストと push リクエストが機能していることを確認します。

1. gcr.io パスを使用して、テストイメージを gcr.io リポジトリのいずれかに push します。

   1. gcr.io パスを使用してイメージにタグ付けします。たとえば、次のコマンドではイメージ local-image に us.gcr.io/my-project/test-image というタグが付けられます。

      docker tag local-image us.gcr.io/my-project/test-image
      

   2. タグ付けしたイメージを push します。たとえば、次のコマンドはイメージ us.gcr.io/my-project/test-image を push します。

      docker push us.gcr.io/my-project/test-image
      

2. リポジトリ内のイメージを一覧表示して、イメージが正常にアップロードされたことを確認します。たとえば、us.gcr.io/my-project 内のイメージを一覧表示するには、次のコマンドを実行します。

   gcloud container images list --repository=us.gcr.io/my-project
   

3. Container Registry パスを使用してリポジトリからイメージを pull します。たとえば、次のコマンドはイメージ us.gcr.io/my-project/test-image を pull します。

   docker pull us.gcr.io/my-project/test-image
   

この初期テストが完了したら、次のように、イメージのビルドとデプロイに関する既存の自動化が期待どおりに動作することを確認します。

• リダイレクトが有効になっている場合、Container Registry を使用しているユーザーとサービス アカウントは、引き続き push、pull、デプロイができます。
• 自動化は、イメージを既存のリポジトリにのみ push します。
• Artifact Analysis の脆弱性スキャンが有効になっている場合、スキャンによって gcr.io リポジトリに脆弱性が存在するイメージが特定されます。
• Binary Authorization を使用する場合、既存のポリシーが gcr.io リポジトリからデプロイされたイメージに対して正しく機能します。
• 構成済みの Pub/Sub サブスクリプションには、gcr.io リポジトリの変更の通知が含まれます。

Container Registry イメージをクリーンアップする。

リダイレクトが有効な場合、gcr.io パス内のイメージを削除するコマンドで、対応する Artifact Registry gcr.io リポジトリ内のイメージを削除します。gcr.io パス内のイメージを削除する delete コマンドでは、Container Registry ホストに保存されているイメージは削除されません。

すべての Container Registry イメージを安全に削除するには、各 Container Registry ホスト名の Cloud Storage バケットを削除します。

各 Container Registry ストレージ バケットを削除するには:

gcloud storage rm gs://BUCKET-NAME --recursive

Removing gs://artifacts.my-project.appspot.com/...

他の Google Cloud サービスが同じ Google Cloud プロジェクトで実行されている場合は、Container Registry API を有効にしておきます。Container Registry API を無効化する場合。構成済みの依存関係がある他のサービスがプロジェクトで有効になっている場合、Container Registry には警告が表示されます。Container Registry API を無効にすると、構成済みの依存関係を持つ同じプロジェクト内のサービスが自動的に無効になります。現在これらのサービスと Container Registry を使用していない場合も同様です。

次のステップ

• Docker のクイックスタートを試してみてください。
• gcr.io リポジトリについて学習する。