For AI agents: a documentation index is available at https://www.mongodb.com/docs/llms.txt — markdown versions of all pages are available by appending .md to any URL path.
Docs Menu

Use MongoDB Search and Vector Search

After you install the MongoDBSearch custom resource, you can create MongoDB Search and Vector Search indexes as the mdb-user and run MongoDB Search and Vector Search queries using the indexes. This page describes how to load sample data, create MongoDB Search and Vector Search indexes for the sample data, and run MongoDB Search and Vector Search queries against the sample data.

To use MongoDB Search and Vector Search, you must have the following:

1
  1. To set the environment variables for use in the subsequent steps in this procedure, copy the following, set the values for the environment variables, and then load the environment variables:

    1# The env vars here are all commented out because this snippets module
    2# is reusable across different MongoDB deployments and all the necessary variables
    3# should be already defined there.
    4
    5# set it to the context name of the k8s cluster
    6#export K8S_CTX="<local cluster context>"
    7# the following namespace will be used to deploy mongodb tools pod
    8#export MDB_NS="mongodb"
    9
    10# regular user performing restore and search queries on sample mflix database
    11# the user should be able to restore database using mongorestore
    12#export MDB_USER_PASSWORD="mdb-user-password-CHANGE-ME"
    13
    14# name of MongoDB or MongoDBCommunity resource in case it's deployed in the same cluster
    15# user only for the connection string in MDB_CONNECTION_STRING env var below
    16#export MDB_RESOURCE_NAME="mdbc-rs"
    17
    18# TLS-related resources used by the snippets in this module
    19#export MDB_TLS_CA_SECRET_NAME="${MDB_RESOURCE_NAME}-ca"
    20#export MDB_TLS_CA_CONFIGMAP="${MDB_RESOURCE_NAME}-ca-configmap"
    21#export MDB_TLS_SERVER_CERT_SECRET_NAME="${MDB_RESOURCE_NAME}-tls"
    22#export MDB_SEARCH_TLS_SECRET_NAME="${MDB_RESOURCE_NAME}-search-tls"
    23
    24# default connection string if MongoDB database is deployed using the operator
    25#export MDB_CONNECTION_STRING="mongodb://mdb-user:${MDB_USER_PASSWORD}@${MDB_RESOURCE_NAME}-0.${MDB_RESOURCE_NAME}-svc.${MDB_NS}.svc.cluster.local:27017/?replicaSet=${MDB_RESOURCE_NAME}"
    26# To enable TLS for the shared snippets, append driver options directly to the connection string, for example:
    27#export MDB_CONNECTION_STRING="mongodb://mdb-user:${MDB_USER_PASSWORD}@${MDB_RESOURCE_NAME}-0.${MDB_RESOURCE_NAME}-svc.${MDB_NS}.svc.cluster.local:27017/?replicaSet=${MDB_RESOURCE_NAME}&tls=true&tlsCAFile=/tls/ca.crt"
  2. To connect using the TLS-enabled connection string, as shown (on line 27) in the env_variables.sh file, download the CA certificate for the MongoDBSearch service so that the mongosh client can reference it.

2

Deploy a pod named mongodb-tools-pod to run MongoDB client tools like mongosh and mongorestore from within the Kubernetes cluster. Running a pod inside the cluster simplifies connectivity to MongoDB without needing to expose the database externally.

The following command deploys a pod that runs a MongoDB Community Server image, which ships with mongosh. The pod is kept running with a sleep infinity command so that you can use kubectl exec to run MongoDB client tools against your actual cluster.

1kubectl apply -n "${MDB_NS}" --context "${K8S_CTX}" -f - <<EOF
2apiVersion: v1
3kind: Pod
4metadata:
5 name: mongodb-tools-pod
6 labels:
7 app: mongodb-tools
8spec:
9 containers:
10 - name: mongodb-tools
11 image: mongodb/mongodb-community-server:${MDB_VERSION%-ent}-ubi8
12 command: ["/bin/bash", "-c"]
13 args: ["sleep infinity"]
14 volumeMounts:
15 - name: mongo-ca
16 mountPath: /tls
17 readOnly: true
18 restartPolicy: Never
19 volumes:
20 - name: mongo-ca
21 configMap:
22 name: ${MDB_TLS_CA_CONFIGMAP:-"${MDB_RESOURCE_NAME}-ca-configmap"}
23 optional: true
24 items:
25 - key: ca.crt
26 path: ca.crt
27EOF
28
29echo "Waiting for the mongodb-tools to be ready..."
30kubectl --context "${K8S_CTX}" -n "${MDB_NS}" wait --for=condition=Ready pod/mongodb-tools-pod --timeout=60s
3

