/ /

Solução de problemas de `mongot` Implantação

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

Localize um problema usando o status do recurso

Um recurso MongoDBSearch executa vários componentes independentes:

Um ou mais mongot StatefulSets
Um balanceador de carga Envoy gerenciado por operador Kubernetes opcional
Um encaminhador de métricas opcional do Cloud Manager ou do MongoDB Ops Manager.

Em uma implantação de múltiplos clusters, cada um deles é executado por cluster nó. Quando a pesquisa não se comportar como esperado, use o status do recurso para localizar o problema em um cluster e componente específicos antes de inspecionar Pods ou logs.

Para ler o status:

kubectl get mongodbsearch ${MDB_RESOURCE_NAME} \
  -n ${MDB_NS} --context ${K8S_CTX} -o yaml

Comece com os campos de nível superior e, em seguida, restrinja usando status.clusters:

Campo	O que ele diz a você
`status.phase`	A fase geral do recurso. Isso reflete a prontidão do `mongot` StatefulSet em todos os cluster (pior) e a prontidão do balanceador de carga gerenciado. O recurso está na fase `Pending` se o `mongot` de qualquer cluster ou o balanceador de carga gerenciado pelo operador do Kubernetes não estiver pronto. O encaminhador de métricas não afeta esta fase.
`status.loadBalancer`	A fase agregada do balanceador de carga Envoy gerenciado em todos os clusters. Isso só é preenchido quando `spec.clusters[].loadBalancer.managed` é definido.
`status.metricsForwarder`	A fase agregada do encaminhador de métricas do MongoDB Ops Manager em todos os clusters. Isso só é preenchido quando o encaminhador de métricas está habilitado.
`status.clusters[]`	Uma entrada por cluster de nós, cada uma com seu próprio `name` e `index` e subfases independentes para `search`, `loadBalancer` e `metricsForwarder`. Cada subfase tem um campo `*Message` correspondente (por exemplo, `searchMessage`) que explica o motivo quando a subfase não é `Running`.

Dica

Um recurso MongoDBSearch pode ser Pending mesmo quando a subfase search de cada cluster é Running — um loadBalancer gerenciado degradado em qualquer cluster pode manter todo o recurso na fase Pending. Leia as subfases por cluster para identificar qual cluster e componente são responsáveis.

O exemplo a seguir mostra uma implantação de dois cluster onde o balanceador de carga Envoy do segundo cluster está travado no meio da implantação. O recurso é Pending mesmo que mongot em ambos os cluster esteja saudável porque a prontidão do balanceador de carga gerenciado afeta a fase geral.

Exemplo: Fase pendente

status:
  phase: Pending
  message: "Waiting for managed load balancer to be ready"
  clusters:
    - name: member-cluster-1
      index: 0
      search: Running
      loadBalancer: Running
    - name: member-cluster-2
      index: 1
      search: Running
      loadBalancer: Pending
      loadBalancerMessage: "Load balancer deployment mdb-search-search-lb-1
        rollout in progress: 1 unavailable replica(s)"

Use o name e o index do cluster afetado para inspecionar o componente correspondente:

For a search sub-phase that is not Running, inspect that cluster's mongot StatefulSet and Pods. The searchMessage typically reports which StatefulSet is not ready. See The mongot Pod Fails to Start.
Para uma subfase loadBalancer que não seja Running, inspecione a implantação do Envoy desse cluster. Mensagens como rollout in progress ou unavailable replica(s) indicam que os novos pods do Envoy não estão agendando ou ficando prontos.
Para uma subfase metricsForwarder que não seja Running, inspecione a implantação do encaminhador de métricas desse cluster.

To collect the Pod state, logs, and events for the identified component, see Gather Diagnostic Information.

O Pod `mongot` falha ao iniciar

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

Diagnose: Run the commands in Gather Diagnostic Information and review the pod events and MongoDBSearch status. Common indicators include scheduling failures, volume-mount errors, and image-pull errors.

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:

If the mongot pod is not Running, work through The mongot Pod Fails to Start.
Se o log mostrar erros de autenticação, verifique as credenciais e a função do usuário search-sync-source. Para saber mais, consulte Proteja a conexão da pesquisa ao MongoDB.
Se os registros mostrarem erros de TLS, confirme que mongod e mongot confiam na mesma CA. Para saber mais, consulte Proteger a conexão do MongoDB para o Search.

`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:

If the exit reason is OOMKilled, increase the memory resources for mongot. See mongot Runs Out of Memory.
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 registros mostrarem que mongot não consegue ler ou escrever seus dados de índice, confirme se a declaração de volume persistente está vinculada e gravável. Consulte Falha ao iniciar o Pod mongot.

`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:

Aumente os recursos de memória alocados para mongot no recurso MongoDBSearch. mongot reinicia para aplicar a alteração.
Revise o tamanho do índice e a carga de query em relação à orientação de dimensionamento em Planejamento e dimensionamento de recursos de pesquisa e pesquisa vetorial.

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 no handshake TLS entre `mongod` e `mongot`

Sintaxe: os registros mongot mostram erros de handshake TLS ou de validação de certificado e mongod não consegue estabelecer uma conexão com mongot.

Diagnóstico: revise os registros mongot em busca de erros de certificado e confirme se os segredos TLS referenciados pelo recurso MongoDBSearch existem:

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

Resolver:

Confirme que 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

If you contact MongoDB Support, include the mongot logs, the MongoDBSearch resource description, and recent namespace events:

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

Perguntas frequentes

Solução de problemas de mongot Implantação

Obter informações de diagnóstico

Localize um problema usando o status do recurso

O Pod mongot falha ao iniciar

Query de pesquisa falham ao alcançar mongot

mongot Reinicia repetidamente

mongot Fica sem memória

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

Falhas no handshake TLS entre mongod e mongot

Falha no embedding automatizado

Capturar diagnósticos para suporte

Saiba mais

Solução de problemas de `mongot` Implantação

O Pod `mongot` falha ao iniciar

Query de pesquisa falham ao alcançar `mongot`

`mongot` Reinicia repetidamente

`mongot` Fica sem memória

Falhas no handshake TLS entre `mongod` e `mongot`