安裝 Google Kubernetes Symphony 供應商

如要將 IBM Symphony 與 Google Kubernetes Engine (GKE) 整合，以進行動態資源管理，您必須安裝及設定 GKE 的 Symphony 供應商。這個供應商可讓 Symphony 在 GKE 叢集中以 Pod 形式佈建及管理運算資源，透過 Kubernetes 自動化調度管理功能，有效率地調度工作負載資源。

如要啟用這項整合功能，請在叢集中安裝 Kubernetes 運算子，在 Symphony 主要主機上安裝供應商外掛程式，並設定 Symphony 的主機出廠服務，與 GKE 通訊。

如要進一步瞭解 Symphony Connectors for Google Cloud，請參閱「整合 IBM Spectrum Symphony 與Google Cloud」。

事前準備

如要安裝 GKE 的 Symphony 供應商，您必須具備下列資源：

• 已啟用主機出廠服務的 IBM Spectrum Symphony 叢集。
• 正在執行的 GKE 叢集。如要建立叢集，請參閱 GKE 總覽。
• 具備適當權限的服務帳戶。詳情請參閱「必要角色」一節。
• kubectl 指令列工具已安裝並設定為與 GKE 叢集通訊。

必要的角色

如要取得安裝運算子及管理 Symphony Pod 所需的權限，請要求管理員在專案中授予您下列 IAM 角色：

• 如要管理 Kubernetes 資源： Kubernetes Engine 管理員 (roles/container.admin)

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

您或許也能透過自訂角色或其他預先定義的角色，取得必要權限。

安裝 Kubernetes 運算子

安裝 GKE 供應商前，請先安裝相關聯的 Kubernetes 運算子。運算子會管理 GKE 叢集內的 Symphony 運算 Pod 生命週期。

建構運算子映像檔

如要產生及部署運算子的 Kubernetes 資訊清單，您必須先建構運算子容器映像檔。資訊清單包含運算子用來管理 Symphony 的自訂資源定義 (CRD)。如要取得映像檔，可以從來源建構。

如要從來源建構運算子映像檔，請完成下列步驟：

1. 從 GitHub 複製 symphony-gcp-connector 存放區：

   git clone https://github.com/GoogleCloudPlatform/symphony-gcp-connector.git
   

2. 請前往 k8s-operator 目錄：

   cd symphony-gcp-connector/k8s-operator
   

3. 設定映像檔名稱、登錄檔和標記的環境變數：

   export IMAGE="gcp-symphony-operator"
   export REGISTRY="IMAGE_REPO"
   export TAG="TAG"
   

   更改下列內容：

   • IMAGE_REPO：儲存運算子映像檔的映像檔存放區。舉例來說，您可以使用 Artifact Registry 儲存運算子映像檔。詳情請參閱「建立 Docker 存放區」。
   • TAG：運算子圖片的標記，例如 0.0.1。

4. 建構並推送運算子映像檔：

   bash -c 'docker buildx build --platform linux/amd64 -t $IMAGE:$TAG -t $IMAGE:latest -t $REGISTRY/$IMAGE:$TAG -t $REGISTRY/$IMAGE:latest .'
   bash -c 'docker push $REGISTRY/$IMAGE:$TAG && docker push $REGISTRY/$IMAGE:latest'
   

設定運算子資訊清單

取得運算子映像檔後，您需要產生及設定 Kubernetes 資訊清單。

1. 如要產生資訊清單，請使用 export-manifests 指令搭配運算子映像檔：

   docker run --rm gcp-symphony-operator:latest export-manifests > manifests.yaml
   

2. 在您選擇的文字編輯器中開啟 manifests.yaml 檔案。

3. 在 spec.template.spec.containers 區段中，找出 image 欄位，然後將其值更新為您推送至登錄檔的圖片完整路徑。

   ...
   containers:
   - image: IMAGE_REPO/gcp-symphony-operator:TAG
     name: manager
   ...
   

   更改下列內容：

   • IMAGE_REPO：您推送運算子映像檔的映像檔存放區路徑。

   • TAG：您在建構運算子映像檔時指派給該映像檔的標記。

4. 選用：您也可以修改 imagePullPolicy 值，配合叢集管理做法。

套用運算子資訊清單

設定資訊清單後，請將其套用至 Kubernetes 叢集。您可以使用 kubectl 或 Cluster Toolkit 套用資訊清單。

• kubectl：如要使用 kubectl 套用資訊清單，請執行下列指令：

  kubectl apply -f manifests.yaml
  

• Cluster Toolkit：如果您的 GKE 基礎架構是由 Cluster Toolkit 管理，請在 GKE 藍圖中新增 modules/management/kubectl-apply 來源，以套用資訊清單。以下是設定範例，假設 manifests.yaml 檔案與 GKE 藍圖位於相同目錄：

    -   id: symphony_operator_install
        source: modules/management/kubectl-apply
        use: [gke_cluster]
        settings:
        apply_manifests:
          -   source: $(ghpc_stage("manifests.yaml"))
  

  詳情請參閱「叢集工具包總覽」。

載入主機工廠環境變數

如要設定或管理主機工廠服務，必須先將 Symphony 環境變數載入至 Shell 工作階段。在 Symphony 主要主機 VM 上，執行下列指令：

source INSTALL_FOLDER/profile.platform

將 INSTALL_FOLDER 替換為安裝資料夾的路徑。Symphony 的預設安裝資料夾路徑為 /opt/ibm/spectrumcomputing。不過，如果您將 Symphony 安裝在其他位置，就必須使用環境的正確路徑。

這個指令會執行 profile.platform 指令碼，匯出 $EGO_TOP 和 $HF_TOP 等重要環境變數，並將 Symphony 指令列工具新增至殼層的 PATH。您必須為每個新的終端機工作階段執行這項指令，確保環境設定正確。

安裝供應商外掛程式

如要將 GKE 供應商與 Symphony 的主機工廠整合，請從 RPM 套件安裝預先建構的供應商外掛程式，或從原始碼建構供應商。

安裝預先建構的供應商外掛程式

如要使用 RPM 套件安裝供應器外掛程式，請在 Symphony 主要主機 VM 上執行下列步驟：

1. 為 Google Cloud Symphony 連接器新增 yum 存放區：

   sudo tee /etc/yum.repos.d/google-cloud-symphony-connector.repo << EOM
   [google-cloud-symphony-connector] name=Google Cloud Symphony Connector
   baseurl=https://packages.cloud.google.com/yum/repos/google-cloud-symphony-connector-x86-64
   enabled=1
   gpgcheck=0
   repo_gpgcheck=0
   gpgkey=https://packages.cloud.google.com/yum/doc/yum-key.gpg
          https://packages.cloud.google.com/yum/doc/rpm-package-key.gpg
   EOM
   

2. 安裝 GKE 的供應商套件：

   sudo yum install -y hf-gcpgke-provider.x86_64
   

RPM 安裝作業會自動將供應商可執行檔和指令碼放在 Symphony 主機出廠服務的正確目錄中。安裝後，供應商外掛程式的目錄結構會顯示在 $HF_TOP/$HF_VERSION/providerplugins/gcpgke 路徑中，如下所示：

├── bin
│   ├── hf-gke
│   └── README.md
└── scripts
    ├── getAvailableTemplates.sh
    ├── getRequestStatus.sh
    ├── getReturnRequests.sh
    ├── requestMachines.sh
    └── requestReturnMachines.sh

從原始碼建構供應商

如要在供應商外掛程式目錄的 bin 目錄中建構及安裝 CLI 可執行檔，請按照下列步驟操作：

1. 從 GitHub 複製 symphony-gcp-connector 存放區：

   git clone https://github.com/GoogleCloudPlatform/symphony-gcp-connector.git
   

2. 請前往 hf-provider 目錄：

   cd PROJECT_ROOT/hf-provider
   

   將 PROJECT_ROOT 替換為包含 hf-provider 目錄的頂層目錄路徑，例如 /home/user/symphony-gcp-connector。

3. 如果沒有安裝 uv，請安裝：

   pip install uv
   

4. 使用 uv Python 套件管理工具建立 Python 虛擬環境：

   uv venv
   

5. 啟用虛擬環境：

   source .venv/bin/activate
   

6. 安裝必要的專案依附元件：

   uv pip install .
   

7. 安裝 PyInstaller，將 Python 應用程式封裝成獨立可執行檔：

   uv pip install pyinstaller
   

