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

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

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

レジストリ ミラーは、一般公開レジストリのファイル構造をコピーまたはミラーリングする公開レジストリのローカルコピーです。たとえば、ローカル レジストリ ミラーのパスが 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 の作成を高速化できます。
• 独自の脆弱性スキャンを実行できます。
• レジストリへのコマンド発行頻度に関する一般公開レジストリによる制限を回避します。

注: gcr.io/anthos-baremetal-release/kindest/node の画像の pull は gcr.io にフォールバックしません。これらのイメージは、レジストリ ミラーからのみ pull されます。レジストリ ミラーが機能しない場合、pull は失敗します。

始める前に

• ネットワークに Container Registry サーバーが設定されている必要があります。
• レジストリ サーバーでプライベート TLS 証明書を実行する場合は、認証局（CA）ファイルが必要です。
• レジストリ サーバーで認証が必要な場合は、適切なログイン認証情報または Docker 構成ファイルが必要です。
• レジストリ ミラーを使用するには、コンテナ ランタイムを containerd に設定する必要があります。

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

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

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

次のコマンドを実行して、イメージをイメージ パッケージからレジストリ サーバーにアップロードします。

[HTTPS_PROXY=http://PROXY_IP:PORT] ./bmctl push images \
    --source=./bmpackages_VERSION.tar.xz \
    --private-registry=REGISTRY_IP:PORT \
    [--cacert=CERT_PATH] \
    [--need-credential=false]

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

• ワークステーションからレジストリ サーバーにイメージをアップロードするためにプロキシが必要な場合は、PROXY_IP:PORT をプロキシの IP アドレスとポートに置き換えます。
• VERSION は、ダウンロード ページからダウンロードしたイメージ パッケージのバージョンに置き換えます。
• REGISTRY_IP:PORT は、プライベート レジストリ サーバーの IP アドレスとポートに置き換えます。
• レジストリ サーバーがプライベート TLS 証明書を使用している場合は、CERT_PATH を CA 証明書ファイルのパスに置き換えます。

プロンプトが表示されたら、ユーザー名とパスワードを入力するか、Docker 構成ファイルを選択します。レジストリ サーバーで認証情報が必要ない場合は、--need-credential=false を指定します。

bmctl push images コマンドについて詳しくは、以下を実行してください。

bmctl push images --help

独自の名前空間を使用する

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

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

./bmctl push images \
    --source=./bmpackages_VERSION.tar.xz \
    --private-registry=172.18.0.20:5000/test-namespace \
    --username=<USERNAME> \
    --password=<PASSWORD> \
    --cacert <path/to/cert.crt>

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

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

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

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

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

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

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

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

次のサンプル クラスタの構成ファイルでは、エンドポイントが https://172.18.0.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://172.18.0.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_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 セクションを確認して、ローカルにミラーリングされているホストを特定します。構成ファイルの例では、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 を一覧取得する必要はありません。

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 します。