Troubleshoot mongot Deployment

진단 정보 수집

특정 시나리오를 실행하기 전에 mongot 팝의 현재 상태, 로그 및 최근 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'

포드가 루프에서 다시 시작되면 이전 컨테이너 인스턴스의 로그를 보아 재시작의 원인이 된 오류를 확인합니다.

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

리소스 상태를 사용하여 문제 현지화

MongoDBSearch 리소스는 여러 개의 독립 컴포넌트를 실행합니다.

• 하나 이상의 mongot StatefulSet

• 선택 사항인 Kubernetes Operator managed Envoy load balancer

• 선택 사항인 Cloud Manager 또는 MongoDB Ops Manager 지표 전송기입니다.

다중 클러스터 배포서버에서는 각 노드 클러스터마다 이가 실행됩니다. 검색이 예상대로 작동하지 않을 경우 Pod 또는 로그를 검사하기 전에 리소스 상태를 사용하여 문제를 특정 클러스터 및 컴포넌트로 지역화합니다.

상태를 읽으려면:

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

최상위 필드로 시작한 다음 status.clusters을 사용하여 점점 줄여날입니다.

다음 예시에서는 두 개의 클러스터 배포에서 두 번째 클러스터의 Envoy 로드 밸런서가 배포 중간에 걸려 있는 상태를 보여줍니다. 두 클러스터 모두에서 mongot이(가) 정상이어도 리소스는 Pending 입니다. managed 로드 밸런서의 준비상태가 전체 단계에 영향을 미치기 때문입니다.

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)"

영향을 받은 클러스터의 name과 index을 사용하여 해당 컴포넌트를 검사합니다.

• 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.

• Running이 아닌 loadBalancer 하위 단계의 경우 해당 클러스터의 Envoy 배포서버를 검사합니다. rollout in progress 또는 unavailable replica(s)와 같은 메시지는 새 Envoy Pod가 예정되지 않거나 준비되지 않음을 나타냅니다.

• metricsForwarder 하위 단계가 Running이 아닌 경우 해당 클러스터의 지표 전송자 배포서버를 검사합니다.

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

The mongot Pod Fails to Start

증상: mongot 팝이 Pending, ContainerCreating 또는 Error 에 머물러 Running에 도달하지 않거나 MongoDBSearch 리소스가 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.

해결:

• If the pod cannot be scheduled, confirm that a node with sufficient CPU and memory is available and your StorageClass can bind the requested Persistent Volume Claim. To learn more about sizing mongot, see Search & Vector Search Resource Planning and Sizing.

• search-sync-source 사용자에 대한 비밀번호 시크릿이 없는 경우 생성합니다. MongoDBSearch 리소스에서는 ${MDB_RESOURCE_NAME}-search-sync-source-password라는 이름의 시크릿이 필요합니다.

• mongot 컨테이너 이미지를 가져올 수 없는 경우 이미지 이름과 레지스트리 자격 증명을 확인합니다. kubectl get events -n ${MDB_NS} | grep -i pull의 이미지 가져오기 오류를 확인합니다.

• 소스 mongod 복제본 세트가 Running 상태가 아니면 먼저 해결합니다. Kubernetes 연산자용 MongoDB 컨트롤러는 mongot를 배포하기 전에 소스 리소스를 기다립니다.

검색 쿼리가 도달하지 않음 mongot

증상: $search, $searchMeta, 또는 $vectorSearch 쿼리가 mongod 가 검색 서비스에 연결할 수 없음을 나타내는 오류로 실패합니다.

Diagnose: Confirm that the mongot pod is Running and that its service exists:

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

연결 또는 인증 오류에 대해 mongot 로그를 검토하고, 검색 호스트를 참조하는 오류에 대해 mongod 로그를 검토합니다.

해결:

• If the mongot pod is not Running, work through The mongot Pod Fails to Start.

• 로그에 인증 오류가 표시되면 search-sync-source 사용자 자격 증명과 역할을 확인합니다. 자세한 내용은 검색에서 MongoDB로의 연결 보안을 참조하세요.

• If the logs show TLS errors, confirm that mongod and mongot trust the same CA. To learn more, see Secure the Connection from MongoDB to Search.

mongot 반복 재시작

증상: mongot 팝에 재시작 횟수가 높거나 CrashLoopBackOff이(가) 보고됩니다.

진단: 이전 컨테이너 인스턴스의 로그를 보아 재시작을 트리거한 오류를 캡처합니다.

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

포드의 마지막 상태와 종료 이유를 확인합니다.

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

해결:

