Monitore, mantenha e solucione problemas de implantações do Model Gateway, incluindo atualizações de configuração do modelo, rotação de credenciais, monitoramento de integridade, coleta de logs e resolução de problemas comuns de conectividade e autenticação.

Após a implantação, o gerenciamento operacional contínuo do Model Gateway ajuda a garantir acesso confiável aos modelos de IA configurados e minimiza as interrupções do serviço. Os administradores podem revisar configurações de modelo ativas, atualizar credenciais de provedores, rotacionar segredos, monitorar a integridade do gateway e coletar informações de diagnóstico quando ocorrem problemas.

Visualizando modelos configurados

Há dois níveis para visualizar modelos — o que está na configuração e o que bob-inference efetivamente carregou em runtime.

Nível de configuração — recupere a configuração atual do model gateway a partir do ConfigMap de inferência:

oc get cm bob-inference-config -n <bob-namespace> -o yaml | yq '.data."config.yaml"'

Nível de runtime — o que bob-inference registrou e está ativamente roteando:

oc exec -n <bob-namespace> deploy/bob-gateway -- \\
  curl -sk https://bob-inference.<bob-namespace>.svc.cluster.local:7330/v1/model/info | jq .

Nota:

O endpoint de runtime /v1/model/info lista apenas modelos onde exposed: true. O arquivo de configuração é a única forma de ver o conjunto completo de modelos configurados.

Atualizando credenciais de provedores

As credenciais são armazenadas em bob.modelGateway.secrets no config.yaml. Use bobctl update-model-config --update-secrets para enviar as credenciais atualizadas para o cluster.

Atualizar a credencial

Atualize a credencial no config.yaml em bob.modelGateway.secrets.

Enviar o secret atualizado para o cluster

bobctl update-model-config --update-secrets

O ibm-bob-operator reconcilia o deployment bob-inference e monta o novo secret automaticamente.

Dica:

Se você estiver atualizando tanto o arquivo de configuração do modelo quanto as credenciais ao mesmo tempo, você pode enviar ambos em um único comando:

bobctl update-model-config --model-config ./my-model-config.yaml --update-secrets

Rotacionando segredos

A rotação de segredos segue o mesmo padrão de uma atualização de credenciais, com cuidado adicional quanto ao timing para evitar downtime.

Sequência de rotação com zero downtime recomendada:

Atualize bob.modelGateway.secrets no config.yaml com o novo valor de credencial.

Envie o novo secret para o cluster: bobctl update-model-config --update-secrets.

Reinicie o Inference Service para aplicar o novo secret:

oc rollout restart deploy/inference-service -n <bob-namespace>

Confirme que a nova credencial está funcionando usando o teste de inferência de Verificação pós-instalação.

Revogue a credencial antiga no lado do provedor somente após o deployment ser confirmado como saudável.

Notas específicas do provedor:

openai_compatible / chaves de API — a nova chave entra em vigor imediatamente após o secret ser atualizado. É seguro revogar a chave antiga após o deployment estar saudável.

bedrock — certifique-se de que a nova chave de acesso IAM esteja ativa na AWS antes de executar update-model-config. A propagação do IAM pode levar alguns segundos.

vertex — gere e codifique em base64 a nova chave de conta de serviço, atualize o config.yaml, execute bobctl update-model-config --update-secrets, verifique e depois exclua a chave antiga no GCP.

ca_cert_pem — para renovação de certificado, verifique se o novo certificado não está expirado antes de aplicar. Consulte Validação de certificado TLS.

Monitorando a integridade do gateway

Contagem de reinicializações do pod — um número crescente de reinicializações é um sinal precoce de uma falha de inicialização recorrente (montagem de secret inválida, erro de análise de configuração):

oc get pods -n <bob-namespace> -l app=bob-inference \
  -o custom-columns='NAME:.metadata.name,RESTARTS:.status.containerStatuses[0].restartCount'

Probes de liveness e readiness — verifique a configuração e o status atual dos probes:

oc describe deploy/bob-inference -n <bob-namespace> | grep -A 10 "Liveness\|Readiness"

Verificação periódica de integridade — o endpoint /v1/model/info serve como uma verificação simples de liveness. Se ele retornar uma lista válida de modelos, o gateway está ativo. Isso pode ser monitorado a partir de uma ferramenta de monitoramento ou um cron job dentro do cluster.

Coletando logs e diagnósticos

Logs para uma janela de tempo específica (mais útil ao investigar um incidente relatado):

oc logs -n <bob-namespace> deploy/bob-inference \
  --since-time="2025-01-01T12:00:00Z" > bob-inference.log

Logs de uma instância anterior do pod (se o pod reiniciou e os logs de falha foram perdidos):

oc logs -n <bob-namespace> deploy/bob-inference --previous

Bundle de diagnóstico completo para suporte:

oc describe pod -n <bob-namespace> -l app=bob-inference >> diagnostics.txt
oc get events -n <bob-namespace> --sort-by='.lastTimestamp' >> diagnostics.txt
oc logs -n <bob-namespace> deploy/bob-inference --since=1h >> diagnostics.txt

Nota:

O bundle de diagnóstico contém nomes de variáveis de ambiente do pod, mas não valores de secret (os secrets são montados, não impressos nos logs). Revise os logs em busca de qualquer saída acidental de credenciais antes de enviar ao suporte.

Solucionando problemas de conectividade e autenticação

Modelo não aparece em /v1/model/info

Verifique se exposed: false está definido — se sim, este é o comportamento esperado.

Verifique os logs de inicialização em busca de um erro de registro para aquele model_name.

Verifique o bloco do provedor — base_url, ID do model e credenciais corretos.

401 Unauthorized em solicitações de inferência

Confirme se o valor do secret em bob.modelGateway.secrets está correto e atualizado.

Confirme se a referência env.<VAR> na configuração do modelo corresponde exatamente ao nome da chave do secret (sensível a maiúsculas/minúsculas).

Reinicie o Inference Service e tente novamente — o secret pode ter sido atualizado sem uma reinicialização.

Teste a credencial fora de banda. Consulte Validação de autenticação.

502 Bad Gateway ou connection refused

Confirme se o endpoint do modelo está ativo e acessível a partir do cluster. Consulte Teste de conectividade.

Verifique problemas com base_url — barras no final, esquema incorreto (http vs https), porta incorreta.

Verifique se houve mudanças nas políticas de rede que possam ter bloqueado o tráfego de saída desde a instalação.

certificate signed by unknown authority

Confirme se ca_cert_pem está definido e referencia uma variável de ambiente válida.

Confirme se a variável de ambiente está presente em bob.modelGateway.secrets.

Verifique se o certificado não está expirado: openssl x509 -noout -dates.

Confirme se o certificado cobre o hostname do endpoint verificando os Subject Alternative Names.

Pod do Inference Service em CrashLoopBackOff

Verifique os logs da instância anterior: oc logs --previous.

Procure erros de análise de configuração — YAML malformado na configuração do model gateway.

Procure montagens de secret ausentes na seção Events: oc describe pod.

Confirme se o YAML da configuração do model gateway é válido antes de reaplicar.

Operações e solução de problemas