コンテナ イメージにレジストリ ミラーを使用する

このページでは、gcr.io などの一般公開レジストリからではなく、レジストリ ミラーから pull されたイメージを使用してクラスタを作成およびアップグレードする方法について説明します。この機能は、クラスタのライフサイクルの任意の時点で有効または無効にできます。

このページは、ストレージのパフォーマンス、使用状況、費用を構成および管理するオペレーターとストレージ スペシャリストを対象としています。コンテンツで参照する一般的なロールとタスク例の詳細については、一般的な GKE Enterprise ユーザーロールとタスクをご覧ください。 Google Cloud

レジストリ ミラーは、一般公開レジストリのファイル構造をコピーまたはミラーリングする公開レジストリのローカルコピーです。たとえば、ローカル レジストリ ミラーのパスが 172.18.0.20:5000 であるとします。containerd が gcr.io/kubernetes-e2e-test-images/nautilus:1.0 のようなイメージを pull するリクエストを受信すると、containerd は gcr.io ではなくパス: 172.18.0.20:5000/kubernetes-e2e-test-images/nautilus:1.0のローカル レジストリからイメージを pull しようとします。イメージがこのローカル レジストリ パスに存在しない場合は、イメージが gcr.io 一般公開レジストリから自動的に pull されます。

レジストリ ミラーを使用することには、次の利点があります。

  • 一般公開レジストリの停止から保護します。
  • Pod の作成を高速化できます。
  • 独自の脆弱性スキャンを実行できます。
  • レジストリへのコマンド発行頻度に関する一般公開レジストリによる制限を回避します。

始める前に

  • ネットワークに Container Registry サーバーが設定されている必要があります。
  • レジストリ サーバーでプライベート TLS 証明書を実行する場合は、認証局（CA）ファイルが必要です。
  • レジストリ サーバーで認証が必要な場合は、適切なログイン認証情報または Docker 構成ファイルが必要です。
  • Red Hat Quay レジストリを使用している場合は、ローカル レジストリのディレクトリ構造を手動で作成する必要があります。
  • レジストリ ミラーを使用するには、コンテナ ランタイムを containerd に設定する必要があります。
  • 管理ワークステーションに、画像のアップロードをサポートするのに十分なディスク容量があることを確認します。画像アップロード コマンド bmctl push images は、ダウンロードした画像パッケージ ファイルを解凍し、すべての画像ファイルをローカルに抽出してからアップロードします。画像のアップロードに対応するには、ダウンロードした画像パッケージ ファイルのサイズの 3 倍以上のディスク容量が必要です。たとえば、圧縮された bmpackages_1.31.200-gke.59.tar.xz ファイルは約 8.5 GB のディスク容量を使用するため、ファイルをダウンロードする前に 25.5 GB 以上の空きディスク容量が必要です。

Google Distributed Cloud に必要なすべてのイメージをダウンロードする

[ダウンロード] ページから、bmctl ツールとイメージ パッケージの最新バージョンをダウンロードします。

コンテナ イメージをレジストリ サーバーにアップロードする

bmctl push images を使用してコンテナ イメージをリポジトリ サーバーにアップロードすると、bmctl は次の手順を順番に実行します。

  1. ダウンロードした画像パッケージの圧縮 tar ファイル（bmpackages_1.31.200-gke.59.tar.xz など）を bmpackages_1.31.200-gke.59.tar に解凍します。

  2. 解凍した tar ファイルからすべてのイメージを bmpackages_1.31.200-gke.59 というディレクトリに抽出します。

  3. 指定された限定公開レジストリに各イメージ ファイルを push します。

    bmctl は、基本認証に --username と --password の値を使用して、イメージを非公開レジストリに push します。

以降のセクションでは、リポジトリ サーバーにイメージをアップロードする bmctl push images コマンドの一般的なバリエーションをいくつか示します。

レジストリで認証し、TLS 証明書を共有する