Import the sample_mflix database, which contains the following collections:

Collection Name
Description

comments

Contains comments associated with specific movies.

embedded_movies

Contains details on movies in the Western, Action, and Fantasy genres from the movies collection with the following additional fields:

  • plot_embedding_voyage_3_large - Contains 2048d embeddings created from the plot field using Voyage AI's voyage-3-large embedding model and converted to binData for efficient storage and retrieval.

  • plot_embedding - Contains 1536d embeddings created from the plot field using OpenAI's text-embedding-ada-002 embedding model and converted to binData for efficient storage and retrieval.

movies

Contains movie information, including release year, director, and reviews.

sessions

Metadata field. Contains users' JSON Web Tokens.

theaters

Contains locations of movie theaters.

users

Contains user information.

The following command downloads the sample dataset and uses mongorestore to load the data into the sample_mflix database in your MongoDB deployment, connecting as the mdb-user.

1echo "Downloading sample database archive..."
2kubectl exec -n "${MDB_NS}" --context "${K8S_CTX}" mongodb-tools-pod -- \
3 curl -fSL https://atlas-education.s3.amazonaws.com/sample_mflix.archive \
4 -o /tmp/sample_mflix.archive
5
6echo "Restoring sample database..."
7kubectl exec -n "${MDB_NS}" --context "${K8S_CTX}" mongodb-tools-pod -- \
8 mongorestore \
9 --archive=/tmp/sample_mflix.archive \
10 --verbose=1 \
11 --drop \
12 --nsInclude 'sample_mflix.*' \
13 --uri="${MDB_CONNECTION_STRING}"
4

You can create a MongoDB Search or a Vector Search index. You must create a MongoDB Search index to run $search and $searchMeta queries and Vector Search index to run $vectorSearch queries.

  • MongoDB Search provides flexible index definitions that support dynamic and static field mappings, various analyzers (standard, language-specific, custom), and features like synonyms and faceted search. To learn more, see Define Your Index.

  • Vector Search provides simple index definition that supports querying vector embeddings or text (if you enabled mongot for Automated Embedding) in your data based on semantic similarity by using ANN and ENN search algorithm. To learn more, see Define Vector Search Index.

  1. Copy, paste, and run the following command in your terminal to create a MongoDB Search or a Vector Search index.

    The command uses kubectl exec to run mongosh in the mongodb-tools-pod. It connects to the sample_mflix database and uses the db.<collection>.createSearchIndex() method to create an index.

  2. Verify that the index creation succeeded.

    Run the following command to retrieve the list of indexes for the collection.

5

After the index creation is successful, you can run MongoDB Search or Vector Search queries using the index. You can also combine MongoDB Search with Vector Search. To learn more about running MongoDB Search queries, see Define Your Query. To learn more about Vector Search queries, see Run Vector Search ANN and ENN Queries.

The following script defines the aggregation pipeline query criteria and uses the kubectl exec command to load mongosh to execute the query.

