Installa il provider Google Kubernetes Symphony

Per integrare IBM Symphony con Google Kubernetes Engine (GKE) per la gestione dinamica delle risorse, devi installare e configurare il provider Symphony per GKE. Questo provider consente a Symphony di eseguire il provisioning e gestire le risorse di calcolo come pod nel cluster GKE, il che consente una scalabilità efficiente del workload tramite l'orchestrazione di Kubernetes.

Per abilitare questa integrazione, installa un operatore Kubernetes nel tuo cluster, installa il plug-in del provider sull'host primario di Symphony e configura il servizio di fabbrica di host di Symphony per comunicare con GKE.

Per ulteriori informazioni su Symphony Connectors per Google Cloud, vedi Integrare IBM Spectrum Symphony con Google Cloud.

Prima di iniziare

Per installare il provider Symphony per GKE, devi disporre delle seguenti risorse:

Un cluster IBM Spectrum Symphony in esecuzione con il servizio Host Factory attivato.
Un cluster GKE in esecuzione. Per crearne uno, consulta la panoramica di GKE.
Un account di servizio con le autorizzazioni appropriate. Per i dettagli, consulta la sezione Ruoli obbligatori.
Lo strumento a riga di comando kubectl installato e configurato per comunicare con il tuo cluster GKE.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per installare l'operatore e gestire i pod Symphony, chiedi all'amministratore di concederti i seguenti ruoli IAM nel progetto:

Per gestire le risorse Kubernetes: Amministratore Kubernetes Engine (roles/container.admin)

Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Installa l'operatore Kubernetes

Prima di installare il provider GKE, devi installare l'operatore Kubernetes associato. L'operatore gestisce il ciclo di vita dei pod di calcolo Symphony all'interno del cluster GKE.

Crea l'immagine dell'operatore

Per generare ed eseguire il deployment dei manifest Kubernetes per l'operatore, devi prima creare l'immagine container dell'operatore. I manifest includono la definizione di risorsa personalizzata (CRD) che l'operatore utilizza per gestire Symphony. Per acquisire l'immagine, puoi crearla dal codice sorgente.

Per creare l'immagine dell'operatore dall'origine, completa i seguenti passaggi:

Clona il repository symphony-gcp-connector da GitHub:

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

Vai alla directory k8s-operator:
```
cd symphony-gcp-connector/k8s-operator
```
Imposta le variabili di ambiente per il nome, il registro e il tag dell'immagine:
```
export IMAGE="gcp-symphony-operator"
export REGISTRY="IMAGE_REPO"
export TAG="TAG"
```
Sostituisci quanto segue:
- IMAGE_REPO: il repository di immagini in cui è archiviata l'immagine dell'operatore. Ad esempio, puoi utilizzare Artifact Registry per archiviare le immagini degli operatori. Per saperne di più, consulta Creare repository Docker.
- TAG: il tag per l'immagine dell'operatore, ad esempio 0.0.1.

Crea ed esegui il push dell'immagine dell'operatore:

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'

Configura i manifest dell'operatore

Dopo aver ottenuto l'immagine dell'operatore, devi generare e configurare i manifest Kubernetes.

Per generare i manifest, utilizza il comando export-manifests con l'immagine dell'operatore:
```
docker run --rm gcp-symphony-operator:latest export-manifests > manifests.yaml
```
Apri il file manifests.yaml in un editor di testo di tua scelta.
Nella sezione spec.template.spec.containers, individua il campo image e aggiorna il relativo valore con il percorso completo dell'immagine che hai inviato al tuo registro.
```
...
containers:
- image: IMAGE_REPO/gcp-symphony-operator:TAG
  name: manager
...
```
Sostituisci quanto segue:
- IMAGE_REPO: il percorso del repository di immagini in cui hai eseguito il push dell'immagine dell'operatore.
- TAG: il tag che hai assegnato all'immagine dell'operatore quando l'hai creata.
(Facoltativo) Puoi anche modificare il valore di imagePullPolicy in modo che sia in linea con le tue pratiche di gestione dei cluster.

Applica i manifest dell'operatore

Dopo aver configurato i manifest, applicali al tuo cluster Kubernetes. Puoi applicare i manifest utilizzando kubectl o Cluster Toolkit.

kubectl: per applicare i manifest utilizzando kubectl, esegui il seguente comando:
```
kubectl apply -f manifests.yaml
```
Cluster Toolkit: se la tua infrastruttura GKE è gestita da Cluster Toolkit, aggiungi una origine modules/management/kubectl-apply al tuo progetto GKE per applicare i manifest. Di seguito è riportato un esempio di configurazione, supponendo che il file manifests.yaml si trovi nella stessa directory del blueprint GKE:
```
  -   id: symphony_operator_install
      source: modules/management/kubectl-apply
      use: [gke_cluster]
      settings:
      apply_manifests:
        -   source: $(ghpc_stage("manifests.yaml"))
```
Per saperne di più, consulta la panoramica di Cluster Toolkit.

