建立管理員叢集，用於拓撲網域

預先發布版

這項功能 適用《服務專屬條款》。 正式發布前的功能是按照「原樣」提供，支援範圍可能有限。 詳情請參閱推出階段說明。

本頁說明如何建立管理員叢集，以用於 Google Distributed Cloud 拓撲網域。管理員叢集會管理執行工作負載的使用者叢集。如要使用拓撲網域，必須使用 Google Distributed Cloud 1.31 以上版本。

如要設定拓撲網域，必須啟用進階叢集。請注意，進階叢集預覽功能有下列限制：

• 只有在建立新的 1.31 叢集時，才能啟用進階叢集。
• 啟用進階叢集後，您將無法將叢集升級至 1.32 版。請僅在測試環境中啟用進階叢集。

本文適用於負責設定、監控及管理技術基礎架構的管理員、架構師和作業人員。如要進一步瞭解我們在 Google Cloud 內容中提及的常見角色和範例工作，請參閱「常見的 GKE 使用者角色和工作」。

如要進一步瞭解管理員叢集，請參閱安裝總覽。

程序總覽

建立管理員叢集的主要步驟如下：

1. 填寫管理員設定檔

   填寫管理員叢集設定檔，指定新管理員叢集的詳細資料。

2. 填寫 vSphere 基礎架構設定檔

   在 vSphere 基礎架構設定檔中，指定有關拓撲網域的詳細資料。

3. 填寫 IP 區塊檔案

   在 IP 區塊檔案中，指定閘道、網路遮罩和控制層節點的 IP 位址。

4. 取得 OS 映像檔

   下載一般 Google Distributed Cloud 套裝組合。然後執行 gkectl prepare，將 OS 映像檔匯入 vSphere，並視需要將容器映像檔推送至私人登錄檔。

5. 建立管理員叢集。

   使用 gkectl 建立新的管理員叢集，如已完成的設定檔中所指定。Google Distributed Cloud 建立管理員叢集時，會部署 Kubernetes in Docker (kind) 叢集，暫時代管建立管理員叢集所需的 Kubernetes 控制器。這個暫時性叢集稱為「啟動叢集」。使用者叢集是由管理員建立及升級，不需要使用啟動程序叢集。

6. 確認管理員叢集正在執行中。

   使用 kubectl 查看叢集節點。

完成這項程序後，您將擁有可用的管理員叢集，可用於在拓撲網域中建立及管理使用者叢集。

事前準備

• 請確認您已設定管理員工作站，並能登入，如「建立管理員工作站」一文所述。管理員工作站具備建立管理員叢集所需的工具。在管理工作站上完成這份文件中的所有步驟。

• 查看 IP 位址規劃文件。確認您有足夠的 IP 位址，可供三個控制層節點和一個控制層 VIP 使用。

• 設定負載平衡器以進行手動負載平衡。您必須先設定負載平衡器，才能建立管理員叢集。

• 請參閱「privateRegistry」一節，決定要為 Google Distributed Cloud 元件使用公開或私有登錄檔。

• 預先查看 osImageType 欄位，然後決定要在管理員叢集節點上執行的作業系統類型。

• 如果貴機構要求輸出流量通過 Proxy 伺服器，請務必將必要 API 和 Artifact Registry 位址加入允許清單。

• 收集存取每個 vCenter Server 執行個體所需的資訊。您需要這項資訊，才能填寫 vSphere 基礎架構設定檔中的「Secret」和「VSphereInfraConfig.credentials.vCenters」部分。如要瞭解如何取得所需資訊，請參閱下列文章：

  • vCenter 使用者帳戶權限
  • 判斷 vCenter 伺服器位址
  • 取得 vCenter CA 根憑證

填寫管理員叢集設定檔

如果您使用 gkeadm 建立管理員工作站，系統會產生名為 admin-cluster.yaml 的設定檔。

如果您未使用 gkeadm 建立管理員工作站，請在管理員工作站上執行下列指令，產生 admin-cluster.yaml：

gkectl create-config admin

這個設定檔用於建立管理員叢集。

請詳閱管理員叢集設定檔文件，瞭解設定檔。建議您在另一個分頁或視窗中開啟這份文件， 因為您會在完成下列步驟時參考這份文件。

name

如要指定管理員叢集的名稱，請填寫 name 欄位。

bundlePath

套件是包含叢集元件的 ZIP 檔案。管理員工作站隨附這項功能。系統會自動填入這個欄位。

enableAdvancedCluster

將 enableAdvancedCluster 設為 true。這樣才能啟用進階叢集，設定拓撲網域時需要進階叢集。

infraConfigFilePath

在 infraConfigFilePath 欄位中，新增vSphere 基礎架構設定檔的完整路徑。

vCenter

移除整個部分。您可以在 vSphere 基礎架構設定檔中設定 vCenter Server 資訊。