次のコマンドには、レジストリ サーバーでのユーザー認証用の --username フラグと --password フラグが含まれています。このコマンドには、CA トランスポート レイヤ セキュリティ（TLS）証明書を渡す --cacert フラグも含まれています。この証明書は、イメージの push や pull など、レジストリ サーバー間の安全な通信に使用されます。これらのフラグは、レジストリ サーバーの基本的なセキュリティを提供します。

レジストリ サーバーで認証が必要な場合、--username フラグと --password フラグを使用しない場合は、bmctl push images の実行時に認証情報が求められます。パスワードを入力するか、認証情報を含む Docker 構成ファイルを選択します。

認証とプライベート CA 証明書を使用してイメージをアップロードするには、次のようなコマンドを使用します。

bmctl push images \
    --source IMAGES_TAR_FILE_PATH \
    --private-registry REGISTRY_IP:PORT \
    --username USERNAME \
    --password PASSWORD \
    --cacert CERT_PATH

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

  • IMAGES_TAR_FILE_PATH: ダウンロードしたイメージ パッケージ tar ファイルのパス（bmpackages_1.31.200-gke.59.tar.xz など）。

  • REGISTRY_IP:PORT: 限定公開レジストリ サーバーの IP アドレスとポート。

  • USERNAME: レジストリ サーバーにイメージをアップロードするアクセス権を持つユーザーのユーザー名。

  • PASSWORD: レジストリ サーバーで認証するためのユーザーのパスワード。

  • CERT_PATH: CA 証明書ファイルのパス（レジストリ サーバーがプライベート TLS 証明書を使用している場合）。

次に例を示します。

bmctl push images \
    --source bmpackages_1.31.200-gke.59.tar.xz \
    --private-registry 172.18.0.20:5000 \
    --username alex --password pa55w0rd \
    --cacert /etc/pki/tls/certs/ca-bundle.crt

ユーザー認証や証明書なしで画像をアップロードする

レジストリ サーバーでユーザー名やパスワードなどの認証情報が不要な場合は、bmctl コマンドで --need-credential=false を指定します。レジストリ サーバーが公開 TLS 証明書を使用している場合は、--cacert フラグを使用する必要はありません。このタイプのアップロード コマンドは、本番環境よりもセキュリティの懸念が少ないテスト環境に最適です。

認証やプライベート CA 証明書なしでイメージをアップロードするには、次のコマンドを使用します。

bmctl push images \
    --source IMAGES_TAR_FILE_PATH \
    --private-registry REGISTRY_IP:PORT \
    --need-credential=false

次に例を示します。

bmctl push images \
    --source bmpackages_1.31.200-gke.59.tar.xz \
    --private-registry 172.18.0.20:5000 \
    --need-credential=false.

スレッド数を調整する

画像パッケージ tar ファイル内のコンテナ イメージのサイズと数により、画像アップロード ルーティンに時間がかかる場合があります。並列スレッドの数を増やすと、ルーティンの実行速度が向上します。--threads フラグを使用すると、bmctl push images で使用する並列スレッドの数を変更できます。

デフォルトでは、画像アップロード ルーティンは 4 つのスレッドを使用します。画像のアップロードに時間がかかりすぎる場合は、この値を増やしてください。ベンチマークとして、Google のテスト環境では、4 つの CPU を搭載したワークステーションからイメージをアップロードする場合、8 つの並列スレッドで約 10 分かかります。

bmctl push images \
    --source IMAGES_TAR_FILE_PATH \
    --private-registry REGISTRY_IP:PORT \
    --cacert CERT_PATH \
    --threads NUM_THREADS

NUM_THREADS は、画像アップロードの処理に使用する並列スレッドの数に置き換えます。デフォルトでは、bmctl push images は 4 つの並列スレッドを使用します。

次のコマンドは、アップロードのスレッド数を 4 から 8 に増やして、アップロード時間を短縮します。

bmctl push images \
    --source bmpackages_1.31.200-gke.59.tar.xz \
    --private-registry 172.18.0.20:5000 \
    --cacert ~/cert.pem \
    --threads 8

プロキシ経由でアップロードする