1
  1. To set the environment variables for use in the subsequent steps in this procedure, copy the following, set the values for the environment variables, and then load the environment variables:

    1# The env vars here are all commented out because this snippets module
    2# is reusable across different MongoDB deployments and all the necessary variables
    3# should be already defined there.
    4
    5# set it to the context name of the k8s cluster
    6#export K8S_CTX="<local cluster context>"
    7# the following namespace will be used to deploy mongodb tools pod
    8#export MDB_NS="mongodb"
    9
    10# regular user performing restore and search queries on sample mflix database
    11# the user should be able to restore database using mongorestore
    12#export MDB_USER_PASSWORD="mdb-user-password-CHANGE-ME"
    13
    14# name of MongoDB or MongoDBCommunity resource in case it's deployed in the same cluster
    15# user only for the connection string in MDB_CONNECTION_STRING env var below
    16#export MDB_RESOURCE_NAME="mdbc-rs"
    17
    18# TLS-related resources used by the snippets in this module
    19#export MDB_TLS_CA_SECRET_NAME="${MDB_RESOURCE_NAME}-ca"
    20#export MDB_TLS_CA_CONFIGMAP="${MDB_RESOURCE_NAME}-ca-configmap"
    21#export MDB_TLS_SERVER_CERT_SECRET_NAME="${MDB_RESOURCE_NAME}-tls"
    22#export MDB_SEARCH_TLS_SECRET_NAME="${MDB_RESOURCE_NAME}-search-tls"
    23
    24# default connection string if MongoDB database is deployed using the operator
    25#export MDB_CONNECTION_STRING="mongodb://mdb-user:${MDB_USER_PASSWORD}@${MDB_RESOURCE_NAME}-0.${MDB_RESOURCE_NAME}-svc.${MDB_NS}.svc.cluster.local:27017/?replicaSet=${MDB_RESOURCE_NAME}"
    26# To enable TLS for the shared snippets, append driver options directly to the connection string, for example:
    27#export MDB_CONNECTION_STRING="mongodb://mdb-user:${MDB_USER_PASSWORD}@${MDB_RESOURCE_NAME}-0.${MDB_RESOURCE_NAME}-svc.${MDB_NS}.svc.cluster.local:27017/?replicaSet=${MDB_RESOURCE_NAME}&tls=true&tlsCAFile=/tls/ca.crt"
  2. To connect using the TLS-enabled connection string, as shown (on line 27) in the env_variables.sh file, download the CA certificate for the MongoDBSearch service so that the mongosh client can reference it.

2

Deploy a pod named mongodb-tools-pod to run MongoDB client tools like mongosh and mongorestore from within the Kubernetes cluster. Running a pod inside the cluster simplifies connectivity to MongoDB without needing to expose the database externally.

The following command deploys a pod that runs a MongoDB Community Server image, which ships with mongosh. The pod is kept running with a sleep infinity command so that you can use kubectl exec to run MongoDB client tools against your actual cluster.

1kubectl apply -n "${MDB_NS}" --context "${K8S_CTX}" -f - <<EOF
2apiVersion: v1
3kind: Pod
4metadata:
5 name: mongodb-tools-pod
6 labels:
7 app: mongodb-tools
8spec:
9 containers:
10 - name: mongodb-tools
11 image: mongodb/mongodb-community-server:${MDB_VERSION%-ent}-ubi8
12 command: ["/bin/bash", "-c"]
13 args: ["sleep infinity"]
14 volumeMounts:
15 - name: mongo-ca
16 mountPath: /tls
17 readOnly: true
18 restartPolicy: Never
19 volumes:
20 - name: mongo-ca
21 configMap:
22 name: ${MDB_TLS_CA_CONFIGMAP:-"${MDB_RESOURCE_NAME}-ca-configmap"}
23 optional: true
24 items:
25 - key: ca.crt
26 path: ca.crt
27EOF
28
29echo "Waiting for the mongodb-tools to be ready..."
30kubectl --context "${K8S_CTX}" -n "${MDB_NS}" wait --for=condition=Ready pod/mongodb-tools-pod --timeout=60s
3

Import the sample_mflix database, which contains the following collections:

Collection Name
Description

comments

Contains comments associated with specific movies.

embedded_movies

Contains details on movies in the Western, Action, and Fantasy genres from the movies collection with the following additional fields:

  • plot_embedding_voyage_3_large - Contains 2048d embeddings created from the plot field using Voyage AI's voyage-3-large embedding model and converted to binData for efficient storage and retrieval.

  • plot_embedding - Contains 1536d embeddings created from the plot field using OpenAI's text-embedding-ada-002 embedding model and converted to binData for efficient storage and retrieval.

movies

Contains movie information, including release year, director, and reviews.

sessions

Metadata field. Contains users' JSON Web Tokens.

theaters

Contains locations of movie theaters.

users

Contains user information.

The following command downloads the sample dataset and uses mongorestore to load the data into the sample_mflix database in your MongoDB deployment, connecting as the mdb-user.

