使用 GKE On-Prem API 用戶端建立使用者叢集

本頁面說明如何使用 Google Cloud 控制台、Google Cloud CLI (gcloud CLI) 或 Terraform 建立使用者叢集。

什麼是 GKE On-Prem API？

GKE On-Prem API 是 Google Cloud代管的 API，可讓您使用 Terraform 和標準Google Cloud 應用程式，管理內部部署叢集的生命週期。GKE On-Prem API 會在 Google Cloud的基礎架構中執行。Terraform、控制台和 gcloud CLI 都是 API 的用戶端，會使用 API 在資料中心建立叢集。

如要管理叢集的生命週期，GKE On-Prem API 必須在 Google Cloud中儲存叢集狀態的中繼資料，並使用您在建立叢集時指定的Google Cloud 區域。這項中繼資料可讓 API 管理叢集生命週期，但不包含工作負載專屬資料。

使用 GKE On-Prem API 用戶端建立叢集時，請指定Google Cloud 專案。叢集建立完成後，系統會自動向指定專案的機群註冊。此專案稱為「機群主專案」。叢集建立後，就無法變更機群主機專案。

如要建立使用者叢集，可以建立使用者叢集設定檔，然後使用 bmctl，如「建立使用者叢集」一文所述。

如要使用 Terraform、主控台或 gcloud CLI 管理透過 bmctl 建立的叢集生命週期，請參閱「設定由 GKE On-Prem API 管理的使用者叢集」。

事前準備

本節說明使用 GKE On-Prem API 用戶端建立使用者叢集時的相關規定。

授予 IAM 權限

如果您不是專案擁有者，則必須取得 roles/gkeonprem.admin 角色。

如要在控制台中存取 Google Kubernetes Engine 頁面，您也必須具備下列角色：

• roles/container.viewer。
• roles/gkehub.viewer

建立叢集後，如果您不是專案擁有者，且想使用連線閘道透過指令列連線至使用者叢集，則必須具備下列角色：

• roles/gkehub.gatewayAdmin： 這個角色可讓您存取 Connect Gateway API。如果只需要叢集的唯讀存取權，roles/gkehub.gatewayReader 就足夠了。

• roles/gkehub.viewer：這個角色可讓您擷取叢集憑證。

如要瞭解如何授予角色，請參閱「管理專案、資料夾和機構的存取權」一文。

必要 Google API

確認已在車隊主專案中啟用所有必要的 Google API。

如果您要使用 gcloud CLI 建立叢集，請務必啟用 GKE On-Prem API。如果您使用控制台建立叢集，系統會自動啟用 GKE On-Prem API。

gcloud services enable --project FLEET_HOST_PROJECT_ID \
    gkeonprem.googleapis.com

管理員叢集必要條件

您必須具備運作中的管理員叢集，才能建立使用者叢集。管理叢集必須符合下列條件：

• 在使用者叢集建立完成後，即可存取 Kubernetes API 伺服器。

• 使用者叢集建立後，請確保網路連線可連至使用者叢集的所有節點。

• 必須註冊至機群。管理員叢集 gkeConnect.projectID 欄位中設定的專案 ID (稱為機群主機專案)，必須與您要建立使用者叢集的專案相同。

設定叢集節點機器的必要步驟

請參閱「設定叢集節點機器的必要步驟」，確認要執行使用者叢集的機器符合必要條件。

指令列存取權

建立叢集後，如要在管理工作站以外的電腦上使用連線閘道對使用者叢集執行 kubectl，請在要使用的電腦上安裝下列指令列工具。

注意： 如果您使用 Cloud Shell 做為與 Google Cloud互動的 Shell 環境，系統會為您安裝這些工具。

• 最新版 gcloud CLI。
• kubectl，可對 Kubernetes 叢集執行指令。如需安裝 kubectl，請按照這些說明操作。

建立使用者叢集

您可以使用 Terraform、 Google Cloud 控制台或 Google Cloud CLI (gcloud CLI)，建立由 GKE On-Prem API 管理的叢集。如果您是第一次安裝 Google Distributed Cloud，可能會覺得控制台是最容易使用的工具。

進一步瞭解建立叢集時需要提供的資訊後，您可能會發現 Terraform 或 gcloud CLI 更方便，特別是當您要建立多個叢集時。Terraform 是業界標準的基礎架構即程式碼工具，如果貴機構已使用 Terraform，您可能想用它來建立叢集，並管理叢集生命週期。

使用 gcloud CLI 時，您可以將指令及其引數儲存至文字檔，並視需要進行變更，以建立其他叢集。如果您使用 Cloud Build 等 CI/CD 工具，可以透過 gcloud 指令建立叢集和節點集區，並指定 --impersonate-service-account 標記來自動建立。

控制台

主控台中的大多數設定都對應至叢集設定檔中的欄位。

1. 前往控制台的「建立裸機叢集」頁面。

   前往「建立裸機叢集」

2. 選取要建立叢集的 Google Cloud 專案。 選取的專案也會做為機群主專案。這必須是管理員叢集註冊的專案。建立使用者叢集後，系統會自動向所選專案的機群註冊。

3. 點選「下一步」，開始設定叢集。

以下各節將逐步引導您設定使用者叢集。

叢集基本資訊

輸入叢集的基本資訊。

1. 輸入使用者叢集的名稱。

2. 在「管理員叢集」下方，從清單中選取管理員叢集。

3. 在「Google Cloud API Location」(Google Cloud API 位置) 欄位中，從清單選取 Google Cloud區域。這項設定會指定下列 API 和服務的執行區域：

   • GKE On-Prem API (gkeonprem.googleapis.com)
   • 車隊服務 (gkehub.googleapis.com)
   • 連結服務 (gkeconnect.googleapis.com)

   這項設定也會控管下列項目的儲存區域：

   • GKE On-Prem API 管理叢集生命週期所需的使用者叢集中繼資料
   • 系統元件的 Cloud Logging 和 Cloud Monitoring 資料
   • Cloud 稽核記錄建立的管理員稽核記錄

   叢集名稱、專案和位置資訊會共同識別 Google Cloud中的叢集。

4. 選取使用者叢集的版本。使用者叢集的子版本必須與管理員叢集相同，或是僅低於管理員叢集一個子版本。

5. 身為叢集建立者，您會獲得叢集的叢集管理員權限。視需要，在「管理員使用者」欄位中輸入其他叢集管理員的電子郵件地址。

   建立叢集時，GKE On-Prem API 會將 Kubernetes 依據角色的存取權控管 (RBAC) 政策套用至叢集，授予您和其他管理員使用者 Kubernetes clusterrole/cluster-admin 角色，讓使用者能完整存取叢集和所有命名空間中的全部資源。

   注意： 除了 Kubernetes RBAC 政策，您也必須授予非專案擁有者使用者部分 Identity and Access Management (IAM) 角色。如要瞭解如何授予 IAM 角色，請參閱授予必要角色。

6. 在「節點設定」部分，指定下列項目：

   • 每個節點的 Pod 數上限：輸入可在單一節點上執行的 Pod 數量上限。允許的值介於 32 到 250 之間 (包含這兩者)。Kubernetes 會為每個節點指派無類別跨網域路由 (CIDR) 區塊，讓每個 Pod 擁有一個不重複的 IP 位址。CIDR 區塊的大小對應每個節點的最大 Pod 數。如要進一步瞭解如何設定每個節點的 Pod 數量上限，請參閱「Pod 網路」。

   • 容器執行階段：叢集唯一可用的容器執行階段為 containerd。

