Google Kubernetes Symphony プロバイダをインストールする

動的リソース管理のために IBM Symphony を Google Kubernetes Engine（GKE）と統合するには、GKE 用の Symphony プロバイダをインストールして構成する必要があります。このプロバイダを使用すると、Symphony は GKE クラスタ内の Pod としてコンピューティングリソースをプロビジョニングして管理できます。これにより、Kubernetes オーケストレーションによる効率的なワークロードスケーリングが可能になります。

この統合を有効にするには、クラスタに Kubernetes オペレータをインストールし、Symphony のプライマリホストにプロバイダプラグインをインストールして、GKE と通信するように Symphony のホストファクトリーサービスを構成します。

Google Cloud向け Symphony コネクタの詳細については、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）が含まれています。イメージを取得するには、ソースからビルドします。

ソースからオペレーターイメージをビルドするには、次の操作を行います。

GitHub から symphony-gcp-connector リポジトリのクローンを作成します。
```
git clone https://github.com/GoogleCloudPlatform/symphony-gcp-connector.git
```
k8s-operator ディレクトリに移動します。
```
cd symphony-gcp-connector/k8s-operator
```
イメージ名、レジストリ、タグの環境変数を設定します。
```
export IMAGE="gcp-symphony-operator"
export REGISTRY="IMAGE_REPO"
export TAG="TAG"
```
次のように置き換えます。
- IMAGE_REPO: オペレーターイメージが保存されているイメージリポジトリ。たとえば、Artifact Registry を使用してオペレーターイメージを保存できます。詳細については、Docker リポジトリを作成するをご覧ください。
- TAG: オペレータイメージのタグ（例: 0.0.1）。

オペレーターイメージをビルドして push します。

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 マニフェストを生成して構成する必要があります。

マニフェストを生成するには、オペレーターイメージを指定して export-manifests コマンドを使用します。
```
docker run --rm gcp-symphony-operator:latest export-manifests > manifests.yaml
```
任意のテキストエディタで manifests.yaml ファイルを開きます。
spec.template.spec.containers セクションで、image フィールドを見つけて、その値をレジストリに push したイメージのフルパスに更新します。
```
...
containers:
- image: IMAGE_REPO/gcp-symphony-operator:TAG
  name: manager
...
```
次のように置き換えます。
- IMAGE_REPO: オペレーターイメージを push したイメージリポジトリのパス。
- TAG: オペレーターイメージのビルド時に割り当てたタグ。
省略可: imagePullPolicy 値を変更して、クラスタ管理のプラクティスに合わせることもできます。

Operator マニフェストを適用する

マニフェストを構成したら、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"))
```
詳細については、Cluster Toolkit の概要をご覧ください。

ホストファクトリ環境変数を読み込む

ホストファクトリーサービスを構成または管理する前に、Symphony 環境変数をシェルセッションに読み込む必要があります。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 で次の操作を行います。

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

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 実行可能ファイルをビルドしてインストールする手順は次のとおりです。

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 パッケージマネージャーを使用して、Python 仮想環境を作成します。
```
uv venv
```
仮想環境をアクティブにします。
```
source .venv/bin/activate
```
必要なプロジェクトの依存関係をインストールします。
```
uv pip install .
```
Python アプリケーションをスタンドアロンの実行可能ファイルにバンドルする PyInstaller をインストールします。
```
uv pip install pyinstaller
```
Google Kubernetes Engine クラスタの hf-gke CLI を作成します。
```
uv run pyinstaller hf-gke.spec --clean
```
インストールを確認するには、実行可能ファイルに対して --help コマンドを実行します。必要な環境変数を設定しないと、エラーが表示されることがあります。
```
dist/hf-gke --help
```
プロバイダを手動でビルドする場合は、バイナリとスクリプトのプロバイダプラグインディレクトリを作成します。
```
mkdir -p $HF_TOP/$HF_VERSION/providerplugins/gcpgke/bin
mkdir -p $HF_TOP/$HF_VERSION/providerplugins/gcpgke/scripts
```
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 プロバイダプラグインを有効にするには、ホストファクトリ構成に登録する必要があります。

${HF_TOP}/conf/providerplugins/hostProviderPlugins.json ファイルを開きます。

source コマンドは、環境内の $HF_TOP 環境変数を定義します。値は、IBM Spectrum Symphony ホストファクトリーサービスの最上位のインストールディレクトリのパスです。

gcpgke プロバイダプラグインセクションを追加します。

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

プロバイダインスタンスを設定する

環境の GKE プロバイダを構成するには、プロバイダインスタンスを作成します。

コネクタを手動でビルドする場合は、$HF_TOP/conf/providers/gcpgkeinst/ などのプロバイダインスタンスのディレクトリを作成します。

profile.platform script を取得している場合、$HF_TOP 環境変数は環境内で定義されています。値は、IBM Spectrum Symphony ホストファクトリーサービスの最上位のインストールディレクトリのパスです。

プロバイダインスタンスディレクトリ（$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 クラスタの標準 kubectl 構成ファイルのパスを定義する GKE_KUBECONFIG 変数のみを構成する必要があります。パスを指定しない場合、デフォルトはプロバイダインスタンスディレクトリの kubeconfig になります。このパスが、このプロバイダインスタンスが使用する Kubernetes クラスタの有効な kubectl 構成ファイルを指していることを確認する必要があります。

次に、構成の例を示します。

{
  "GKE_KUBECONFIG": "kubeconfig"
}

次の構成変数がサポートされています。

変数名	説明	デフォルト値
`GKE_KUBECONFIG`	kubectl コマンドで使用される構成ファイルのパス。	なし
`GKE_CRD_NAMESPACE`*	すべてのリソースが作成される Kubernetes Namespace を定義します。	`gcp-symphony`
`GKE_CRD_GROUP`*	GKE ホストファクトリーオペレーターのカスタムリソースの識別に使用されるリソースグループ。	`accenture.com`
`GKE_CRD_VERSION`*	GKE ホストファクトリーオペレーターのカスタムリソースの識別に使用されるバージョン。	`v1`
`GKE_CRD_KIND`*	コンピューティングリソース（Pod）のリクエストを定義するカスタムリソース定義に付けられた名前。	`GCP Symphony Resource`
`GKE_CRD_SINGULAR`*	Google Cloud Symphony `Resource` CR のインスタンスを参照するときに API 呼び出しで使用されます。	`gcp-symphony-resource`
`GKE_CRD_RETURN_REQUEST_KIND`*	コンピューティングリソース（Pod）を返すリクエストを定義するカスタムリソース定義に付けられた名前。	`Machine Return Request`
`GKE_CRD_RETURN_REQUEST_SINGULAR`*	単一の `MachineReturnRequest` カスタムリソースインスタンスを参照するときに API 呼び出しで使用されます。	`machine-return-request`
`GKE_REQUEST_TIMEOUT`	GKE コントロールプレーンへのリクエストがレスポンスを待つ時間（秒単位）。	`300`
`LOG_LEVEL`	GKE プロバイダがログファイルに書き込むログの詳細レベルを制御します。オプションは `CRITICAL`、`WARNING`、`ERROR`、`INFO`、`DEBUG` です。	`WARNING`

同じディレクトリに、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"
        }
    ]
}

同じディレクトリに、Kubernetes クラスタの有効な kubectl 構成ファイルである kubeconfig ファイルを作成します。
プロバイダインスタンスディレクトリで、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
```
これらのファイルを作成したら、プロバイダインスタンスディレクトリが次のように表示されることを確認します。
```
├── gcpgkeinstprov_config.json
├── gcpgkeinstprov_templates.json
├── kubeconfig
└── pod-specs
    └── pod-spec.yaml
```

プロバイダインスタンスを有効にする

プロバイダインスタンスを有効にするには、ホストファクトリ構成ファイルで有効にします。

$HF_TOP/conf/providers/hostProviders.json ファイルを開きます。
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 インストール内の正しいサブディレクトリを指すようにします。ホストファクトリーサービスは、これらの変数を使用して、実行時に完全なパスを構築します。

リクエスト元インスタンスを有効にする

特定のリクエスト元に対して GKE プロバイダを有効にすると、そのリクエスト元が GKE プロバイダを使用してリソースをプロビジョニングできるようになります。

$HF_TOP/conf/requestors/hostRequestors.json ファイルを開きます。
適切なリクエスタインスタンスで、providers パラメータに gcpgkeinst を追加します。
```
"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 ドキュメントのクラウドホストのリクエストと返却を手動でスケジュールするをご覧ください。
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 コネクタのトラブルシューティング

Google Kubernetes Symphony プロバイダをインストールする コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

始める前に

必要なロール

Kubernetes オペレータをインストールする

オペレーター イメージをビルドする

オペレータ マニフェストを構成する

Operator マニフェストを適用する

ホスト ファクトリ環境変数を読み込む

プロバイダ プラグインをインストールする

事前ビルド済みのプロバイダ プラグインをインストールする