network

• 從設定檔中移除下列項目：

  • 整個 network.hostConfig 部分。這項資訊是在每個拓撲網域的 vSphere 基礎架構設定檔中設定。
  • network.vCenter.networkName 欄位。這個欄位是在每個拓撲網域的 vSphere 基礎架構設定檔中設定。
  • 整個 network.controlPlaneIPBlock 部分。閘道、網路遮罩和控制層節點的 IP 位址是在 IP 區塊檔案中設定。

• 將 network.ipMode.ipBlockFilePath 設為 IP 區塊檔案的路徑。

• 將 network.ipMode.type 設為 static。

• 「network.podCIDR」network.podCIDR和「network.serviceCIDR」network.serviceCIDR欄位已預先填入值，除非這些值與網路中已使用的位址衝突，否則您可以保留不變。Kubernetes 會使用這些範圍，將 IP 位址指派給叢集中的 Pod 和 Service。

loadBalancer

• 將 loadBalancer.kind 設為 "ManualLB"，並移除 manualLB 區段。

• 為管理員叢集的 Kubernetes API 伺服器預留 VIP。將 VIP 設為 loadBalancer.vips.controlPlaneVIP 的值

詳情請參閱「管理員叢集子網路中的 VIP」。

antiAffinityGroups

將 antiAffinityGroups.enabled 設為 false。拓撲網域不支援分散式資源排程器 (DRS) 反親和性規則。

adminMaster

• 如要為管理員叢集的控制平面節點指定 CPU 和記憶體，請填寫 adminMaster 部分的 cpus 和 memoryMB 欄位。

• 管理員叢集必須有三個控制層節點。將 adminMaster 區段中的 replicas 欄位設為 3。

• 如要指定控制平面節點使用的特定拓撲網域，請將拓撲網域名稱新增至 adminMaster.topologyDomains 欄位。如果未在此處指定名稱，則必須在 vSphere 基礎架構設定檔的 vSphereInfraConfig.defaultTopologyDomain 中設定名稱。

proxy

如果管理員叢集節點所在的網路位於 Proxy 伺服器後方，請填寫「proxy」部分。

privateRegistry

決定要將 Google Distributed Cloud 元件的容器映像檔儲存在何處。選項如下：

• Artifact Registry

• 您自己的私密 Docker 登錄檔。

  如要使用自己的私人登錄檔，請填寫privateRegistry部分。

componentAccessServiceAccountKeyPath

Google Distributed Cloud 會使用元件存取服務帳戶，從 Artifact Registry 下載叢集元件。這個欄位會保留元件存取服務帳戶的 JSON 金鑰檔案路徑。

系統會自動填入這個欄位。

gkeConnect

填寫gkeConnect部分，將管理員叢集註冊至機群 Google Cloud 。gkeConnect.projectID 中的 ID 必須與 stackdriver.projectID 和 cloudAuditLogging.projectID 中設定的 ID 相同。如果專案 ID 不同，叢集建立作業就會失敗。

您可以選擇在 gkeConnect.location 中指定車隊和 Connect 服務的執行區域。如果未加入這個欄位，叢集會使用這些服務的全球執行個體。

如果加入 gkeConnect.location，指定的區域必須與 cloudAuditLogging.clusterLocation、stackdriver.clusterLocation 和 gkeOnPremAPI.location 中設定的區域相同。如果區域不同，叢集建立作業就會失敗。

gkeOnPremAPI

本節說明如何向 GKE On-Prem API 註冊叢集。

gkectl 指令列工具是唯一可用的叢集生命週期管理工具，適用於使用拓撲網域的叢集。雖然使用拓撲網域的叢集不支援 Google Cloud 控制台、Google Cloud CLI 和 Terraform，但您可以在建立叢集時，選擇在 GKE On-Prem API 中註冊叢集。

如果專案已啟用 GKE On-Prem API，專案中的所有叢集都會在 stackdriver.clusterLocation 中設定的區域，自動註冊 GKE On-Prem API。 Google Cloud gkeOnPremAPI.location 區域必須與 cloudAuditLogging.clusterLocation、gkeConnect.location 和 stackdriver.clusterLocation 中指定的區域相同。如果區域不同，叢集建立作業就會失敗。

• 如要在專案中註冊所有叢集，請務必按照「事前準備」一節中的步驟，在專案中啟用及使用 GKE On-Prem API。

• 如果不想在 GKE On-Prem API 中註冊叢集，請加入這個區段，並將 gkeOnPremAPI.enabled 設為 false。如果不想在專案中註冊任何叢集，請在專案中停用 gkeonprem.googleapis.com (GKE On-Prem API 的服務名稱)。如需操作說明，請參閱「停用服務」。

stackdriver

填寫 stackdriver 部分，為叢集啟用 Cloud Logging 和 Cloud Monitoring。