7. 按一下「下一步」前往「網路」部分。

網路

在本節中，您將指定叢集節點、Pod 和 Service 的 IP 位址。如果您使用 MetalLB 進行套裝組合負載平衡，也請一併設定。

1. 在「控制層」節點部分，輸入每個控制層節點的 IPv4 位址。控制層節點會執行系統工作負載。一般來說，如為基本部署項目，控制層會使用 1 個機器，如為高可用性 (HA) 部署項目，則會使用 3 個機器。為確保高可用性，請指定奇數節點，以達到絕對多數。更新或升級叢集時，可以變更這個欄位。

   視需要按一下「+ 新增 IP 位址」，輸入更多 IP 位址。

2. 在「Load balancer」(負載平衡器) 專區中，從「Mode」(模式) 清單選取要為叢集設定的負載平衡器。詳情請參閱「負載平衡器總覽」。

   隨附於 MetalLB

   使用套裝組合的 MetalLB 負載平衡器設定負載平衡。選擇這個選項後，Google Distributed Cloud 會部署第 4 層負載平衡器，在專屬的工作站節點集區中運作，也可以與控制層位於相同的節點。

   1. 在「Load balancer node pools」(負載平衡器節點集區) 部分，選取下列其中一個選項：

      • 使用控制層節點：選擇這個選項，即可在與控制層相同的節點上執行負載平衡器。

      • 建立負載平衡器節點集區：如要在專用的工作站節點集區上執行負載平衡器，請選擇這個進階選項。負載平衡器節點集區中的所有節點，都必須與您在「負載平衡器位址集區」部分設定的負載平衡器虛擬 IP (VIP) 位於同一個第 2 層子網路。

        1. 在「負載平衡器節點集區 IP 1」欄位中，輸入負載平衡器節點集區中節點的 IPv4 位址。

        2. 視需要按一下「+ 新增 IP 位址」，輸入其他 IP 位址。

   2. 在「Load balancer address pools」(負載平衡器位址集區) 部分，新增一或多個位址集區，供 MetalLB 控制器選擇並指派給 LoadBalancer 類型的服務。您在「虛擬 IP」部分指定的 Ingress VIP 必須位於其中一個集區。

      1. 輸入位址集區名稱。

      2. 以 CIDR 標記法 (例如 192.0.2.0/26) 或範圍標記法 (例如 192.0.2.64-192.0.2.72) 輸入 IP 位址範圍。如要在集區中指定單一 IP 位址，請在 CIDR 標記法中使用 /32 (例如 192.0.2.1/32)。

      3. 如果 Ingress VIP 不在位址範圍內，請選取「+ 新增 IP 位址範圍」，然後輸入包含 Ingress VIP 的其他位址範圍。

         每個集區中的 IP 位址均不得重疊，而且必須與叢集節點位於相同的子網路。

      4. 在「指派 IP 位址」下方，選取下列其中一個選項：

         • 自動：如要讓 MetalLB 控制器自動將位址集區中的 IP 位址指派給 LoadBalancer 類型的服務，請選擇這個選項。
         • 手動：如果您打算使用集區中的位址，手動指定 LoadBalancer 類型的 Service 位址，請選擇這個選項。

      5. 如要避免 MetalLB 控制器使用結尾為 .0 或 .255 的集區位址，請按一下「避免使用發生錯誤的 IP 位址」。這樣可避免發生錯誤的消費者裝置誤將傳送至這些特殊 IP 位址的流量捨棄。

      6. 完成後，請按一下「完成」。

      7. 如有需要，請按一下「新增位址集區」。

   手動負載平衡器

   手動負載平衡可讓您自行設定負載平衡解決方案，控管控制層和資料層流量。您必須先在外部負載平衡器設定控制層 VIP，再建立叢集。外部控制層負載平衡器也可用於資料層流量，您也可以為資料層設定個別的負載平衡器。詳情請參閱「設定手動負載平衡」。

3. 在「虛擬 IP」部分中，輸入下列內容：

   • 控制層 VIP：傳送至使用者叢集 Kubernetes API 伺服器的流量所使用的目的地 IP 位址。控制層 VIP 必須與負載平衡器節點位於同一個子網路，且不得位於負載平衡器位址集區使用的任何位址範圍內。

   • 通訊埠：Kubernetes API 伺服器接收流量時使用的目的地通訊埠。預設值為 443。

   • Ingress VIP：要在 Ingress Proxy 的負載平衡器上設定的 IP 位址。輸入其中一個負載平衡器位址集區中的位址。

4. 在「服務和 Pod CIDR」部分，以 CIDR 標記法指定 Kubernetes Service 和 Pod IP 位址範圍。範圍不得相互重疊，也不能與您要從叢集內部連結的任何外部位址重疊。建議您使用 RFC 1918 定義的私有 IP 位址範圍。控制台提供下列預設位址範圍，但您可以變更這些範圍：

   • 服務 CIDR：10.96.0.0/20 如果不接受預設值，請輸入介於 /24 和 /12 之間的 CIDR 範圍，其中 /12 可提供最多的 IP 位址。

   • Pod CIDR：192.168.0.0/16如果不接受預設值，請輸入介於 /18 和 /8 之間的 CIDR 範圍，其中 /8 可提供最多的 IP 位址。

5. 在「進階屬性」屬性部分，視需要指定下列屬性：

   • Proxy 網址：Proxy 伺服器的 HTTP 位址。即使通訊埠號碼與架構的預設通訊埠相同，也請一併加入，例如：http://my-proxy.example.local:80

   • 網址：以半形逗號分隔的 IP 位址、IP 位址範圍、主機名稱和網域名稱清單，這些項目不應透過 Proxy 伺服器傳輸。Google Distributed Cloud 會直接將要求傳送至這些地址、主機或網域。

6. 點選「下一步」。

儲存空間

Google Distributed Cloud 軟體僅提供區塊和檔案儲存空間介面。這些項目有預設選項，但也能自訂設定。詳情請參閱「設定本機儲存空間」。

1. 您也可以視需要設定下列項目：

   • 本機磁碟區佈建工具節點掛接：指定已掛接磁碟所支援的本機 PersistentVolumes (PV) 設定。您必須格式化並掛接這些磁碟，這項作業可在建立叢集之前或之後執行。

   • 本機磁碟區佈建工具共用：為共用檔案系統中子目錄支援的本機 PersistentVolumes 指定設定，系統會在建立叢集時自動建立這些子目錄。

2. 點選「下一步」。

功能

為協助您監控、排解叢集問題及操作叢集，系統會自動啟用下列功能，且無法停用：

• 系統服務的 Cloud Logging
• 系統服務的 Cloud Monitoring
• 管理員活動稽核記錄

在控制台中建立節點集區

叢集至少須有一個工作站節點的節點集區。節點集區是在這個叢集中建立的工作站節點群組範本。

在控制台中，您至少要設定一個節點集區 (或接受預設值)，然後建立叢集。叢集建立完成後，您可以新增其他節點集區。使用 gcloud CLI 時，請先建立叢集，然後將一或多個節點集區新增至新建立的叢集。

