イメージを push および pull する

このページでは、Docker を使用したコンテナ イメージの push と pull について説明します。また、Google Kubernetes Engine で問題のトラブルシューティングを行う場合は、crictl ツールでイメージを pull する方法についても説明します。

Google Cloud ランタイム環境へのデプロイについては、Google Cloud にデプロイするをご覧ください。

イメージのリスト表示、タグ付け、削除の手順については、イメージの管理をご覧ください。

始める前に

1. ターゲット リポジトリが存在しない場合は、新しいリポジトリを作成します。
2. ユーザーは少なくとも、リポジトリに対する Artifact Registry 書き込みアクセス権が必要です。
3. Docker をまだインストールしていなければ、インストールします。

必要なロール

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

• イメージを pull する: Artifact Registry 読み取り（roles/artifactregistry.reader）
• イメージにタグを付けて push する: Artifact Registry 書き込み（roles/artifactregistry.writer）

ロールの付与の詳細については、アクセスの管理をご覧ください。

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

リポジトリに対する認証

Docker リポジトリまたは Docker リポジトリで別のサードパーティ クライアントを使用する場合は、リポジトリに対して認証を行う必要があります。このセクションでは、認証に成功するために必要なことの概要を説明します。詳細な手順については、Docker の認証の設定をご覧ください。

認証情報ヘルパーの使用

gcloud CLI 認証ヘルパーまたはスタンドアロン認証情報ヘルパーの場合、使用する Artifact Registry ホストが Docker 構成ファイルに含まれている必要があります。

Artifact Registry では、すべてのレジストリ ホストが Docker 構成ファイルに自動的に追加されるわけではありません。構成されたレジストリが多い場合、Docker の応答時間が大幅に遅くなります。構成ファイル内のレジストリの数を最小限に抑えるには、必要なホストをファイルに追加します。

構成されたホストを確認するには、次のコマンドを実行して構成ファイルの内容を表示します。

• Linux: cat ~/.docker/config.json
• Windows: cat %USERPROFILE%\.docker\config.json

credHelpers セクションには、構成済みの Artifact Registry Docker ホストが一覧表示されます。ホスト名の末尾は -docker.pkg.dev です。次の例では、gcloud CLI 認証ヘルパー用に構成されたホストをいくつか示しています。

"credHelpers": {
  "asia.gcr.io": "gcloud",
  "eu.gcr.io": "gcloud",
  "gcr.io": "gcloud",
  "marketplace.gcr.io": "gcloud",
  "northamerica-northeast1-docker.pkg.dev": "gcloud",
  "us-central1-docker.pkg.dev": "gcloud",
  "us-east1-docker.pkg.dev": "gcloud",
  "us.gcr.io": "gcloud"
}

使用するホストがリストにない場合は、認証情報ヘルパーを再度実行してホストを追加します。たとえば、次のコマンドは us-east1-docker.pkg.dev を追加します。

• gcloud CLI 認証ヘルパー

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

• スタンドアロン認証情報ヘルパー

  docker-credential-gcr configure-docker us-east1-docker.pkg.dev
  

アクセス トークンの使用

アクセス トークン認証では、トークンを生成し、docker login コマンドでパスワードとして使用します。トークンは 60 分間有効であるため、イメージのタグ付け、push、pull の直前に認証を行う必要があります。

次の例では、サービス アカウントのなりすましを使用してアクセス トークンを生成し、Artifact Registry に対して認証します。この方法でトークンを生成するには、サービス アカウント トークン作成者のロール（roles/iam.serviceAccountTokenCreator）に対する権限が必要です。

Linux

gcloud auth print-access-token \
  --impersonate-service-account  ACCOUNT | docker login \
  -u oauth2accesstoken \
  --password-stdin https://LOCATION-docker.pkg.dev

ウィンドウ

gcloud auth print-access-token \
--impersonate-service-account  ACCOUNT

ya29.8QEQIfY_...

