將使用者叢集遷移至 Controlplane V2

本文說明如何使用 kubeception 將 1.29 版使用者叢集遷移至 Controlplane V2。如果叢集版本為 1.30 以上，建議按照「規劃叢集遷移至建議功能」一文中的操作說明進行。

1.29：預先發布版
1.28：不適用

關於使用者叢集控制層

在 Google Distributed Cloud 1.13 版之前，使用者叢集的控制層會在管理員叢集的一或多個節點上執行。這類控制層稱為 kubeception。在 1.13 版中，我們為新的使用者叢集導入了 Controlplane V2。啟用 Controlplane V2 後，使用者叢集的控制層會在使用者叢集本身執行。

Controlplane V2 的優點包括：

  • 故障隔離。管理員叢集發生故障時，使用者叢集不會受到影響。

  • 營運分離。升級管理員叢集不會導致使用者叢集停機。

  • 部署作業分離。您可以將管理員和使用者叢集放在不同的故障網域或地理位置。舉例來說，邊緣位置的使用者叢集可以與管理員叢集位於不同的地理位置。

需求條件

如要將使用者叢集遷移至 Controlplane V2，使用者叢集必須符合下列條件：

  • 使用者叢集必須為 1.29 以上版本。管理員叢集和節點集區的版本可比使用者叢集低一或兩個子版本。如有需要，請升級叢集。

  • 使用者叢集必須啟用 Dataplane V2。這個欄位無法變更，因此如果叢集未啟用 Dataplane V2，就無法遷移至 Controlplane V2。

  • 使用者叢集必須設定為使用 MetalLB 或手動負載平衡器。如果使用者叢集使用 SeeSaw 負載平衡器，可以遷移至 MetalLB。

  • 請參閱IP 位址規劃文件，確保您有足夠的 IP 位址供使用者叢集的控制層節點使用。控制層節點需要靜態 IP 位址，您還需要額外的 IP 位址，做為新的控制層虛擬 IP (VIP)。

為遷移作業做好準備

如果使用者叢集曾啟用「永久密碼加密」，您必須先按照「停用永久密碼加密並解密密碼」一文中的步驟操作，才能開始遷移作業。否則，新的 Controlplane V2 叢集就無法解密密鑰。

開始遷移前，請執行下列指令，查看是否曾啟用永久密碼加密功能：

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

如果上述指令的輸出內容為空白，表示您從未啟用永久密碼加密功能。您可以開始遷移。

如果上述指令的輸出內容不為空白，表示先前已啟用永久密碼加密功能。遷移前，請務必完成下一節的步驟，確保新的 Controlplane V2 叢集可以解密密鑰。

以下範例顯示非空白輸出內容：

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

停用永久密碼加密，並視需要解密密碼

如要停用永久密碼加密功能並解密密碼，請按照下列步驟操作：

  1. 在使用者叢集設定檔中，如要停用永續加密密鑰，請在 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. 以 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。遷移作業完成後，您可以在叢集上重新啟用永久密碼加密。

修正設定錯誤的工作負載 Webhook

如果 Webhook 包含 kube-system 命名空間中的系統 Pod，請新增 namespaceSelector，篩除 kube-system 命名空間。

例如：

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

更新使用者叢集設定檔

對現有的使用者叢集設定檔進行下列變更：

  1. 將 enableControlplaneV2 設為 true。

  2. 您也可以選擇讓 Controlplane V2 使用者叢集的控制層具備高可用性 (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. 使用控制層 VIP 的新 IP 位址更新 loadBalancer.vips.controlPlaneVIP 欄位。請注意，這必須與控制層節點 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 區段中指定的每個新控制層節點 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 完成期間無法使用。(根據我們的測試，停機時間不到 7 分鐘，但實際時間長度取決於您的基礎架構)。

  • 遷移作業完成後，系統會刪除 kubeception 叢集的使用者叢集控制層節點。 如果管理員叢集的 network.ipMode.type 設為「static」，您可以從管理員叢集設定檔中移除部分未使用的靜態 IP，然後執行 gkectl update admin，回收這些 IP。您可以使用 kubectl get nodes -o wide 列出管理員叢集節點物件，查看目前使用的 IP。

遷移後

如果您在遷移前停用了永久密碼加密功能，請按照下列步驟重新啟用：

  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