Para agentes de IA: um índice de documentação está disponível em https://www.mongodb.com/pt-br/docs/llms.txt — as versões de markdown de todas as páginas estão disponíveis anexando .md a qualquer caminho de URL.
Menu Docs
Página inicial do Docs
/ /
Implementar pesquisa e Vector Search
Página inicial do Docs
/
Gestão
/
Controladores para o Operador do Kubernetes
/
Implementar pesquisa e Vector Search
Página inicial do Docs
/
Gestão
/
Controladores para o Operador do Kubernetes
/
Implementar pesquisa e Vector Search

Solução de problemas de implantação mongot

O operador MongoDB Controllers for Kubernetes implanta mongot como um processo separado em seu próprio Pod, definido por um recurso MongoDBSearch. Os clientes nunca se conectam diretamente ao mongot: as query de pesquisa do MongoDB e as query de pesquisa vetorial são executadas no mongod, que as envia para o mongot. mongot se conecta de volta ao mongod para transmitir eventos de alteração e criar seus índices em um Persistent Volume dedicado.

Esta página descreve como diagnosticar e resolver problemas comuns de tempo de execução com uma implantação mongot. Para solução de problemas específica para criação de índice durante a configuração inicial, consulte Usar MongoDB Search e pesquisa vetorial. Para configurar métricas e registro antes de investigar, consulte Monitorar sua implantação.

Os procedimentos nesta página pressupõem que você definiu as seguintes variáveis de ambiente para corresponder à sua implantação:

export MDB_NS="<your-namespace>"
export K8S_CTX="<your-kubectl-context>"
export MDB_RESOURCE_NAME="<your-mongodbsearch-resource-name>"

Obter informações de diagnóstico

Antes de trabalhar em um cenário específico, colete o estado atual do pod mongot, seus logs e eventos recentes do Kubernetes:

# Check the status and restart count of the mongot pod
kubectl get pods -n ${MDB_NS} --context ${K8S_CTX} | grep search
# Review the most recent mongot logs
kubectl logs statefulset/${MDB_RESOURCE_NAME}-search-0 \
  -n ${MDB_NS} --context ${K8S_CTX} --tail=100
# Inspect the MongoDBSearch resource status and conditions
kubectl describe mongodbsearch ${MDB_RESOURCE_NAME} \
  -n ${MDB_NS} --context ${K8S_CTX}
# List recent events in the namespace
kubectl get events -n ${MDB_NS} --context ${K8S_CTX} \
  --sort-by='.lastTimestamp'

Se o pod reiniciar em um loop, visualize os logs da instância anterior do contêiner para capturar o erro que causou a reinicialização:

kubectl logs statefulset/${MDB_RESOURCE_NAME}-search-0 \
  -n ${MDB_NS} --context ${K8S_CTX} --previous

O Pod mongot não inicia

Sintomas: o pod mongot permanece em Pending, ContainerCreating ou Error e nunca atinge Running, ou o recurso MongoDBSearch não atinge o estado Running.

Diagnosticar: execute os comandos em Coletar informações de diagnóstico e revise os eventos do pod e o status MongoDBSearch. Os indicadores comuns incluem falhas de agendamento, erros de montagem de volume e erros de extração de imagem.

Resolver:

  • Se o pod não puder ser agendado, confirme se um nó com CPU e memória suficientes está disponível e se o seu StorageClass pode vincular o Persistent Volume Claim solicitado. Para aprender mais sobre o dimensionamento mongot, consulte Planejamento e dimensionamento de recursos de pesquisa e pesquisa vetorial.

  • Se a senha secreta do usuário search-sync-source estiver faltando, crie-a. O recurso MongoDBSearch espera um segredo chamado ${MDB_RESOURCE_NAME}-search-sync-source-password.

  • Se a imagem do contêiner mongot não puder ser extraída, verifique o nome da imagem e suas credenciais de registro. Verifique se há erros de extração de imagem com kubectl get events -n ${MDB_NS} | grep -i pull.

  • Se o conjunto de réplicas de origem mongod não estiver no estado Running, resolva esse problema primeiro. O operador MongoDB Controllers for Kubernetes espera o recurso de origem antes de implantar mongot.

Query de pesquisa falham ao alcançar mongot

Sintomas: $search, $searchMeta ou $vectorSearch query falham com um erro que indica que mongod não consegue alcançar o serviço de pesquisa.

Diagnosticar: Confirme se o pod mongot é Running e se o serviço existe:

kubectl get pods,svc -n ${MDB_NS} --context ${K8S_CTX} \
  | grep search

Revise os logs mongot para erros de conexão ou autenticação e revise os logs mongod para erros que referenciam o host de pesquisa.

Resolver:

mongot Reinicia repetidamente

Sintomas: o pod mongot mostra uma alta contagem de reinícios ou relata CrashLoopBackOff.

Diagnosticar: visualize os logs da instância de contêiner anterior para capturar o erro que acionou a reinicialização:

kubectl logs statefulset/${MDB_RESOURCE_NAME}-search-0 \
  -n ${MDB_NS} --context ${K8S_CTX} --previous

Verifique o último estado do pod e o motivo da saída:

kubectl describe pod ${MDB_RESOURCE_NAME}-search-0-0 \
  -n ${MDB_NS} --context ${K8S_CTX}