1. 按一下左側導覽列中的「default pool」。

2. 在「Node pool defaults」(節點集區預設值) 區段中，輸入「Node pool name」(節點集區名稱)，或接受「default-pool」做為名稱。

3. 在「Worker nodes」(工作站節點) 區段中，輸入要執行叢集的機器 IP 位址。

4. 在「節點集區中繼資料 (選用)」專區中，如要新增 Kubernetes 標籤和汙點，請按照下列步驟操作：

   1. 按一下「+ Add Kubernetes Labels」(+ 新增 Kubernetes 標籤)。輸入標籤的「Key」(鍵) 和「Value」(值)。視需要重複上述步驟。
   2. 按一下「+ Add Taint」(新增汙染)。輸入汙染的「鍵」、「值」和「效果」。視需要重複上述步驟。

5. 按一下「驗證並完成」，建立使用者叢集。建立使用者叢集需要 15 分鐘以上。主控台會顯示狀態訊息，驗證設定並在資料中心建立叢集。

   如果設定有問題，控制台會顯示錯誤訊息，您應該能據此修正設定問題，然後再次嘗試建立叢集。

gcloud CLI

您可以使用下列指令建立使用者叢集：

gcloud container bare-metal clusters create

建立叢集後，您需要使用下列指令建立至少一個節點集區：

gcloud container bare-metal node-pools create

建立叢集和節點集區的大部分標記，都對應至使用者叢集設定檔中的欄位。如要開始使用，請在「Examples」部分測試完整指令。如要瞭解標記，請參閱範例後方的章節，或參閱 gcloud CLI 參考資料。

事前準備

建立使用者叢集時選取的版本，必須是管理員叢集支援的版本。此外，最新子版本或修補程式版本發布後，要過 7 到 14 天，才會在 GKE On-Prem API 中提供。您可以執行 gcloud 指令，取得可安裝的支援叢集版本清單。

1. 請務必更新元件：

   gcloud components update
   

2. 取得管理員叢集的名稱和機群成員位置：

   gcloud container fleet memberships list \
     --project=FLEET_HOST_PROJECT_ID
   

   將 FLEET_HOST_PROJECT_ID 替換為管理員叢集註冊的專案 ID。

   輸出結果會與下列內容相似：

   NAME             EXTERNAL_ID                           LOCATION
   admin-cluster-1  bb7803b4-8438-4b22-859f-4559b4b29072  global
   admin-cluster-2  ee16ee2b-6ec0-49fc-9413-3c89cbc70854  global
   admin-cluster-3  fc2b7ef5-39ff-4b63-b919-04c5adc67be4  us-west1
   

   位置會指定 Fleet 和 Connect 服務的執行位置。1.28 之前的管理叢集是由全域機群和 Connect 服務管理。在 1.28 以上版本中，建立管理叢集時，您可以指定 global 或 Google Cloud 區域。在下列範例指令中，您會在 --admin-cluster-membership-location 旗標中指定區域。

3. 取得可在使用者叢集上安裝的版本清單：

   gcloud container bare-metal clusters query-version-config \
     --admin-cluster-membership=ADMIN_CLUSTER_NAME \
     --admin-cluster-membership-project=FLEET_HOST_PROJECT_ID \
     --admin-cluster-membership-location=ADMIN_CLUSTER_REGION \
     --location=REGION
   

   更改下列內容：

   • ADMIN_CLUSTER_NAME：管理員叢集的名稱。

   • FLEET_HOST_PROJECT_ID：管理員叢集註冊的專案 ID。

   • ADMIN_CLUSTER_REGION：管理員叢集的 Fleet 成員區域。這可以是全域或 Google Cloud區域。使用 gcloud container fleet memberships list 輸出內容中的管理員叢集位置。

   • REGION：建立叢集時要使用的 Google Cloud 區域。這是 GKE On-Prem API 和 Fleet 與 Connect 服務的執行區域。指定 us-west1 或其他支援的區域。

   指令會輸出類似以下的結果：

   versions:
   - version: 1.16.2
   - version: 1.16.1
   - version: 1.16.0
   - version: 1.15.7
   - version: 1.15.6
   - version: 1.15.5
   

建議您使用支援的最高版本，取得最新的修正項目和改善措施。

範例

本節提供指令範例，說明如何使用 MetalLB 負載平衡器建立叢集，以及如何使用手動負載平衡器建立叢集。您指定的資訊會因使用的負載平衡器類型而異。詳情請參閱負載平衡器總覽。

這些範例會建立叢集，但不含任何節點集區。叢集執行後，您必須新增節點集區，才能部署工作負載。

MetalLB

本例說明如何使用隨附的 MetalLB 負載平衡器建立使用者叢集。

gcloud container bare-metal clusters create USER_CLUSTER_NAME \
  --project=FLEET_HOST_PROJECT_ID \
  --admin-cluster-membership=ADMIN_CLUSTER_NAME \
  --admin-cluster-membership-project=FLEET_HOST_PROJECT_ID \
  --admin-cluster-membership-location=ADMIN_CLUSTER_REGION \
  --location=REGION \
  --version=VERSION \
  --admin-users=YOUR_EMAIL_ADDRESS \
  --admin-users=ANOTHER_EMAIL_ADDRESS \
  --metal-lb-address-pools='pool=NAME,avoid-buggy-ips=True|False,manual-assign=True|False,addresses=IP_ADDRESS_RANGE_1;IP_ADDRESS_RANGE_2;...' \
  --control-plane-node-configs='node-ip=CP_IP_ADDRESS_1,labels=CP_KEY_1.1=CP_VALUE_1.1;CP_KEY_1.2=CP_VALUE_1.2;...' \
  --control-plane-vip=CONTROL_PLANE_VIP \
  --control-plane-load-balancer-port=CONTROL_PLANE_LB_PORT \
  --ingress-vip=INGRESS_VIP \
  --island-mode-service-address-cidr-blocks=SERVICE_CIDR_BLOCK \
  --island-mode-pod-address-cidr-blocks=POD_CIDR_BLOCK \
  --lvp-share-path=/mnt/localpv-share \
  --lvp-share-storage-class=local-shared \
  --lvp-node-mounts-config-path=/mnt/localpv-disk \
  --lvp-node-mounts-config-storage-class=local-disks

取代下列項目：

• USER_CLUSTER_NAME：使用者叢集的名稱，可自行選擇。叢集建立完成後即無法變更名稱。 名稱必須符合以下條件：
  • 最多可包含 40 個半形字元
  • 只能包含小寫英數字元或連字號 (-)
  • 開頭必須是字母字元
  • 結尾為英數字元
• FLEET_HOST_PROJECT_ID：要在其中建立叢集的專案 ID。指定的專案也會做為機群主專案。這必須是管理員叢集註冊的專案。建立使用者叢集後，系統會自動向所選專案的機群註冊該叢集。叢集建立後，機群主機專案就無法變更。
• ADMIN_CLUSTER_NAME：管理使用者叢集的管理員叢集名稱。在 --admin-cluster-membership 旗標中，您可以使用完整指定的叢集名稱，格式如下：

      projects/FLEET_HOST_PROJECT_ID/locations/ADMIN_CLUSTER_REGION/memberships/ADMIN_CLUSTER_NAME

  或者，您可以將 --admin-cluster-membership 設為管理員叢集的名稱，如範例指令所示。只使用管理員叢集名稱時，請使用 --admin-cluster-membership-project 設定管理員叢集的專案 ID，並使用 --admin-cluster-membership-location 設定位置。管理叢集的位置可以是 global 或 Google Cloud 地區。如需尋找區域，請執行 gcloud container fleet memberships list。