1echo "Downloading sample database archive..."
2kubectl exec -n "${MDB_NS}" --context "${K8S_CTX}" mongodb-tools-pod -- \
3 curl -fSL https://atlas-education.s3.amazonaws.com/sample_mflix.archive \
4 -o /tmp/sample_mflix.archive
5
6echo "Restoring sample database..."
7kubectl exec -n "${MDB_NS}" --context "${K8S_CTX}" mongodb-tools-pod -- \
8 mongorestore \
9 --archive=/tmp/sample_mflix.archive \
10 --verbose=1 \
11 --drop \
12 --nsInclude 'sample_mflix.*' \
13 --uri="${MDB_CONNECTION_STRING}"
4

You can create a MongoDB Search or a Vector Search index. You must create a MongoDB Search index to run $search and $searchMeta queries and Vector Search index to run $vectorSearch queries.

  • MongoDB Search provides flexible index definitions that support dynamic and static field mappings, various analyzers (standard, language-specific, custom), and features like synonyms and faceted search. To learn more, see Define Your Index.

  • Vector Search provides simple index definition that supports querying vector embeddings or text (if you enabled mongot for Automated Embedding) in your data based on semantic similarity by using ANN and ENN search algorithm. To learn more, see Define Vector Search Index.

  1. Copy, paste, and run the following command in your terminal to create a MongoDB Search or a Vector Search index.

    The command uses kubectl exec to run mongosh in the mongodb-tools-pod. It connects to the sample_mflix database and uses the db.<collection>.createSearchIndex() method to create an index.

  2. Verify that the index creation succeeded.

    Run the following command to retrieve the list of indexes for the collection.

5

After the index creation is successful, you can run MongoDB Search or Vector Search queries using the index. You can also combine MongoDB Search with Vector Search. To learn more about running MongoDB Search queries, see Define Your Query. To learn more about Vector Search queries, see Run Vector Search ANN and ENN Queries.

The following script defines the aggregation pipeline query criteria and uses the kubectl exec command to load mongosh to execute the query.

1
  1. To set the environment variables for use in the subsequent steps in this procedure, copy the following, uncomment the variables, replace the placeholder values with your deployment details, and then load the environment variables:

    1# The env vars here are all commented out because this
    2# snippets module is reusable across different sharded
    3# MongoDB Search deployments and all the necessary
    4# variables should be already defined there.
    5#
    6# Required env var contract:
    7# MDB_ADMIN_CONNECTION_STRING
    8# — for import/sharding commands (admin privileges)
    9# MDB_USER_CONNECTION_STRING
    10# — for search queries (regular user privileges)
    11# MDB_CONNECTION_STRING
    12# — fallback if the above are not set
    13# (e.g., non-sharded usage)
    14# K8S_CTX — Kubernetes context
    15# MDB_NS — Kubernetes namespace
    16# MDB_VERSION
    17# — MongoDB version (e.g., 8.2.6-ent)
    18# MDB_TLS_CA_CONFIGMAP
    19# — CA certificate ConfigMap name for tools pod
    20# TLS mount
    21
    22# set it to the context name of the k8s cluster
    23#export K8S_CTX="<local cluster context>"
    24# the following namespace will be used to deploy
    25# mongodb tools pod
    26#export MDB_NS="mongodb"
    27
    28# MongoDB version (used for tools pod image)
    29#export MDB_VERSION="8.3.4-ent"
    30
    31# admin user connection string (for import and sharding commands)
    32#export MDB_ADMIN_CONNECTION_STRING="mongodb://mdb-admin:PASSWORD@HOST/?tls=true&tlsCAFile=/tls/ca-pem&authSource=admin&authMechanism=SCRAM-SHA-256"
    33
    34# regular user connection string (for search queries)
    35#export MDB_USER_CONNECTION_STRING="mongodb://mdb-user:PASSWORD@HOST/?tls=true&tlsCAFile=/tls/ca-pem&authSource=admin&authMechanism=SCRAM-SHA-256"
    36
    37# TLS CA ConfigMap mounted in the tools pod at /tls
    38#export MDB_TLS_CA_CONFIGMAP="ext-mdb-sh-ca"
  2. To connect using the TLS-enabled connection strings defined in the env_variables.sh file, ensure that the CA certificate referenced by MDB_TLS_CA_CONFIGMAP is available so that the mongosh client can verify the server's TLS certificate.

2

Deploy a pod named mongodb-tools to run MongoDB client tools like mongosh and mongorestore from within the Kubernetes cluster. Running a pod inside the cluster simplifies connectivity to MongoDB without needing to expose the database externally.

