Instalar o provedor do Google Kubernetes Symphony

Para integrar o IBM Symphony ao Google Kubernetes Engine (GKE) para gerenciamento dinâmico de recursos, instale e configure o provedor do Symphony para GKE. Esse provedor permite que o Symphony provisione e gerencie recursos de computação como pods no cluster do GKE, o que permite o escalonamento eficiente da carga de trabalho pela orquestração do Kubernetes.

Para ativar essa integração, instale um operador do Kubernetes no seu cluster, o plug-in do provedor no host principal do Symphony e configure o serviço de fábrica de hosts do Symphony para se comunicar com o GKE.

Para mais informações sobre os conectores do Symphony para Google Cloud, consulte Integrar o IBM Spectrum Symphony ao Google Cloud.

Antes de começar

Para instalar o provedor do Symphony para GKE, você precisa ter os seguintes recursos:

Um cluster do IBM Spectrum Symphony em execução com o serviço de fábrica de hosts ativado.
Um cluster do GKE em execução. Para criar um, consulte a visão geral do GKE.
Uma conta de serviço com as permissões adequadas. Consulte a seção Funções necessárias para mais detalhes.
A ferramenta de linha de comando kubectl instalada e configurada para se comunicar com o cluster do GKE.

Funções exigidas

Para ter as permissões necessárias para instalar o operador e gerenciar pods do Symphony, peça ao administrador para conceder a você os seguintes papéis do IAM no projeto:

Para gerenciar recursos do Kubernetes: Administrador do Kubernetes Engine (roles/container.admin)

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

Instalar o operador do Kubernetes

Antes de instalar o provedor do GKE, instale o operador do Kubernetes associado. O operador gerencia o ciclo de vida dos pods de computação do Symphony no cluster do GKE.

Criar a imagem do operador

Para gerar e implantar os manifestos do Kubernetes para o operador, primeiro é necessário criar a imagem do contêiner do operador. Os manifestos incluem a definição de recurso personalizado (CRD) que o operador usa para gerenciar o Symphony. Para adquirir a imagem, crie-a da origem.

Para criar a imagem do operador da origem, siga estas etapas:

Clone o repositório symphony-gcp-connector do GitHub:

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

Navegue até o diretório k8s-operator:
```
cd symphony-gcp-connector/k8s-operator
```
Defina as variáveis de ambiente para o nome da imagem, o registro e a tag:
```
export IMAGE="gcp-symphony-operator"
export REGISTRY="IMAGE_REPO"
export TAG="TAG"
```
Substitua:
- IMAGE_REPO: o repositório de imagens em que a imagem do operador está armazenada. Por exemplo, é possível usar o Artifact Registry para armazenar as imagens do operador. Para mais informações, consulte Criar repositórios do Docker.
- TAG: a tag da imagem do operador, por exemplo, 0.0.1.

Crie e envie a imagem do 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'

Configurar os manifestos do operador

Depois de ter a imagem do operador, gere e configure os manifestos do Kubernetes.

Para gerar os manifestos, use o comando export-manifests com a imagem do operador:

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

Abra o arquivo manifests.yaml em um editor de texto de sua preferência.
Na seção spec.template.spec.containers, localize o campo image e atualize o valor dele para o caminho completo da imagem enviada por push ao registro.
```
...
containers:
- image: IMAGE_REPO/gcp-symphony-operator:TAG
  name: manager
...
```
Substitua:
- IMAGE_REPO: o caminho para o repositório de imagens em que você enviou a imagem do operador.
- TAG: a tag que você atribuiu à imagem do operador ao criá-la.
Opcional: também é possível modificar o valor imagePullPolicy para se alinhar às suas práticas de gerenciamento de cluster.

Aplicar os manifestos do operador

Depois de configurar os manifestos, aplique-os ao cluster do Kubernetes. É possível aplicar os manifestos usando kubectl ou o Cluster Toolkit.

kubectl: para aplicar os manifestos usando kubectl, execute o seguinte comando:
```
kubectl apply -f manifests.yaml
```
Cluster Toolkit: se a infraestrutura do GKE for gerenciada pelo Cluster Toolkit, adicione uma fonte modules/management/kubectl-apply ao blueprint do GKE para aplicar os manifestos. Este é um exemplo de configuração, supondo que o arquivo manifests.yaml esteja no mesmo diretório que o blueprint do GKE:
```
  -   id: symphony_operator_install
      source: modules/management/kubectl-apply
      use: [gke_cluster]
      settings:
      apply_manifests:
        -   source: $(ghpc_stage("manifests.yaml"))
```
Para mais informações, consulte a visão geral do Cluster Toolkit.