• REGION：GKE On-Prem API (gkeonprem.googleapis.com)、Fleet 服務 (gkehub.googleapis.com) 和 Connect 服務 (gkeconnect.googleapis.com) 執行的 Google Cloud 區域。指定 us-west1 或其他支援的區域。叢集建立後，就無法變更區域。這項設定會指定下列項目的儲存區域：
  • GKE On-Prem API 管理叢集生命週期所需的使用者叢集中繼資料
  • 系統元件的 Cloud Logging 和 Cloud Monitoring 資料
  • Cloud 稽核記錄建立的管理員稽核記錄

  叢集名稱、專案和位置資訊會共同識別 Google Cloud中的叢集。

  重要事項：如要安裝 Cloud Service Mesh，請務必安裝 1.19.3 以上版本。這是因為 Fleet 和 Connect 服務會在特定區域執行。
• VERSION：使用者叢集的 Google Distributed Cloud 版本。
• YOUR_EMAIL_ADDRESS 和 ANOTHER_EMAIL_ADDRESS： 如果您未加入 --admin-users 旗標，身為叢集建立者，系統預設會授予您叢集管理員權限。但如果加入 --admin-users 指定其他使用者為管理員，就會覆寫預設值，因此必須同時加入您的電子郵件地址和其他管理員的電子郵件地址。舉例來說，如要新增兩位管理員：

      --admin-users=[e-mail] \
      --admin-users=[e-mail]

  建立叢集時，GKE On-Prem API 會將 Kubernetes 角色型存取權控管 (RBAC) 政策套用至叢集，授予您和其他管理員使用者 Kubernetes clusterrole/cluster-admin 角色，讓您能完整存取叢集和所有命名空間中的全部資源。

  注意：除了 Kubernetes RBAC 政策，您也必須為非專案擁有者的使用者授予部分 Identity and Access Management (IAM) 角色。 如要瞭解如何授予 IAM 角色，請參閱「授予必要角色」。

MetalLB 位址集區

• --metal-lb-address-pools：指定 MetalLB 負載平衡器使用的位址集區設定。旗標的值格式如下：

'pool=NAME,avoid-buggy-ips=True|False,manual-assign=True|False,addresses=IP_ADDRESS_RANGE_1;IP_ADDRESS_RANGE_2;...' \

值包含以關鍵字 pool、avoid-buggy-ip、manual-assign 和 addresses 開頭的區隔。並以半形逗號區隔每個區隔。

• pool：您為集區選用的名稱。

• avoid-buggy-ips：如果將此值設為 True，MetalLB 控制器就不會將結尾為 .0 或 .255 的 IP 位址指派給 Service。這樣可避免有問題的消費裝置誤將傳送至這些特殊 IP 位址的流量捨棄。如未指定，則預設為 False。

• manual-assign：如果您不希望 MetalLB 控制器自動將這個集區的 IP 位址指派給服務，請將這個值設為 True。接著，開發人員可以建立 LoadBalancer 類型的 Service，然後手動指定集區中的其中一個位址。如未指定，manual-assign 會設為 False。

• 在 addresses 清單中，每個位址都必須是 CIDR 或連字號範圍格式的範圍。如要在集區中指定單一 IP 位址 (例如 Ingress VIP)，請使用 CIDR 標記法中的 /32 (例如 192.0.2.1/32)。

請注意下列語法規則：

• 以單引號括住整個值。
• 不得包含空白字元。
• 請以半形分號分隔各 IP 位址範圍。

您可以指定多個標記例項，如下例所示：

--metal-lb-address-pools='pool=pool1,avoid-buggy-ips=False,manual-assign=True,addresses=192.0.2.0/26;192.0.2.64-192.0.2.72'
--metal-lb-address-pools='pool=pool2,avoid-buggy-ips=True,manual-assign=True,addresses=10.251.133.0/24;10.251.134.80/32'

MetalLB 節點

• 選用：--metal-lb-load-balancer-node-configs： 根據預設，負載平衡器會與控制層位於相同的節點。如要在專用工作節點集區上執行負載平衡器，請為每個節點指定這個標記。負載平衡器節點集區中的所有節點，都必須與負載平衡器虛擬 IP (VIP) 位於同一個第 2 層子網路。

  重要事項： 如果您建立叢集時未設定專屬的負載平衡器節點集區，之後就無法新增。如果叢集已設定至少一個負載平衡器節點，您可以更新叢集，在負載平衡器節點集區中新增更多節點。

  標記的值採用以下格式：

  'node-ip=LB_IP_ADDRESS_1,labels=LB_KEY_1.1=LB_VALUE_1.1;LB_KEY_1.2=LB_VALUE_1.2;...' \
  

  值包含以關鍵字 node-ip 和 labels 開頭的區隔。並以半形逗號區隔每個區隔。

  • node-ip：負載平衡器節點集區中節點的 IP 位址。每個標記只能指定一個 node-ip。如要指定多個節點，請為每個節點再次加入旗標。

  • labels：附加至節點的一或多個 key=value 組合。

  請注意下列語法規則：

  • 以單引號括住整個值。
  • 不得包含空白字元。
  • 以半形分號分隔 labels 區段中的每個 key=value 組合。

  如果您指定 --metal-lb-load-balancer-node-configs，可以選擇性加入下列旗標：

  • --metal-lb-load-balancer-node-labels：使用這個標記將標籤新增至負載平衡器節點集區中的所有節點。請以半形逗號分隔鍵/值組合清單。

    --metal-lb-load-balancer-node-labels=KEY_1=VALUE_1,KEY_2=VALUE_2
    

  • --metal-lb-load-balancer-node-taints：使用這個旗標將汙點新增至負載平衡器節點集區中的所有節點。每個汙點都是與效果相關聯的鍵/值配對，效果必須是下列其中一項：PreferNoSchedule、NoSchedule 或 NoExecute。

    --metal-lb-load-balancer-node-taints=KEY_1=VALUE_1:EFFECT_1,KEY_2=VALUE_2:EFFECT_2
    

  以下範例會在負載平衡器節點集區中新增三個節點。所有節點都標示為 lb-pool-key=lb-pool-value，且具有汙染 dedicated=experimental:PreferNoSchedule，

  --metal-lb-load-balancer-node-configs='node-ip=192.0.2.1' \
  --metal-lb-load-balancer-node-configs='node-ip=192.0.2.2,labels=key2.1=value2.1' \
  --metal-lb-load-balancer-node-configs='node-ip=192.0.2.3,labels=key3.1=value3.1;key3.2=value3.2' \
  --metal-lb-load-balancer-node-labels=lb-pool-key=lb-pool-value \
  --metal-lb-load-balancer-node-taints=dedicated=experimental:PreferNoSchedule \
  

控制層節點