The following command deploys a pod that runs a MongoDB server image, which ships with mongosh, and mounts the CA certificate from the MDB_TLS_CA_CONFIGMAP ConfigMap at /tls. The pod is kept running with a sleep infinity command so that you can use kubectl exec to run MongoDB client tools against your actual cluster.

1echo "Deploying mongodb-tools pod..."
2
3TOOLS_IMAGE="mongodb/mongodb-community-server:${MDB_VERSION%-ent}-ubi8"
4
5echo " Image: ${TOOLS_IMAGE}"
6kubectl apply --context "${K8S_CTX}" -f - <<EOF
7apiVersion: v1
8kind: Pod
9metadata:
10 name: mongodb-tools
11 namespace: ${MDB_NS}
12spec:
13 restartPolicy: Never
14 containers:
15 - name: mongodb-tools
16 image: ${TOOLS_IMAGE}
17 command: ["sleep", "infinity"]
18 volumeMounts:
19 - name: tls
20 mountPath: /tls
21 readOnly: true
22 volumes:
23 - name: tls
24 configMap:
25 # CA certificate is mounted at /tls/ca-pem
26 name: ${MDB_TLS_CA_CONFIGMAP}
27EOF
28
29# Wait for pod to be ready
30echo "Waiting for mongodb-tools pod to be ready..."
31kubectl wait --for=condition=Ready pod/mongodb-tools \
32 -n "${MDB_NS}" \
33 --context "${K8S_CTX}" \
34 --timeout=120s
35
36conn_str="${MDB_USER_CONNECTION_STRING:-${MDB_CONNECTION_STRING}}"
37echo "mongodb-tools pod is ready"
38echo ""
39echo "You can now run MongoDB commands using:"
40echo " kubectl exec -it mongodb-tools -n ${MDB_NS} -- mongosh \"${conn_str}\""
3

Import the sample_mflix database, which contains the following collections:

Collection Name
Description

comments

Contains comments associated with specific movies.

embedded_movies

Contains details on movies in the Western, Action, and Fantasy genres from the movies collection with the following additional fields:

  • plot_embedding_voyage_3_large - Contains 2048d embeddings created from the plot field using Voyage AI's voyage-3-large embedding model and converted to binData for efficient storage and retrieval.

  • plot_embedding - Contains 1536d embeddings created from the plot field using OpenAI's text-embedding-ada-002 embedding model and converted to binData for efficient storage and retrieval.

movies

Contains movie information, including release year, director, and reviews.

sessions

Metadata field. Contains users' JSON Web Tokens.

theaters

Contains locations of movie theaters.

users

Contains user information.

The following command uses the admin connection string to:

  1. Download the sample_mflix archive.

  2. Load the collection using mongorestore.

  3. Enable sharding on the sample_mflix database.

  4. Create a hashed index on movies._id.

  5. Shard the movies collection.

1echo "Importing sample_mflix dataset..."
2
3admin_conn="${MDB_ADMIN_CONNECTION_STRING:-${MDB_CONNECTION_STRING}}"
4
5echo "Downloading sample_mflix archive (~50MB)..."
6kubectl exec mongodb-tools -n "${MDB_NS}" --context "${K8S_CTX}" -- \
7 curl -sL 'https://atlas-education.s3.amazonaws.com/sample_mflix.archive' \
8 -o /tmp/sample_mflix.archive
9echo " Download complete"
10
11echo "Restoring database..."
12kubectl exec mongodb-tools -n "${MDB_NS}" --context "${K8S_CTX}" -- \
13 mongorestore --archive=/tmp/sample_mflix.archive \
14 --uri="${admin_conn}" \
15 --nsInclude='sample_mflix.*' \
16 --drop \
17 --numParallelCollections=1 \
18 --numInsertionWorkersPerCollection=1
19echo " Database restored"
20
21kubectl exec mongodb-tools -n "${MDB_NS}" --context "${K8S_CTX}" -- \
22 rm -f /tmp/sample_mflix.archive
23
24echo "Configuring sharding..."
25
26kubectl exec mongodb-tools -n "${MDB_NS}" --context "${K8S_CTX}" -- \
27 mongosh "${admin_conn}" --quiet --eval 'sh.enableSharding("sample_mflix")'
28echo " Enabled sharding on sample_mflix database"
29
30kubectl exec mongodb-tools -n "${MDB_NS}" --context "${K8S_CTX}" -- \
31 mongosh "${admin_conn}" --quiet --eval \
32 'db.getSiblingDB("sample_mflix").movies.createIndex({ _id: "hashed" })'
33echo " Created hashed index on movies._id"
34
35kubectl exec mongodb-tools -n "${MDB_NS}" --context "${K8S_CTX}" -- \
36 mongosh "${admin_conn}" --quiet --eval \
37 'sh.shardCollection("sample_mflix.movies", { _id: "hashed" })'
38echo " Sharded sample_mflix.movies collection"
39
40echo ""
41echo "Sample data imported and sharded"
4