docker login -u oauth2accesstoken -p "ya29.8QEQIfY_..." \
https://LOCATION-docker.pkg.dev

サービス アカウントの権限借用が許可されていない場合は、gcloud CLI セッションでサービス アカウントを有効にして、トークンを取得します。詳しくは、アクセス トークン認証の設定手順をご覧ください。

サービス アカウント キーの使用

サービス アカウント キーの場合は、docker login コマンドでパスワードとしてキーを使用します。

たとえば、次のコマンドでは、ファイル key.json 内の base64 でエンコードされたサービス アカウント キーを使用して us-east1-docker.pkg.dev への認証を行います。

Linux

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

Windows

docker login -u _json_key_base64 --password-stdin https://us-east1-docker.pkg.dev < key.json

詳細については、サービス アカウント キー認証の設定手順をご覧ください。

イメージの push

リポジトリ モード: 標準

ローカル イメージを標準の Docker リポジトリに push するには、そのイメージをリポジトリ名でタグ付けしてから push します。

Artifact Registry Docker リポジトリでタグの不変性が有効になっている場合、タグは常にリポジトリ内の同じイメージ ダイジェストを参照する必要があります。リポジトリに push した同じイメージの別のバージョンでタグを使用することはできません。イメージ ダイジェスト、タグ、タグの不変性の詳細については、コンテナ イメージのバージョンをご覧ください。

サイズの大きいイメージの場合は、次の制限が適用されます。

アップロード時間

アクセス トークンを使用して Artifact Registry に対して認証する場合、トークンは 60 分間のみ有効です。アップロード時間が 60 分を超えると想定される場合は、別の認証方法を使用します。

イメージサイズ

アーティファクトの最大サイズは 5 TB です。

Artifact Registry では、Docker による

チャンクされたアップロードをサポートしていません。ツールの中には、チャンクされたアップロードか 1 回のモノリシック アップロードのいずれかを使用して、サイズの大きいイメージをアップロードできるものがあります。Artifact Registry にイメージを push する際は、モノリシック アップロードを使用する必要があります。

ローカル イメージにタグ付けする

1. リポジトリに対して認証されていることを確認します。

2. イメージの名前を特定します。完全なイメージ名の形式は次のとおりです。

   LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE
   

   次の値を置き換えます。

   • LOCATION は、イメージが保存されるリポジトリのリージョンまたはマルチリージョンのロケーション（us-east1 または us）です。

   • PROJECT-ID は、Google Cloud コンソール プロジェクト ID です。プロジェクト ID にコロン（:）が含まれている場合は、ドメインをスコープとするプロジェクトをご覧ください。

   • REPOSITORY は、イメージが保存されるリポジトリの名前です。

   • IMAGE はイメージの名前です。イメージのローカル名とは別の名前にできます。

   たとえば、次のような特性を持つイメージについて考えてみましょう。

   • リポジトリの場所: us-east1
   • リポジトリ名: my-repo
   • プロジェクト ID: my-project
   • ローカル イメージ名: my-image
   • ターゲット イメージ名: test-image

   この例のイメージ名は次のとおりです。

   us-east1-docker.pkg.dev/my-project/my-repo/test-image
   

   注: リポジトリに保存するイメージの名前は、ローカルマシン上のイメージ名と異なっていてもかまいません。

   イメージ名の形式とドメインをスコープとするプロジェクトの処理の詳細については、リポジトリとイメージの名前をご覧ください。