Carregar as variáveis de ambiente de fábrica de host

Antes de configurar ou gerenciar os serviços de fábrica de host, carregue as variáveis de ambiente do Symphony na sessão do shell. Na VM do host principal do Symphony, execute o seguinte comando:

source INSTALL_FOLDER/profile.platform

Substitua INSTALL_FOLDER pelo caminho da pasta de instalação. O caminho padrão da pasta de instalação do Symphony é /opt/ibm/spectrumcomputing. No entanto, se você instalou o Symphony em outro lugar, use o caminho correto para seu ambiente.

Esse comando executa o script profile.platform, que exporta variáveis de ambiente essenciais, como $EGO_TOP e $HF_TOP, e adiciona as ferramentas de linha de comando do Symphony ao PATH do shell. Execute esse comando para cada nova sessão de terminal e garantir que o ambiente esteja configurado corretamente.

Instalar o plug-in do provedor

Para integrar o provedor do GKE à fábrica de hosts do Symphony, instale o plug-in de provedor pré-criado do pacote RPM ou crie o provedor com o código fonte.

Instalar o plug-in do provedor pré-criado

Para instalar o plug-in do provedor usando pacotes RPM, siga estas etapas na VM do host principal do Symphony:

Adicione o repositório yum para os Google Cloud Symphony Connectors:

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

Instale o pacote do provedor para o GKE:

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

A instalação do RPM coloca automaticamente os executáveis e scripts do provedor nos diretórios corretos para o serviço de fábrica do host do Symphony. Após a instalação, a estrutura de diretórios do plug-in do provedor aparece da seguinte forma para o caminho $HF_TOP/$HF_VERSION/providerplugins/gcpgke:

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

Criar o provedor usando o código-fonte

Para criar e instalar o executável da CLI no diretório bin do diretório de plug-ins do provedor, siga estas etapas:

Clone o repositório symphony-gcp-connector do GitHub:

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

Navegue até o diretório hf-provider:
```
cd PROJECT_ROOT/hf-provider
```
Substitua PROJECT_ROOT pelo caminho para o diretório de nível superior que contém o diretório hf-provider, como /home/user/symphony-gcp-connector.
Se você não tiver o uv instalado, faça isso:
```
pip install uv
```
Crie um ambiente virtual em Python usando o gerenciador de pacotes uv do Python:
```
uv venv
```
Ative o ambiente virtual:
```
source .venv/bin/activate
```
Instale as dependências do projeto necessárias:
```
uv pip install .
```
Instale o PyInstaller, que agrupa o aplicativo Python em um executável independente:
```
uv pip install pyinstaller
```
Crie a CLI hf-gke para clusters do Google Kubernetes Engine:
```
uv run pyinstaller hf-gke.spec --clean
```
Para verificar a instalação, execute o comando --help em um executável. Se você não definir as variáveis de ambiente necessárias, um erro poderá aparecer.
```
dist/hf-gke --help
```

Se você criar o provedor manualmente, crie diretórios de plug-in do provedor para o binário e os scripts:

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

Copie o binário e os scripts hf-gke para os diretórios de plug-ins do provedor. O binário hf-gke está no diretório dist/ criado pelo PyInstaller, e os scripts estão no diretório scripts/gcpgke/:
```
cp dist/hf-gke $HF_TOP/$HF_VERSION/providerplugins/gcpgke/bin/
cp scripts/gcpgke/* $HF_TOP/$HF_VERSION/providerplugins/gcpgke/scripts/
```
Após a instalação, a estrutura de diretórios do plug-in do provedor aparece da seguinte maneira para o caminho $HF_TOP/$HF_VERSION/providerplugins/gcpgke:

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

Ativar o plug-in do provedor

Para ativar o plug-in do provedor do GKE, registre-o na configuração da fábrica de hosts.

Abra o arquivo ${HF_TOP}/conf/providerplugins/hostProviderPlugins.json.

O comando source define a variável de ambiente $HF_TOP no seu ambiente. O valor é o caminho para o diretório de instalação de nível superior do serviço de fábrica de hosts do IBM Spectrum Symphony.