You can create a MongoDB Search or a Vector Search index. You must create a MongoDB Search index to run $search and $searchMeta queries, and Vector Search index to run $vectorSearch queries.

  • MongoDB Search provides flexible index definitions that support dynamic and static field mappings, various analyzers (standard, language-specific, custom), and features like synonyms and faceted search. To learn more, see Define Your Index.

  • Vector Search provides simple index definition that supports querying vector embeddings in your data based on semantic similarity by using ANN and ENN search algorithm. To learn more, see Define Vector Search Index.

  1. Copy, paste, and run the following command in your terminal to create a MongoDB Search or a Vector Search index.

    The command uses kubectl exec to run mongosh in the mongodb-tools pod using the user connection string and calls createSearchIndex() to create the index. Kubernetes Operator creates the indexes through mongos and automatically distributes them to each shard's mongot instance through the Envoy proxy, an L7 load balancer that the operator manages automatically.

  2. Verify that the index creation succeeded.

    Run the following command to retrieve the list of indexes for the collection.

5

After the index creation is successful, you can run MongoDB Search or Vector Search queries using the index. You can also combine MongoDB Search with Vector Search. To learn more about running MongoDB Search queries, see Define Your Query. To learn more about Vector Search queries, see Run Vector Search ANN and ENN Queries.

The following script defines the aggregation pipeline query criteria and uses the kubectl exec command to load mongosh to execute the query.

Symptoms: The createSearchIndex command times out or fails.

Check:

# Verify that the mongot pod is running
kubectl get pods -n ${MDB_NS} --context ${K8S_CTX} | grep search
# Check mongot logs for connection or sync errors
kubectl logs ${MDB_RESOURCE_NAME}-search-0-0 \
-n ${MDB_NS} --context ${K8S_CTX} --tail=50
# Verify index status from the replica set
kubectl exec -n ${MDB_NS} --context ${K8S_CTX} \
${MDB_RESOURCE_NAME}-0 -c mongod -- \
mongosh --quiet --eval \
'db.getSiblingDB("sample_mflix").runCommand({ listSearchIndexes: "movies" })'

Common Causes:

  • The mongot pod is not ready.

  • The search-sync-source user credentials are incorrect or the password Secret was not created.

    Verify by running the following command:

    kubectl get secret ${MDB_RESOURCE_NAME}-search-sync-source-password -n ${MDB_NS}
  • TLS certificate mismatch between mongod and mongot.

    The MongoDBSearch TLS certificate referenced by spec.security.tls.certificateKeySecretRef must be trusted by the MongoDBCommunity replica set members.

    Deprecated since version 1.8.0: Use spec.security.tls.certsSecretPrefix instead.

Symptoms: The createSearchIndex command times out or fails.

Check:

# Verify that the mongot pod is running
kubectl get pods -n ${MDB_NS} --context ${K8S_CTX} | grep search
# Check mongot logs for connection or sync errors
kubectl logs ${MDB_RESOURCE_NAME}-search-0-0 \
-n ${MDB_NS} --context ${K8S_CTX} --tail=50
# Verify index status from the replica set
kubectl exec -n ${MDB_NS} --context ${K8S_CTX} \
${MDB_RESOURCE_NAME}-0 -c mongodb-enterprise-database -- \
mongosh --quiet --eval \
'db.getSiblingDB("sample_mflix").runCommand({ listSearchIndexes: "movies" })'

