將使用者叢集遷移至 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.controlPlaneNodePortloadBalancer.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