安裝 Compute Engine Symphony 供應商

本文說明如何安裝及設定 Compute Engine 適用的 IBM Symphony 提供者。您將瞭解如何設定 Pub/Sub 來監控虛擬機器 (VM) 執行個體事件、建構及安裝供應商外掛程式，以及在 Symphony 主機工廠環境中設定供應商執行個體。

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

事前準備

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

已啟用主機出廠服務的 IBM Spectrum Symphony 叢集。您擁有 IBM Spectrum Symphony 主機的主機名稱。
具備必要角色的專屬服務帳戶。如要進一步瞭解如何建立這個服務帳戶，請參閱「建立服務帳戶」。

您已設定防火牆規則，允許 Symphony 主要主機與 Compute Engine 通訊。例如：

gcloud compute firewall-rules create allow-symphony-primary-to-compute \
    --project=PROJECT_ID \
    --direction=INGRESS \
    --priority=1000 \
    --network=NETWORK_NAME \
    --allow=all \
    --source-tags=NETWORK_TAGS_MASTER \
    --target-tags=NETWORK_TAGS

gcloud compute firewall-rules create allow-symphony-compute-to-primary \
    --project=PROJECT_ID \
    --direction=INGRESS \
    --priority=1000 \
    --network=NETWORK_NAME \
    --allow=all \
    --source-tags=NETWORK_TAGS \
    --target-tags=NETWORK_TAGS_MASTER

更改下列內容：

PROJECT_ID：專案 ID。 Google Cloud
NETWORK_NAME：部署 Symphony 資源的虛擬私有雲網路名稱。
NETWORK_TAGS_MASTER：套用至 Symphony 主要主機 VM 的網路標記。
NETWORK_TAGS：套用至 Symphony 運算節點 VM 的網路標記。

詳情請參閱「建立虛擬私有雲防火牆規則」。

必要的角色

如要取得建立及管理使用服務帳戶的執行個體所需的權限，請要求管理員在專案中授予下列 IAM 角色：

Compute 執行個體管理員 (v1) (roles/compute.instanceAdmin.v1)
服務帳戶使用者 (roles/iam.serviceAccountUser)

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

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

準備 Compute Engine 環境

如要讓 Symphony 主機出廠設定建立及管理 VM，您需要設定多個 Google Cloud 資源：

執行個體範本：定義主機出廠設定所建立 Symphony Compute VM 設定的藍圖。
代管執行個體群組 (MIG)：使用執行個體範本建立的一組相同 VM。主機出廠設定會根據工作負載需求新增或移除 VM，藉此擴充或縮減這個群組。
Pub/Sub 主題和訂閱項目：這項訊息服務會將 VM 生命週期事件 (例如搶占或刪除) 通知 Symphony 提供者。這項服務可讓供應商維持叢集的準確狀態。

建立執行個體範本

使用 gcloud compute instance-templates create 指令，為 Symphony 計算主機建立執行個體範本。這個範本會定義所建立 VM 的屬性。這些 VM 必須安裝 Symphony。您可以選擇使用預先安裝 Symphony 的映像檔，也可以在建立 VM 後，使用啟動指令碼安裝 Symphony。如要瞭解如何在運算主機 VM 上安裝 Symphony，請參閱 IBM 說明文件中的「在 Linux 運算主機上安裝」。

  gcloud compute instance-templates create INSTANCE_TEMPLATE_NAME \
    --machine-type=MACHINE_TYPE \
    --network-interface=nic-type=GVNIC,stack-type=IPV4_ONLY,subnet=SUBNET_NAME,no-address \
    --instance-template-region=REGION \
    --service-account=SERVICE_ACCOUNT_EMAIL \
    --scopes=https://www.googleapis.com/auth/devstorage.read_only,https://www.googleapis.com/auth/logging.write,https://www.googleapis.com/auth/monitoring.write,https://www.googleapis.com/auth/service.management.readonly,https://www.googleapis.com/auth/servicecontrol,https://www.googleapis.com/auth/trace.append \
    --tags=NETWORK_TAGS \
    --create-disk=auto-delete=yes,boot=yes,device-name=INSTANCE_TEMPLATE_NAME,image-family=rocky-linux-9,image-project=rocky-linux-cloud,mode=rw,size=20,type=pd-balanced \
    --shielded-secure-boot \
    --shielded-vtpm \
    --shielded-integrity-monitoring