ワークステーションからレジストリ サーバーにイメージをアップロードするためにプロキシが必要な場合は、bmctl コマンドの前にプロキシの詳細を追加できます。

HTTPS_PROXY=http://PROXY_IP:PORT bmctl push images \
    --source=IMAGES_TAR_FILE_PATH \
    --private-registry=REGISTRY_IP:PORT \
    --cacert=CERT_PATH

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

  • PROXY_IP:PORT: プロキシの IP アドレスとポート。

  • IMAGES_TAR_FILE_PATH: ダウンロードしたイメージ パッケージ tar ファイルのパス（bmpackages_1.31.200-gke.59.tar.xz など）。

  • REGISTRY_IP:PORT: 限定公開レジストリ サーバーの IP アドレスとポート。

  • CERT_PATH: CA 証明書ファイルのパス（レジストリ サーバーがプライベート TLS 証明書を使用している場合）。

プロンプトが表示されたら、ユーザー名とパスワードを入力するか、Docker 構成ファイルを選択します。

次のコマンドは、プロキシ経由で画像をアップロードします。

HTTPS_PROXY=http://10.128.0.136:3128 bmctl push images \
    --source bmpackages_1.31.200-gke.59.tar.xz \
    --private-registry 172.18.0.20:5000 \
    --cacert ~/cert.pem

bmctl push images で独自の名前空間を使用する

レジストリ サーバーでルート名前空間ではなく独自の名前空間を使用する必要がある場合は、限定公開レジストリの API エンドポイントをクラスタ構成ファイルの registryMirrors.endpoint フィールドに指定すると、containerd がこの名前空間から pull できるようになります。エンドポイントは通常、<REGISTRY_IP:PORT>/v2/<NAMESPACE> の形式になります。詳細については、非公開レジストリのユーザーガイドをご覧ください。詳細については、レジストリ エンドポイントでの v2 の使用についてをご覧ください。

bmctl push images \
    --source=IMAGES_TAR_FILE_PATH \
    --private-registry=REGISTRY_IP:PORT/NAMESPACE \
    --cacert=CERT_PATH

NAMESPACE は、イメージをアップロードするレジストリ サーバー内の Namespace の名前に置き換えます。

たとえば、198.51.20:5000/test-namespace/ へのアクセス権のみを付与されている場合は、次のようなコマンドを使用して、test-namespace 名前空間の下にあるすべての画像をアップロードできます。

bmctl push images \
    --source=./bmpackages_1.31.200-gke.59.tar.xz \
    --private-registry=198.51.20:5000/test-namespace \
    --username=alex \
    --password=pa55w0rd \
    --cacert /etc/pki/tls/certs/ca-bundle.crt

次に、クラスタ構成ファイルに次のように追加して、containerd が test-namespace 名前空間から pull するように設定できます。

registryMirrors:
  - endpoint: https://198.51.20:5000/v2/test-namespace

bmctl push images コマンドの詳細については、bmctl コマンド リファレンスをご覧ください。

レジストリ ミラーを使用するようにクラスタを構成する

クラスタのレジストリ ミラーは、クラスタの作成時、または既存のクラスタを更新するたびに構成できます。使用する構成方法は、クラスタタイプと、ユーザー クラスタの場合はクラスタの作成とクラスタの更新のどちらを行うかによって異なります。以降の 2 つのセクションでは、レジストリ ミラーの構成に使用できる 2 つの方法について説明します。

クラスタ構成ファイルのヘッダー セクションを使用する

Google Distributed Cloud では、クラスタ構成ファイルのヘッダー セクションで、クラスタ仕様の外部にレジストリ ミラーを指定できます。

  • 管理クラスタ、ハイブリッド クラスタ、スタンドアロン クラスタの場合、レジストリ ミラーを構成する唯一の方法は、クラスタ構成ファイルのヘッダー セクションを使用することです。この方法は、クラスタの作成またはクラスタの更新に適用されます。

  • ユーザー クラスタの場合、この方法はクラスタの作成時にのみレジストリ ミラーを構成するために使用できます。既存のユーザー クラスタにレジストリ ミラーを構成するには、Cluster 仕様の nodeConfig.registryMirrors セクションを使用します。

