Resolver problemas com os conectores do IBM Spectrum Symphony

Este documento ajuda a resolver problemas comuns com a integração do IBM Spectrum Symphony para Google Cloud. Especificamente, este documento fornece orientações de solução de problemas para o serviço de fábrica de hosts do IBM Spectrum Symphony, os conectores para provedores do Compute Engine e do GKE e o operador do Symphony para Kubernetes.

Problemas com o serviço de fábrica de hosts do Symphony

Esses problemas estão relacionados ao serviço central de fábrica de hosts do Symphony. O arquivo de registro principal desse serviço pode ser encontrado no seguinte local no Linux:

$EGO_TOP/hostfactory/log/hostfactory.hostname.log

Você define a variável de ambiente $EGO_TOP ao carregar as variáveis de ambiente da fábrica de hosts. No IBM Spectrum Symphony, $EGO_TOP aponta para a raiz de instalação do Enterprise Grid Orchestrator (EGO), que é o gerenciador de recursos principal do cluster. O caminho de instalação padrão para $EGO_TOP no Linux geralmente é /opt/ibm/spectrumcomputing.

O cluster não adiciona novas VMs para cargas de trabalho pendentes

Esse problema ocorre quando a fila do Symphony contém jobs, mas a fábrica de hosts não provisiona novas máquinas virtuais (VMs) para gerenciar a carga. O arquivo de registro da fábrica do host não contém mensagens SCALE-OUT.

Esse problema geralmente ocorre quando o solicitante do Symphony não está configurado ou ativado corretamente. Para resolver o problema, verifique o status do solicitante configurado para verificar se ele está ativado e se há uma carga de trabalho pendente.

Localize o arquivo de configuração do solicitante. Normalmente, o arquivo está localizado em:
```
$HF_TOP/conf/requestors/hostRequestors.json
```
A variável de ambiente $HF_TOP é definida no seu ambiente quando você usa o comando source. 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.
Abra o arquivo hostRequestors.json e localize a entrada symAinst. Nessa seção, verifique se o parâmetro enabled está definido como um valor de 1 e se a lista de provedores inclui o nome da sua instância de provedor Google Cloud configurada.
- Para configurações do Compute Engine, a lista de provedores precisa mostrar o nome do provedor do Compute Engine que você criou em Ativar a instância do provedor durante a instalação do provedor do Compute Engine.
- Para configurações do GKE, a lista de provedores precisa mostrar o nome do provedor do GKE criado em Ativar a instância do provedor durante a instalação do provedor do GKE.
Depois de confirmar que o solicitante do symAinst está ativado, verifique se um consumidor tem uma carga de trabalho pendente que exige escalonamento horizontal.

Confira uma lista de todos os consumidores e o status da carga de trabalho deles:
```
egosh consumer list
```
Na saída, procure o consumidor associado à sua carga de trabalho e verifique se ela está pendente. Se o solicitante estiver ativado e uma carga de trabalho estiver pendente, mas o serviço de fábrica de host não iniciar solicitações de expansão horizontal, verifique os registros do serviço HostFactory em busca de erros.

O serviço de fábrica do host não está sendo iniciado

Se o serviço de fábrica de host não for executado, siga estas etapas para resolver o problema:

Verifique o status do serviço HostFactory:
```
egosh service list
```
Na saída, localize o serviço HostFactory e verifique se o campo STATE mostra o status STARTED.

Se o serviço HostFactory não estiver iniciado, reinicie-o:

egosh service stop HostFactory
egosh service start HostFactory

Outros erros e geração de registros

Se você encontrar outros erros com o serviço de fábrica de host, aumente a verbosidade do registro para receber registros mais detalhados. Para isso, siga as etapas abaixo:

Abra o arquivo hostfactoryconf.json para edição. Normalmente, o arquivo está localizado em:
```
$EGO_TOP/hostfactory/conf/
```
Para mais informações sobre o valor da variável de ambiente $EGO_TOP, consulte Problemas no serviço de fábrica de hosts do Symphony.

Atualize o valor de HF_LOGLEVEL de LOG_INFO para LOG_DEBUG:

{
  ...
  "HF_LOGLEVEL": "LOG_DEBUG",
  ...
}

Salve o arquivo depois de fazer a mudança.

Para que a mudança entre em vigor, reinicie o serviço HostFactory:

egosh service stop HostFactory
egosh service start HostFactory

Depois de reiniciar, o serviço HostFactory gera registros mais detalhados, que podem ser usados para resolver problemas complexos. É possível conferir esses registros no arquivo de registros principal da fábrica de hosts, localizado em $EGO_TOP/hostfactory/log/hostfactory.hostname.log no Linux.