更改下列內容：

INSTANCE_TEMPLATE_NAME：新執行個體範本的名稱。
MACHINE_TYPE：運算執行個體的機器類型。詳情請參閱使用自訂機型建立 VM。
SUBNET_NAME：執行個體的子網路名稱。詳情請參閱「查看執行個體的網路設定」。
SERVICE_ACCOUNT_EMAIL：您在「事前準備」一節中設定的服務帳戶電子郵件地址。請確保這個服務帳戶具備「必要角色」一節中指定的角色。
REGION：您要在其中建立資源的 Google Cloud 區域。
NETWORK_TAGS：要套用至執行個體的網路標記，可用於防火牆規則，例如 symphony-compute。

建立代管執行個體群組

使用上一個步驟中的執行個體範本，建立代管執行個體群組 (MIG)。主機工廠供應商會根據工作負載需求，新增或移除執行個體，藉此調度這個群組的資源。

gcloud compute instance-groups managed create INSTANCE_GROUP_NAME \
    --project=PROJECT_ID \
    --base-instance-name=INSTANCE_GROUP_NAME \
    --template=projects/PROJECT_ID/regions/REGION/instanceTemplates/INSTANCE_TEMPLATE_NAME \
    --size=0 \
    --zone=ZONE
    --default-action-on-vm-failure=repair \
    --no-force-update-on-repair \
    --standby-policy-mode=manual \
    --list-managed-instances-results=pageless

更改下列內容：

INSTANCE_GROUP_NAME：您為代管執行個體群組選擇的名稱。
PROJECT_ID：專案 ID。 Google Cloud詳情請參閱「找出專案名稱、編號和 ID」。
INSTANCE_TEMPLATE_NAME：您在上一個步驟中建立的執行個體範本名稱。
REGION：資源所在的區域，例如 us-east。
ZONE：所選區域內的可用區，例如 a。

如要進一步瞭解如何建立 MIG，請參閱在單一可用區中建立 MIG。

設定 Pub/Sub

如要讓 Symphony 供應商接收有關 VM 生命週期事件的通知，請設定 Pub/Sub 主題和訂閱項目：

在 Symphony 主要主機上，設定下列環境變數：
```
export GCP_PROJECT=PROJECT_ID
export PUBSUB_TOPIC=PUBSUB_TOPIC
```
更改下列內容：
- PROJECT_ID： Google Cloud 專案的 ID。
- PUBSUB_TOPIC：Google Cloud 主題的名稱，例如 hf-gce-vm-events。

建立 Pub/Sub 主題：

gcloud pubsub topics create $PUBSUB_TOPIC

使用 gcloud logging sinks create 指令建立記錄接收器，將稽核記錄匯出至 Pub/Sub：

