ユーザー クラスタを Controlplane V2 に移行する

このドキュメントでは、kubeception を使用してバージョン 1.29 のユーザー クラスタを Controlplane V2 に移行する方法について説明します。クラスタのバージョンが 1.30 以降の場合は、推奨機能へのクラスタの移行を計画するの説明に沿って操作することをおすすめします。

1.29: プレビュー
1.28: 利用不可

ユーザー クラスタ コントロール プレーンについて

Google Distributed Cloud バージョン 1.13 より前は、ユーザー クラスタのコントロール プレーンは管理クラスタ内の 1 つ以上のノードで実行されていました。この種類のコントロール プレーンは kubeception と呼ばれます。バージョン 1.13 では、新しいユーザー クラスタ用に Controlplane V2 が導入されました。Controlplane V2 が有効になっている場合、ユーザー クラスタのコントロール プレーンはユーザー クラスタ自体で実行されます。

Controlplane V2 には、次のメリットがあります。

  • 障害の分離。管理クラスタの障害は、ユーザー クラスタに影響しません。

  • 運用上の分離。管理クラスタのアップグレードでユーザー クラスタのダウンタイムは発生しません。

  • デプロイの分離。管理クラスタとユーザー クラスタを、異なる障害発生ドメインまたは地理的な場所に配置できます。たとえば、エッジ ロケーションのユーザー クラスタを、管理クラスタとは地理的に異なる場所に配置できます。

要件

ユーザー クラスタを Controlplane V2 に移行するには、ユーザー クラスタが次の要件を満たしている必要があります。

  • ユーザー クラスタはバージョン 1.29 以降である必要があります。管理クラスタとノードプールは、ユーザー クラスタより 1 つまたは 2 つ前のマイナー バージョンにする必要があります。必要に応じて、クラスタをアップグレードします。

  • ユーザー クラスタで Dataplane V2 が有効になっている必要があります。このフィールドは不変です。クラスタで Dataplane V2 が有効になっていない場合、Controlplane V2 に移行することはできません。

  • ユーザー クラスタは、MetalLB または手動ロードバランサを使用するように構成する必要があります。ユーザー クラスタで SeeSaw ロードバランサを使用している場合は、MetalLB に移行できます。

  • IP アドレス計画のドキュメントを確認し、ユーザー クラスタのコントロール プレーン ノードに十分な IP アドレスがあることを確認します。コントロール プレーン ノードには静的 IP アドレスが必要です。新しいコントロール プレーン仮想 IP（VIP）には追加の IP アドレスが必要になります。

移行を準備する

ユーザー クラスタで Secret の常時暗号化が有効になっている場合は、移行を開始する前に、Secret の常時暗号化を無効にして Secret を復号するの手順に沿って操作する必要があります。そうしないと、新しい Controlplane V2 クラスタは Secret を復号できません。

移行を開始する前に、次のコマンドを実行して、Secret の常時暗号化が有効になったことがあるかどうかを確認します。

kubectl --kubeconfig ADMIN_CLUSTER_KUBECONFIG \
  get onpremusercluster USER_CLUSTER_NAME \
  -n USER_CLUSTER_NAME-gke-onprem-mgmt \
  -o jsonpath={.spec.secretsEncryption}

前のコマンドの出力が空の場合、Secret の常時暗号化は有効になっていないため、移行を開始できます。

前述のコマンドの出力が空でない場合、Secret の常時暗号化が以前に有効にされていました。移行する前に、次のセクションの手順に沿って、新しい Controlplane V2 クラスタが Secret を復号できるようにする必要があります。

次の例は、空でない出力を示しています。

{"generatedKeyVersions":{"keyVersions":[1]}}

必要に応じて、Secret の常時暗号化を無効にして Secret を復号する

Secret の常時暗号化を無効にして Secret を復号するには、次の操作を行います。

  1. ユーザー クラスタの構成ファイルで、Secret の常時暗号化を無効にするには、secretsEncryption セクションに disabled: true フィールドを追加します。

    secretsEncryption:
    mode: GeneratedKey
    generatedKey:
        keyVersion: KEY_VERSION
        disabled: true

  2. クラスタを更新します。

    gkectl update cluster --kubeconfig ADMIN_CLUSTER_KUBECONFIG \
    --config USER_CLUSTER_CONFIG

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

    • ADMIN_CLUSTER_KUBECONFIG: 管理クラスタの kubeconfig ファイルのパス
    • USER_CLUSTER_CONFIG: ユーザー クラスタの構成ファイルのパス

  3. 次のように、特定の DaemonSet でローリング アップデートを行います。

    kubectl --kubeconfig ADMIN_CLUSTER_KUBECONFIG \
  rollout restart statefulsets kube-apiserver \
  -n USER_CLUSTER_NAME

  4. ユーザー クラスタ内のすべての Secret のマニフェストを YAML 形式で取得します。

    kubectl --kubeconfig USER_CLUSTER_KUBECONFIG \
  get secrets -A -o yaml > SECRETS_MANIFEST.yaml

  5. すべての Secret が平文として etcd に保存されるように、ユーザー クラスタ内のすべての Secret を再適用します。

    kubectl --kubeconfig USER_CLUSTER_KUBECONFIG \
  apply -f SECRETS_MANIFEST.yaml

    これで、Controlplane V2 への移行を開始できます。移行が完了したら、クラスタで Secret の常時暗号化を有効にできます。

構成ミスのあるワークロード Webhook を修正する

kube-system Namespace にシステム Pod を含む Webhook がある場合は、namespaceSelector を追加して kube-system Namespace を除外します。