• --control-plane-node-configs： 控制層節點的 IPv4 位址。控制層節點會執行系統工作負載。請為每個控制層節點指定這個旗標。 一般來說，如為基本部署項目，控制層會使用 1 個機器，如為高可用性 (HA) 部署項目，則會使用 3 個機器。為確保高可用性，請指定奇數節點，以達到絕對多數。更新或升級叢集時，您可以隨時變更這些地址。

  標記的值採用以下格式：

    'node-ip=CP_IP_ADDRESS_1,labels=CP_KEY_1.1=CP_VALUE_1.1;CP_KEY_1.2=CP_VALUE_1.2;...' \

  值包含以關鍵字 node-ip 和 labels 開頭的區隔。並以半形逗號區隔每個區隔。

• node-ip：控制層節點的 IP 位址。每個標記只能指定一個 node-ip。如要指定多個節點，請為每個節點再次加入旗標。
• labels：附加至節點的一或多個 key=value 組合。

  請注意下列語法規則：

  • 以單引號括住整個值。
  • 不得包含空白字元。
  • 在 labels 區隔中，以半形分號分隔每對 key=value。

  視需要加入下列旗標：

• --control-plane-node-labels：使用這個標記將 標籤新增至所有控制平面節點。以半形逗號分隔鍵=值組合清單。
    --control-plane-node-labels=KEY_1=VALUE_1,KEY_2=VALUE_2

• --control-plane-node-taints：使用這個標記將新增至所有控制平面節點。每個汙點都是與效果相關聯的 key=value 配對，效果必須是下列其中一個：PreferNoSchedule、NoSchedule 或 NoExecute。

  以下範例會在控制層節點中新增三個節點。所有節點都標有 cp-node-pool-key=cp-node-pool-value，且具有汙染 dedicated=experimental:PreferNoSchedule。

    --control-plane-node-configs='node-ip=192.0.2.1' \
    --control-plane-node-configs='node-ip=192.0.2.2,labels=key2.1=value2.1' \
    --control-planer-node-configs='node-ip=192.0.2.3,labels=key3.1=value3.1;key3.2=value3.2' \
    --control-plane-node-labels=cp-node-pool-key=cp-node-pool-value \
    --control-plane-node-taints=dedicated=experimental:PreferNoSchedule \

虛擬 IP

• CONTROL_PLANE_VIP：您選擇在使用者叢集的 Kubernetes API 伺服器負載平衡器上設定的 IP 位址。

  範例：--control-plane-vip=203.0.113.3

• CONTROL_PLANE_LB_PORT：負載平衡器提供 Kubernetes API 伺服器服務的通訊埠。

  範例：-control-plane-load-balancer-port=443

• INGRESS_VIP：您選擇在負載平衡器上設定的 IP 位址，用於輸入 Proxy。

  範例：--ingress-vip=10.251.134.80

  Ingress VIP 的 IP 位址必須位於其中一個 MetalLB 位址集區。

服務和 Pod CIDR

• SERVICE_CIDR_BLOCK：以 CIDR 格式表示的 IP 位址範圍，用於叢集中的服務。CIDR 範圍必須介於 /24 和 /12 之間，其中 /12 可提供最多的 IP 位址。

  範例：--island-mode-service-address-cidr-blocks=10.96.0.0/20

• POD_CIDR_BLOCK：IP 位址範圍 (CIDR 格式)，用於叢集中的 Pod。CIDR 範圍必須介於 /18 和 /8 之間，其中 /8 可提供最多的 IP 位址。

  範例：--island-mode-pod-address-cidr-blocks=192.168.0.0/16

儲存空間

1. --lvp-share-path：這是主機機器路徑，可在其中建立子目錄。系統會為每個子目錄建立本機 PersistentVolume (PV)。
2. --lvp-share-storage-class：這是用於建立永久磁碟區的 StorageClass。系統會在建立叢集時建立 StorageClass。
3. --lvp-node-mounts-config-path：這是主機路徑，可供探索已掛接的磁碟。系統會為每個掛接項目建立本機 PersistentVolume (PV)。
4. --lvp-node-mounts-config-storage：叢集建立期間，PV 建立時使用的儲存空間類別。

如要進一步瞭解儲存空間，請參閱「設定本機儲存空間」。

手動

手動負載平衡可讓您自行設定負載平衡解決方案，控管控制層和資料層流量。您必須先在外部負載平衡器設定控制層 VIP，再建立叢集。外部控制層負載平衡器也可用於資料層流量，您也可以為資料層設定個別的負載平衡器。詳情請參閱「設定手動負載平衡」。

如有需要，請捲動滑鼠，填寫 --admin-cluster-membership 標記的 ADMIN_CLUSTER_NAME 預留位置。

gcloud container bare-metal clusters create USER_CLUSTER_NAME \
  --project=FLEET_HOST_PROJECT_ID \
  --admin-cluster-membership=ADMIN_CLUSTER_NAME \
  --admin-cluster-membership-project=FLEET_HOST_PROJECT_ID \
  --admin-cluster-membership-location=ADMIN_CLUSTER_REGION \
  --location=REGION \
  --version=VERSION \
  --admin-users=YOUR_EMAIL_ADDRESS \
  --admin-users=ANOTHER_EMAIL_ADDRESS \
  --enable-manual-lb \
  --control-plane-node-configs='node-ip=CP_IP_ADDRESS_1,labels=CP_KEY_1.1=CP_VALUE_1.1;CP_KEY_1.2=CP_VALUE_1.2;...' \
  --control-plane-vip=CONTROL_PLANE_VIP \
  --control-plane-load-balancer-port=CONTROL_PLANE_LB_PORT \
  --ingress-vip=INGRESS_VIP \
  --island-mode-service-address-cidr-blocks=SERVICE_CIDR_BLOCK \
  --island-mode-pod-address-cidr-blocks=POD_CIDR_BLOCK \
  --lvp-share-path=/mnt/localpv-share \
  --lvp-share-storage-class=local-shared \
  --lvp-node-mounts-config-path=/mnt/localpv-disk \
  --lvp-node-mounts-config-storage-class=local-disks

更改下列內容：

• USER_CLUSTER_NAME：使用者叢集的名稱，可自行選擇。叢集建立完成後即無法變更名稱。 名稱必須符合以下條件：
  • 最多可包含 40 個半形字元
  • 只能包含小寫英數字元或連字號 (-)
  • 開頭必須是字母字元
  • 結尾為英數字元
• FLEET_HOST_PROJECT_ID：要在其中建立叢集的專案 ID。指定的專案也會做為機群主專案。這必須是管理員叢集註冊的專案。建立使用者叢集後，系統會自動向所選專案的機群註冊該叢集。叢集建立後，機群主機專案就無法變更。
• ADMIN_CLUSTER_NAME：管理使用者叢集的管理員叢集名稱。在 --admin-cluster-membership 旗標中，您可以使用完整指定的叢集名稱，格式如下：

      projects/FLEET_HOST_PROJECT_ID/locations/ADMIN_CLUSTER_REGION/memberships/ADMIN_CLUSTER_NAME

  或者，您可以將 --admin-cluster-membership 設為管理員叢集的名稱，如範例指令所示。只使用管理員叢集名稱時，請使用 --admin-cluster-membership-project 設定管理員叢集的專案 ID，並使用 --admin-cluster-membership-location 設定位置。管理叢集的位置可以是 global 或 Google Cloud 地區。如需尋找區域，請執行 gcloud container fleet memberships list。

