使用 GKE On-Prem API 用戶端建立管理員叢集

控制台

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

   前往「建立裸機叢集」

2. 選取要建立叢集的 Google Cloud 專案。 選取的專案也會做為機群主專案。

「必要條件」頁面會顯示管理工作站和叢集節點機器的需求。「網路需求」部分中的 IP 位址規劃工具，可協助您規劃安裝一個管理員叢集和一個使用者叢集時所需的 IP 位址。

設定管理員工作站的必要步驟

展開這個部分，即可查看管理員工作站的硬體、作業系統和連線需求。

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

展開這個部分，即可查看叢集節點機器的硬體、作業系統和連線需求。

網路需求

本節將協助您規劃最精簡環境所需的 IP 位址。(選用) 在「節點 IP 和虛擬 IP 位址」部分，您可以提供起始節點 IP 位址和虛擬 IP 位址 (VIP)，主控台會顯示您需要的 IP 位址表格。這些 IP 位址不會套用至管理員叢集設定。這些 IP 位址僅供參考，可協助您規劃安裝作業所需的 IP 位址。您可以將表格下載為 CSV 檔案，然後匯入試算表或 IP 位址規劃工具，做為追蹤叢集所需 IP 位址的起點。

檢查 Google Cloud 資源：

確認已在車隊主專案中啟用所有必要的 Google API。此外，您還需要啟用 GKE On-Prem API：

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

將 FLEET_HOST_PROJECT_ID 替換為車隊主專案的專案 ID。

建立叢集前，請先在管理員工作站上執行 bmctl register bootstrap 指令，如「準備啟動環境」一文所述。這個指令可以建立必要的服務帳戶，並授予建立管理員叢集所需的最低 IAM 權限。您也可以選擇手動設定服務帳戶。

準備好開始時，請按一下左側導覽列中的「Install bootstrap environment」(安裝啟動程序環境)。

gcloud CLI

硬體、網路和作業系統必要條件

使用 GKE On-Prem API 用戶端建立管理員叢集時，需要與使用 bmctl 建立叢集時相同的硬體、網路和作業系統先決條件。詳情請參閱「安裝必要條件」。

必要 Google API

確認已在車隊主專案中啟用所有必要的 Google API。此外，您還需要啟用 GKE On-Prem API：

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

將 FLEET_HOST_PROJECT_ID 替換為車隊主專案的專案 ID。

必要服務帳戶和權限

建立叢集前，請先在管理員工作站上執行 bmctl register bootstrap 指令，如「準備啟動環境」一文所述。這個指令可以建立必要的服務帳戶，並授予建立管理員叢集所需的最低 IAM 權限。您也可以選擇手動設定服務帳戶。

規劃 IP 位址

建立管理員叢集前，請先規劃叢集的 IP 位址。請參閱「規劃 IP 位址」一文，瞭解如何為高可用性 (HA) 管理員叢集和兩個 HA 使用者叢集分配 IP 位址。即使您將使用 gcloud CLI 建立管理員叢集，還是可以按照本節中的主控台步驟，使用 IP 位址規劃工具。

控制台

1. 輸入管理員叢集的名稱。請注意，啟動叢集名稱是透過在管理員叢集名稱前加上 bootstrap- 衍生而來。

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. 控制台會顯示您需要在管理員工作站上執行的指令。bmctl 指令列工具必須與您要建立的叢集版本相符。如果管理員工作站已下載適用版本的 bmctl，則不必再次下載。

gcloud CLI

1. 請務必更新元件：

   gcloud components update
   

2. 執行下列指令，使用 Google 帳戶登入：

   gcloud auth login
   

3. 列出可安裝的 Bare Metal 叢集版本：

   您下載用來建立啟動環境的 bmctl 版本，必須與您要在管理員叢集上安裝的版本相符。

   gcloud container bare-metal admin-clusters query-version-config \
     --location=REGION
   

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

bmctl 建立 SA

如要bmctl建立必要服務帳戶，並授予建立管理員叢集所需的最低權限，請使用下列指令。這個指令假設 bmctl 位於目前的工作目錄。

./bmctl register bootstrap \
  --ssh-key=YOUR_PRIVATE_KEY \
  --target-cluster-name=ADMIN_CLUSTER_NAME \
  --project-id=FLEET_HOST_PROJECT_ID

更改下列內容：

• YOUR_PRIVATE_KEY：私密安全殼層金鑰的路徑。您在設定節點的根層級安全殼層存取權時，建立了安全殼層金鑰。

如果您複製了控制台中顯示的指令，系統會自動填入下列欄位。

• ADMIN_CLUSTER_NAME：管理員叢集名稱。

• FLEET_HOST_PROJECT_ID：叢集建立後，管理員叢集會自動註冊的專案。

bmctl register bootstrap 指令會建立下列服務帳戶：服務帳戶金鑰會儲存在 bmctl-workspace/.sa-keys 目錄中。

指定服務帳戶金鑰檔案

您也可以傳遞您建立的服務帳戶金鑰檔案 bmctl。下列指令會使用「手動設定服務帳戶」中的金鑰檔案名稱，並假設 bmctl 和金鑰檔案位於目前的工作目錄中。