3. ローカル イメージにレジストリ名でタグ付けする

   docker tag SOURCE-IMAGE LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE:TAG
   

   SOURCE-IMAGE はローカル イメージ名またはイメージ ID に置き換え、TAG はタグに置き換えます。タグを指定しない場合、Docker はデフォルトの latest タグを適用します。

   不変のイメージタグ設定が有効になっている場合（プレビュー版）、タグは latest タグを含め、イメージ バージョンごとに一意である必要があります。タグがリポジトリ内の別のバージョンの同じイメージですでに使用されている場合、イメージをリポジトリに push することはできません。リポジトリで設定が有効になっているかどうかを確認するには、次のコマンドを実行します。

   gcloud artifacts repositories describe REPOSITORY \
       --project=PROJECT-ID \
       --location=LOCATION
   

   前の手順のサンプル イメージで、ローカル イメージ my-image が現在のディレクトリにある場合は、次のコマンドを使用します。

   docker tag my-image us-east1-docker.pkg.dev/my-project/my-repo/test-image
   

   特定のタグを適用する場合は、次のコマンドを使用します。

   docker tag SOURCE-IMAGE LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE:TAG
   

   サンプル イメージで staging タグを使用するには、コマンドに :staging を追加します。

   docker tag my-image us-east1-docker.pkg.dev/my-project/my-repo/test-image:staging
   

タグ付きイメージを Container Registry に push する

注: Artifact Registry では、Docker によるチャンクされたアップロードをサポートしていません。コンテナ イメージ ツールの中には、チャンクされたアップロードと 1 回のモノリシック アップロードのどちらかを使用して大規模なコンテナ イメージをアップロードできるものがあります。Container Registry にコンテナ イメージを push する際は、モノリシック アップロードを使用する必要があります。

1. リポジトリに対して認証されていることを確認します。

   gcloud auth configure-docker または docker-credential-gcr configure-docker を使用して Docker クライアントを構成した場合は、ターゲット ホスト名が Docker 構成ファイルに含まれていることを確認します。

2. 次のコマンドを使用して、タグ付きイメージを push します。

   docker push LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE
   

   このコマンドは、latest タグが付けられたイメージを push します。別のタグが付けられたイメージを push する場合は、次のコマンドを使用します。

   docker push LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE:TAG
   

イメージを push すると、指定したリポジトリに保存されます。

イメージを push した後、次のことが可能になります。

• Google Cloud コンソールに移動し、イメージを表示します。

• gcloud コマンドを実行して、イメージのタグと自動生成されたダイジェストを表示します。

  gcloud artifacts docker images list \
  LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE [--include-tags]
  

  次の出力例は、切り捨てられたイメージ ダイジェストを示していますが、このコマンドは、常にイメージ ダイジェストの全体を返します。

   IMAGE                                                 DIGEST         CREATE_TIME          UPDATE_TIME
    us-east1-docker.pkg.dev/my-project/my-repo/my-image  sha256:85f...  2019-04-10T15:08:45  2019-04-10T15:08:45
    us-east1-docker.pkg.dev/my-project/my-repo/my-image  sha256:238...  2019-04-10T17:23:53  2019-04-10T17:23:53
    us-east1-docker.pkg.dev/my-project/my-repo/my-image  sha256:85f...  2019-04-10T15:08:46  2019-04-10T15:08:46
  

Docker を使用したイメージの pull

リポジトリ モード: 標準、リモート、仮想

1. リポジトリに対して認証されていることを確認します。

   gcloud auth configure-docker または docker-credential-gcr configure-docker を使用して Docker クライアントを構成した場合は、ターゲット ホスト名が Docker 構成ファイルに含まれていることを確認します。