たとえば、次のようにします。

  namespaceSelector:
    matchExpressions:
    - key: kubernetes.io/metadata.name
      operator: NotIn
      values:
      - kube-system

ユーザー クラスタの構成ファイルを更新する

ユーザー クラスタ構成ファイルを次のように変更します。

  1. enableControlplaneV2 を true に設定します。

  2. 必要に応じて、Controlplane V2 ユーザー クラスタのコントロール プレーンを高可用性（HA）にします。非 HA クラスタから HA クラスタに変更するには、masterNode.replicas を 1 から 3 に変更します。

  3. ユーザー クラスタ コントロール プレーン ノードの静的 IP アドレスを network.controlPlaneIPBlock.ips セクションに追加します。コントロール プレーン ノードの IP アドレスは、ワーカーノードと同じ VLAN に存在する必要があります。ホスト名は必須です。

  4. network.controlPlaneIPBlock セクションにネットマスクとゲートウェイを入力します。

  5. network.hostConfig セクションが空白の場合は、入力します。

  6. ユーザー クラスタで手動ロード バランシングを使用する場合は、次のセクションで説明するようにロードバランサを構成します。

  7. ユーザー クラスタで手動ロード バランシングを使用している場合は、loadBalancer.manualLB.controlPlaneNodePort と loadBalancer.manualLB.konnectivityServerNodePort を 0 に設定します。Controlplane V2 が有効になっているときに、この機能は必要ありません。

  8. loadBalancer.vips.controlPlaneVIP フィールドを更新して、コントロール プレーン VIP の新しい IP アドレスを指定します。コントロール プレーン ノードの IP アドレスと同じ VLAN に存在する必要があります。

  9. 移行のためにクラスタを更新する場合を除き、以前のフィールドはすべて不変です。すべての設定を再度確認してください。

  10. gkectl diagnose cluster を実行し、コマンドで検出された問題を修正します。

    gkectl diagnose cluster --kubeconfig=ADMIN_CLUSTER_KUBECONFIG \
      --cluster-name=USER_CLUSTER_NAME

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

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

    • USER_CLUSTER_NAME : ユーザー クラスタの名前。

手動ロードバランサの構成を調整する

ユーザー クラスタで手動ロード バランシングを使用している場合は、このセクションで説明する操作を行います。それ以外の場合は、このセクションをスキップします。

CPv2 ユーザー クラスタのロードバランサの構成と同様に、ロードバランサで、network.controlPlaneIPBlock セクションで指定した 3 つの新しいコントロール プレーン ノード IP アドレスのマッピングを構成します。

  • (ingressVIP:80) -> (NEW_NODE_IP_ADDRESS:ingressHTTPNodePort)
  • (ingressVIP:443) -> (NEW_NODE_IP_ADDRESS:ingressHTTPNodePort)

クラスタを更新する

次のコマンドを実行して、クラスタを Controlplane V2 に移行します。

gkectl update cluster \
    --kubeconfig ADMIN_CLUSTER_KUBECONFIG \
    --config USER_CLUSTER_CONFIG

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

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

  • USER_CLUSTER_CONFIG: ユーザー クラスタの構成ファイルのパス

このコマンドは、次のことを行います。

  1. ControlPlane V2 を有効にして、新しいクラスタのコントロール プレーンを作成します。

  2. kubeception クラスタの Kubernetes コントロール プレーンを停止します。

  3. kubeception クラスタの etcd スナップショットを作成します。

  4. kubeception クラスタのユーザー クラスタ コントロール プレーン ノードをオフにします。障害復旧（Kubeception クラスタへのフォールバック）のため、移行が完了するまでノードは削除されません。

  5. 前述の etcd スナップショットを使用して、新しいコントロール プレーンでクラスタデータを復元します。

  6. kubeception クラスタのノードプール ノードを新しいコントロール プレーンに接続します。新しい controlPlaneVIP を使用してアクセスできます。

  7. 復元されたユーザー クラスタを調整して、ControlPlane V2 が有効になっているクラスタの最終状態を満たします。

注

  • 移行中、ユーザー クラスタのワークロードはダウンタイムなしで実行されます。

  • 移行中、ユーザー クラスタのコントロール プレーンでダウンタイムが発生します。具体的には、ステップ 2 からステップ 6 の完了まで、コントロール プレーンは使用できません（Google のテストではダウンタイムは 7 分未満ですが、実際の長さはインフラストラクチャによって異なります）。

  • 移行が完了すると、kubeception クラスタのユーザー クラスタ コントロール プレーン ノードが削除されます。管理クラスタで network.ipMode.type が static に設定されている場合、管理クラスタの構成ファイルから未使用の静的 IP を削除して gkectl update admin を実行すると、未使用の静的 IP の一部をリサイクルできます。kubectl get nodes -o wide を使用して管理クラスタ ノード オブジェクトを一覧取得し、使用中の IP を確認できます。

  • 移行後も古いコントロール プレーン VIP アドレスは機能しますが、不安定です。これに依存しないでください。古い VIP アドレスの依存関係を更新して、できるだけ早く新しい VIP アドレスを使用するようにします。

移行後

移行前に Secret の常時暗号化を無効にした場合は、次の手順でこの機能を再度有効にします。

  1. ユーザー クラスタの構成ファイルで、secretsEncryption.generatedKey.disabled を false に設定します。例:

    secretsEncryption:
    mode: GeneratedKey
    generatedKey:
        keyVersion: KEY_VERSION
        disabled: false

  2. ユーザー クラスタを更新します。

    gkectl update cluster --kubeconfig ADMIN_CLUSTER_KUBECONFIG \
    --config USER_CLUSTER_CONFIG