Carica le variabili di ambiente della fabbrica di host

Prima di poter configurare o gestire i servizi di fabbrica host, devi caricare le variabili di ambiente Symphony nella sessione della shell. Nella VM host primaria di Symphony, esegui questo comando:

source INSTALL_FOLDER/profile.platform

Sostituisci INSTALL_FOLDER con il percorso della cartella di installazione. Il percorso predefinito della cartella di installazione di Symphony è /opt/ibm/spectrumcomputing. Tuttavia, se hai installato Symphony altrove, devi utilizzare il percorso corretto per il tuo ambiente.

Questo comando esegue lo script profile.platform, che esporta le variabili di ambiente essenziali come $EGO_TOP e $HF_TOP e aggiunge gli strumenti a riga di comando di Symphony a PATH della shell. Devi eseguire questo comando per ogni nuova sessione del terminale per assicurarti che l'ambiente sia configurato correttamente.

Installare il plug-in del fornitore

Per integrare il provider GKE con l'host factory di Symphony, installa il plug-in del provider predefinito dal pacchetto RPM o crea il provider dal codice sorgente.

Installa il plug-in del fornitore predefinito

Per installare il plug-in del provider utilizzando i pacchetti RPM, segui questi passaggi sulla VM host principale di Symphony:

Aggiungi il repository yum per i Google Cloud connettori Symphony:

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

Installa il pacchetto del provider per GKE:

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

L'installazione di RPM inserisce automaticamente gli eseguibili e gli script del provider nelle directory corrette per il servizio di fabbrica host Symphony. Dopo l'installazione, la struttura di directory del plug-in del provider viene visualizzata come segue per il percorso $HF_TOP/$HF_VERSION/providerplugins/gcpgke:

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

Crea il provider dal codice sorgente

Per creare e installare l'eseguibile CLI nella directory bin della directory dei plug-in del provider, segui questi passaggi:

Clona il repository symphony-gcp-connector da GitHub:

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

Vai alla directory hf-provider:
```
cd PROJECT_ROOT/hf-provider
```
Sostituisci PROJECT_ROOT con il percorso della directory di primo livello che contiene la directory hf-provider, ad esempio /home/user/symphony-gcp-connector.
Se non hai installato uv, installalo:
```
pip install uv
```
Crea un ambiente virtuale Python utilizzando il gestore di pacchetti Python uv:
```
uv venv
```
Attiva l'ambiente virtuale:
```
source .venv/bin/activate
```
Installa le dipendenze del progetto richieste:
```
uv pip install .
```
Installa PyInstaller, che raggruppa l'applicazione Python in un eseguibile autonomo:
```
uv pip install pyinstaller
```
Crea la CLI hf-gke per i cluster Google Kubernetes Engine:
```
uv run pyinstaller hf-gke.spec --clean
```
Per verificare l'installazione, esegui il comando --help per un eseguibile. Potresti visualizzare un errore se non imposti le variabili di ambiente richieste.
```
dist/hf-gke --help
```

Se crei manualmente il provider, crea le directory dei plug-in del provider per il binario e gli script:

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

Copia il file binario hf-gke e gli script nelle directory dei plug-in del provider. Il file binario hf-gke si trova nella directory dist/ creata da PyInstaller e gli script si trovano nella directory scripts/gcpgke/:
```
cp dist/hf-gke $HF_TOP/$HF_VERSION/providerplugins/gcpgke/bin/
cp scripts/gcpgke/* $HF_TOP/$HF_VERSION/providerplugins/gcpgke/scripts/
```
Dopo l'installazione, la struttura delle directory del plug-in del provider viene visualizzata come segue per il percorso $HF_TOP/$HF_VERSION/providerplugins/gcpgke:

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

Attiva il plug-in del provider

Per abilitare il plug-in del provider GKE, devi registrarlo nella configurazione della fabbrica host.

Apri il file ${HF_TOP}/conf/providerplugins/hostProviderPlugins.json.

Il comando source definisce la variabile di ambiente $HF_TOP nel tuo ambiente. Il valore è il percorso della directory di installazione di primo livello per il servizio di fabbrica host IBM Spectrum Symphony.

Aggiungi una sezione del plug-in del provider gcpgke:

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

Configura un'istanza del fornitore