2. リポジトリから pull するには、次のコマンドを使用します。

   docker pull LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE:TAG
   

   または

   docker pull LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE@IMAGE-DIGEST
   

   次の値を置き換えます。

   • LOCATION は、イメージが保存されるリポジトリのリージョンまたはマルチリージョンのロケーション（us-east1 または us）です。
   • PROJECT は、Google Cloud コンソール プロジェクト ID です。プロジェクト ID にコロン（:）が含まれている場合は、ドメインをスコープとするプロジェクトをご覧ください。
   • REPOSITORY は、イメージが保存されるリポジトリの名前です。
   • IMAGE は、リポジトリ内のイメージの名前です。
   • TAG は、pull するイメージ バージョンのタグです。
   • IMAGE-DIGEST は、イメージ コンテンツの sha256 ハッシュ値です。 イメージの各バージョンにはそれぞれ固有のイメージ ダイジェストがあります。Google Cloud コンソールで、メタデータを表示する特定のイメージをクリックします。ダイジェストはイメージのダイジェストとして一覧表示されます。

   たとえば、次のような特性を持つイメージについて考えてみましょう。

   • リポジトリの場所: us-east1
   • リポジトリ名: my-repo
   • プロジェクト ID: my-project
   • イメージ名: test-image
   • タグ: staging

   イメージを pull するこのコマンドは:

   docker pull us-east1-docker.pkg.dev/my-project/my-repo/test-image:staging
   

Docker が指定されたイメージをダウンロードします。

リモート リポジトリからイメージをリクエストし、キャッシュ リポジトリが存在しない場合は、リモート リポジトリがアップストリーム ソースからイメージをダウンロードしてキャッシュに保存します。

仮想リポジトリからイメージをリクエストすると、Artifact Registry はリクエストされたイメージのアップストリーム リポジトリを検索します。複数のアップストリーム リポジトリに存在する利用可能なバージョンをリクエストすると、Artifact Registry は仮想リポジトリ用に構成された優先度設定に基づいて、使用するアップストリーム リポジトリを選択します。

たとえば、アップストリーム リポジトリに次の優先度設定がある仮想リポジトリについて考えます。

• main-repo: 優先度が 100 に設定
• secondary-repo1: 優先度が 80 に設定
• secondary-repo2: 優先度が 80 に設定
• test-repo: 優先度が 20 に設定

main-repo は優先度が最も高いため、仮想リポジトリは常に最初に検索します。

secondary-repo1 と secondary-repo2 の優先度はどちらも 80 に設定されています。リクエストされたイメージが main-repo にない場合、Artifact Registry は次にこれらのリポジトリを検索します。どちらも同じ優先度の値を持つため、両方にそのバージョンがある場合、Artifact Registry はどちらか一方のリポジトリからイメージを提供するように選択できます。

test-repo の優先度は最も低くなります。他のアップストリーム リポジトリにアーティファクトがない場合、保存されたアーティファクトが提供されます。

crictl によるイメージの pull

crictl は、Kubernetes コンポーネントを設定せずにランタイムをデバッグする CRI ランタイム デベロッパー向けの便利なコマンドライン ツールです。Google Kubernetes Engine ノードで containerd ランタイムを使用している場合は、crictl を使用して Artifact Registry からイメージを pull できます。

crictl は主にトラブルシューティング ツールであるため、イメージの push やタグ付けなどの一部の Docker コマンドは使用できません。

Artifact Registry からイメージを pull するには:

1. Google Cloud コンソールで、[VM インスタンス] ページに移動します。

   [VM インスタンス] に移動

2. トラブルシューティングするノードに SSH で接続します。

3. リポジトリで認証するためのアクセス トークンを取得します。

   curl -s "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/token" -H "Metadata-Flavor: Google"

4. crictl pull --creds 値と access_token 値を使用してイメージを pull する

   crictl pull --creds "oauth2accesstoken:ACCESS_TOKEN" LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE:TAG

   または

   crictl pull --creds "oauth2accesstoken:ACCESS_TOKEN" LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE@IMAGE-DIGEST

   出力は次のようになります。

   Image is up to date for sha256:0f25067aa9c180176967b4b50ed49eed096d43fa8c17be9a5fa9bff05933bee5

次のステップ

• タグの管理とイメージの削除について学習する。
• Compute Engine 上でコンテナを実行する場合、Compute Engine 上のコンテナについて学習する。
• crictl を使用して Kubernetes ノードをデバッグする
• crictl を使用して限定公開 Artifact Registry リポジトリからイメージを pull する方法を学習する
• crictl イメージ レジストリの構成の詳細を確認する