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

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

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

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

始める前に

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

必要なロール

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

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

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

リポジトリに対する認証

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-west1-docker.pkg.dev　を追加します。

  • gcloud CLI 認証ヘルパー

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

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

    docker-credential-gcr configure-docker us-west1-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

Windows

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-west1-docker.pkg.dev に対して認証します。

Linux

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

Windows

docker login -u _json_key_base64 --password-stdin https://us-west1-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 は、イメージが保存されているリポジトリのリージョンまたはマルチリージョンのロケーションです。
    • PROJECT-ID は、Google Cloud コンソール プロジェクト ID です。プロジェクト ID にコロン（:）が含まれている場合は、ドメインをスコープとするプロジェクトをご覧ください。
    • REPOSITORY は、イメージが保存されるリポジトリの名前です。
    • IMAGE はイメージの名前です。イメージのローカル名とは別の名前にできます。

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

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

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

    us-west1-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-west1-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-west1-docker.pkg.dev/my-project/my-repo/test-image:staging

タグ付きイメージを 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-west1-docker.pkg.dev/my-project/my-repo/my-image  sha256:85f...  2019-04-10T15:08:45  2019-04-10T15:08:45
  us-west1-docker.pkg.dev/my-project/my-repo/my-image  sha256:238...  2019-04-10T17:23:53  2019-04-10T17:23:53
  us-west1-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 は、イメージが保存されているリポジトリのリージョンまたはマルチリージョンのロケーションです。
    • PROJECT は、Google Cloud コンソール プロジェクト ID です。プロジェクト ID にコロン（:）が含まれている場合は、ドメインをスコープとするプロジェクトをご覧ください。
    • PROJECT は、Google Cloud コンソール プロジェクト ID です。
    • REPOSITORY は、イメージが保存されるリポジトリの名前です。
    • IMAGE は、リポジトリ内のイメージの名前です。
    • TAG は、pull するイメージ バージョンのタグです。
    • IMAGE-DIGEST は、イメージ コンテンツの sha256 ハッシュ値です。イメージの各バージョンにはそれぞれ固有のイメージ ダイジェストがあります。Google Cloud コンソールで、メタデータを表示する特定のイメージをクリックします。ダイジェストはイメージのダイジェストとして一覧表示されます。

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

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

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

    docker pull us-west1-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

次のステップ