• REGION：GKE On-Prem API (gkeonprem.googleapis.com)、Fleet 服務 (gkehub.googleapis.com) 和 Connect 服務 (gkeconnect.googleapis.com) 執行的 Google Cloud 區域。指定 us-west1 或其他支援的區域。叢集建立後，就無法變更區域。這項設定會指定下列項目的儲存區域：
  • GKE On-Prem API 管理叢集生命週期所需的使用者叢集中繼資料
  • 系統元件的 Cloud Logging 和 Cloud Monitoring 資料
  • Cloud 稽核記錄建立的管理員稽核記錄

  叢集名稱、專案和位置資訊會共同識別 Google Cloud中的叢集。

  重要事項：如要安裝 Cloud Service Mesh，請務必安裝 1.19.3 以上版本。這是因為 Fleet 和 Connect 服務會在特定區域執行。
• VERSION：使用者叢集的 Google Distributed Cloud 版本。
• YOUR_EMAIL_ADDRESS 和 ANOTHER_EMAIL_ADDRESS： 如果您未加入 --admin-users 旗標，身為叢集建立者，系統預設會授予您叢集管理員權限。但如果加入 --admin-users 指定其他使用者為管理員，就會覆寫預設值，因此必須同時加入您的電子郵件地址和其他管理員的電子郵件地址。舉例來說，如要新增兩位管理員：

      --admin-users=[e-mail] \
      --admin-users=[e-mail]

  建立叢集時，GKE On-Prem API 會將 Kubernetes 角色型存取權控管 (RBAC) 政策套用至叢集，授予您和其他管理員使用者 Kubernetes clusterrole/cluster-admin 角色，讓您能完整存取叢集和所有命名空間中的全部資源。

  注意：除了 Kubernetes RBAC 政策，您也必須為非專案擁有者的使用者授予部分 Identity and Access Management (IAM) 角色。 如要瞭解如何授予 IAM 角色，請參閱「授予必要角色」。

控制層節點

• --control-plane-node-configs： 控制層節點的 IPv4 位址。控制層節點會執行系統工作負載。請為每個控制層節點指定這個旗標。 一般來說，如為基本部署項目，控制層會使用 1 個機器，如為高可用性 (HA) 部署項目，則會使用 3 個機器。為確保高可用性，請指定奇數節點，以達到絕對多數。更新或升級叢集時，您可以隨時變更這些地址。

  標記的值採用以下格式：

    'node-ip=CP_IP_ADDRESS_1,labels=CP_KEY_1.1=CP_VALUE_1.1;CP_KEY_1.2=CP_VALUE_1.2;...' \

  值包含以關鍵字 node-ip 和 labels 開頭的區隔。並以半形逗號區隔每個區隔。

• node-ip：控制層節點的 IP 位址。每個標記只能指定一個 node-ip。如要指定多個節點，請為每個節點再次加入旗標。
• labels：附加至節點的一或多個 key=value 組合。

  請注意下列語法規則：

  • 以單引號括住整個值。
  • 不得包含空白字元。
  • 在 labels 區隔中，以半形分號分隔每對 key=value。

  視需要加入下列旗標：

• --control-plane-node-labels：使用這個標記將 標籤新增至所有控制平面節點。以半形逗號分隔鍵=值組合清單。
    --control-plane-node-labels=KEY_1=VALUE_1,KEY_2=VALUE_2

• --control-plane-node-taints：使用這個標記將新增至所有控制平面節點。每個汙點都是與效果相關聯的鍵值組，效果必須是下列其中一個：PreferNoSchedule、NoSchedule 或 NoExecute。

  以下範例會在控制層節點中新增三個節點。所有節點都標有 cp-node-pool-key=cp-node-pool-value，且具有汙染 dedicated=experimental:PreferNoSchedule。

    --control-plane-node-configs='node-ip=192.0.2.1' \
    --control-plane-node-configs='node-ip=192.0.2.2,labels=key2.1=value2.1' \
    --control-planer-node-configs='node-ip=192.0.2.3,labels=key3.1=value3.1;key3.2=value3.2' \
    --control-plane-node-labels=cp-node-pool-key=cp-node-pool-value \
    --control-plane-node-taints=dedicated=experimental:PreferNoSchedule \

虛擬 IP

• CONTROL_PLANE_VIP：您選擇在使用者叢集的 Kubernetes API 伺服器負載平衡器上設定的 IP 位址。

  範例：--control-plane-vip=203.0.113.3

• CONTROL_PLANE_LB_PORT：負載平衡器提供 Kubernetes API 伺服器服務的通訊埠。

  範例：-control-plane-load-balancer-port=443

• INGRESS_VIP：您選擇在負載平衡器上設定的 IP 位址，用於輸入 Proxy。

  範例：--ingress-vip=10.251.134.80

  Ingress VIP 的 IP 位址必須位於其中一個 MetalLB 位址集區。

服務和 Pod CIDR

• SERVICE_CIDR_BLOCK：以 CIDR 格式表示的 IP 位址範圍，用於叢集中的服務。CIDR 範圍必須介於 /24 和 /12 之間，其中 /12 可提供最多的 IP 位址。

  範例：--island-mode-service-address-cidr-blocks=10.96.0.0/20

• POD_CIDR_BLOCK：IP 位址範圍 (CIDR 格式)，用於叢集中的 Pod。CIDR 範圍必須介於 /18 和 /8 之間，其中 /8 可提供最多的 IP 位址。

  範例：--island-mode-pod-address-cidr-blocks=192.168.0.0/16

儲存空間

1. --lvp-share-path：這是主機機器路徑，可在其中建立子目錄。系統會為每個子目錄建立本機 PersistentVolume (PV)。
2. --lvp-share-storage-class：這是用於建立永久磁碟區的 StorageClass。系統會在建立叢集時建立 StorageClass。
3. --lvp-node-mounts-config-path：這是主機路徑，可供探索已掛接的磁碟。系統會為每個掛接項目建立本機 PersistentVolume (PV)。
4. --lvp-node-mounts-config-storage：叢集建立期間，用來建立 PV 的儲存空間類別。

如要進一步瞭解儲存空間，請參閱「設定本機儲存空間」。

執行 gcloud 指令建立叢集前，建議您加入 --validate-only，驗證您在 gcloud 指令的旗標中指定的設定。準備好建立叢集時，請移除這個標記並執行指令。

指令輸出內容如下所示：

Waiting for operation [projects/example-project-12345/locations/us-west1/operations/operation-1679543737105-5f7893fd5bae9-942b3f97-75e59179] to complete.

在範例輸出內容中，字串 operation-1679543737105-5f7893fd5bae9-942b3f97-75e59179 是長時間執行的作業的 OPERATION_ID。您可以使用下列指令查詢作業狀態：

gcloud container bare-metal operations describe OPERATION_ID \
  --project=FLEET_HOST_PROJECT_ID \
  --location=REGION

建立使用者叢集需要 15 分鐘以上的時間。您可以在 Google Cloud 控制台的「GKE clusters」(GKE 叢集) 頁面中查看叢集。

如需旗標的完整清單和說明，請參閱 gcloud CLI 參考資料。

建立節點集區

