イメージの push(アップロード)と pull(ダウンロード)の 2 つは、Container Registry のタスクの中でも最も一般的なものです。このドキュメントでは、Docker でのイメージの push と pull について説明します。
Cloud Build を使用している場合、コンテナをビルドして Container Registry に push する方法については、Cloud Build のドキュメントをご覧ください。
イメージのリスト表示、タグ付け、削除の手順については、イメージの管理をご覧ください。
始める前に
以下の準備を行います。
レジストリの追加
プロジェクトには、次の Container Registry レジストリを追加できます。
ホスト名 | ストレージのロケーション |
---|---|
gcr.io |
米国のデータセンターにイメージを保存します。 |
asia.gcr.io |
アジアのデータセンターにイメージを保存します。 |
eu.gcr.io |
欧州連合の加盟国内のデータセンターにイメージを保存します。 |
us.gcr.io |
米国のデータセンターにイメージを保存します。 |
ホスト名に対する最初のイメージの push によって、対応する Cloud Storage のストレージ バケット内にレジストリの作成がトリガーされます。この最初の push を行うには、ストレージ バケットを作成するために、プロジェクト全体の権限が必要です。
一旦プロジェクトにレジストリ ホストができると、ストレージ バケットに対する権限を構成して、レジストリ内のイメージへのアクセスを制御できます。
レジストリを追加して権限を構成するには、次のようにします。
必要な権限があることを確認します。注: ストレージ管理者ロール(roles/storage.admin)、または同じ権限を持つカスタムロールまたは事前定義ロール。
プロジェクト レベルでストレージ管理者ロールを付与する手順については、IAM のドキュメントをご覧ください。
最初のイメージをホストに push します。たとえば、次のコマンドを実行します。
- Docker Hub から
busybox
イメージを pull する gcr.io
レジストリ ホストとプロジェクト IDmy-project
を含む Container Registry 内のターゲットパスでイメージにタグを付ける- レジストリへのイメージの push
docker pull busybox docker tag busybox gcr.io/my-project/busybox docker push gcr.io/my-project/busybox
- Docker Hub から
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 することはできません。
レジストリに権限を付与する方法については、アクセス制御の構成をご覧ください。
ローカル イメージにレジストリ名でタグ付けする
イメージにタグを付けるには、次のようにします。
- Container Registry への認証が構成されていることを確認します。
Container Registry 内のイメージの名前を判断します。
ホスト名を選択します。ホストによって、イメージを保存する場所が指定されています。
gcr.io
は米国内のデータセンターでイメージをホストしていますが、今後は場所が変更される可能性があります。us.gcr.io
は米国内のデータセンターでイメージをホストしていますが、gcr.io
によってホストされるイメージからは独立したストレージ バケットです。eu.gcr.io
は、欧州連合でイメージをホストします。asia.gcr.io
は、アジアのデータセンターでイメージをホストします。
これらの場所は、Cloud Storage ストレージ バケットのマルチリージョンに対応します。イメージを新しいホスト名でレジストリに push すると、Container Registry では、指定されたマルチリージョン内にストレージ バケットを作成します。このバケットは、レジストリの基盤となるストレージです。1 つのプロジェクト内では、ホスト名が同じであるすべてのレジストリが 1 つのストレージ バケットを共有します。
イメージのホスト名は、Console で [場所] の下に表示されます。
ローカルマシン上のイメージ名とは異なるターゲット イメージ名を選択します。たとえば、ローカル イメージは
web-image
と呼ばれる場合がありますが、Container Registry にweb-site
として保存することをおすすめします。ホスト名、Google Cloud コンソール プロジェクト ID、ターゲット イメージ名を結合します。
HOSTNAME/PROJECT-ID/TARGET-IMAGE
次に例を示します。
- ホスト名:
gcr.io
- Google Cloud プロジェクト:
my-project
- ターゲット イメージ名:
web-site
ホスト名、プロジェクト、ターゲット イメージ名を組み合わせると、タグ付けに使用するフル イメージパスが得られます。
gcr.io/my-project/web-site
プロジェクト ID にコロン(
:
)が含まれている場合は、ドメインをスコープとするプロジェクトをご覧ください。- ホスト名:
前の手順で取得した名前でローカル イメージにタグを付けます。このバージョンのイメージにタグを付ける場合は、タグ名を含めます。
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 する
Container Registry への認証が構成されていることを確認します。
タグ付きイメージを 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 コマンドを取得するには:
特定のレジストリに移動するには、イメージの名前をクリックします。
レジストリで、pull するイメージのバージョンの横にあるチェックボックスをオンにします。
ページの上部にある [pull コマンドを表示] をクリックします。
タグやダイジェストを使用してイメージを識別する pull コマンドをコピーします。
次のステップ
- タグの追加や削除、イメージの削除など、イメージの管理について学習する。
- アクセス制御の構成について学習する。
- Container Registry のコンポーネントと機能の詳細を読む。
- Compute Engine 上でコンテナを実行する場合、Compute Engine 上のコンテナについて学習する。