次のサンプル クラスタの構成ファイルでは、エンドポイントが https://198.51.20:5000 のローカル レジストリ ミラーからイメージを pull するように指定されています。以降のセクションでは、この構成ファイルの最初に表示されるフィールドの一部について説明します。

# Sample cluster config with registry mirror:
---
gcrKeyPath: /bmctl/bmctl-workspace/.sa-keys/my-gcp-project-anthos-baremetal-gcr.json
sshPrivateKeyPath: /root/ssh-key/id_rsa
registryMirrors:
  - endpoint: https://198.51.20:5000
    caCertPath: /root/ca.crt
    pullCredentialConfigPath: /root/.docker/config.json
    hosts:
      - somehost.io
      - otherhost.io
---
apiVersion: v1
kind: Namespace
metadata:
  name: cluster-admin1
---
apiVersion: baremetal.cluster.gke.io/v1
kind: Cluster
metadata:
  name: admin1
  namespace: cluster-admin1
spec:
  nodeConfig:
    containerRuntime: containerd
...

Cluster 仕様の nodeConfig.registryMirrors セクションを使用する

レジストリ ミラーを作成または更新するこの方法は、ユーザー クラスタにのみ適用されます。管理クラスタ用に作成された Secret をユーザー クラスタと共有できるため、管理している管理クラスタまたはハイブリッド クラスタの nodeConfig.registryMirrors を使用して、ユーザー クラスタの Cluster 仕様にレジストリ ミラーを指定できます。

管理クラスタと同じレジストリ ミラーを使用するようにユーザー クラスタを構成する手順は次のとおりです。

  1. 管理クラスタ リソースの nodeConfig.registryMirrors から、Secret 参照を含む nodeConfig.registryMirror セクションを取得します。

    kubectl get cluster CLUSTER_NAME -n CLUSTER_NAMESPACE \
    --kubeconfig ADMIN_KUBECONFIG \
    -o yaml

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

    • CLUSTER_NAME: ユーザー クラスタを管理する管理クラスタまたはハイブリッド クラスタの名前。

    • CLUSTER_NAMESPACE: 管理クラスタの名前空間名。

    • ADMIN_KUBECONFIG: 管理クラスタの kubeconfig ファイルのパス。

  2. 管理クラスタの nodeConfig.registryMirrors 構成をユーザー クラスタのクラスタ構成ファイルに追加します。

    ユーザー クラスタ構成ファイルの registryMirrors セクションは、次の例のようになります。

    ---
gcrKeyPath: /bmctl/bmctl-workspace/.sa-keys/my-gcp-project-anthos-baremetal-gcr.json
sshPrivateKeyPath: /root/ssh-key/id_rsa
---
apiVersion: v1
kind: Namespace
metadata:
  name: cluster-user1
---
apiVersion: baremetal.cluster.gke.io/v1
kind: Cluster
metadata:
  name: user1
  namespace: cluster-user1
spec:
  nodeConfig:
    containerRuntime: containerd
    registryMirrors:
    -   caCertSecretRef:
        name: the-secret-created-for-the-admin-cluster
        namespace: anthos-creds
      endpoint: https://172.18.0.20:5000
      hosts:
        -   somehost.io
        -   otherhost.io
      pullCredentialSecretRef:
        name: the-image-pull-creds-created-for-the-admin-cluster
        namespace: anthos-creds
...

ユーザー クラスタのレジストリ ミラー構成に後で変更を加える場合は、ユーザー クラスタ構成ファイルの nodeConfig.registryMirrors を編集し、bmctl update で変更を適用します。

クラスタ構成ファイルのヘッダー セクションを使用して、ユーザー クラスタのレジストリ ミラー構成を更新することはできません。

hosts フィールド