建立叢集後，您必須先建立至少一個節點集區，才能部署工作負載。節點集區是在這個叢集中建立的 worker 節點群組範本。使用 gcloud CLI 時，請先建立叢集，然後將一或多個節點集區新增至新建立的叢集。

gcloud container bare-metal node-pools create NODE_POOL_NAME \
  --cluster=USER_CLUSTER_NAME \
  --project=FLEET_HOST_PROJECT_ID \
  --location=REGION \
  --node-configs='node-ip=NP_IP_ADDRESS_1,labels=NP_KEY_1.1=NP_VALUE_1.1;NP_KEY_1.2=NP_VALUE_1.2;...'

更改下列內容：

• NODE_POOL_NAME：您為節點集區選用的名稱。名稱必須符合下列規定：

  • 最多可包含 40 個半形字元
  • 只能包含小寫英數字元或連字號 (-)
  • 開頭必須是字母字元
  • 結尾為英數字元

• USER_CLUSTER_NAME：新建立的使用者叢集名稱。

• FLEET_HOST_PROJECT_ID：叢集註冊的專案 ID。

• REGION：建立叢集時指定的 Google Cloud 區域。

• --node-configs： 工作節點機器的 IPv4 位址。請為每個節點指定這個旗標。標記的值採用以下格式：

  'node-ip=NP_IP_ADDRESS_1,labels=NP_KEY_1.1=NP_VALUE_1.1;NP_KEY_1.2=NP_VALUE_1.2;...' \
  

  值包含以關鍵字 node-ip 和 labels 開頭的區隔。並以半形逗號區隔每個區隔。

  • node-ip：工作站節點的 IP 位址。每個旗標只能指定一個 node-ip。針對節點集區中的每個節點，再次新增這個標記。

  • labels：附加至節點的一或多個 key=value 組合。

  請注意下列語法規則：

  • 以單引號括住整個值。
  • 不得包含空白字元。
  • 以半形分號分隔 labels 區段中的每個 key=value 組合。

  您也可以選擇指定下列項目：

  • --node-labels=KEY=VALUE,...：以半形逗號分隔的 Kubernetes 標籤 (鍵/值配對) 清單，會套用至集區中的每個節點。

  • --node-taints=KEY=VALUE:EFFECT,... 以半形逗號分隔的 Kubernetes 汙染清單，會套用至集區中的每個節點。汙點是與效果相關聯的 key=value 組合。taint 會搭配容許條件用於 Pod 排程。為 EFFECT 指定下列其中一個值：NoSchedule、PreferNoSchedule、NoExecute。

以下範例會在 user-cluster- 上建立名為 default-pool 的節點集區，並在該節點集區中新增兩個節點。兩個節點都標示 node-pool-key=node-pool-value，且具有 taint dedicated=experimental:PreferNoSchedule，

gcloud container bare-metal node-pools create default-pool \
  --cluster=user-cluster-1  \
  --project=example-project-12345 \
  --location=us-west1 \
  --node-configs='node-ip=10.200.0.10' \
  --node-configs='node-ip=10.200.0.11,labels=key2.1=value2.1' \
  --node-labels=node-pool-key=node-pool-value \
  --node-taints=dedicated=experimental:PreferNoSchedule

詳情請參閱 gcloud CLI 參考資料。

Terraform

事前準備

建立使用者叢集時選取的 Google Distributed Cloud (僅限軟體) 裸機版本，必須是管理員叢集支援的版本。此外，最新子版本或修補程式版本發布後，要過 7 到 14 天才會在 GKE On-Prem API 中提供。您可以執行 gcloud 指令，取得可用於安裝使用者叢集的支援版本清單。

1. 請務必更新元件：

   gcloud components update
   

2. 取得管理員叢集的名稱和機群成員位置：

   gcloud container fleet memberships list \
     --project=FLEET_HOST_PROJECT_ID
   

   將 FLEET_HOST_PROJECT_ID 替換為管理員叢集註冊的專案 ID。

   輸出結果會與下列內容相似：

   NAME             EXTERNAL_ID                           LOCATION
   admin-cluster-1  bb7803b4-8438-4b22-859f-4559b4b29072  global
   admin-cluster-2  ee16ee2b-6ec0-49fc-9413-3c89cbc70854  global
   admin-cluster-3  fc2b7ef5-39ff-4b63-b919-04c5adc67be4  us-west1
   

   位置會指定 Fleet 和 Connect 服務的執行位置。1.28 之前的管理叢集是由全域機群和 Connect 服務管理。在 1.28 以上版本中，建立管理叢集時，您可以指定 global 或 Google Cloud 區域。在下列範例指令中，您會在 --admin-cluster-membership-location 旗標中指定區域。

3. 取得可在使用者叢集上安裝的版本清單：

   gcloud container bare-metal clusters query-version-config \
     --admin-cluster-membership=ADMIN_CLUSTER_NAME \
     --admin-cluster-membership-project=FLEET_HOST_PROJECT_ID \
     --admin-cluster-membership-location=ADMIN_CLUSTER_REGION \
     --location=REGION
   

   更改下列內容：

   • ADMIN_CLUSTER_NAME：管理員叢集的名稱。

   • FLEET_HOST_PROJECT_ID：管理員叢集註冊的專案 ID。

   • ADMIN_CLUSTER_REGION：管理員叢集的 Fleet 成員區域。這可以是全域或 Google Cloud區域。使用 gcloud container fleet memberships list 輸出內容中的管理員叢集位置。

   • REGION：建立叢集時要使用的 Google Cloud 區域。這是 GKE On-Prem API 和 Fleet 與 Connect 服務的執行區域。指定 us-west1 或其他支援的區域。

   指令會輸出類似以下的結果：

   versions:
   - version: 1.16.2
   - version: 1.16.1
   - version: 1.16.0
   - version: 1.15.7
   - version: 1.15.6
   - version: 1.15.5
   

建議您使用支援的最高版本，取得最新的修正項目和改善措施。

範例

您可以使用下列基本設定範例，建立搭載 MetalLB 負載平衡器的使用者叢集。詳情請參閱google_gkeonprem_bare_metal_cluster參考說明文件。

在 terraform.tfvars 中設定變數

範例提供範例變數檔案，可傳遞至 main.tf，說明如何設定隨附的 MetalLB 負載平衡器。

1. 複製 anthos-samples 存放區，並變更為 Terraform 範例所在的目錄：

   git clone https://github.com/GoogleCloudPlatform/anthos-samples
   cd anthos-samples/anthos-onprem-terraform/abm_user_cluster_metallb
   

   範例提供範例變數檔案，可傳遞至 main.tf。

2. 建立 terraform.tfvars.sample 檔案副本：

   cp terraform.tfvars.sample terraform.tfvars
   