請注意下列要求：

• stackdriver.projectID 中的 ID 必須與 gkeConnect.projectID 和 cloudAuditLogging.projectID 中的 ID 相同。

• stackdriver.clusterLocation 中設定的 Google Cloud 區域必須與 cloudAuditLogging.clusterLocation 和 gkeConnect.location 中設定的區域相同。此外，如果 gkeOnPremAPI.enabled 為 true，則 gkeOnPremAPI.location 中必須設定相同區域。

如果專案 ID 和區域不同，叢集建立作業就會失敗。

cloudAuditLogging

如要整合叢集 Kubernetes API 伺服器的稽核記錄與 Cloud 稽核記錄，請填寫cloudAuditLogging部分。

請注意新叢集的下列需求：

• 由於 enableAdvancedCluster 設為 true，您必須在 cloudAuditLogging.serviceAccountKeyPath 和 stackdriver.serviceAccountKeyPath 中指定相同路徑。

• cloudAuditLogging.projectID 中的 ID 必須與 gkeConnect.projectID 和 stackdriver.projectID 中的 ID 相同。

• cloudAuditLogging.clusterLocation 中設定的 Google Cloud 區域必須與 stackdriver.clusterLocation 和 gkeConnect.location 中設定的區域相同 (如果設定檔中包含該欄位)。此外，如果 gkeOnPremAPI.enabled 為 true，則必須在 gkeOnPremAPI.location 中設定相同區域。

如果專案 ID 和區域不同，叢集建立作業就會失敗。

clusterBackup

移除這個部分。 系統不支援備份管理員叢集至 vSphere 資料存放區。

autoRepair

如要為管理員叢集啟用自動節點修復功能，請將 autoRepair.enabled 設為 true。

secretsEncryption

由於 enableAdvancedCluster 設為 true，請移除這個部分。

osImageType

設定 osImageType。ubuntu_cgroupv2 和 ubuntu_containerd。

preparedSecrets

移除 preparedSecrets 欄位。 啟用拓撲網域時，系統不支援準備好的憑證。

填寫完畢的設定檔範例

以下是填寫完畢的管理員叢集設定檔範例。這項設定會啟用部分可用功能，但並非全部。

vc-01-admin-cluster.yaml

apiVersion: v1
kind: AdminCluster
name: "gke-admin-01"
bundlePath: "/var/lib/gke/bundles/gke-onprem-vsphere-1.31.0-gke.1-full.tgz"
enableAdvancedCluster: true
infraConfigFilePath: "/my-config-folder/vsphere-infrastructure-config.yaml"
network:
  serviceCIDR: "10.96.232.0/24"
  podCIDR: "192.168.0.0/16"
  ipMode:
    type: "static"
    ipBlockFilePath: "/my-config-folder/admin-cluster-ipblock.yaml"
loadBalancer:
  vips:
    controlPlaneVIP: "172.16.20.59"
  kind: "ManualLB"
antiAffinityGroups:
  enabled: false
adminMaster:
  cpus: 4
  memoryMB: 16384
  replicas: 3
  topologyDomains: "admin-cluster-domain"
componentAccessServiceAccountKeyPath: "sa-key.json"
gkeConnect:
  projectID: "my-project-123"
  registerServiceAccountKeyPath: "connect-register-sa-2203040617.json"
stackdriver:
  projectID: "my-project-123"
  clusterLocation: "us-central1"
  enableVPC: false
  serviceAccountKeyPath: "log-mon-sa-2203040617.json"
  disableVsphereResourceMetrics: false
autoRepair:
  enabled: true
osImageType: "ubuntu_containerd"

填寫 vSphere 基礎架構設定檔

將 vSphere 基礎架構設定檔的範本複製到管理員叢集設定檔 infraConfigFilePath 欄位中指定的目錄。管理員叢集和所有受管理的使用者叢集，都只有一個 vSphere 基礎架構設定檔。

Secret

在 vSphere 基礎架構設定檔中，填寫 Secret 區段。本節說明 vSphere 憑證 Secret，其中儲存每個 vCenter Server 的憑證。

VSphereInfraConfig.name

填寫「VSphereInfraConfig,name」欄位。

VSphereInfraConfig.credentials.vCenters

為每個 Secret 新增對應的 VSphereInfraConfig.credentials.vCenters 區段。

VSphereInfraConfig,topologyDomains

填寫「VSphereInfraConfig.topologyDomains」部分，定義拓撲網域。

填寫 IP 區塊檔案

將 IP 區塊檔案的範本複製到管理員叢集設定檔中 network.ipMode.ipBlockFilePath 欄位指定的目錄檔案。新增閘道、網路遮罩和三個控制層節點的 IP 位址。針對每個控制層節點 IP 位址，新增 isControlPlane: true，如拓撲網域範例所示。