containerd は、クラスタ構成ファイルの hosts セクションを確認して、ローカルにミラーリングされているホストを特定します。これらのホストは、クラスタ構成ファイル（registryMirror.endpoint）で指定されたレジストリ ミラー エンドポイントにマッピングされます。前のセクションの構成ファイルの例では、hosts セクションにリストされている一般公開レジストリは somehost.io と otherhost.io です。これらの一般公開レジストリは hosts セクションに表示されるため、containerd は somehost.io または otherhost.io からのイメージの pull リクエストを検出すると、まず非公開レジストリ ミラーを確認します。

たとえば、containerd が somehost.io/kubernetes-e2e-test-images/nautilus:1.0 への pull コマンドを受信するとします。somehost.io はクラスタ構成ファイルの hosts セクションにホストの 1 つとしてリストされているため、containerd は kubernetes-e2e-test-images/nautilus:1.0 イメージのローカル レジストリ ミラーを検索します。somehost.io が hosts セクションにない場合、containerd は somehost.io のローカルミラーが存在することを認識しません。その場合、containerd はイメージのミラーを確認せず、somehost.io 一般公開レジストリからイメージを pull します。

デフォルトでは、Google Distributed Cloud は自動的に gcr.io のイメージをミラーリングするため、hosts セクションにホストとして gcr.io を一覧取得する必要はありません。

hosts 値と endpoint 値が重複しないようにしてください。たとえば、次の構成サンプルは、エンドポイント値のドメイン部分と一致するホスト europe-docker.pkg.dev を示しています。この場合、hosts 値を指定する必要はありません。

...
registryMirrors:
  ...
  endpoint: https://europe-docker.pkg.dev:5000/v2/cloud-data-fusion-images
  hosts:
    - europe-docker.pkg.dev
    ...

gcrKeyPath フィールド

Google Distributed Cloud で Container Registry（gcr.io）を自動的に使用して、ローカル レジストリに表示されないイメージを pull する場合は、Container Registry サービス アカウント キーへのパスを指定する必要があります。Google Distributed Cloud には、他の一般公開レジストリに鍵を提供するためのメカニズムはありません。

イメージがローカル レジストリにない場合に、イメージを gcr.io から pull する機能を使用する予定がない場合は、gcrKeyPath をクラスタ構成ファイルに追加する必要はありません。

caCertPath フィールド

レジストリでプライベート トランスポート層セキュリティ（TLS）証明書が必要な場合、このフィールドにはサーバーのルート CA 証明書ファイルへのパスが入ります。この証明書ファイルは、bmctl コマンドを実行するマシンの管理ワークステーション上にある必要があります。レジストリでプライベート TLS 証明書が不要な場合は、caCertPath フィールドを空白のままにできます。

pullCredentialConfigPath フィールド

レジストリ サーバーで認証 Docker 構成ファイルが不要な場合は、pullCredentialConfigPath フィールドを空白のままにできます。これは、bmctl コマンドを実行しているマシン上の構成ファイルのパスです。

ユーザー クラスタでレジストリ ミラーを使用する

管理クラスタが行うように構成されている場合、ユーザー クラスタはレジストリ ミラーからイメージを自動的に pull しません。ユーザー クラスタがレジストリ ミラーから pull するように設定するには、レジストリ ミラーを使用するようにクラスタを構成するの説明に沿って、個別に構成する必要があります。

レジストリ ミラー エンドポイント、証明書、pull 認証情報を更新する

レジストリ ミラー エンドポイント、証明書、または pull 認証情報を更新するには、次のように操作します。

  1. クラスタ構成ファイルで、pull 認証情報構成ファイルのエンドポイント、CA 証明書ファイル、パスを更新します。

  2. 次のコマンドを実行して、変更を適用します。

    bmctl update cluster -c CLUSTER_NAME --kubeconfig=ADMIN_KUBECONFIG

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

    • CLUSTER_NAME は、更新するクラスタの名前に置き換えます。

    • ADMIN_KUBECONFIG は、管理クラスタ構成ファイルのパスで置き換えます。

イメージがレジストリ ミラーから pull されていることを確認する

