イメージの push と pull

イメージの push（アップロード）と pull（ダウンロード）の 2 つは、Container Registry のタスクの中でも最も一般的なものです。このドキュメントでは、Docker でのイメージの push と pull について説明します。

Cloud Build を使用している場合、コンテナをビルドして Container Registry に push する方法については、Cloud Build のドキュメントをご覧ください。

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

始める前に

以下の準備を行います。

  1. プロジェクトで Container Registry を有効にしていること。

  2. インストールして構成された Docker。

レジストリの追加

プロジェクトには、次の Container Registry レジストリを追加できます。

ホスト名 ストレージの場所
gcr.io 米国のデータセンターにイメージを保存します。
asia.gcr.io アジアのデータセンターにイメージを保存します。
eu.gcr.io 欧州連合の加盟国内のデータセンターにイメージを保存します。
us.gcr.io 米国のデータセンターにイメージを保存します。

ホスト名に対する最初のイメージの push によって、対応する Cloud Storage のストレージ バケット内にレジストリの作成がトリガーされます。この最初の push を行うには、ストレージ バケットを作成するために、プロジェクト全体の権限が必要です。

一旦プロジェクトにレジストリ ホストができると、ストレージ バケットに対する権限を構成して、レジストリ内のイメージへのアクセスを制御できます。

レジストリを追加して権限を構成するには、次のようにします。

  1. 必要な権限があることを確認します。注: ストレージ管理者ロール（roles/storage.admin）、または同じ権限を持つカスタムロールまたは事前定義ロール。

    プロジェクト レベルでストレージ管理者のロールを付与する手順については、IAM のドキュメントをご覧ください。

  2. 最初のイメージをホストに push します。たとえば、次のコマンドを実行します。

    • Docker Hub から busybox イメージを pull する
    • gcr.io レジストリ ホストとプロジェクト ID my-project を含む Container Registry 内のターゲットパスでイメージにタグを付ける
    • レジストリへのイメージの push
    docker pull busybox
docker tag busybox gcr.io/my-project/busybox
docker push gcr.io/my-project/busybox

Container Registry は、レジストリをプロジェクトに追加し、レジストリのストレージ バケットを作成して、イメージを保存します。

これで、レジストリ ストレージ バケットでアクセス制御を構成して、レジストリ アクセスを他のユーザーに許可できるようになりました。

イメージのレジストリへの push

Docker や他のサードパーティ ツールを使用して Container Registry にローカル イメージを push するには、最初にレジストリ名でタグ付けしてからイメージを push する必要があります。

大きな画像のアップロードは、次の要因の影響を受ける可能性があります。

アップロード時刻
Container Registry に送信するリクエストには、2 時間のタイムアウト制限があります。アクセス トークンを使用して Container Registry を認証すると、トークンは 60 分後に期限切れになります。アップロード時間が 60 分を超える場合は、別の認証方法を使用してください。
画像サイズ
Container Registry は、各レジストリの基盤となるストレージとして Cloud Storage を使用します。各レジストリに Cloud Storage の割り当てと上限が適用されます（ストレージ内のオブジェクトの最大サイズ 5 TB など）。
Container Registry では、Docker によるチャンクされたアップロードをサポートしていません。ツールの中には、チャンクされたアップロードか 1 回のモノリシック アップロードのいずれかを使用して、サイズの大きいイメージをアップロードできるものがあります。Container Registry にイメージを push するには、モノリシック アップロードを使用する必要があります。

必要な権限

イメージを push するには、次のいずれかの Cloud Storage のロールか、同じ権限を持つロールが必要です。

プロジェクト内のレジストリに最初のイメージを push する

ロール: Google Cloud プロジェクト レベルでのストレージ管理者（roles/storage.admin）。事前定義されたオーナーロールには、これらの権限が含まれています。

イメージをプロジェクト内のレジストリ ホスト（gcr.io など）に初めて push すると、Container Registry によってレジストリのストレージ バケットが作成されます。ストレージ管理者ロールには、ストレージ バケットの作成に必要な権限があります。

プロジェクトの既存のレジストリにイメージを push する

ロール: レジストリ ストレージ バケットに対する Storage レガシー バケット書き込み（roles/storage.legacyBucketWriter）。

このロールには、プロジェクト内の既存のレジストリ ホストのイメージを push および pull する権限があります。たとえば、プロジェクトに gcr.io レジストリのみが含まれている場合、Storage レガシー バケット書き込みロールを持つユーザーは、イメージを gcr.io に push できますが、asia.gcr.io にイメージを push することはできません。

レジストリに権限を付与する方法については、アクセス制御の構成をご覧ください。

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