Problemas com o provedor de fábrica de host

Os problemas a seguir ocorrem nos scripts do provedor de fábrica de hosts para o Compute Engine ou o Google Kubernetes Engine.

Verifique os registros do provedor (hf-gce.log ou hf-gke.log) para ver mensagens de erro detalhadas. O local dos arquivos hf-gce.log e hf-gke.log é determinado pela variável LOGFILE definida no arquivo de configuração do provedor em Ativar a instância do provedor.

A máquina virtual ou o pod não foi provisionado

Esse problema pode ocorrer depois que os registros do provedor de fábrica do host mostram uma chamada para o script requestMachines.sh, mas o recurso não aparece no projeto Google Cloud.

Para resolver o problema, siga estas etapas:

Verifique os registros de script do provedor (hf-gce.log ou hf-gke.log) para mensagens de erro da API Google Cloud . O local dos arquivos hf-gce.log e hf-gke.log é determinado pela variável LOGFILE definida no arquivo de configuração do provedor em Ativar a instância do provedor.
Verifique se a conta de serviço tem as permissões corretas do IAM:
1. Siga as instruções em Ver acesso atual.
2. Verifique se a conta de serviço tem o papel do IAM Administrador da instância do Compute (v1) (roles/compute.instanceAdmin.v1) no projeto. Para mais informações sobre como conceder papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.
Para garantir que os parâmetros do Compute Engine no modelo de host sejam válidos, verifique o seguinte:
1. Os parâmetros do modelo de host precisam estar no arquivo gcpgceinstprov_templates.json criado ao configurar uma instância de provedor durante a instalação do provedor do Compute Engine. Os parâmetros mais comuns para validação são gcp_zone e gcp_instance_group.
2. Verifique se o grupo de instâncias definido pelo parâmetro gcp_instance_group existe. Para confirmar o grupo de instâncias, siga as instruções em Ver as propriedades de um MIG usando os valores de nome gcp_instance_group e zona gcp_zone do arquivo de modelo.

O pod fica travado no estado `Pending` ou `Error` no GKE

Esse problema pode ocorrer depois que o registro hf-gke mostra que criou o recurso GCPSymphonyResource, mas o pod correspondente no cluster do GKE nunca atinge um estado Running e pode mostrar um status como Pending, ImagePullBackOff ou CrashLoopBackOff.

Esse problema ocorre se houver um problema no cluster do Kubernetes, como um nome de imagem de contêiner inválido, recursos insuficientes de CPU ou memória ou uma configuração de volume ou rede incorreta.

Para resolver esse problema, use kubectl describe para inspecionar os eventos do recurso personalizado e do pod e identificar a causa raiz:

kubectl describe gcpsymphonyresource RESOURCE_NAME
kubectl describe pod POD_NAME

Substitua:

RESOURCE_NAME: o nome do recurso.
POD_NAME: o nome do pod.

Resolver problemas do operador do Kubernetes

O operador do Kubernetes gerencia o ciclo de vida de um pod do Symphony. As seções a seguir podem ajudar você a resolver problemas comuns que podem surgir com o operador e esses recursos.

Diagnosticar problemas com campos de status de recursos

O operador do Kubernetes gerencia cargas de trabalho do Symphony no GKE com dois tipos de recursos principais:

O recurso GCPSymphonyResource (GCPSR) gerencia o ciclo de vida dos pods de computação para cargas de trabalho do Symphony.
O recurso MachineReturnRequest (MRR) processa o retorno e a limpeza de recursos de computação.

Use estes campos de status para diagnosticar problemas com o recurso GCPSymphonyResource:

phase: a fase atual do ciclo de vida do recurso. As opções são Pending, Running, WaitingCleanup ou Completed.
availableMachines: o número de pods de computação prontos.
conditions: condições de status detalhadas com carimbos de data/hora.
returnedMachines: uma lista de pods retornados.

Use estes campos de status para diagnosticar problemas com o recurso MachineReturnRequest:

phase: a fase atual da solicitação de devolução. As opções são Pending, InProgress, Completed, Failed ou PartiallyCompleted.
totalMachines: o número total de máquinas a serem retornadas.
returnedMachines: o número de máquinas retornadas com sucesso.
failedMachines: o número de máquinas que não retornaram.
machineEvents: detalhes do status por máquina.

Recurso `GCPSymphonyResource` travado no estado `Pending`

Esse problema ocorre quando o recurso GCPSymphonyResource permanece no estado Pending e o valor de availableMachines não aumenta.

Esse problema pode ocorrer por um destes motivos:

Capacidade insuficiente de nós no cluster.
Problemas ao extrair a imagem do contêiner.
Limitações de cota de recursos.

Para resolver o problema:

Verifique o status dos pods para identificar problemas com extrações de imagens ou alocação de recursos:
```
kubectl describe pods -n gcp-symphony -l symphony.requestId=REQUEST_ID
```
Substitua REQUEST_ID pelo ID da solicitação.
Inspecione os nós para garantir capacidade suficiente:
```
kubectl get nodes -o wide
```
Os pods podem mostrar um status Pending. Esse problema geralmente ocorre quando o cluster do Kubernetes precisa ser escalonar verticalmente e leva mais tempo do que o esperado. Monitore os nós para garantir que o plano de controle possa ser escalonar horizontalmente.

Os pods não são retornados

Esse problema ocorre quando você cria uma MachineReturnRequest (MRR), mas o número de returnedMachines não aumenta.

Esse problema pode ocorrer pelos seguintes motivos:

Os pods estão travados no estado Terminating.
Há problemas de conectividade do nó.

Para resolver o problema:

Verifique se há pods presos no estado Terminating:

kubectl get pods -n gcp-symphony --field-selector=status.phase=Terminating

Descreva o MachineReturnRequest para receber detalhes sobre o processo de devolução:
```
kubectl describe mrr MRR_NAME -n gcp-symphony
```
Substitua MRR_NAME pelo nome do MachineReturnRequest.
Exclua manualmente o objeto de recurso personalizado. Essa exclusão ativa a lógica de limpeza final:
```
kubectl delete gcpsymphonyresource RESOURCE_NAME
```
Substitua RESOURCE_NAME pelo nome do recurso GCPSymphonyResource.

Alto número de máquinas com falha em um `MachineReturnRequest`

Esse problema ocorre quando a contagem de failedMachines no status MachineReturnRequest é maior que 0. Esse problema pode ocorrer pelos seguintes motivos:

O tempo de espera para exclusão do pod foi atingido.
Um nó está indisponível.

Para resolver o problema:

Verifique o machineEvents no status MachineReturnRequest para mensagens de erro específicas:
```
kubectl describe mrr MRR_NAME -n gcp-symphony
```
Procure eventos de falha de nó ou problemas de desempenho do plano de controle:
1. Confira o status de todos os nós:
```
kubectl get nodes -o wide
```
2. Inspecione um nó específico:
```
kubectl describe node NODE_NAME
```

Os pods não são excluídos

Esse problema ocorre quando os pods excluídos ficam presos no estado Terminating ou Error.

Esse problema pode ocorrer pelos seguintes motivos:

Um plano de controle ou operador sobrecarregado, que pode causar tempos limite ou eventos de limitação da API.
A exclusão manual do recurso GCPSymphonyResource principal.

Para resolver o problema:

Verifique se o recurso pai GCPSymphonyResource ainda está disponível e não está no estado WaitingCleanup:
```
kubectl describe gcpsymphonyresource RESOURCE_NAME
```
Se o recurso pai GCPSymphonyResource não estiver mais no sistema, remova manualmente o finalizador do pod ou dos pods. O finalizador informa ao Kubernetes para aguardar que o operador do Symphony conclua as tarefas de limpeza antes que o Kubernetes exclua totalmente o pod. Primeiro, inspecione a configuração YAML para encontrar o finalizador:
```
kubectl get pods -n gcp-symphony -l symphony.requestId=REQUEST_ID -o yaml
```
Substitua REQUEST_ID pelo ID da solicitação associada aos pods.
Na saída, procure o campo "finalizers" na seção de metadados. Você vai ver uma saída semelhante a este snippet:
```
metadata:
...
finalizers:
-   symphony-operator/finalizer
```

Para remover manualmente o finalizador do pod ou dos pods, use o comando kubectl patch:

kubectl patch pod -n gcp-symphony -l symphony.requestId=REQUEST_ID --type json -p '[{"op": "remove", "path": "/metadata/finalizers", "value": "symphony-operator/finalizer"}]'

Substitua REQUEST_ID pelo ID da solicitação associada aos pods.

Os recursos antigos do Symphony não são excluídos automaticamente do cluster do GKE.

Depois que uma carga de trabalho é concluída e o GKE interrompe os pods, os objetos GCPSymphonyResource e MachineReturnRequest associados permanecem no cluster do GKE por mais tempo do que o período de limpeza esperado de 24 horas.

Esse problema ocorre quando um objeto GCPSymphonyResource não tem a condição Completed status obrigatória. O processo de limpeza automática do operador depende desse status para remover o objeto. Para resolver esse problema, siga estas etapas:

Revise os detalhes do recurso GCPSymphonyResource em questão:
```
kubectl get gcpsr GCPSR_NAME -o yaml
```
Substitua GCPSR_NAME pelo nome do recurso GCPSymphonyResource com esse problema.

Revise as condições de um tipo Completed com status True:

status:
  availableMachines: 0
  conditions:
  -   lastTransitionTime: "2025-04-14T14:22:40.855099+00:00"
    message: GCPSymphonyResource g555dc430-f1a3-46bb-8b69-5c4c481abc25-2pzvc has
      no pods.
    reason: NoPods
    status: "True"        # This condition will ensure this
    type: Completed       # custom resource is cleaned up by the operator
  phase: WaitingCleanup
  returnedMachines:
  -   name: g555dc430-f1a3-46bb-8b69-5c4c481abc25-2pzvc-pod-0
    returnRequestId: 7fd6805f-9a00-41f9-afe9-c38aa35002db
    returnTime: "2025-04-14T14:22:39.373216+00:00"

Se essa condição não aparecer nos detalhes de GCPSymphonyResource, mas o phase: WaitingCleanup for mostrado, o evento Completed foi perdido.

Verifique se há pods associados ao GCPSymphonyResource:
```
kubectl get pods -l symphony.requestId=REQUEST_ID
```
Substitua REQUEST_ID pelo ID da solicitação.
Se não houver pods, exclua o recurso GCPSymphonyResource com segurança:
```
kubectl delete gcpsr GCPSR_NAME
```
Substitua GCPSR_NAME pelo nome do GCPSymphonyResource.
Se os pods existiam antes da exclusão do GCPSymphonyResource, é necessário excluí-los. Se os pods ainda existirem, siga as etapas na seção Os pods não são excluídos.

O pod não entra no cluster do Symphony

Esse problema ocorre quando um pod é executado no GKE, mas não aparece como um host válido no cluster do Symphony.

Esse problema ocorre quando o software do Symphony em execução no pod não consegue se conectar e se registrar com o host principal do Symphony. Esse problema geralmente ocorre devido a problemas de conectividade de rede ou configuração incorreta do cliente do Symphony no contêiner.

Para resolver esse problema, verifique os registros dos serviços do Symphony em execução no pod.

Use SSH ou exec para acessar o pod e ver os registros:
```
kubectl exec -it POD_NAME -- /bin/bash
```
Substitua POD_NAME pelo nome do pod.
Quando você tem um sh dentro do pod, os registros dos daemons EGO e LIM estão localizados no diretório $EGO_TOP/kernel/log. A variável de ambiente $EGO_TOP aponta para a raiz da instalação do IBM Spectrum Symphony:
```
cd $EGO_TOP/kernel/log
```
Para mais informações sobre o valor da variável de ambiente $EGO_TOP, consulte Problemas do serviço de fábrica de hosts do Symphony.
Examine os registros em busca de erros de configuração ou de rede que bloqueiem a conexão do pod do GKE com o pod principal do Symphony local.

Falha na solicitação de devolução da máquina

Esse problema pode ocorrer durante operações de redução quando você cria um recurso personalizado MachineReturnRequest, mas o objeto fica preso, e o operador não encerra o pod do Symphony correspondente.

Uma falha na lógica do finalizador do operador impede a exclusão limpa do pod e do recurso personalizado associado. Esse problema pode levar a recursos órfãos e custos desnecessários.

Para resolver esse problema, exclua manualmente o recurso personalizado, o que deve ativar a lógica de limpeza do operador:

kubectl delete gcpsymphonyresource RESOURCE_NAME

Substitua RESOURCE_NAME pelo nome do recurso.

Resolver problemas com os conectores do IBM Spectrum Symphony Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Problemas com o serviço de fábrica de hosts do Symphony

O cluster não adiciona novas VMs para cargas de trabalho pendentes

O serviço de fábrica do host não está sendo iniciado

Outros erros e geração de registros

Problemas com o provedor de fábrica de host

A máquina virtual ou o pod não foi provisionado

O pod fica travado no estado Pending ou Error no GKE

Resolver problemas do operador do Kubernetes

Diagnosticar problemas com campos de status de recursos

Recurso GCPSymphonyResource travado no estado Pending

Os pods não são retornados

Alto número de máquinas com falha em um MachineReturnRequest

Os pods não são excluídos

Os recursos antigos do Symphony não são excluídos automaticamente do cluster do GKE.

O pod não entra no cluster do Symphony

Falha na solicitação de devolução da máquina

Resolver problemas com os conectores do IBM Spectrum Symphony

O pod fica travado no estado `Pending` ou `Error` no GKE

Recurso `GCPSymphonyResource` travado no estado `Pending`

Alto número de máquinas com falha em um `MachineReturnRequest`