Adicione uma seção de plug-in do provedor gcpgke:

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

Configurar uma instância de provedor

Para configurar o provedor do GKE no seu ambiente, crie uma instância de provedor.

Se você criar o conector manualmente, crie um diretório para a instância do provedor, como: $HF_TOP/conf/providers/gcpgkeinst/.

A variável de ambiente $HF_TOP é definida no seu ambiente se você originar o profile.platform script. O valor é o caminho para o diretório de instalação de nível superior do serviço de fábrica de hosts do IBM Spectrum Symphony.

No diretório da instância do provedor ($HF_TOP/conf/providers/gcpgkeinst/), crie ou configure o arquivo gcpgkeinstprov_config.json. Esse arquivo contém a configuração principal do provedor.

Se você instalou o plug-in do provedor usando o pacote RPM, copie o arquivo de configuração de exemplo e personalize-o:

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

Se você compilou o provedor da origem, crie um arquivo gcpgkeinstprov_config.json.

Para esse arquivo, normalmente você só precisa configurar a variável GKE_KUBECONFIG, que define o caminho para um arquivo de configuração kubectl padrão do cluster do GKE associado. Se você não especificar um caminho, o padrão será kubeconfig no diretório da instância do provedor. Verifique se esse caminho aponta para um arquivo de configuração kubectl válido para o cluster do Kubernetes usado por essa instância de provedor.

Veja a seguir um exemplo de configuração:

{
  "GKE_KUBECONFIG": "kubeconfig"
}

As seguintes variáveis de configuração são compatíveis:

Nome da variável	Descrição	Valor padrão
`GKE_KUBECONFIG`	O caminho para o arquivo de configuração usado pelo comando kubectl.	Nenhum
`GKE_CRD_NAMESPACE`*	Define o namespace do Kubernetes em que todos os recursos são criados.	`gcp-symphony`
`GKE_CRD_GROUP`*	O grupo de recursos usado para identificar recursos personalizados para o operador de fábrica de host do GKE.	`accenture.com`
`GKE_CRD_VERSION`*	A versão usada para identificar recursos personalizados para o operador de fábrica de hosts do GKE.	`v1`
`GKE_CRD_KIND`*	O nome dado à definição de recurso personalizado que define uma solicitação de recursos de computação (pods).	`GCP Symphony Resource`
`GKE_CRD_SINGULAR`*	Usado em chamadas de API ao se referir a uma instância do CR `Resource` do Google Cloud Symphony.	`gcp-symphony-resource`
`GKE_CRD_RETURN_REQUEST_KIND`*	O nome dado à definição de recurso personalizada que define uma solicitação para retornar recursos de computação (pods).	`Machine Return Request`
`GKE_CRD_RETURN_REQUEST_SINGULAR`*	Usado em chamadas de API ao se referir a uma única instância de recurso personalizado `MachineReturnRequest`.	`machine-return-request`
`GKE_REQUEST_TIMEOUT`	A duração, em segundos, que uma solicitação ao plano de controle do GKE aguarda uma resposta.	`300`
`LOG_LEVEL`	Controla o nível de detalhe do registro que o provedor do GKE grava no arquivo de registros. As opções são `CRITICAL`, `WARNING`, `ERROR`, `INFO`, `DEBUG`.	`WARNING`

No mesmo diretório, crie ou configure o arquivo gcpgkeinstprov_templates.json. Esse arquivo define os modelos para os pods que o provedor pode criar.

Se você instalou o plug-in do provedor usando o pacote RPM, copie o arquivo de modelos de exemplo e personalize-o:

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

Se você compilou o provedor da origem, crie um arquivo gcpgkeinstprov_templates.json.

Os atributos do modelo precisam estar alinhados com os recursos em uma especificação de pod. Confira um exemplo de modelo:

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

No mesmo diretório, crie um arquivo kubeconfig que seja um arquivo de configuração kubectl válido para seu cluster do Kubernetes.
No diretório da instância do provedor, crie ou edite o arquivo pod-spec.yaml. Esse arquivo funciona como um modelo que define as especificações dos pods de computação do Symphony criados no cluster do GKE.

Os pods criados com base nessa especificação funcionam como nós de computação e precisam de acesso à instalação do Symphony. Esse acesso pode ser fornecido pela imagem do contêiner, que inclui a instalação do Symphony, ou por uma montagem de sistema de arquivos compartilhada que contém a instalação. Na inicialização, os pods usam esse acesso para participar do cluster do Symphony.

