Instala el proveedor de Google Kubernetes Symphony

Para integrar IBM Symphony con Google Kubernetes Engine (GKE) para la administración dinámica de recursos, debes instalar y configurar el proveedor de Symphony para GKE. Este proveedor permite que Symphony aprovisione y administre recursos de procesamiento como Pods en tu clúster de GKE, lo que permite un ajuste de escala eficiente de la carga de trabajo a través de la organización de Kubernetes.

Para habilitar esta integración, instala un operador de Kubernetes en tu clúster, instala el complemento del proveedor en tu host principal de Symphony y configura el servicio de fábrica de hosts de Symphony para que se comunique con GKE.

Para obtener más información sobre los conectores de Symphony para Google Cloud, consulta Integrate IBM Spectrum Symphony with Google Cloud.

Antes de comenzar

Para instalar el proveedor de Symphony para GKE, debes tener los siguientes recursos:

Un clúster de IBM Spectrum Symphony en ejecución con el servicio de fábrica de hosts habilitado.
Un clúster de GKE en ejecución Para crear uno, consulta la visión general de GKE.
Una cuenta de servicio con los permisos adecuados Consulta la sección Roles requeridos para obtener más detalles.
La herramienta de línea de comandos de kubectl instalada y configurada para comunicarse con tu clúster de GKE

Roles obligatorios

Para obtener los permisos que necesitas para instalar el operador y administrar los Pods de Symphony, pídele a tu administrador que te otorgue los siguientes roles de IAM en tu proyecto:

Para administrar recursos de Kubernetes, debes tener el rol de Administrador de Kubernetes Engine (roles/container.admin).

Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

También puedes obtener los permisos necesarios a través de roles personalizados o cualquier otro rol predefinido.

Instala el operador de Kubernetes

Antes de instalar el proveedor de GKE, debes instalar el operador de Kubernetes asociado. El operador administra el ciclo de vida de los Pods de procesamiento de Symphony dentro de tu clúster de GKE.

Compila la imagen del operador

Para generar e implementar los manifiestos de Kubernetes para el operador, primero debes compilar la imagen del contenedor del operador. Los manifiestos incluyen la Definición de recurso personalizado (CRD) que el operador usa para administrar Symphony. Para adquirir la imagen, puedes compilarla desde la fuente.

Para compilar la imagen del operador desde la fuente, completa los siguientes pasos:

Clona el repositorio de symphony-gcp-connector desde GitHub:

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

Navega al directorio k8s-operator:
```
cd symphony-gcp-connector/k8s-operator
```
Establece las variables de entorno para el nombre, el registro y la etiqueta de la imagen:
```
export IMAGE="gcp-symphony-operator"
export REGISTRY="IMAGE_REPO"
export TAG="TAG"
```
Reemplaza lo siguiente:
- IMAGE_REPO: Es el repositorio de imágenes en el que se almacena la imagen del operador. Por ejemplo, puedes usar Artifact Registry para almacenar tus imágenes de operador. Para obtener más información, consulta Crea repositorios de Docker.
- TAG: Es la etiqueta de la imagen del operador, por ejemplo, 0.0.1.

Compila y envía la imagen del operador:

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 los manifiestos del operador

Después de obtener la imagen del operador, debes generar y configurar los manifiestos de Kubernetes.

Para generar los manifiestos, usa el comando export-manifests con la imagen del operador:
```
docker run --rm gcp-symphony-operator:latest export-manifests > manifests.yaml
```
Abre el archivo manifests.yaml en el editor de texto que prefieras.
En la sección spec.template.spec.containers, busca el campo image y actualiza su valor a la ruta de acceso completa de la imagen que enviaste a tu registro.
```
...
containers:
- image: IMAGE_REPO/gcp-symphony-operator:TAG
  name: manager
...
```
Reemplaza lo siguiente:
- IMAGE_REPO: Es la ruta de acceso al repositorio de imágenes en el que enviaste la imagen del operador.
- TAG: Es la etiqueta que asignaste a la imagen del operador cuando la compilaste.
Opcional: También puedes modificar el valor de imagePullPolicy para que se alinee con tus prácticas de administración de clústeres.

Aplica los manifiestos del operador

Después de configurar los manifiestos, aplícalos a tu clúster de Kubernetes. Puedes aplicar los manifiestos con kubectl o Cluster Toolkit.

kubectl: Para aplicar los manifiestos con kubectl, ejecuta el siguiente comando:
```
kubectl apply -f manifests.yaml
```
Cluster Toolkit: Si Cluster Toolkit administra tu infraestructura de GKE, agrega una fuente modules/management/kubectl-apply a tu esquema de GKE para aplicar los manifiestos. A continuación, se muestra un ejemplo de configuración, en el que se supone que el archivo manifests.yaml se encuentra en el mismo directorio que el blueprint de GKE:
```
  -   id: symphony_operator_install
      source: modules/management/kubectl-apply
      use: [gke_cluster]
      settings:
      apply_manifests:
        -   source: $(ghpc_stage("manifests.yaml"))
```
Para obtener más información, consulta la descripción general del Cluster Toolkit.

Carga las variables de entorno de la fábrica de host

Antes de configurar o administrar los servicios de la fábrica de hosts, debes cargar las variables de entorno de Symphony en tu sesión de shell. En la VM del host principal de Symphony, ejecuta el siguiente comando:

source INSTALL_FOLDER/profile.platform

Reemplaza INSTALL_FOLDER por la ruta de acceso a tu carpeta de instalación. La ruta de acceso predeterminada a la carpeta de instalación de Symphony es /opt/ibm/spectrumcomputing. Sin embargo, si instalaste Symphony en otro lugar, debes usar la ruta correcta para tu entorno.

Este comando ejecuta la secuencia de comandos profile.platform, que exporta variables de entorno esenciales, como $EGO_TOP y $HF_TOP, y agrega las herramientas de línea de comandos de Symphony a PATH de tu shell. Debes ejecutar este comando para cada sesión de terminal nueva para asegurarte de que el entorno esté configurado correctamente.

Instala el complemento del proveedor

Para integrar el proveedor de GKE con la fábrica de hosts de Symphony, instala el complemento del proveedor prediseñado desde el paquete RPM o compila el proveedor desde el código fuente.

Instala el complemento del proveedor precompilado

Para instalar el complemento del proveedor con paquetes RPM, sigue estos pasos en la VM del host principal de Symphony:

Agrega el repositorio yum para los conectores de Google Cloud 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

Instala el paquete del proveedor para GKE:

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

La instalación de RPM coloca automáticamente los ejecutables y las secuencias de comandos del proveedor en los directorios correctos para el servicio de fábrica del host de Symphony. Después de la instalación, la estructura de directorios del complemento del proveedor aparece de la siguiente manera para la ruta de acceso $HF_TOP/$HF_VERSION/providerplugins/gcpgke:

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

Compila el proveedor a partir del código fuente

Para compilar e instalar el ejecutable de la CLI en el directorio bin del directorio del complemento del proveedor, sigue estos pasos:

Clona el repositorio de symphony-gcp-connector desde GitHub:

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

Navega al directorio hf-provider:
```
cd PROJECT_ROOT/hf-provider
```
Reemplaza PROJECT_ROOT por la ruta de acceso al directorio de nivel superior que contiene el directorio hf-provider, como /home/user/symphony-gcp-connector.
Si no tienes instalado uv, hazlo:
```
pip install uv
```
Crea un entorno virtual de Python con el administrador de paquetes de Python uv:
```
uv venv
```
Activa el entorno virtual:
```
source .venv/bin/activate
```
Instala las dependencias necesarias del proyecto:
```
uv pip install .
```
Instala PyInstaller, que agrupa la aplicación de Python en un archivo ejecutable independiente:
```
uv pip install pyinstaller
```
Crea la CLI de hf-gke para los clústeres de Google Kubernetes Engine:
```
uv run pyinstaller hf-gke.spec --clean
```
Para verificar la instalación, ejecuta el comando --help para un archivo ejecutable. Es posible que veas un error si no configuras las variables de entorno necesarias.
```
dist/hf-gke --help
```
Si compilas el proveedor de forma manual, crea directorios de complementos del proveedor para el binario y los secuencias de comandos:
```
mkdir -p $HF_TOP/$HF_VERSION/providerplugins/gcpgke/bin
mkdir -p $HF_TOP/$HF_VERSION/providerplugins/gcpgke/scripts
```
Copia los objetos binarios y las secuencias de comandos de hf-gke en los directorios de complementos del proveedor. El objeto binario hf-gke se encuentra en el directorio dist/ que creó PyInstaller, y los secuencias de comandos están en el directorio scripts/gcpgke/:
```
cp dist/hf-gke $HF_TOP/$HF_VERSION/providerplugins/gcpgke/bin/
cp scripts/gcpgke/* $HF_TOP/$HF_VERSION/providerplugins/gcpgke/scripts/
```
Después de la instalación, la estructura de directorios del complemento del proveedor aparecerá de la siguiente manera para la ruta de acceso $HF_TOP/$HF_VERSION/providerplugins/gcpgke:

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

Habilita el complemento del proveedor

Para habilitar el complemento del proveedor de GKE, debes registrarlo en la configuración de la fábrica de hosts.

Abre el archivo ${HF_TOP}/conf/providerplugins/hostProviderPlugins.json.

El comando source define la variable de entorno $HF_TOP en tu entorno. El valor es la ruta de acceso al directorio de instalación de nivel superior para el servicio de fábrica de hosts de IBM Spectrum Symphony.

