このページでは、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
は次の手順を順番に実行します。
ダウンロードした画像パッケージの圧縮 tar ファイル(
bmpackages_1.31.200-gke.59.tar.xz
など)をbmpackages_1.31.200-gke.59.tar
に解凍します。解凍した tar ファイルからすべてのイメージを
bmpackages_1.31.200-gke.59
というディレクトリに抽出します。指定された限定公開レジストリに各イメージ ファイルを 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 仕様にレジストリ ミラーを指定できます。
管理クラスタと同じレジストリ ミラーを使用するようにユーザー クラスタを構成する手順は次のとおりです。
管理クラスタ リソースの
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 ファイルのパス。
管理クラスタの
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 認証情報を更新するには、次のように操作します。
クラスタ構成ファイルで、pull 認証情報構成ファイルのエンドポイント、CA 証明書ファイル、パスを更新します。
次のコマンドを実行して、変更を適用します。
bmctl update cluster -c CLUSTER_NAME --kubeconfig=ADMIN_KUBECONFIG
次のように置き換えます。
CLUSTER_NAME
は、更新するクラスタの名前に置き換えます。ADMIN_KUBECONFIG
は、管理クラスタ構成ファイルのパスで置き換えます。
イメージがレジストリ ミラーから pull されていることを確認する
containerd
がローカル レジストリからイメージを pull しているかどうかは、次の手順で config.toml
ファイルの内容を調べることで判断できます。
ノードにログインして、次のファイル(
/etc/containerd/config.toml
)の内容を調べます。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