Common Causes:

  • The mongot pod is not ready.

  • The search-sync-source user credentials are incorrect or the password Secret was not created.

    Verify by running the following command:

    kubectl get secret ${MDB_RESOURCE_NAME}-search-sync-source-password -n ${MDB_NS}
  • TLS certificate mismatch between mongod and mongot.

    The MongoDBSearch TLS certificate referenced by spec.security.tls.certificateKeySecretRef must be trusted by the MongoDB replica set members.

    Deprecated since version 1.8.0: Use spec.security.tls.certsSecretPrefix instead.

Symptoms: The createSearchIndex command times out or fails when run through mongos.

Check:

# Verify that all per-shard mongot pods are running
kubectl get pods -n ${MDB_NS} --context ${K8S_CTX} | grep search
# Check mongot logs for a specific shard
kubectl logs ${MDB_SEARCH_RESOURCE_NAME}-search-0-${MDB_EXTERNAL_SHARD_0_NAME}-0 \
-n ${MDB_NS} --context ${K8S_CTX} --tail=50
# Verify index status from mongos
kubectl exec mongodb-tools -n ${MDB_NS} --context ${K8S_CTX} -- \
mongosh "${MDB_USER_CONNECTION_STRING}" --quiet --eval \
'db.getSiblingDB("sample_mflix").runCommand({ listSearchIndexes: "movies" })'

Common Causes:

  • mongot pods are not ready on one or more shards.

    All per-shard mongot instances must be running before index creation succeeds.

  • The search-sync-source user credentials are incorrect or the password Secret was not created.

    Verify by running the following command:

    kubectl get secret ${MDB_SEARCH_RESOURCE_NAME}-search-sync-source-password -n ${MDB_NS}
  • TLS CA mismatch between mongod and mongot.

    The CA certificate in MDB_TLS_CA_CONFIGMAP must be the same CA that signed the external mongod server certificates.

  • The Envoy proxy is not routing traffic correctly.

    Verify that per-shard proxy Services exist:

    kubectl get svc -n ${MDB_NS} | grep proxy-svc
  • The mongotHost parameter on the external mongod instances does not match the Envoy proxy Service endpoint for that shard.

Symptoms: The MongoDBSearch resource stays in Pending state and never transitions to Running.

Check:

kubectl describe mongodbsearch ${MDB_RESOURCE_NAME} \
-n ${MDB_NS} --context ${K8S_CTX}
kubectl get events -n ${MDB_NS} --context ${K8S_CTX} \
--field-selector involvedObject.name=${MDB_RESOURCE_NAME}
# Check operator logs for reconciliation errors
kubectl logs -l app.kubernetes.io/name=mongodb-kubernetes-operator \
-n ${MDB_NS} --context ${K8S_CTX} --tail=100

Common Causes:

  • The password Secret for the search-sync-source user was not created. The MongoDBSearch CR expects a Secret named ${MDB_RESOURCE_NAME}-search-sync-source-password.

  • TLS certificate Secrets are missing. Verify with kubectl get secrets -n ${MDB_NS} | grep tls.

  • The MongoDBCommunity replica set is not in Running state. The operator waits for the source resource before deploying the mongot pod.

  • The mongot container image cannot be pulled. Check for image pull errors with kubectl get events -n ${MDB_NS} | grep pull.

Symptoms: The MongoDBSearch resource stays in Pending state and never transitions to Running.

Check:

kubectl describe mongodbsearch ${MDB_RESOURCE_NAME} \
-n ${MDB_NS} --context ${K8S_CTX}
kubectl get events -n ${MDB_NS} --context ${K8S_CTX} \
--field-selector involvedObject.name=${MDB_RESOURCE_NAME}
# Check operator logs for reconciliation errors
kubectl logs -l app.kubernetes.io/name=enterprise-operator \
-n ${MDB_NS} --context ${K8S_CTX} --tail=100

Common Causes:

  • The password Secret for the search-sync-source user was not created. The MongoDBSearch CR expects a Secret named ${MDB_RESOURCE_NAME}-search-sync-source-password.

  • TLS certificate Secrets are missing. Verify with kubectl get secrets -n ${MDB_NS} | grep tls.

  • The MongoDB replica set is not in Running state. The operator waits for the source MongoDB resource before deploying the mongot pod.

  • The mongot container image cannot be pulled. Check for image pull errors with kubectl get events -n ${MDB_NS} | grep pull.