./bmctl register bootstrap \
  --ssh-key=YOUR_PRIVATE_KEY \
  --target-cluster-name=ADMIN_CLUSTER_NAME \
  --project-id=FLEET_HOST_PROJECT_ID \
  --gcr-service-account-key=anthos-baremetal-gcr.json \
  --gke-agent-service-account-key=connect-agent.json \
  --gke-register-service-account-key=connect-register.json \
  --cloud-operation-service-account-key=anthos-baremetal-cloud-ops.json

更改下列內容：

• YOUR_PRIVATE_KEY：私密安全殼層金鑰的路徑。您在設定節點的根層級安全殼層存取權時，建立了安全殼層金鑰。

• ADMIN_CLUSTER_NAME：管理員叢集名稱。

• FLEET_HOST_PROJECT_ID：叢集建立後，管理員叢集會自動註冊的專案。

下列旗標會指定金鑰檔案的路徑：

• -gcr-service-account-key：服務帳戶的金鑰檔案路徑，用於提取容器映像檔 (anthos-baremetal-gcr)。

• --gke-agent-service-account-key：Connect Agent 服務帳戶的金鑰檔案路徑 (anthos-baremetal-connect)。

• --gke-register-service-account-key：Connect Agent 服務帳戶的金鑰檔案路徑，該帳戶會將叢集註冊至車隊 (anthos-baremetal-register)。

• --cloud-operation-service-account-key：服務帳戶的稽核記錄和監控專案金鑰檔案路徑 (anthos-baremetal-cloud-ops)。

控制台

1. 在「Install bootstrap environment」(安裝啟動程序環境) 頁面上，按一下「Check Connection」(檢查連線)。

   成功後，主控台會顯示「Connection established」(已建立連線) check_circle。

   必須先建立與啟動程序叢集的連線，才能繼續。如果連線未建立，請檢查您為 bmctl register bootstrap 指令指定的引數：

   • 請確認 --target-cluster-name 的值與「Bootstrap environment basics」(啟動環境基本資訊) 部分顯示的「Admin cluster name」(管理員叢集名稱) 相符。

   • 確認 --project-id 的值與您在控制台中選取的專案 ID 相符。

   如要變更啟動程序叢集名稱或專案 ID，請輸入 Ctrl-C 退出 bmctl register bootstrap，然後重新執行指令。

2. 按一下「下一步」，開始設定管理員叢集。主控台中的大部分設定都對應至叢集設定檔中的欄位。

3. 在「節點設定」下方，於「每個節點的 Pod 數上限」輸入介於 64 到 250 之間的值，或接受預設值 110。叢集建立後，您就無法更新這個值。

   每個節點的 Pod 數上限 (稱為 Pod 密度) 也會受到叢集可用 IP 資源的限制。詳情請參閱「Pod 網路」。

4. 點選「下一步」。

5. 在「網路」頁面中，定義叢集中的節點和元件如何互相通訊，以及與 Kubernetes 控制層通訊。

   如需詳細資訊，請將指標懸停在每個欄位旁的 question_mark 上。

6. 按一下「驗證並建立」。

   主控台會顯示狀態訊息，同時驗證設定並在資料中心建立叢集。

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

gcloud CLI

建立管理員叢集前，請先確認啟動叢集已註冊為機群成員：

gcloud container fleet memberships list \
  --project=FLEET_HOST_PROJECT_ID

如果沒有列出啟動叢集，請檢查您指定的啟動叢集名稱和專案 ID bmctl register bootstrap。如要變更啟動程序叢集名稱或專案 ID，請輸入 Ctrl-C 退出 bmctl register bootstrap，然後重新執行指令。

使用下列指令建立管理員叢集：

gcloud container bare-metal admin-clusters create

您為指令指定的標記，大多會對應至使用者叢集設定檔中的欄位。

如要使用套裝組合負載平衡器建立管理員叢集，請按照下列步驟操作：

gcloud container bare-metal admin-clusters create ADMIN_CLUSTER_NAME \
  --project=FLEET_HOST_PROJECT_ID \
  --location=REGION \
  --version=VERSION \
  --max-pods-per-node=MAX_PODS_PER_NODE \
  --control-plane-vip=CONTROL_PLANE_VIP \
  --control-plane-load-balancer-port=CONTROL_PLANE_LOAD_BALANCER_PORT \
  --control-plane-node-configs 'CONTROL_PLANE_NODE_CONFIG' \
  --island-mode-service-address-cidr-blocks=SERVICE_ADDR_CIDR \
  --island-mode-pod-address-cidr-blocks=POD_ADDR_CIDR \
  --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

如要使用手動負載平衡，請在指令中加入 --enable-manual-lb。

更改下列內容：

• ADMIN_CLUSTER_NAME：管理員叢集名稱。 叢集建立完成後即無法變更名稱。

• FLEET_HOST_PROJECT_ID：叢集建立後，管理員叢集會自動註冊的專案。叢集建立後，就無法變更機群主機專案。

• REGION：GKE On-Prem API 執行的 Google Cloud 區域。指定 us-west1 或其他支援的區域。叢集建立後，就無法變更區域。這項設定會指定下列項目的儲存區域：

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

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

• VERSION：不含作業系統的叢集版本。版本必須與您用來執行 bmctl register bootstrap 的 bmctl 版本相符。您可以在管理員工作站上執行 bmctl version，查看 bmctl 版本。

• MAX_PODS_PER_NODE ：對於管理員叢集，允許的值為 32 到 250，非高可用性叢集則為 64 到 250。如果指令中未包含 --max-pods-per-node，預設值為 110。叢集建立後，這個值就無法更新。

  每個節點的 Pod 數上限 (稱為 Pod 密度) 也會受到叢集可用 IP 資源的限制。詳情請參閱「Pod 網路」。

• CONTROL_PLANE_VIP：叢集 Kubernetes API 伺服器負載平衡器中的虛擬 IP (VIP)。請填入控制層 VIP，這個 VIP 必須與負載平衡器節點位於相同的子網路。請勿填入負載平衡器位址集區中的控制層 VIP。

• CONTROL_PLANE_LOAD_BALANCER_PORT：負載平衡器提供控制層服務的通訊埠。雖然可以設定其他值，但通訊埠 443 是 HTTPS 連線使用的標準通訊埠。

• CONTROL_PLANE_NODE_CONFIG：控制平面節點的 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-configs 'node-ip=192.0.2.1' \
  --control-plane-node-configs 'node-ip=192.0.2.2,labels=key2.1=value2.1' \
  --control-plane-node-configs 'node-ip=192.0.2.3,labels=key3.1=value3.1;key3.2=value3.2' \
  

• SERVICE_ADDR_CIDR：叢集內 Service 的 IPv4 位址範圍 (CIDR 格式)。CIDR 範圍必須介於 /24 和 /12 之間，其中 /12 可提供最多的 IP 位址。建議您使用私人網際網路的 IP 位址空間範圍 (如 10.96.0.0/20)，這類範圍定義於 RFC 1918。

• POD_ADDR_CIDR：以 CIDR 格式表示的 IPv4 位址範圍，用於使用者叢集中的 Pod。CIDR 範圍必須介於 /18 和 /8 之間，其中 /8 可提供最多的 IP 位址。建議您使用私人網際網路的 IP 位址空間範圍 (如 192.168.0.0/16)，這類範圍定義於 RFC 1918。

您必須指定下列儲存空間旗標。範例指令包含一般值。詳情請參閱「設定本機儲存空間」。

• --lvp-share-path：這是主機機器路徑，可建立子目錄。系統會為每個子目錄建立本機 PersistentVolume (PV)。

• --lvp-share-storage-class：這是用於建立永久磁碟的 StorageClass。系統會在建立叢集時建立 StorageClass。

• --lvp-node-mounts-config-path：這是主機路徑，可供探索已掛接的磁碟。系統會為每個掛接點建立本機 PersistentVolume (PV)。

• --lvp-node-mounts-config-storage：在叢集建立期間，用來建立 PV 的儲存空間類別。

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

指令輸出內容如下所示：

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

詳情請參閱 gcloud container bare-metal operations。

修正預檢錯誤

建立叢集前，bmctl 會執行一系列預檢，驗證設定。如果設定有問題，gcloud ... create 指令會結束，並顯示類似下列內容的錯誤訊息：

ERROR: (gcloud.container.bare-metal.admin-clusters.create) Invalid resource state for "projects/694677185633/locations/us-west1/bareMetalAdminClusters/abm-cluster-1": cluster preflight checks failed

舉例來說，假設預檢失敗是因為無法連線至控制層節點。管理員工作站會顯示類似下列的內容：

[2023-03-27 20:34:38+0000] Waiting for preflight check job to finish... OK
[2023-03-27 20:35:58+0000] - Validation Category: machines and network
[2023-03-27 20:35:58+0000]    - [PASSED] pod-cidr
[2023-03-27 20:35:58+0000]    - [FAILED] node-network (log: bmctl-workspace/log/register-bootstrap-20230327-201548/node-network)
[2023-03-27 20:35:58+0000]        - Failed to connect to the host via ssh: ssh: connect to host 10.100.0.5 port 22: Connection timed out
[2023-03-27 20:35:58+0000] Flushing logs... OK
[2023-03-27 20:35:58+0000] Error polling the preflight check abm-cluster-mar-27 in the cluster-abm-cluster-mar-27: preflight check failed

1. 在管理員工作站上，確認 bmctl register bootstrap 程序仍在執行中。如果不是，請使用相同引數重新執行指令，並新增 --reuse-bootstrap-cluster=true 標記。

2. 執行 gcloud ... update，修正無效的 IP 位址：

   gcloud container bare-metal admin-clusters update ADMIN_CLUSTER_NAME \
     --project=FLEET_HOST_PROJECT_ID \
     --location=REGION \
     --control-plane-node-configs 'node-ip=NEW_NODE_ID_ADDRESS'
   

   詳情請參閱 gcloud container bare-metal admin-clusters update。