イメージにタグを付けるには、次のようにします。

  1. Container Registry への認証が構成されていることを確認します。

  2. Container Registry 内のイメージの名前を判断します。

    1. ホスト名を選択します。ホストによって、イメージを保存する場所が指定されています。

      • gcr.io は米国内のデータセンターでイメージをホストしていますが、今後は場所が変更される可能性があります。
      • us.gcr.io は米国内のデータセンターでイメージをホストしていますが、gcr.io によってホストされるイメージからは独立したストレージ バケットです。
      • eu.gcr.io は、欧州連合でイメージをホストします。
      • asia.gcr.io は、アジアのデータセンターでイメージをホストします。

      これらの場所は、Cloud Storage ストレージ バケットのマルチリージョンに対応します。イメージを新しいホスト名でレジストリに push すると、Container Registry では、指定されたマルチリージョン内にストレージ バケットを作成します。このバケットは、レジストリの基盤となるストレージです。1 つのプロジェクト内では、ホスト名が同じであるすべてのレジストリが 1 つのストレージ バケットを共有します。

      イメージのホスト名は、Console で [場所] の下に表示されます。

    2. ローカルマシン上のイメージ名とは異なるターゲット イメージ名を選択します。たとえば、ローカル イメージは web-image と呼ばれる場合がありますが、Container Registry に web-site として保存することをおすすめします。

    3. ホスト名、Google Cloud コンソール プロジェクト ID、ターゲット イメージ名を結合します。

      HOSTNAME/PROJECT-ID/TARGET-IMAGE

      次に例を示します。

      • ホスト名: gcr.io
      • Google Cloud プロジェクト: my-project
      • ターゲット イメージ名: web-site

      ホスト名、プロジェクト、ターゲット イメージ名を組み合わせると、タグ付けに使用するフル イメージパスが得られます。

      gcr.io/my-project/web-site

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

  3. 前のステップで取得した名前でローカル イメージにタグを付けます。このバージョンのイメージにタグを付ける場合は、タグ名を含めます。

    docker tag SOURCE_IMAGE HOSTNAME/PROJECT-ID/TARGET-IMAGE:TAG

    次のように置き換えます。

    • SOURCE_IMAGE はローカル イメージ名またはイメージ ID です。
    • HOSTNAME は、ステップ 2 で選択したレジストリ ホストです。
    • PROJECT は、Google Cloud プロジェクト ID です。
    • TARGET-IMAGE は、Container Registry に保存されているイメージの名前です。
    • TAG は、このイメージ バージョンに関連付けるタグです。

    たとえば、次のコマンドは、Container Registry でタグ v1.5 でローカル イメージ web-image を gcr.io/my-project/web-site としてタグ付けします。

    docker tag web-image gcr.io/my-project/web-site:v1.5

    タグを指定しない場合、Docker はデフォルトの latest タグを追加します。latest はデフォルトのタグであるため、latest タグで最後にタグ付けされたイメージのバージョンを表し、必ずしもイメージの最新バージョンとは限りません。

Docker は、コマンドで指定したイメージ名とタグを使用してイメージをタグ付けします。

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

  1. Container Registry への認証が構成されていることを確認します。

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

    特定のタグの付いたイメージを push するには、次のコマンドを実行します。

    docker push HOSTNAME/PROJECT-ID/IMAGE:TAG

    :TAG を省略すると、Docker は latest でタグ付けされたイメージのバージョンを push します。

    たとえば、次のコマンドは、タグ v1.5 でイメージ gcr.io/my-project/web-site を push します。

    docker push gcr.io/my-project/web-site:v1.5

プロジェクトにまだ存在しないレジストリ ホストにイメージを push すると、Container Registry はレジストリ ホスト用のストレージ バケットを作成します。

push したイメージを表示するには、次のようにします。

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

  • gcloud container images list-tags を実行して、イメージタグと自動生成されたダイジェストを表示します。

    gcloud container images list-tags HOSTNAME/PROJECT-ID/IMAGE

    コマンドの出力は次のようになります。

    DIGEST        TAGS        TIMESTAMP
44bde...      test        2017-..-..

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

イメージを pull するには、レジストリ ストレージ バケットの Storage オブジェクト閲覧者か、同じ権限を持つロールが必要です。

Container Registry から pull するには、次のコマンドを使用します。

docker pull HOSTNAME/PROJECT-ID/IMAGE:TAG

または

docker pull HOSTNAME/PROJECT-ID/IMAGE@IMAGE_DIGEST

ここで

  • HOSTNAME は、Console で [場所] の下に表示されます。gcr.io、us.gcr.io、eu.gcr.io、asia.gcr.io の 4 つのうち、いずれかのオプションになります。
  • PROJECT-ID は、Google Cloud Console プロジェクト ID です。プロジェクト ID にコロン（:）が含まれている場合は、ドメインをスコープとするプロジェクトをご覧ください。
  • IMAGE は、Container Registry 内のイメージ名です。
  • TAG はイメージに適用されるタグです。レジストリでは、タグはイメージに固有です。
  • IMAGE_DIGEST は、イメージ コンテンツの sha256 ハッシュ値です。Google Cloud コンソールで、メタデータを表示する特定のイメージをクリックします。ダイジェストはイメージのダイジェストとして一覧表示されます。

特定のイメージの pull コマンドを取得するには:

  1. 特定のレジストリに移動するには、イメージの名前をクリックします。

  2. レジストリで、pull するイメージのバージョンの横にあるチェックボックスをオンにします。

  3. ページの上部にある [pull コマンドを表示] をクリックします。

  4. タグやダイジェストを使用してイメージを識別する pull コマンドをコピーします。

次のステップ