Resolver:

  • Se o motivo da saída for OOMKilled, aumente os recursos de memória para mongot. Consulte mongot fica sem memória.

  • Se os logs mostrarem um erro de configuração ou autenticação, corrija a configuração e deixe que os Controladores MongoDB para Kubernetes operador reconciliem a alteração.

  • Se os logs mostrarem que mongot não consegue ler ou gravar seus dados de índice, confirme se o Persistent Volume Claim está vinculado e gravável. Consulte O Pod mongot não inicia.

mongot Fica sem memória

Sintomas: O pod mongot é encerrado com um motivo OOMKilled e a contagem de reinícios aumenta.

Diagnosticar: Confirme o motivo do encerramento do pod:

kubectl describe pod ${MDB_RESOURCE_NAME}-search-0-0 \
  -n ${MDB_NS} --context ${K8S_CTX}

mongot é uma carga de trabalho mapeada por memória baseada em Lucene. A pressão da memória geralmente resulta de limites de memória subdimensionados em relação ao tamanho do índice e à carga de query.

Resolver:

A sincronização inicial é lenta ou o atraso de replicação aumenta

Sintomas: os índices recém-criados permanecem em estado de criação por um longo tempo, ou os resultados da query ficam atrasados em relação às gravações recentes em mongod.

Diagnosticar: revise os logs mongot para progresso de replicação e erros. Use as métricas que você configurou em Monitorar sua implantação para acompanhar o progresso da construção do índice e o atraso de replicação ao longo do tempo.

Resolver:

  • Permita que a sincronização inicial seja concluída. O tempo para criar um índice é dimensionado com o tamanho dos dados de origem.

  • Se o atraso persistir sob carga constante, a instância mongot pode não ter recursos suficientes para o volume de gravação. Revise Planejamento e dimensionamento de recursos de pesquisa e pesquisa vetorial.

  • Confirme se o desempenho do armazenamento atende às recomendações para uma carga de trabalho Lucene com muitas leituras aleatórias. O armazenamento lento é uma causa comum de atraso sustentado.

Falhas de handshake TLS entre mongod e mongot

Sintomas: Os logs do mongot mostram erros de handshake TLS ou de validação de certificado, e o mongod não consegue estabelecer uma conexão com o mongot.

Diagnosticar: Revise o log mongot para erros de certificado e confirme que os TLS Secrets referenciados pelo recurso MongoDBSearch existem:

kubectl get secrets -n ${MDB_NS} --context ${K8S_CTX} \
  | grep -i tls

Resolver:

  • Confirme se mongod e mongot confiam na mesma CA.

  • Depois de substituir ou girar um certificado, reinicie mongot para que ele leia o novo certificado. mongot lê certificados na inicialização e não os recarrega durante a execução.

  • Para saber mais, consulte Proteger a conexão do MongoDB para pesquisar.

Falha no embedding automatizado

Observação

O embedding automatizado é um recurso de visualização e se integra apenas aos modelos Voyage AI.

Sintomas: os índices que usam embedding automatizado não são criados ou as solicitações de embedding retornam erros nos logs mongot.

Diagnosticar: revise os logs mongot para erros que referenciam o provedor de embedding, como falhas de autenticação ou tempos limite de solicitação.

Resolver:

  • Verifique se sua chave de API do Voyage AI é válida e se o Secret que a contém existe no namespace.

  • Confirme se o mongot pode alcançar o ponto de extremidade do provedor de embedding do seu cluster Kubernetes.

Capturar diagnósticos para suporte

Se você entrar em contato com o Suporte do MongoDB, inclua os logs mongot, a descrição do recurso MongoDBSearch e os eventos recentes do namespace:

kubectl logs statefulset/${MDB_RESOURCE_NAME}-search-0 \
  -n ${MDB_NS} --context ${K8S_CTX} > mongot.log
kubectl describe mongodbsearch ${MDB_RESOURCE_NAME} \
  -n ${MDB_NS} --context ${K8S_CTX} > mongodbsearch-describe.txt
kubectl get events -n ${MDB_NS} --context ${K8S_CTX} \
  --sort-by='.lastTimestamp' > events.txt

Você também pode incluir arquivos FTDC de cada pod de pesquisa afetado. mongot grava arquivos FTDC em /mongot/data/diagnostic.data/ dentro do pod.

O caminho /mongot/data é um PersistentVolumeClaim que o operador Kubernetes monta no pod por meio de um volumeClaimTemplate no StatefulSet de pesquisa, para que os dados de diagnóstico persistam em todas as reinicializações do pod. Quando um pod é substituído, o StatefulSet anexa novamente o mesmo PersistentVolumeClaim, para que os dados de diagnóstico sejam retidos.

Copie os dados FTDC do pod de pesquisa para sua máquina local. Para clusters sharded, copie os dados FTDC de cada pod de pesquisa por shard para sua máquina local. Repita para cada shard:

kubectl cp -n ${MDB_NS} --context ${K8S_CTX} \
   ${MDB_SEARCH_RESOURCE_NAME}-search-0-${MDB_EXTERNAL_SHARD_0_NAME}-0:/mongot/data/diagnostic.data \
   ./mongot-diagnostic.data-${MDB_EXTERNAL_SHARD_0_NAME}

Saiba mais

Voltar

Limitações conhecidas

Próximo

Perguntas frequentes

Nesta página