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

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

如要設定拓撲網域，必須啟用進階叢集。

本頁面適用於設定、監控及管理技術基礎架構的管理員、架構師和操作員。如要進一步瞭解 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 控制器。這個暫時叢集稱為「啟動叢集」。使用者叢集是由管理員建立及升級，不需使用 bootstrap 叢集。

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.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 不同，叢集建立作業就會失敗。

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

如果加入 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。

• 如果不想在 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_cgv2。

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_cgv2"

填寫 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 建構及簽署，且已可部署。

建立管理員叢集

建立管理員叢集：

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 連線至管理員叢集節點。這樣一來，您就能排解及調查與管理員叢集連線的任何問題。

將管理員叢集的安全殼層金鑰擷取至名為 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 備份到其他位置。

疑難排解

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

後續步驟

建立要在拓撲網域中使用的使用者叢集