3. 修改 terraform.tfvars 中的參數值，然後儲存檔案。

   
   project_id          = "PROJECT_ID"
   region              = "ON_PREM_API_REGION"
   admin_cluster_name  = "ADMIN_CLUSTER_NAME"
   bare_metal_version  = "VERSION"
   admin_user_emails   = ["YOUR_EMAIL_ADDRESS", "ADMIN_2_EMAIL_ADDRESS"]
   cluster_name        = "abm-user-cluster-metallb"
   control_plane_ips   = ["10.200.0.4"]
   worker_node_ips     = ["10.200.0.5", "10.200.0.6"]
   control_plane_vip   = "10.200.0.50"
   ingress_vip         = "10.200.0.51"
   lb_address_pools    = [
       { name = "lbpool_1", addresses = ["10.200.0.51-10.200.0.70"] }
   ]
   

   變數說明如下：

   • project_id：要在其中建立叢集的專案 ID。指定的專案也會做為機群主專案。這必須與管理員叢集註冊的專案相同。建立使用者叢集後，系統會自動將其註冊至所選專案的機群。叢集建立後，就無法變更機群主機專案。

   • region：GKE On-Prem API (gkeonprem.googleapis.com)、Fleet 服務 (gkehub.googleapis.com) 和 Connect 服務 (gkeconnect.googleapis.com) 的執行 Google Cloud 區域。指定 us-west1 或其他支援的區域。

   重要事項： 如要安裝 Cloud Service Mesh，請務必安裝 1.19.3 以上版本。這是必要步驟，因為 Fleet 和 Connect 服務會在特定區域中執行。

   • admin_cluster_name：管理使用者叢集的管理員叢集名稱。這個範例假設管理員叢集使用 global 做為區域。如果您有區域管理員叢集：

     1. 在文字編輯器中開啟 main.tf。

     2. 搜尋 admin_cluster_membership，看起來如下所示：

        admin_cluster_membership = "projects/${var.project_id}/locations/global/memberships/${var.admin_cluster_name}"

     3. 將 global 變更為管理員叢集使用的區域，然後儲存檔案。

   • bare_metal_version：使用者叢集的 Google Distributed Cloud 版本。指定與管理員叢集相同的版本，或比管理員叢集低一個子版本。

   • admin_user_emails：要授予叢集管理權限的使用者電子郵件地址清單。如果您打算管理叢集，請務必新增電子郵件地址。

     建立叢集時，GKE On-Prem API 會將 Kubernetes 角色型存取權控管 (RBAC) 政策套用至叢集，授予管理員使用者 Kubernetes clusterrole/cluster-admin 角色，讓使用者能完整存取叢集和所有命名空間中的全部資源。使用者也能透過 Google 身分識別登入控制台。

   • cluster_name：使用者叢集的名稱，可自行選擇。叢集建立完成後即無法變更名稱。名稱必須符合下列規定：

     • 最多可包含 40 個半形字元
     • 只能包含小寫英數字元或連字號 (-)
     • 開頭必須是字母字元
     • 結尾為英數字元

   • control_plane_ips：控制平面節點的一或多個 IPv4 位址清單。控制層節點會執行系統工作負載。一般來說，如為基本部署項目，控制層會使用 1 個機器，如為高可用性 (HA) 部署項目，則會使用 3 個機器。為確保高可用性，請指定奇數節點，以達到絕對多數。更新或升級叢集時，您可以隨時變更這些位址。

   • worker_node_ips：工作節點機器的 IPv4 位址清單 (一或多個)。

   • control_plane_vip：您選擇在使用者叢集的 Kubernetes API 伺服器負載平衡器上設定的虛擬 IP 位址 (VIP)。

   • ingress_vip：您選擇在負載平衡器上設定的 IP 位址，用於輸入 Proxy。

   • lb_address_pools：定義 MetalLB 負載平衡器所用位址集區的地圖清單。Ingress VIP 必須位於其中一個集區。

4. 在 terraform.tfvars 中儲存變更。

5. 初始化並建立 Terraform 方案：

   terraform init
   

   Terraform 會安裝任何需要的程式庫，例如 Google Cloud 供應商。

6. 檢查設定並視需要進行變更：

   terraform plan
   

7. 套用 Terraform 方案，建立使用者叢集：

   terraform apply
   

   建立使用者叢集需要 15 分鐘以上的時間。您可以在 Google Cloud 控制台的「GKE clusters」(GKE 叢集) 頁面中查看叢集。

連線至使用者叢集

在控制台中建立使用者叢集時，系統會使用 Kubernetes 角色型存取權控管 (RBAC) 政策設定叢集，讓您使用 Google Cloud 身分登入叢集。使用 gcloud CLI 建立使用者叢集時，如果未加入 --admin-users 標記，系統預設會授予這些 RBAC 政策。如果您加入 --admin-users 指定其他使用者為管理員，系統會覆寫預設值，因此您必須同時加入自己的電子郵件地址和其他管理員的電子郵件地址。如要進一步瞭解必要的 IAM 和 RBAC 政策，請參閱「設定 Google 身分驗證」。

所有叢集都有標準端點，端點會公開 Kubernetes API 伺服器，讓 kubectl 和其他服務透過 TCP 通訊埠 443 與叢集控制層通訊。這個端點無法透過公開網際網路存取。如果您可以透過 VPC 存取叢集的私密端點，可以直接連線至私密端點並直接產生 kubeconfig 檔案。否則，請使用連線閘道。

如要透過指令列存取使用者叢集，您需要 kubeconfig 檔案。 取得 kubeconfig 檔案的方法有兩種：

• 使用連線閘道，從已安裝 Google Cloud CLI 的電腦存取叢集。在這種情況下，kubectl 會使用 Connect 閘道的 kubeconfig，代表您安全地將流量轉送至私有端點。

• 如要直接存取私人端點，請在管理員工作站上建立 kubeconfig 檔案，並從管理員工作站管理叢集。

請務必等待 Google Cloud 控制台顯示使用者叢集狀態為正常。

連結閘道

1. 初始化 gcloud CLI，以便搭配機群主機專案使用，或執行下列指令，登入 Google 帳戶、將機群主機專案設為預設專案，並更新元件：

   gcloud auth login
   gcloud config set project PROJECT_ID
   gcloud components update
   

2. 擷取用於與 Connect 閘道互動的叢集憑證。在下列指令中，將 MEMBERSHIP_NAME 替換為叢集名稱。如果是裸機上的 Google Distributed Cloud (僅限軟體)，成員名稱與叢集名稱相同。

   gcloud container fleet memberships get-credentials MEMBERSHIP_NAME
   

   這項指令會傳回專用的連線閘道kubeconfig，可讓您透過閘道連線至叢集。

取得必要憑證後，您就可以使用 kubectl 執行指令，就像對任何 Kubernetes 叢集執行指令一樣，而且不需要指定 kubeconfig 檔案的名稱，例如：

kubectl get namespaces

管理員工作站

使用 bmctl get credentials 指令，為新建立的使用者叢集擷取 kubeconfig 檔案。

bmctl get credentials --cluster CLUSTER_NAME --admin-kubeconfig ADMIN_KUBECONFIG_PATH

更改下列內容：

• CLUSTER_NAME：目標使用者叢集的名稱。

• ADMIN_KUBECONFIG_PATH：管理員叢集 kubeconfig 檔案的路徑。

使用使用者叢集的憑證，將 kubeconfig 寫入檔案 bmctl-workspace/CLUSTER_NAME/CLUSTER_NAME-TIMESTAMP-kubeconfig。檔案名稱中的 TIMESTAMP 表示檔案的建立日期和時間。

由於這個檔案包含叢集的驗證憑證，因此請將其儲存在安全的位置，並限制存取權。

後續步驟

• 使用 SELinux 保護容器
• 透過 Google Cloud 控制台管理叢集