Per configurare il provider GKE per il tuo ambiente, crea un'istanza del provider.

Se crei manualmente il connettore, crea una directory per l'istanza del fornitore, ad esempio: $HF_TOP/conf/providers/gcpgkeinst/.

La variabile di ambiente $HF_TOP è definita nel tuo ambiente se hai recuperato profile.platform script. Il valore è il percorso della directory di installazione di primo livello per il servizio host factory di IBM Spectrum Symphony.

Nella directory dell'istanza del provider ($HF_TOP/conf/providers/gcpgkeinst/), crea o configura il file gcpgkeinstprov_config.json. Questo file contiene la configurazione principale per il provider.

Se hai installato il plug-in del provider utilizzando il pacchetto RPM, puoi copiare il file di configurazione di esempio e poi personalizzarlo:
```
cp $HF_TOP/conf/providers/gcpgkeinst/gcpgkeinstprov_config.json.dist $HF_TOP/conf/providers/gcpgkeinst/gcpgkeinstprov_config.json
```
Se hai creato il fornitore dal codice sorgente, crea un file gcpgkeinstprov_config.json.

Per questo file, in genere devi configurare solo la variabile GKE_KUBECONFIG, che definisce il percorso di un file di configurazione kubectl standard per il cluster GKE associato. Se non specifichi un percorso, il valore predefinito è kubeconfig nella directory dell'istanza del provider. Devi assicurarti che questo percorso punti a un file di configurazione kubectl valido per il cluster Kubernetes utilizzato da questa istanza del provider.

Di seguito è riportata una configurazione di esempio:

{
  "GKE_KUBECONFIG": "kubeconfig"
}

Sono supportate le seguenti variabili di configurazione:

Nome variabile	Descrizione	Valore predefinito
`GKE_KUBECONFIG`	Il percorso del file di configurazione utilizzato dal comando kubectl.	Nessuno
`GKE_CRD_NAMESPACE`*	Definisce lo spazio dei nomi Kubernetes in cui vengono create tutte le risorse.	`gcp-symphony`
`GKE_CRD_GROUP`*	Il gruppo di risorse utilizzato per identificare le risorse personalizzate per l'operatore di fabbrica host GKE.	`accenture.com`
`GKE_CRD_VERSION`*	La versione utilizzata per identificare le risorse personalizzate per l'operatore host factory GKE.	`v1`
`GKE_CRD_KIND`*	Il nome assegnato alla definizione della risorsa personalizzata che definisce una richiesta di risorse di calcolo (pod).	`GCP Symphony Resource`
`GKE_CRD_SINGULAR`*	Utilizzato nelle chiamate API quando si fa riferimento a un'istanza della richiesta di modifica Google Cloud Symphony `Resource`.	`gcp-symphony-resource`
`GKE_CRD_RETURN_REQUEST_KIND`*	Il nome assegnato alla definizione della risorsa personalizzata che definisce una richiesta di restituzione delle risorse di calcolo (pod).	`Machine Return Request`
`GKE_CRD_RETURN_REQUEST_SINGULAR`*	Utilizzato nelle chiamate API quando si fa riferimento a una singola istanza di risorsa personalizzata `MachineReturnRequest`.	`machine-return-request`
`GKE_REQUEST_TIMEOUT`	La durata, in secondi, durante la quale una richiesta al control plane GKE attende una risposta.	`300`
`LOG_LEVEL`	Controlla il livello di dettaglio del log che il provider GKE scrive nel file di log. Le opzioni sono `CRITICAL`, `WARNING`, `ERROR`, `INFO`, `DEBUG`.	`WARNING`

Nella stessa directory, crea o configura il file gcpgkeinstprov_templates.json. Questo file definisce i modelli per i pod che il provider può creare.

Se hai installato il plug-in del provider utilizzando il pacchetto RPM, puoi copiare il file dei modelli di esempio e personalizzarlo:

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

Se hai creato il fornitore dal codice sorgente, crea un file gcpgkeinstprov_templates.json.

Gli attributi del modello devono essere allineati alle risorse in una specifica del pod. Di seguito è riportato un modello di esempio:

{
    "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"
        }
    ]
}

Nella stessa directory, crea un file kubeconfig valido per kubectl per il tuo cluster Kubernetes.
Nella directory dell'istanza del provider, crea o modifica il file pod-spec.yaml. Questo file funge da modello che definisce le specifiche per i pod di calcolo Symphony creati nel tuo cluster GKE.

I pod creati da questa specifica funzionano come nodi di calcolo e richiedono l'accesso all'installazione di Symphony. Questo accesso può essere fornito tramite l'immagine container, che include l'installazione di Symphony, o tramite un montaggio del file system condiviso che contiene l'installazione. All'avvio, i pod utilizzano questo accesso per partecipare al cluster Symphony.

I passaggi per creare il file dipendono da come hai installato il fornitore:
- Se hai installato il provider da un pacchetto RPM, copia il file pod-spec.yaml.dist di esempio incluso nell'installazione:
```
cp $HF_TOP/conf/providers/gcpgkeinst/pod-specs/pod-spec.yaml.dist
$HF_TOP/conf/providers/gcpgkeinst/pod-specs/pod-spec.yaml
```
- Se hai creato il provider dal codice sorgente, crea manualmente la directory pod-specs e il file pod-spec.yaml:
```
mkdir -p $HF_TOP/conf/providers/gcpgkeinst/pod-specs touch
$HF_TOP/conf/providers/gcpgkeinst/pod-specs/pod-spec.yaml
```

Dopo aver creato questi file, verifica che la directory dell'istanza del provider venga visualizzata come segue:

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

Abilita l'istanza del provider

Per attivare l'istanza del fornitore, attivala nel file di configurazione della fabbrica host:

Apri il file $HF_TOP/conf/providers/hostProviders.json.
Aggiungi una sezione dell'istanza del provider gcpgkeinst:
```
{
    "name": "gcpgkeinst",
    "enabled": 1,
    "plugin": "gcpgke",
    "confPath": "${HF_CONFDIR}/providers/gcpgkeinst/",
    "workPath": "${HF_WORKDIR}/providers/gcpgkeinst/",
    "logPath": "${HF_LOGDIR}/"
}
```
Non devi sostituire le variabili ${HF_CONFDIR}, ${HF_WORKDIR} e ${HF_LOGDIR} in questa configurazione perché sono variabili di ambiente standard definite automaticamente dall'ambiente host factory di IBM Spectrum Symphony.

Quando configuri la sessione della shell eseguendo source command, questo script imposta queste variabili in modo che puntino alle sottodirectory corrette all'interno dell'installazione di Symphony. Il servizio di fabbrica dell'host utilizza queste variabili per costruire i percorsi completi in fase di runtime.

Abilitare l'istanza del richiedente

Per consentire a un componente Symphony specifico di utilizzare il provider GKE per eseguire il provisioning delle risorse, attivalo per il richiedente.

Apri il file $HF_TOP/conf/requestors/hostRequestors.json.
Nell'istanza del richiedente appropriata, aggiungi gcpgkeinst al parametro providers:
```
"providers": ["gcpgkeinst"],
```
Il valore del fornitore deve corrispondere al nome del fornitore che utilizzi in Attiva l'istanza del fornitore.

Avvia il servizio di fabbrica dell'host

Per applicare le modifiche alla configurazione, avvia il servizio di fabbrica dell'host. Nella VM host principale di Symphony, accedi come amministratore del cluster e avvia il servizio:

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

Sostituisci quanto segue:

SYMPHONY_USERNAME: il nome utente Symphony per l'autenticazione.
SYMPHONY_PASSWORD: la password per l'utente Symphony.

Testare i connettori

Crea una richiesta di risorse per testare il provider per GKE.

Per farlo, utilizza uno dei seguenti metodi:

GUI di Symphony: per istruzioni su come creare una richiesta di risorse utilizzando la GUI di Symphony, consulta Pianificazione manuale delle richieste e dei ritorni di host cloud nella documentazione IBM.

API REST: per creare una richiesta di risorse utilizzando l'API REST, segui questi passaggi:

Trova l'host e la porta dell'API REST di Host Factory:

egosh client view REST_HOST_FACTORY_URL

L'output è simile a questo esempio:

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

Per creare una richiesta di risorse utilizzando l'API REST, utilizza il seguente comando:
```
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
```
Sostituisci quanto segue:
- PRIMARY_HOST: il nome host dell'host principale dall'output del comando precedente.
- PORT: il numero di porta dell'host principale dall'output del comando precedente, ad esempio 9080.
- SYMPHONY_TEMPLATE_ID: il templateId definito nel file gcpgkeinstprov_templates.json, ad esempio template-gcp-01.
- SYMPHONY_USER: l'utente Symphony per l'autenticazione.
- SYMPHONY_PASSWORD: la password per l'utente Symphony.
Se l'operazione va a buon fine, l'output è simile a questo esempio:
```
{"scheduled_request_id":["SD-641ef442-1f9e-40ae-ae16-90e152ed60d2"]}
```

Passaggi successivi

Risolvere i problemi relativi ai connettori IBM Spectrum Symphony