containerd がローカル レジストリからイメージを pull しているかどうかは、次の手順で config.toml ファイルの内容を調べることで判断できます。

  1. ノードにログインして、次のファイル（/etc/containerd/config.toml）の内容を調べます。

  2. config.toml ファイルの plugins."io.containerd.grpc.v1.cri".registry.mirrors セクションを確認して、レジストリ サーバーが endpoint フィールドにリストされているかどうかを確認します。endpoint ファイルが太字で表示されている config.toml ファイルの例からの抜粋を次に示します。

    version = 2
root = "/var/lib/containerd"
state = "/run/containerd"
...
[plugins."io.containerd.grpc.v1.cri".registry]
  [plugins."io.containerd.grpc.v1.cri".registry.configs]
    [plugins."io.containerd.grpc.v1.cri".registry.configs."gcr.io"]
      [plugins."io.containerd.grpc.v1.cri".registry.configs."privateregistry2.io".tls]
        ca_file = '/etc/containerd/certs.d/privateregistry2.io/ca.crt'
  [plugins."io.containerd.grpc.v1.cri".registry.mirrors]
    [plugins."io.containerd.grpc.v1.cri".registry.mirrors."gcr.io"]
      endpoint = ["http://privateregistry.io", "http://privateregistry2.io"]
...

    レジストリ ミラーが endpoint フィールドに表示される場合、ノードは一般公開レジストリではなくレジストリ ミラーからイメージを pull します。

レジストリ ミラーの設定に関するトラブルシューティング

コンテナ ランタイム インターフェース コマンドライン ツールである crictl を使用して、個々のイメージ ファイルをダウンロードしてレジストリ設定をテストできます。各イメージ ファイルには、意味のあるバージョン文字列が個別にタグ付けされます。たとえば、クラスタ API コントローラ イメージには Google Distributed Cloud リリース バージョンのタグが付けられ、etcd イメージには対応する etcd バージョンのタグが付けられます。

ベアメタル向け Google Distributed Cloud のバージョン 1.31.200-gke.59 リリースでは、クラスタ API コントローラ イメージ cluster-api-controller と etcd イメージ etcd には次のタグが付いています。

  • cluster-api-controller:1.31.200-gke.59
  • etcd:v3.4.30-0-gke.1

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

レジストリ ミラーで名前空間を使用していない場合は、次のコマンドを使用してイメージを pull します。

crictl pull REGISTRY_IP:PORT/IMAGE_PATH:IMAGE_TAG

名前空間を使用するレジストリ ミラーからイメージを pull する

レジストリ ミラーが Namespace を使用している場合は、次のコマンドを使用してイメージを pull します。

crictl pull REGISTRY_IP:PORT/NAMESPACE/IMAGE_PATH:IMAGE_TAG

レジストリ エンドポイントでの v2 の使用について

レジストリでカスタム Namespace を使用する場合は、クラスタ構成ファイルのレジストリ エンドポイント（registryMirror.endpoint）の Namespace の前に v2/ を追加する必要があります。Namespace を使用していない場合は、v2 を使用しないでください。どちらの場合も、--private-registry フラグの値やイメージ pull コマンドで v2 を使用しないでください。

Namespace なし

  • 有効:
    • endpoint: https://172.18.0.20:5000
    • crictl pull 172.18.0.20:5000/anthos-baremetal-release/etcd:v3.4.30-0-gke.1
  • 無効:
    • endpoint: https://172.18.0.20:5000/v2
    • crictl pull 172.18.0.20:5000/v2/anthos-baremetal-release/etcd:v3.4.30-0-gke.1

Namespace を使用する

  • 有効:
    • endpoint: https://172.18.0.21:5000/v2/namespace
    • crictl 172.18.0.21:5000/namespace/anthos-baremetal-release/etcd:v3.4.30-0-gke.1
  • 無効:
    • endpoint: https://172.18.0.21:5000/namespace
    • crictl pull 172.18.0.21:5000/v2/namespace/anthos-baremetal-release/etcd:v3.4.30-0-gke.1