Symptoms: The MongoDBSearch resource stays in Pending state and never transitions to Running.

Check:

kubectl describe mongodbsearch ${MDB_SEARCH_RESOURCE_NAME} \
-n ${MDB_NS} --context ${K8S_CTX}
kubectl get events -n ${MDB_NS} --context ${K8S_CTX} \
--field-selector involvedObject.name=${MDB_SEARCH_RESOURCE_NAME}
# Check operator logs for reconciliation errors
kubectl logs -l app.kubernetes.io/name=enterprise-operator \
-n ${MDB_NS} --context ${K8S_CTX} --tail=100

Common Causes:

  • The password Secret for the search-sync-source user was not created. The MongoDBSearch CR expects a Secret named ${MDB_SEARCH_RESOURCE_NAME}-search-sync-source-password.

  • TLS certificate Secrets are missing. Verify with kubectl get secrets -n ${MDB_NS} | grep tls.

  • The external sharded cluster hostnames in spec.source.external.shardedCluster.router.hosts and spec.source.external.shardedCluster.shards[].hosts are incorrect or unreachable from the Kubernetes cluster.

  • The mongot container image cannot be pulled. Check for image pull errors with kubectl get events -n ${MDB_NS} | grep pull.

This issue applies to deployments that use a managed Envoy load balancer (spec.loadBalancer.managed).

Symptoms: When you create a MongoDB Search or Vector Search index, the command fails with the following error:

MongoServerError[CommandFailed]: Error connecting to Search Index Management service.

Check:

# Inspect the DNS names in the load balancer server certificate
kubectl get secret \
${MDB_TLS_CERT_SECRET_PREFIX}-${MDB_RESOURCE_NAME}-search-lb-0-cert \
-n ${MDB_NS} --context ${K8S_CTX} \
-o "jsonpath={.data['tls\.crt']}" | base64 -d | \
openssl x509 -noout -text | grep -A1 "Subject Alternative Name"
# Inspect the DNS names in the load balancer client certificate
kubectl get secret \
${MDB_TLS_CERT_SECRET_PREFIX}-${MDB_RESOURCE_NAME}-search-lb-0-client-cert \
-n ${MDB_NS} --context ${K8S_CTX} \
-o "jsonpath={.data['tls\.crt']}" | base64 -d | \
openssl x509 -noout -text | grep -A1 "Subject Alternative Name"

Common Causes:

  • The DNS names in the load balancer client or server certificates don't include the load balancer hostname that mongod uses to connect to mongot.

    Review the DNS names in the certificates. If they aren't correct, update the certificates and re-create the certificate Secrets. For the load balancer certificate naming conventions, see Deploy MongoDB Search and Vector Search.

Symptoms: When you create a MongoDB Search or Vector Search index through mongos, the command fails with the following error:

MongoServerError[CommandFailed]: Error connecting to Search Index Management service.

Check:

# Inspect the DNS names in the load balancer server certificate
kubectl get secret \
${MDB_TLS_CERT_SECRET_PREFIX}-${MDB_SEARCH_RESOURCE_NAME}-search-lb-0-cert \
-n ${MDB_NS} --context ${K8S_CTX} \
-o "jsonpath={.data['tls\.crt']}" | base64 -d | \
openssl x509 -noout -text | grep -A1 "Subject Alternative Name"
# Inspect the DNS names in the load balancer client certificate
kubectl get secret \
${MDB_TLS_CERT_SECRET_PREFIX}-${MDB_SEARCH_RESOURCE_NAME}-search-lb-0-client-cert \
-n ${MDB_NS} --context ${K8S_CTX} \
-o "jsonpath={.data['tls\.crt']}" | base64 -d | \
openssl x509 -noout -text | grep -A1 "Subject Alternative Name"

Common Causes:

  • The wildcard SAN in the load balancer server certificate doesn't cover all per-shard proxy Service host names that mongod uses to connect to mongot through SNI routing.

  • The load balancer client certificate is not signed by the CA that mongot trusts.

    Review the SANs in the server certificate and verify that the client certificate is signed by the correct CA. If they aren't correct, update the certificates and re-create the certificate Secrets. For the load balancer certificate naming conventions, see Deploy MongoDB Search and Vector Search.

To learn more about creating indexes and running search queries, see: