AI エージェント向け: ドキュメントインデックスは https://www.mongodb.com/ja-jp/docs/llms.txt で利用できます。すべてのページの markdown バージョンは、いずれかの URL パスに .md を追加することで利用できます。
Docs Menu

Troubleshoot mongot Deployment

The MongoDB Controllers for Kubernetes Operator deploys mongot as a separate process in its own Pod, defined by a MongoDBSearch resource. Clients never connect to mongot directly: MongoDB Search and Vector Search queries run on mongod, which proxies them to mongot. mongot connects back to mongod to stream change events and build its indexes on a dedicated Persistent Volume.

このページでは、mongot 配置で発生する一般的なランタイムの問題を診断し、解決する方法について説明します。初期設定時のインデックス作成に特有のトラブルシューティングについては、 MongoDB Search とベクトル検索の使用を参照してください。調査する前にメトリクスとログを設定するには、 配置のモニターを参照してください。

このページの手順では、次の環境変数を配置に合わせて設定していることを前提としています。

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

特定のシナリオに取り組む前に、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 リソースはいくつかの独立したコンポーネントを実行します。

  • 1 つ以上の mongot StatefulSets

  • 任意のKubernetes OperatorマネージドEnvoyロードバランサー

  • 任意の Cloud Manager または MongoDB Ops Manager メトリクスフォワーダー。

マルチクラスター配置では、これらの各々は、ノードクラスターごとに実行されます。検索が期待どおりに動作しない場合は、リソースステータスを使用して、Pod やログを調査する前に、問題を特定のクラスターとコンポーネントにローカライズします。

ステータスを読み取るには、

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

最上位のフィールドから開始し、status.clustersを使用して絞り込みます。

フィールド
これが示すもの

status.phase

全体的なリソースフェーズ。これは、すべてのクラスターにおける mongot StatefulSet の準備状況 (最悪の場合) とマネージドロードバランサーの準備状況の両方を反映します。いずれかのクラスターの mongot または Kubernetes 演算子マネージドロードバランサーが準備でない場合、リソースは Pending フェーズにあります。メトリクス転送はこのフェーズに影響しませ

status.loadBalancer

すべてのクラスターで集約されたマネージド Envoy ロードバランサーフェーズ。これは、spec.clusters[].loadBalancer.managed が設定されている場合にのみ移入されます。

status.metricsForwarder

すべてのクラスターで集計された MongoDB Ops Manager メトリクス フォワーダー フェーズ。メトリクス フォワーダーが有効になっている場合にのみです。

status.clusters[]

ノード クラスターごとに 1 つのエントリがあり、それぞれに固有の nameindex があり、searchloadBalancermetricsForwarder のサブフェーズが独立しています。各サブフェーズには、サブフェーズが Running でない場合に理由を説明する一致する *Message フィールド(例:searchMessage)があります。

Tip

クラスターの search サブフェーズがすべて Running であっても、MongoDBSearch リソースは Pending できます。クラスターの劣化したマネージド loadBalancer は、リソース全体を Pending フェーズに保持できます。クラスターごとのサブフェーズを読み取り、責任を負うクラスターとコンポーネントを特定します。

次の例は、2 つのクラスターの配置で、2 番目のクラスターの Envoy ロード バランサーがロールアウトの途中で停滞している場合を示しています。マネージド ロード バランサーの準備状況はフェーズ全体に影響するため、両クラスターの mongot が正常であっても、リソースは Pending です。

例: 保留フェーズ
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)"

影響を受けたクラスターの nameindex を使用して、対応するコンポーネントを調査します。

  • 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 Deployment を調査します。rollout in progressunavailable replica(s) などのメッセージは、新しい Envoy Pod がスケジューリングされていないか、準備できていないことを示しています。

  • Running ではない metricsForwarder サブフェーズの場合は、そのクラスターのメトリクスフォワーダー配置を調査します。

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

症状: mongot ポッドが PendingContainerCreatingError の状態のまま 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 Controllers 演算子は、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 ログを検討します。

解決:

症状: mongot ポッドの再起動回数が多いか、CrashLoopBackOff が報告されます。

診断: 前のコンテナ インスタンスのログを表示して、再起動をトリガーしたエラーをキャプチャします。

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

pod の最終状態と終了理由を確認します。

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 Controllers 演算子によって変更を調整させます。

  • 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 ポッドが OOMKilled の理由で終了され、再起動回数が増加します。

診断: ポッドの終了理由を確認します。

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

mongot Lucene に基づいたメモリマップワークロードです。メモリの圧力は、インデックスサイズとクエリロードに対するメモリの制限が小さすぎることによって発生することがよくあります。

解決:

  • MongoDBSearch リソースの mongot に割り当てられるメモリ リソースを増加します。mongot を再起動して変更を適用します。

  • 検索とベクトル検索のリソース計画とサイジングのサイジングガイダンスに対して、インデックスのサイズとクエリロードを検討します。

症状: 新しく作成されたインデックスが長時間ビルド状態のままになるか、クエリ結果がmongodへの最近の書き込みに対して遅れる。

診断: mongotログでレプリケーションの進捗状況とエラーを確認します。配置のモニターで設定したメトリクスを使用して、インデックス構築の進捗状況とレプリケーションラグを経時的に追跡します。

解決:

  • 最初の同期が完了するまで待機します。インデックスをビルドする時間は、ソースデータのサイズに応じて増えます。

  • 安定した負荷の下でも遅延が続く場合、mongot インスタンスには書き込み量に十分なリソースがない可能性があります。検索とベクトル検索のリソース計画とサイジ設定。を検討します。

  • ランダム読み取りの多い Lucene ワークロードのストレージパフォーマンスが推奨事項を満たしていることを確認します。ストレージの低速化は、持続的な遅延の一般的な原因です。

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 からサーチへの接続を保護するを参照してください。

注意

自動埋め込みはプレビュー機能であり、Voyage AI モデルのみと統合されます。

症状: 自動埋め込みを使用するインデックスのビルドに失敗するか、埋め込みリクエストが mongot ログでエラーを返します。

診断: 認証の失敗やリクエストのタイムアウトなど、埋め込みプロバイダーを参照するエラーについて mongot ログを確認します。

解決:

  • Voyage AI API キーが有効であること、および、それを保持する Secret が名前空間に存在することを確認します。

  • mongot が Kubernetes クラスターから埋め込みプロバイダーのエンドポイントに接続できることを確認します。

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 パスは、検索 StatefulSet の volumeClaimTemplate を介して Kubernetes 演算子がポッドにマウントする 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}