Agrega una sección del complemento del proveedor gcpgke:

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

Configura una instancia del proveedor

Para configurar el proveedor de GKE para tu entorno, crea una instancia del proveedor.

Si compilas el conector de forma manual, crea un directorio para la instancia del proveedor, como $HF_TOP/conf/providers/gcpgkeinst/.

La variable de entorno $HF_TOP se define en tu entorno si obtuviste el código fuente de profile.platform script. El valor es la ruta de acceso al directorio de instalación de nivel superior para el servicio de fábrica de hosts de IBM Spectrum Symphony.

En el directorio de la instancia del proveedor ($HF_TOP/conf/providers/gcpgkeinst/), crea o configura el archivo gcpgkeinstprov_config.json. Este archivo contiene la configuración principal del proveedor.

Si instalaste el complemento del proveedor con el paquete RPM, puedes copiar el archivo de configuración de ejemplo y, luego, personalizarlo:
```
cp $HF_TOP/conf/providers/gcpgkeinst/gcpgkeinstprov_config.json.dist $HF_TOP/conf/providers/gcpgkeinst/gcpgkeinstprov_config.json
```
Si compilaste el proveedor desde la fuente, crea un archivo gcpgkeinstprov_config.json.

Para este archivo, por lo general, solo necesitas configurar la variable GKE_KUBECONFIG, que define la ruta de acceso a un archivo de configuración de kubectl estándar para el clúster de GKE asociado. Si no especificas una ruta de acceso, se establecerá de forma predeterminada kubeconfig en el directorio de la instancia del proveedor. Debes asegurarte de que esta ruta de acceso apunte a un archivo de configuración de kubectl válido para el clúster de Kubernetes que usa esta instancia del proveedor.

A continuación, se muestra una configuración de ejemplo:

{
  "GKE_KUBECONFIG": "kubeconfig"
}

Se admiten las siguientes variables de configuración:

Nombre de la variable	Descripción	Valor predeterminado
`GKE_KUBECONFIG`	Es la ruta de acceso al archivo de configuración que usa el comando kubectl.	Ninguno
`GKE_CRD_NAMESPACE`*	Define el espacio de nombres de Kubernetes en el que se crean todos los recursos.	`gcp-symphony`
`GKE_CRD_GROUP`*	Es el grupo de recursos que se usa para identificar los recursos personalizados del operador de la fábrica de hosts de GKE.	`accenture.com`
`GKE_CRD_VERSION`*	Es la versión que se usa para identificar los recursos personalizados del operador de la fábrica de hosts de GKE.	`v1`
`GKE_CRD_KIND`*	Es el nombre que se le asigna a la definición de recurso personalizado que define una solicitud de recursos de procesamiento (pods).	`GCP Symphony Resource`
`GKE_CRD_SINGULAR`*	Se usa en las llamadas a la API cuando se hace referencia a una instancia de la CR de Google Cloud Symphony `Resource`.	`gcp-symphony-resource`
`GKE_CRD_RETURN_REQUEST_KIND`*	Es el nombre que se le asigna a la definición de recurso personalizado que define una solicitud para devolver recursos de procesamiento (pods).	`Machine Return Request`
`GKE_CRD_RETURN_REQUEST_SINGULAR`*	Se usa en las llamadas a la API cuando se hace referencia a una sola instancia de recurso personalizado `MachineReturnRequest`.	`machine-return-request`
`GKE_REQUEST_TIMEOUT`	Es la duración, en segundos, que una solicitud al plano de control de GKE espera una respuesta.	`300`
`LOG_LEVEL`	Controla el nivel de detalle del registro que escribe el proveedor de GKE en el archivo de registro. Las opciones son `CRITICAL`, `WARNING`, `ERROR`, `INFO` y `DEBUG`.	`WARNING`

En el mismo directorio, crea o configura el archivo gcpgkeinstprov_templates.json. Este archivo define las plantillas para los pods que puede crear el proveedor.

Si instalaste el complemento del proveedor con el paquete RPM, puedes copiar el archivo de plantillas de ejemplo y, luego, personalizarlo:

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

Si compilaste el proveedor desde la fuente, crea un archivo gcpgkeinstprov_templates.json.

Los atributos de la plantilla deben alinearse con los recursos de una especificación de pod. A continuación, se muestra una plantilla de ejemplo:

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

En el mismo directorio, crea un archivo kubeconfig que sea un archivo de configuración de kubectl válido para tu clúster de Kubernetes.
En el directorio de la instancia del proveedor, crea o edita el archivo pod-spec.yaml. Este archivo actúa como una plantilla que define las especificaciones de los pods de procesamiento de Symphony que se crean en tu clúster de GKE.

Los pods creados a partir de esta especificación funcionan como nodos de procesamiento y requieren acceso a la instalación de Symphony. Se puede proporcionar este acceso a través de la imagen del contenedor, que incluye la instalación de Symphony, o a través de un montaje del sistema de archivos compartido que contiene la instalación. Al inicio, los pods usan este acceso para unirse al clúster de Symphony.

Los pasos para crear el archivo dependen de cómo instalaste el proveedor:
- Si instalaste el proveedor desde un paquete RPM, copia el archivo pod-spec.yaml.dist de ejemplo que se incluyó en la instalación:
```
cp $HF_TOP/conf/providers/gcpgkeinst/pod-specs/pod-spec.yaml.dist
$HF_TOP/conf/providers/gcpgkeinst/pod-specs/pod-spec.yaml
```
- Si compilaste el proveedor desde la fuente, crea el directorio pod-specs y el archivo pod-spec.yaml de forma manual:
```
mkdir -p $HF_TOP/conf/providers/gcpgkeinst/pod-specs touch
$HF_TOP/conf/providers/gcpgkeinst/pod-specs/pod-spec.yaml
```

Después de crear estos archivos, verifica que el directorio de la instancia del proveedor aparezca de la siguiente manera:

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

Habilita la instancia del proveedor

Para activar la instancia del proveedor, habilítala en el archivo de configuración de la fábrica de host:

Abre el archivo $HF_TOP/conf/providers/hostProviders.json.
Agrega una sección de instancia del proveedor gcpgkeinst:
```
{
    "name": "gcpgkeinst",
    "enabled": 1,
    "plugin": "gcpgke",
    "confPath": "${HF_CONFDIR}/providers/gcpgkeinst/",
    "workPath": "${HF_WORKDIR}/providers/gcpgkeinst/",
    "logPath": "${HF_LOGDIR}/"
}
```
No es necesario que reemplaces las variables ${HF_CONFDIR}, ${HF_WORKDIR} y ${HF_LOGDIR} en esta configuración, ya que son variables de entorno estándar que se definen automáticamente en el entorno de fábrica del host de IBM Spectrum Symphony.

Cuando ejecutas source command para configurar tu sesión de shell, esta secuencia de comandos establece estas variables para que apunten a los subdirectorios correctos dentro de tu instalación de Symphony. Luego, el servicio de fábrica de host usa estas variables para construir las rutas completas en el tiempo de ejecución.

Habilita la instancia del solicitante

Para permitir que un componente específico de Symphony use el proveedor de GKE para aprovisionar recursos, habilítalo para ese solicitante.

Abre el archivo $HF_TOP/conf/requestors/hostRequestors.json.
En la instancia del solicitante adecuada, agrega gcpgkeinst al parámetro providers:
```
"providers": ["gcpgkeinst"],
```
El valor del proveedor debe coincidir con el nombre del proveedor que usas en Habilita la instancia del proveedor.

Inicia el servicio de Host Factory

Para aplicar los cambios de configuración, inicia el servicio de Host Factory. En la VM host principal de Symphony, accede como administrador del clúster y, luego, inicia el servicio:

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

Reemplaza lo siguiente:

SYMPHONY_USERNAME: Es el nombre de usuario de Symphony para la autenticación.
SYMPHONY_PASSWORD: La contraseña del usuario de Symphony.

Probar conectores

Crea una solicitud de recursos para probar el proveedor de GKE.

Para ello, usa uno de los siguientes métodos:

GUI de Symphony: Para obtener instrucciones sobre cómo crear una solicitud de recursos con la GUI de Symphony, consulta Cómo programar manualmente solicitudes y devoluciones de hosts en la nube en la documentación de IBM.
API de REST: Para crear una solicitud de recursos con la API de REST, sigue estos pasos:
1. Busca el host y el puerto de la API de REST de la fábrica de hosts:
```
egosh client view REST_HOST_FACTORY_URL
```
  El resultado es similar al siguiente ejemplo:
```
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. Para crear una solicitud de recurso con la API de REST, usa el siguiente 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
```
  Reemplaza lo siguiente:
  - PRIMARY_HOST: Es el nombre de host de tu host principal del resultado del comando anterior.
  - PORT: El número de puerto de tu host principal del resultado del comando anterior, como 9080.
  - SYMPHONY_TEMPLATE_ID: El templateId definido en el archivo gcpgkeinstprov_templates.json, como template-gcp-01.
  - SYMPHONY_USER: Es el usuario de Symphony para la autenticación.
  - SYMPHONY_PASSWORD: Es la contraseña del usuario de Symphony.
  Si se ejecuta de forma correcta, el resultado será similar al siguiente ejemplo:
```
{"scheduled_request_id":["SD-641ef442-1f9e-40ae-ae16-90e152ed60d2"]}
```

¿Qué sigue?

Soluciona problemas de los conectores de IBM Spectrum Symphony