使用 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

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

• 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 (稱為機群主機專案)，必須與您要建立使用者叢集的專案相同。

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

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

指令列存取權

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

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

• 最新版 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，則可能需要使用 Terraform 建立叢集及管理叢集生命週期。

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

控制台

控制台中的大部分設定都對應至叢集設定檔中的欄位。

1. 在控制台中，前往「Create a bare metal cluster」(建立裸機叢集) 頁面。

   前往「Create a bare metal cluster」(建立 bare metal 叢集) 頁面

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

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

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

叢集基本資訊

輸入叢集的基本資訊。

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

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

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中叢集的專屬 ID。

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

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

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

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

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

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

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

7. 點選「下一步」，前往「網路」部分。

網路

在本節中，您將指定叢集節點、Pod 和 Service 的 IP 位址。如果您使用隨附的負載平衡功能搭配 MetalLB，也需要進行設定。

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

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

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

   隨附於 MetalLB

   使用隨附的 MetalLB 負載平衡器設定負載平衡。如果選擇這個選項，Google Distributed Cloud 會部署第 4 層負載平衡器，在專屬的 worker 節點集區或與控制層相同的節點上運作。

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

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

      • 建立負載平衡器節點集區：如需在專屬 worker 節點集區中執行負載平衡器，請選擇這個進階選項。負載平衡器節點集區中的所有節點，都必須與您在「Load balancer address pools」(負載平衡器位址集區) 區段中設定的負載平衡器虛擬 IP (VIP) 位於同一個第 2 層子網路。

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

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

   2. 在「Load balancer address pools」(負載平衡器位址集區) 區段中，新增一或多個位址集區，供 MetalLB 控制器選擇並指派給 LoadBalancer 類型的 Service。您在「Virtual IPs」(虛擬 IP) 區段中指定的輸入 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. 如果輸入 VIP 不在位址範圍內，請選取「+ Add IP Address Range」(+ 新增 IP 位址範圍)，然後輸入包含輸入 VIP 的其他位址範圍。

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

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

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

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

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

      7. 視需要按一下「Add Address Pool」(新增位址集區)。

   手動負載平衡器

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

3. 在「Virtual IPs」(虛擬 IP) 部分，輸入下列內容：

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

   • Port：傳送至 Kubernetes API 伺服器的流量所使用的目的地通訊埠。預設值為 443。

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

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

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

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

5. 在「Advanced attributes」(進階屬性) 屬性部分，視需要指定下列項目：

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

   • 網址：以逗號分隔的清單，列出不應透過 Proxy 伺服器的 IP 位址、IP 位址範圍、主機名稱和網域名稱。當 Google Distributed Cloud 向這些位址、主機或網域傳送要求時，會直接傳送要求。

6. 點選「下一步」。

儲存空間

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

1. 您也可以視需要進行下列設定：

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

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

2. 點選「下一步」。

功能與特色

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

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

在控制台中建立節點集區

叢集至少須有一個 worker 節點集區。在這個叢集中建立的 worker 節點群組會以節點集區為範本。

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

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

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

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

4. 在「Node pool metadata (optional)」(節點集區中繼資料 (選用)) 區段中，如要新增 Kubernetes 標籤和污點，請執行下列操作：

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

5. 按一下「Verify and Complete」(驗證並完成)，建立使用者叢集。建立使用者叢集需要 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
   

   位置會指定機群和 Connect 服務的執行位置。1.28 版之前建立的管理員叢集，是由全域 Fleet 和 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：管理員叢集的機群成員資格區域。可以是全域或 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中叢集的專屬 ID。

  重要事項：如要安裝 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 位址指派給 Service，請將這個值設為 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： 根據預設，負載平衡器會在與控制層相同的節點上執行。如要在專屬的 worker 節點集區上執行負載平衡器，請為每個節點指定這個旗標。負載平衡器節點集區中的所有節點，都必須與負載平衡器虛擬 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：附加至節點的一或多個鍵/值組合。

  請注意下列語法規則：

  • 請用單引號括住整個值。
  • 不得包含空白字元。
  • 請使用分號分隔 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：使用這個旗標，將污點新增至負載平衡器節點集區中的所有節點。每個污點都是與效果相關聯的 key=value 組合，效果必須是下列其中一項：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：附加至節點的一或多個鍵/值組合。

  請注意下列語法規則：

  • 請用單引號括住整個值。
  • 不得包含空白字元。
  • 請以半形分號隔開 labels 區隔中的每組鍵/值。

  視需要加入下列旗標：

• --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：您選擇在負載平衡器上設定的 IP 位址，用於使用者叢集的 Kubernetes API 伺服器。

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

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

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

• INGRESS_VIP：您選擇在 Ingress Proxy 負載平衡器上設定的 IP 位址。

  範例：--ingress-vip=10.251.134.80

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

服務和 Pod CIDR

• SERVICE_CIDR_BLOCK：叢集內 Service 使用的 IP 位址範圍，格式為 CIDR。CIDR 範圍必須介於 /24 和 /12 之間，其中 /12 可提供最多的 IP 位址。

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

• POD_CIDR_BLOCK：叢集內 Pod 要使用的 IP 位址範圍，格式為 CIDR。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中叢集的專屬 ID。

  重要事項：如要安裝 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：附加至節點的一或多個鍵/值組合。

  請注意下列語法規則：

  • 請用單引號括住整個值。
  • 不得包含空白字元。
  • 請以半形分號隔開 labels 區隔中的每組鍵/值。

  視需要加入下列旗標：

• --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：您選擇在負載平衡器上設定的 IP 位址，用於使用者叢集的 Kubernetes API 伺服器。

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

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

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

• INGRESS_VIP：您選擇在 Ingress Proxy 負載平衡器上設定的 IP 位址。

  範例：--ingress-vip=10.251.134.80

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

服務和 Pod CIDR

• SERVICE_CIDR_BLOCK：叢集內 Service 使用的 IP 位址範圍，格式為 CIDR。CIDR 範圍必須介於 /24 和 /12 之間，其中 /12 可提供最多的 IP 位址。

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

• POD_CIDR_BLOCK：叢集內 Pod 要使用的 IP 位址範圍，格式為 CIDR。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：worker 節點機器的 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：worker 節點的 IP 位址。每個旗標只能指定一個 node-ip。為節點集區中的每個節點再次新增這個旗標。

  • labels：附加至節點的一或多個鍵/值組合。

  請注意下列語法規則：

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

  您也可以視需要指定下列項目：

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

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

以下範例會在 user-cluster- 上建立名為 default-pool 的節點集區，並在節點集區中新增兩個節點。兩個節點都標有 node-pool-key=node-pool-value，且具有 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

事前準備

建立使用者叢集時，您選取的 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
   

   位置會指定機群和 Connect 服務的執行位置。1.28 版之前建立的管理員叢集，是由全域 Fleet 和 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：管理員叢集的機群成員資格區域。可以是全域或 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 以上版本。這是因為機群和 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：worker 節點機器的一或多個 IPv4 位址清單。

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

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

   • 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 Identity 驗證」。

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

如要透過指令列存取使用者叢集，您需要 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 替換為叢集名稱。如果是僅限裸機的 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 控制台管理叢集