• If the exit reason is OOMKilled, increase the memory resources for mongot. See mongot Runs Out of Memory.

• 로그에 구성 또는 인증 오류가 표시되면 설정을 수정하고 Kubernetes 연산자용 MongoDB 컨트롤러가 변경사항을 조정하도록 합니다.

• If the logs show that mongot cannot read or write its index data, confirm that the Persistent Volume Claim is bound and writable. See The mongot Pod Fails to Start.

mongot 메모리 부족

증상: mongot 팟이 OOMKilled 이유로 종료되고 재시작 횟수가 증가합니다.

진단: 팝의 종료 이유를 확인합니다.

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

mongot Lucene 기반의 메모리 매핑된 워크로드입니다. 메모리 부하는 인덱스 크기와 쿼리 로드에 비해 메모리 제한이 작을 때 자주 발생합니다.

해결:

• MongoDBSearch 리소스의 mongot 에 할당된 메모리 리소스를 늘립니다. mongot 가 다시 시작되면 변경사항이 적용됩니다.

• 검색 및 벡터 검색 리소스 계획 및 사이징의 사이징 지침에 대해 인덱스 크기와 쿼리 부하를 검토하세요.

초기 동기화가 느리거나 복제 지연이 증가합니다.

증상: 새로 생성된 인덱스가 오래 동안 빌드 상태에 머물거나 쿼리 결과가 mongod에 대한 최근 쓰기(write)보다 늦어집니다.

진단: 복제 진행 및 오류에 대한 mongot 로그를 검토합니다. 배포서버 모니터 에서 구성한 지표를 사용하여 인덱스 생성 진행 및 복제 지연을 시간에 따라 추적합니다.

해결:

• 초기 동기화가 완료되도록 허용합니다. 인덱스 빌드 시간은 소스 데이터 크기에 따라 확장됩니다.

• 일정한 부하에서 지연이 계속되면 mongot 인스턴스에 쓰기 (write) 볼륨에 충분한 리소스가 없을 수 있습니다. 검색 및 벡터 검색 리소스 계획 및 사이징을 검토.

• 저장 성능이 무작위 읽기 중심의 Lucene 워크로드에 대한 권장 사항을 충족하는지 확인하세요. 느린 저장은 지속적인 지연의 일반적인 원인입니다.

TLS Handshake Failures Between mongod and mongot

Symptoms: The mongot logs show TLS handshake or certificate-validation errors, and mongod cannot establish a connection to mongot.

Diagnose: Review the mongot logs for certificate errors and confirm that the TLS Secrets referenced by the MongoDBSearch resource exist:

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

해결:

• Confirm that mongod and mongot trust the same CA.

• 인증서를 대체하거나 로테이션한 후에는 mongot 을 다시 시작하여 새 인증서를 읽도록 합니다. mongot 은 시작 시 인증서를 읽지만 실행 중에는 다시 로드하지 않습니다.

• 자세한 학습은 MongoDB에서 검색으로의 연결 보안을 참조하세요.

자동화된 임베딩 실패

증상: 자동 임베딩을 사용하는 인덱스가 빌드되지 않거나 mongot 로그에서 임베딩 요청이 오류를 반환합니다.

진단: 인증 실패 또는 요청 타임아웃과 같이 임베딩 제공자를 참조하는 오류가 있는지 mongot 로그를 검토합니다.

해결:

• Voyage AI API 키가 유효하고 키를 보관하는 Secret이 네임스페이스에 존재하는지 확인합니다.

• Kubernetes 클러스터에서 mongot 가 임베딩 제공자 엔드포인트에 액세스할 수 있는지 확인합니다.

지원을 위한 진단 캡처

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

You can also include FTDC files from each affected search pod. mongot writes FTDC files to /mongot/data/diagnostic.data/ inside the pod.

/mongot/data 경로는 Kubernetes Operator가 검색 StatefulSet에 volumeClaimTemplate 를 통해 팝에 마운트하는 PersistentVolumeClaim 이므로 진단 데이터가 팝 재시작에서도 유지됩니다. 팝이 대체되면 StatefulSet은 동일한 PersistentVolumeClaim를 다시 연결하므로 진단 데이터가 유지됩니다.

검색 팝에서 로컬 마신으로 FTDC 데이터를 복사합니다. 샤딩된 클러스터의 경우, 각 샤드별 검색 팝에서 로컬 마신으로 FTDC 데이터를 복사합니다. 모든 샤드에 대해 반복합니다.

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}

자세히 알아보기

• 배포 모니터링

• mongot 배포 제한