As etapas para criar o arquivo dependem de como você instalou o provedor:
- Se você instalou o provedor de um pacote RPM, copie o arquivo de exemplo pod-spec.yaml.dist incluído na instalação:
```
cp $HF_TOP/conf/providers/gcpgkeinst/pod-specs/pod-spec.yaml.dist
$HF_TOP/conf/providers/gcpgkeinst/pod-specs/pod-spec.yaml
```
- Se você criou o provedor da origem, crie o diretório pod-specs e o arquivo pod-spec.yaml manualmente:
```
mkdir -p $HF_TOP/conf/providers/gcpgkeinst/pod-specs touch
$HF_TOP/conf/providers/gcpgkeinst/pod-specs/pod-spec.yaml
```

Depois de criar esses arquivos, verifique se o diretório da instância do provedor aparece da seguinte maneira:

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

Ativar a instância do provedor

Para ativar a instância do provedor, habilite-a no arquivo de configuração da fábrica de hosts:

Abra o arquivo $HF_TOP/conf/providers/hostProviders.json.
Adicione uma seção de instância do provedor gcpgkeinst:
```
{
    "name": "gcpgkeinst",
    "enabled": 1,
    "plugin": "gcpgke",
    "confPath": "${HF_CONFDIR}/providers/gcpgkeinst/",
    "workPath": "${HF_WORKDIR}/providers/gcpgkeinst/",
    "logPath": "${HF_LOGDIR}/"
}
```
Não é necessário substituir as variáveis ${HF_CONFDIR}, ${HF_WORKDIR} e ${HF_LOGDIR} nessa configuração porque elas são variáveis de ambiente padrão definidas automaticamente pelo ambiente de fábrica de hosts do IBM Spectrum Symphony.

Quando você configura a sessão do shell executando source command, esse script define essas variáveis para apontar para os subdiretórios corretos na instalação do Symphony. O serviço de fábrica de host usa essas variáveis para construir os caminhos completos em tempo de execução.

Ativar a instância do solicitante

Para permitir que um componente específico do Symphony use o provedor do GKE para provisionar recursos, ative-o para esse solicitante.

Abra o arquivo $HF_TOP/conf/requestors/hostRequestors.json.
Na instância do solicitante apropriada, adicione gcpgkeinst ao parâmetro providers:
```
"providers": ["gcpgkeinst"],
```
O valor do provedor precisa corresponder ao nome usado em Ativar a instância do provedor.

Iniciar o serviço de fábrica de hosts

Para aplicar as mudanças de configuração, inicie o serviço de fábrica de hosts. Na VM do host principal do Symphony, faça login como administrador do cluster e inicie o serviço:

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

Substitua:

SYMPHONY_USERNAME: o nome de usuário do Symphony para autenticação.
SYMPHONY_PASSWORD: a senha do usuário do Symphony.

Testar conectores

Crie uma solicitação de recurso para testar o provedor do GKE.

Para fazer isso, use um dos seguintes métodos:

GUI do Symphony: para instruções sobre como criar uma solicitação de recurso usando a GUI do Symphony, consulte Como programar manualmente solicitações e devoluções de host na nuvem na documentação da IBM.

API REST: para criar uma solicitação de recurso usando a API REST, siga estas etapas:

Encontre o host e a porta da API REST da fábrica de hosts:

egosh client view REST_HOST_FACTORY_URL

A saída é semelhante a este exemplo:

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

Para criar uma solicitação de recurso usando a API REST, use o comando a seguir:
```
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
```
Substitua:
- PRIMARY_HOST: o nome do host principal da saída do comando anterior.
- PORT: o número da porta do seu host principal na saída do comando anterior, como 9080.
- SYMPHONY_TEMPLATE_ID: o templateId definido no arquivo gcpgkeinstprov_templates.json, como template-gcp-01.
- SYMPHONY_USER: o usuário do Symphony para autenticação.
- SYMPHONY_PASSWORD: a senha do usuário do Symphony.
Se a operação for bem-sucedida, a saída será semelhante a este exemplo:
```
{"scheduled_request_id":["SD-641ef442-1f9e-40ae-ae16-90e152ed60d2"]}
```

A seguir

Resolver problemas com conectores do IBM Spectrum Symphony