8. 建立 Google Kubernetes Engine 叢集的 hf-gke CLI：

   uv run pyinstaller hf-gke.spec --clean
   

9. 如要驗證安裝作業，請對可執行檔執行 --help 指令。如未設定必要的環境變數，系統可能會顯示錯誤訊息。

   dist/hf-gke --help
   

10. 如果您手動建構供應商，請為二進位檔和指令碼建立供應商外掛程式目錄：

    mkdir -p $HF_TOP/$HF_VERSION/providerplugins/gcpgke/bin
    mkdir -p $HF_TOP/$HF_VERSION/providerplugins/gcpgke/scripts
    

11. 將 hf-gke 二進位檔和指令碼複製到供應商外掛程式目錄。hf-gke 二進位檔位於 PyInstaller 建立的 dist/ 目錄中，而指令碼則位於 scripts/gcpgke/ 目錄中：

    cp dist/hf-gke $HF_TOP/$HF_VERSION/providerplugins/gcpgke/bin/
    cp scripts/gcpgke/* $HF_TOP/$HF_VERSION/providerplugins/gcpgke/scripts/
    

    安裝完成後，供應商外掛程式的目錄結構會顯示在 $HF_TOP/$HF_VERSION/providerplugins/gcpgke 路徑中，如下所示：

├── bin
│   └── hf-gke
└── scripts
    ├── getAvailableTemplates.sh
    ├── getRequestStatus.sh
    ├── getReturnRequests.sh
    ├── requestMachines.sh
    └── requestReturnMachines.sh

啟用供應商外掛程式

如要啟用 GKE 提供者外掛程式，請在主機工廠設定中註冊。

1. 開啟 ${HF_TOP}/conf/providerplugins/hostProviderPlugins.json 檔案。

   source 指令會在環境中定義 $HF_TOP 環境變數。這個值是 IBM Spectrum Symphony 主機工廠服務的頂層安裝目錄路徑。

2. 新增 gcpgke 提供者外掛程式區段：

   {
       "name": "gcpgke",
       "enabled": 1,
       "scriptPath": "${HF_TOP}/${HF_VERSION}/providerplugins/gcpgke/scripts/"
   }
   

設定供應商執行個體

如要為環境設定 GKE 供應商，請建立供應商執行個體。

1. 如果您手動建構連接器，請為供應商例項建立目錄，例如：$HF_TOP/conf/providers/gcpgkeinst/。

   如果您已取得 profile.platform script，環境中就會定義 $HF_TOP 環境變數。這個值是 IBM Spectrum Symphony 主機出廠服務的頂層安裝目錄路徑。

2. 在供應商例項目錄 ($HF_TOP/conf/providers/gcpgkeinst/) 中，建立或設定 gcpgkeinstprov_config.json 檔案。這個檔案包含供應商的主要設定。

   • 如果您使用 RPM 套件安裝供應商外掛程式，可以複製範例設定檔，然後自訂該檔案：

     cp $HF_TOP/conf/providers/gcpgkeinst/gcpgkeinstprov_config.json.dist $HF_TOP/conf/providers/gcpgkeinst/gcpgkeinstprov_config.json
     

   • 如果從來源建構供應商，請建立 gcpgkeinstprov_config.json 檔案。

   這個檔案通常只需要設定 GKE_KUBECONFIG 變數，該變數會定義相關聯 GKE 叢集的標準 kubectl 設定檔路徑。如未指定路徑，系統會預設為供應商執行個體目錄中的 kubeconfig。您必須確保這個路徑指向 Kubernetes 叢集的有效 kubectl 設定檔，而這個叢集是此供應商執行個體所使用的。

   以下為設定範例：

   {
     "GKE_KUBECONFIG": "kubeconfig"
   }
   

   系統支援下列設定變數：

   變數名稱	說明	預設值
   GKE_KUBECONFIG	kubectl 指令使用的設定檔路徑。	無
   GKE_CRD_NAMESPACE*	定義所有資源建立所在的 Kubernetes 命名空間。	gcp-symphony
   GKE_CRD_GROUP*	用於識別 GKE 主機出廠設定作業人員自訂資源的資源群組。	accenture.com
   GKE_CRD_VERSION*	用於識別 GKE 主機出廠設定作業人員自訂資源的版本。	v1
   GKE_CRD_KIND*	自訂資源定義的名稱，用於定義運算資源 (Pod) 的要求。	GCP Symphony Resource
   GKE_CRD_SINGULAR*	在 API 呼叫中，參照 Google Cloud Symphony Resource CR 的執行個體時使用。	gcp-symphony-resource
   GKE_CRD_RETURN_REQUEST_KIND*	自訂資源定義的名稱，用於定義傳回運算資源 (Pod) 的要求。	Machine Return Request
   GKE_CRD_RETURN_REQUEST_SINGULAR*	在 API 呼叫中，參照單一 MachineReturnRequest 自訂資源執行個體時使用。	machine-return-request
   GKE_REQUEST_TIMEOUT	要求等待 GKE 控制層回應的時間長度 (以秒為單位)。	300
   LOG_LEVEL	控制 GKE 供應商寫入記錄檔的記錄詳細程度。選項包括 CRITICAL、WARNING、ERROR、INFO、DEBUG。	WARNING

   重要事項： 如果修改標有星號 (*) 的變數，也必須修改 Kubernetes 運算子設定中的對應變數。建議您使用預設值，以維持一致性。

3. 在同一個目錄中，建立或設定 gcpgkeinstprov_templates.json 檔案。這個檔案會定義供應商可建立的 Pod 範本。

   • 如果您使用 RPM 套件安裝供應商外掛程式，可以複製範本檔案並自訂：

     cp $HF_TOP/conf/providers/gcpgkeinst/gcpgkeinstprov_templates.json.dist $HF_TOP/conf/providers/gcpgkeinst/gcpgkeinstprov_templates.json
     

   • 如果從來源建構供應商，請建立 gcpgkeinstprov_templates.json 檔案。

     範本屬性應與 Pod 規格中的資源一致。範本範例如下：

     {
         "templates": [
             {
                 "templateId": "template-gcp-01",
                 "maxNumber": 5000,
                 "attributes": {
                     "type": [ "String", "X86_64" ],
                     "ncores": [ "Numeric", "1" ],
                     "ncpus": [ "Numeric", "1" ],
                     "nram": [ "Numeric", "2048" ]
                 },
                 "podSpecYaml": "pod-specs/pod-spec.yaml"
             }
         ]
     }
     

4. 在同一個目錄中，建立 Kubernetes 叢集的有效 kubectl 設定檔 kubeconfig。

5. 在供應商執行個體目錄中，建立或編輯 pod-spec.yaml 檔案。 這個檔案會做為範本，定義在 GKE 叢集中建立的 Symphony 運算 Pod 規格。

   從這項規格建立的 Pod 會做為運算節點，且需要存取 Symphony 安裝項目。您可以透過包含 Symphony 安裝項目的容器映像檔，或透過包含安裝項目的共用檔案系統掛接，提供這項存取權。啟動時，Pod 會使用這項存取權加入 Symphony 叢集。

   建立檔案的步驟取決於您安裝提供者的方式：

   • 如果您是從 RPM 套件安裝供應商，請複製安裝中包含的範例 pod-spec.yaml.dist 檔案：

     cp $HF_TOP/conf/providers/gcpgkeinst/pod-specs/pod-spec.yaml.dist
     $HF_TOP/conf/providers/gcpgkeinst/pod-specs/pod-spec.yaml
     

   • 如果從來源建構供應商，請手動建立 pod-specs 目錄和 pod-spec.yaml 檔案：

     mkdir -p $HF_TOP/conf/providers/gcpgkeinst/pod-specs touch
     $HF_TOP/conf/providers/gcpgkeinst/pod-specs/pod-spec.yaml
     

6. 建立這些檔案後，請確認供應商執行個體目錄如下所示：

   ├── gcpgkeinstprov_config.json
   ├── gcpgkeinstprov_templates.json
   ├── kubeconfig
   └── pod-specs
       └── pod-spec.yaml
   

啟用供應商執行個體

如要啟用供應商例項，請在主機工廠設定檔中啟用：

1. 開啟 $HF_TOP/conf/providers/hostProviders.json 檔案。

2. 新增gcpgkeinst提供者執行個體區段：

   {
       "name": "gcpgkeinst",
       "enabled": 1,
       "plugin": "gcpgke",
       "confPath": "${HF_CONFDIR}/providers/gcpgkeinst/",
       "workPath": "${HF_WORKDIR}/providers/gcpgkeinst/",
       "logPath": "${HF_LOGDIR}/"
   }
   

   您不需要在這個設定中取代 ${HF_CONFDIR}、${HF_WORKDIR} 和 ${HF_LOGDIR} 變數，因為這些都是標準環境變數，會由 IBM Spectrum Symphony 主機工廠環境自動定義。

   執行 source command 設定殼層工作階段時，這個指令碼會設定這些變數，指向 Symphony 安裝目錄中的正確子目錄。主機出廠服務接著會使用這些變數，在執行階段建構完整路徑。

啟用要求者執行個體

如要讓特定 Symphony 元件使用 GKE 供應商佈建資源，請為該要求者啟用。

1. 開啟 $HF_TOP/conf/requestors/hostRequestors.json 檔案。

2. 在適當的要求者例項中，將 gcpgkeinst 新增至 providers 參數：

   "providers": ["gcpgkeinst"],
   

   供應商值必須與「啟用供應商例項」中使用的供應商名稱相符。

啟動主機出廠服務

如要套用設定變更，請啟動主機原廠服務。在 Symphony 主要主機 VM 上，以叢集管理員身分登入並啟動服務：

sed -i -e "s|MANUAL|AUTOMATIC|g" $EGO_ESRVDIR/esc/conf/services/hostfactory.xml
egosh user logon -u "SYMPHONY_USERNAME -x "SYMPHONY_PASSWORD
egosh service start HostFactory

更改下列內容：

• SYMPHONY_USERNAME：用於驗證的 Symphony 使用者名稱。
• SYMPHONY_PASSWORD：Symphony 使用者的密碼。

測試連接器

建立資源要求，測試 GKE 的供應商。

方法如下：

• Symphony GUI：如要瞭解如何使用 Symphony GUI 建立資源要求，請參閱 IBM 說明文件中的「Manually scheduling cloud host requests and returns」(手動排定雲端主機要求和退貨)。

• REST API：如要使用 REST API 建立資源要求，請按照下列步驟操作：

  1. 找出主機工廠 REST API 的主機和連接埠：

     egosh client view REST_HOST_FACTORY_URL
     

     輸出結果會與下列範例相似：

     CLIENT NAME: REST_HOST_FACTORY_URL
     DESCRIPTION: http://sym2.us-central1-c.c.symphonygcp.internal:9080/platform/rest/hostfactory/
     TTL        : 0
     LOCATION   : 40531@10.0.0.33
     USER       : Admin
     
     CHANNEL INFORMATION:
     CHANNEL             STATE
     9                   CONNECTED
     

  2. 如要使用 REST API 建立資源要求，請使用下列指令：

     HOST=PRIMARY_HOST
     PORT=PORT
     TEMPLATE_NAME=SYMPHONY_TEMPLATE_ID
     PROVIDER_NAME=gcpgkeinst
     
     curl -X POST -u "SYMPHONY_USER:SYMPHONY_PASSWORD" -H "Content-Type: application/json" -d "{ \"demand_hosts\": [ { \"prov_name\": \"$PROVIDER_NAME\", \"template_name\": \"$TEMPLATE_NAME\", \"ninstances\": 1 } ] }" \
     http://$HOST:$PORT/platform/rest/hostfactory/requestor/admin/request
     

     更改下列內容：

     • PRIMARY_HOST：上一個指令輸出內容中的主要主機主機名稱。
     • PORT：主要主機的通訊埠號碼，例如 9080，可從上一個指令的輸出內容取得。
     • SYMPHONY_TEMPLATE_ID：gcpgkeinstprov_templates.json 檔案中定義的 templateId，例如 template-gcp-01。
     • SYMPHONY_USER：用於驗證的 Symphony 使用者。
     • SYMPHONY_PASSWORD：Symphony 使用者的密碼。

     如果成功，輸出結果會與下列範例類似：

     {"scheduled_request_id":["SD-641ef442-1f9e-40ae-ae16-90e152ed60d2"]}
     

後續步驟

• 排解 IBM Spectrum Symphony 連接器問題