gcloud logging sinks create ${PUBSUB_TOPIC}-sink \
    pubsub.googleapis.com/projects/${GCP_PROJECT}/topics/${PUBSUB_TOPIC} \
    --log-filter="
    logName=\"projects/${GCP_PROJECT}/logs/cloudaudit.googleapis.com%2Factivity\"
    resource.type=(\"gce_instance_group_manager\" OR \"gce_instance\")
    protoPayload.methodName=(
        \"v1.compute.instanceGroupManagers.createInstances\"
        OR
        \"v1.compute.instanceGroupManagers.deleteInstances\"
        OR
        \"v1.compute.instances.insert\"
        OR
        \"v1.compute.instances.delete\"
    )
    " \
    --description="Exports MIG VM create/delete audit logs to Pub/Sub"

這項指令的輸出內容包含您在下一步中使用的服務帳戶。

將 Pub/Sub 發布者 (roles/pubsub.publisher) 角色授予上一個步驟中的服務帳戶：
```
gcloud pubsub topics add-iam-policy-binding $PUBSUB_TOPIC \
    --member="serviceAccount:LOGGING_SINK_SERVICE_ACCOUNT" \
    --role="roles/pubsub.publisher"
```
將 LOGGING_SINK_SERVICE_ACCOUNT 替換為記錄接收器建立作業的輸出內容中的服務帳戶名稱。

建立訂閱項目來接收記錄：

gcloud pubsub subscriptions create ${PUBSUB_TOPIC}-sub \
    --topic=${PUBSUB_TOPIC}

確認服務帳戶具備訂閱訂閱項目的正確權限：
```
gcloud pubsub subscriptions add-iam-policy-binding ${PUBSUB_TOPIC}-sub \
    --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
    --role="roles/pubsub.subscriber"
```
將 SERVICE_ACCOUNT_EMAIL 替換為管理執行個體群組的服務帳戶電子郵件地址。這與您在「事前準備」一節中設定的服務帳戶相同。

Pub/Sub 設定完成。如要進一步瞭解如何設定 Pub/Sub，請參閱「使用 Google Cloud CLI 在 Pub/Sub 中發布及接收訊息」。

載入主機工廠環境變數

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

source INSTALL_FOLDER/profile.platform

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

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

安裝供應商外掛程式

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

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

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

為 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

安裝 Compute Engine 的供應商套件：

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

RPM 套件會將供應商可執行檔和指令碼安裝到 Symphony 主機出廠服務的正確目錄中。安裝完成後，目錄結構如下所示：

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

從原始碼建構供應商

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

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

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

前往專案中的 hf-provider 目錄：
```
cd PROJECT_ROOT/hf-provider
```
將 PROJECT_ROOT 替換為包含 hf-provider 目錄的頂層目錄路徑，例如 /home/user/symphony-gcp-connector。
如果沒有安裝 uv，請安裝：
```
pip install uv
```
使用 uv 建立 Python 虛擬環境：
```
uv venv
```
啟用虛擬環境：
```
source .venv/bin/activate
```
安裝必要的專案依附元件：
```
uv pip install .
```
安裝 PyInstaller，將 Python 應用程式封裝成獨立的可執行檔：
```
uv pip install pyinstaller
```
為 Compute Engine 叢集建立 hf-gce CLI：
```
uv run pyinstaller hf-gce.spec --clean
```
如要驗證安裝作業，請對可執行檔執行 --help 指令。如未設定必要的環境變數，系統可能會顯示錯誤訊息。
```
dist/hf-gce --help
```

將可執行檔複製到供應器外掛程式 bin 目錄：

mkdir -p ${HF_TOP}/${HF_VERSION}/providerplugins/gcpgce/bin
cp dist/hf-gce ${HF_TOP}/${HF_VERSION}/providerplugins/gcpgce/bin/

將指令碼複製到供應商外掛程式 scripts 目錄：
```
cp -R ./resources/gce_cli/1.2/providerplugins/gcpgce/scripts ${HF_TOP}/${HF_VERSION}/providerplugins/gcpgce/
```
作業系統必須支援用於建構可執行檔的 Python 版本。這些可執行檔已使用 Python 3.9.6 測試。

安裝完成後，供應商外掛程式的目錄結構會類似以下範例：

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

啟用供應商外掛程式

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

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

使用 source 指令時，系統會在環境中定義 $HF_TOP 環境變數。這個值是 IBM Spectrum Symphony 主機出廠服務的頂層安裝目錄路徑。
新增 gcpgce 提供者外掛程式區段：
```
{
    "name": "gcpgce",
    "enabled": 1,
    "scriptPath": "${HF_TOP}/${HF_VERSION}/providerplugins/gcpgce/scripts/"
}
```
如果您使用 1.2 版的供應商外掛程式，且 $HF_TOP 的預設值為 INSTALL_FOLDER/hostfactory/1.2/providerplugins/gcpgce/scripts/，則產生的 scriptPath 值為：INSTALL_FOLDER/hostfactory/1.2/providerplugins/gcpgce/scripts/。

設定供應商執行個體

如要為環境設定 Compute Engine 提供者，請建立提供者執行個體。

設定供應商執行個體的目錄：

如果從原始碼建構供應商，則必須手動建立目錄和設定檔：
```
mkdir -p $HF_TOP/conf/providers/gcpgceinst/
```

如果您使用 RPM 安裝，這個目錄就已存在，且包含範例設定檔。複製範例檔案來建立設定：

cp $HF_TOP/conf/providers/gcpgceinst/gcpgceinstprov_config.json.dist $HF_TOP/conf/providers/gcpgceinst/gcpgceinstprov_config.json
cp $HF_TOP/conf/providers/gcpgceinst/gcpgceinstprov_templates.json.dist $HF_TOP/conf/providers/gcpgceinst/gcpgceinstprov_templates.json

在 $HF_TOP/conf/providers/gcpgceinst/ 目錄中，建立或編輯 gcpgceinstprov_config.json 檔案。這個檔案包含供應商的主要設定。供應商支援下列設定變數。您必須在這個設定中指定沒有預設值的變數。

變數名稱	說明	預設值
`HF_DBDIR`	供應商儲存狀態資料庫的位置。	在 HostFactory 環境中定義為 `$HF_DBDIR`。
`HF_TEMPLATES_FILENAME`	範本檔案的名稱。	`gcpgceinstprov_templates.json`
`GCP_CREDENTIALS_FILE`	Google Cloud 服務帳戶憑證檔案的位置。	如未指定這個值，應用程式會使用預設憑證。
`GCP_PROJECT_ID`	Google Cloud 專案的 ID。	無
`GCP_INSTANCE_PREFIX`	要加到這個供應商建立的所有主機名稱開頭的字串。	`sym-`
`LOGFILE`	供應商傳送記錄檔的位置。	檔案名稱會自動產生，並位於 HostFactory 環境變數 `HF_PROVIDER_LOGDIR` 定義的目錄中。
`LOG_LEVEL`	Python 記錄檔層級	`WARNING`
`PUBSUB_TIMEOUT`	如果最新的 Pub/Sub 事件早於這個時間長度 (以秒為單位)，Pub/Sub 監聽器就會中斷連線。只有在系統自動啟動 Pub/Sub 事件監聽器時，才會套用這項逾時設定。否則接聽程式會無限期執行，且管理員必須控管生命週期。	`600`
`PUBSUB_TOPIC`	Pub/Sub 主題名稱。這個變數僅適用於回溯相容性。	`hf-gce-vm-events`
`PUBSUB_SUBSCRIPTION`	要監控 VM 事件的 Pub/Sub 訂閱項目名稱。	`hf-gce-vm-events-sub`
`PUBSUB_LOCKFILE`	這個檔案的名稱會指出 Pub/Sub 事件接聽程式是否處於啟用狀態。	`/tmp/sym_hf_gcp_pubsub.lock`
`PUBSUB_AUTOLAUNCH`	如果設為 `true`，供應商會嘗試自動啟動 Pub/Sub 事件監聽器。如果 `false`，您必須使用所選方法啟動 Pub/Sub 事件監聽器，並執行 `hf-gce monitorEvents` 指令。	`true`

以下範例顯示基本設定：

{
    "GCP_PROJECT_ID": "PROJECT_ID",
    "LOG_LEVEL":"INFO",
    "PUBSUB_SUBSCRIPTION": "PUBSUB_SUBSCRIPTION",
    "PUBSUB_TIMEOUT": 100
}

更改下列內容：

PROJECT_ID：專案 ID。 Google Cloud
PUBSUB_SUBSCRIPTION：您建立的 Pub/Sub 訂閱項目名稱，用於監控 VM 事件。詳情請參閱「設定 Pub/Sub」。

在同一個目錄中，建立或編輯 gcpgceinstprov_templates.json 檔案。這個檔案定義了供應商可建立的 VM 範本。範本中的屬性必須與支援執行個體群組的設定一致。

如果您使用 RPM 安裝，請以先前步驟中建立的 gcpgceinstprov_templates.json 檔案做為起點。

如果從來源建構，請使用下列範例範本：

{
    "templates": [
        {
            "templateId": "template-gcp-01",
            "maxNumber": 10,
            "attributes": {
                "type": [ "String", "X86_64" ],
                "ncpus": [ "Numeric", "1" ],
                "nram": [ "Numeric", "1024" ]
            },
            "gcp_zone": "GCP_ZONE",
            "gcp_instance_group": "INSTANCE_GROUP_NAME"
        }
    ]
}

更改下列內容：

GCP_ZONE：執行個體群組所在的 Google Cloud 區域，例如 us-central1-a。
INSTANCE_GROUP_NAME：供應商管理的執行個體群組名稱，例如 symphony-compute-ig。

建立這些檔案後，請確認供應商執行個體目錄與下列範例類似：
```
├── gcpgceinstprov_config.json
└── gcpgceinstprov_templates.json
```

啟用供應商執行個體

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

開啟 $HF_TOP/conf/providers/hostProviders.json 檔案。
新增gcpgceinst提供者執行個體區段：
```
{
    "name": "gcpgceinst",
    "enabled": 1,
    "plugin": "gcpgce",
    "confPath": "${HF_CONFDIR}/providers/gcpgceinst/",
    "workPath": "${HF_WORKDIR}/providers/gcpgceinst/",
    "logPath": "${HF_LOGDIR}/"
}
```
重要事項： 請勿替換這項設定中的 ${HF_CONFDIR}、${HF_WORKDIR} 和 ${HF_LOGDIR} 變數。IBM Spectrum Symphony 主機出廠設定會自動定義這些環境變數。

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

啟用要求者執行個體

如要讓特定 Symphony 元件使用 Compute Engine 供應商佈建資源，請為該要求者啟用這項功能。

開啟 $HF_TOP/conf/requestors/hostRequestors.json 檔案。
在適當的要求者例項中，將 gcpgceinst 新增至 providers 參數：
```
"providers": ["gcpgceinst"],
```
供應商值必須與「啟用供應商例項」中使用的供應商名稱相符。

啟動主機出廠服務

如要套用設定變更，請啟動主機原廠服務。在 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 使用者的密碼。

測試連接器

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

方法如下：

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

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

找出主機工廠 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

如要使用 REST API 建立資源要求，請使用下列指令：
```
HOST=PRIMARY_HOST
PORT=PORT
TEMPLATE_NAME=INSTANCE_TEMPLATE_NAME
PROVIDER_NAME=gcpgceinst

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：gcpgceinstprov_templates.json 檔案中定義的 templateId，例如 template-gcp-01。
- SYMPHONY_USER：用於驗證的 Symphony 使用者。
- SYMPHONY_PASSWORD：Symphony 使用者的密碼。
如果成功，輸出內容會與以下範例類似：
```
{"scheduled_request_id":["SD-641ef442-1f9e-40ae-ae16-90e152ed60d2"]}
```

安裝 Compute Engine Symphony 供應商 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

事前準備

必要的角色

準備 Compute Engine 環境

建立執行個體範本

建立代管執行個體群組

設定 Pub/Sub

載入主機工廠環境變數

安裝供應商外掛程式

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

從原始碼建構供應商

啟用供應商外掛程式

設定供應商執行個體

啟用供應商執行個體

啟用要求者執行個體

啟動主機出廠服務

測試連接器

後續步驟

安裝 Compute Engine Symphony 供應商