取得 OS 映像檔

1. 將一般 Google Distributed Cloud 套裝組合下載至管理工作站：

   gcloud storage cp gs://gke-on-prem-release/gke-onprem-bundle/VERSION/gke-onprem-vsphere-VERSION.tgz /var/lib/gke/bundles/gke-onprem-vsphere-VERSION.tgz
   

   將 VERSION 替換為要安裝的 Google Distributed Cloud 版本。

   這個指令會下載一般套件。請勿下載完整套裝組合，因為進階叢集不支援這項操作。

2. 執行 gkectl prepare 初始化 vSphere 環境：

   gkectl prepare --config ADMIN_CLUSTER_CONFIG
   

   將 ADMIN_CLUSTER_CONFIG 替換為管理員叢集設定的路徑。

   gkectl prepare 指令會執行下列準備工作：

   • 將 OS 映像檔匯入 vSphere，並標示為 VM 範本。

   • 如果您使用私人 Docker 登錄檔，請將容器映像檔推送至登錄檔。

   • (選用) 驗證容器映像檔的建構認證，確認映像檔是由 Google 建構及簽署，可供部署。

   注意： 如果您使用內部 DNS 名稱，或工作站無法存取 Google 公用 DNS 位址 (8.8.8.8 或 8.8.4.4)，則必須在 /etc/resolv.conf 中指定內部名稱伺服器。

建立管理員叢集

建立管理員叢集：

gkectl create admin --config ADMIN_CLUSTER_CONFIG

在失敗後繼續建立管理員叢集

如果管理員叢集建立失敗或取消，您可以再次執行 create 指令：

gkectl create admin --config ADMIN_CLUSTER_CONFIG

找出管理員叢集 kubeconfig 檔案

gkectl create admin 指令會在目前目錄中建立名為 kubeconfig 的 kubeconfig 檔案。您稍後需要這個 kubeconfig 檔案，才能與管理員叢集互動。

kubeconfig 檔案包含管理員叢集的名稱。如要查看叢集名稱，可以執行下列指令：

kubectl config get-clusters --kubeconfig ADMIN_CLUSTER_KUBECONFIG

輸出內容會顯示叢集名稱。例如：

NAME
gke-admin-tqk8x

您可以視需要變更 kubeconfig 檔案的名稱和位置。

確認管理員叢集正在執行中

確認管理員叢集正在執行中：

kubectl get nodes --kubeconfig ADMIN_CLUSTER_KUBECONFIG

將 ADMIN_CLUSTER_KUBECONFIG 替換為管理員叢集 kubeconfig 檔案的路徑。

輸出內容會顯示管理員叢集節點。例如：

admin-cp-vm-1   Ready    control-plane,master   ...
admin-cp-vm-2   Ready    control-plane,master   ...
admin-cp-vm-3   Ready    control-plane,master   ...

設定「PodTemplate」

拓撲標籤會填入拓撲網域中節點的標籤。 除非您的拓撲網域設定使用預設限制 "topology.kubernetes.io/zone" 做為拓撲鍵，否則您需要在 Deployment、StatefulSet 或 ReplicaSet 的 Pod 範本中設定拓撲鍵 (視情況而定)。

舉例來說，假設您在拓撲標籤中將鍵定義為 "topology.examplepetstore.com/zone"。在 PodTemplate 中，您會將金鑰指定為 topologySpreadConstraints.topologyKey 欄位的值。這樣一來，Kubernetes 排程器就能在拓撲網域中分配 Pod，確保高可用性，並避免在發生故障時，Pod 過度集中在單一區域。

如要進一步瞭解如何設定 topologySpreadConstraints，請參閱 Kubernetes 說明文件中的「Pod 拓撲散布限制」。

備份檔案

建議您備份管理員叢集 kubeconfig 檔案。也就是將 kubeconfig 檔案從管理員工作站複製到其他位置。這樣一來，即使您無法存取管理工作站，或是管理工作站上的 kubeconfig 檔案遭到誤刪，您仍可存取管理叢集。

我們也建議您備份管理員叢的私密 SSH 金鑰。 這樣一來，即使無法存取管理員叢集，您還是可以使用 SSH 連線至管理員叢集節點。這樣您就能排解及調查與管理員叢集的連線問題。

將管理員叢集中的安全殼層金鑰擷取至名為 admin-cluster-ssh-key 的檔案：

kubectl --kubeconfig ADMIN_CLUSTER_KUBECONFIG get secrets -n kube-system sshkeys \
    -o jsonpath='{.data.vsphere_tmp}' | base64 -d > admin-cluster-ssh-key

現在你可以將 admin-cluster-ssh-key 備份到所選的其他位置。

疑難排解

請參閱「排解叢集建立和升級問題」。

後續步驟

建立使用者叢集，以便在拓撲網域中使用