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
Docs Home
/ /
Deploy Search & Vector Search
Docs Home
/
Management
/
Controllers for Kubernetes Operator
/
Deploy Search & Vector Search
Docs Home
/
Management
/
Controllers for Kubernetes Operator
/
Deploy Search & Vector Search

Install and Use MongoDB Search and Vector Search With External MongoDB Enterprise Edition

You can use the Kubernetes Operator to deploy MongoDB Search and Vector Search on a Kubernetes cluster to run with an external MongoDB Enterprise Edition v8.0.10 or higher server. This procedure demonstrates how to deploy and configure the mongot process in your Kubernetes cluster to use a new or existing external replica set deployment.

Prerequisites

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

  • A running Kubernetes cluster with kubeconfig available locally.

  • Kubernetes command-line tool, kubectl, configured to communicate with your cluster.

  • Helm, the package manager for Kubernetes, to install the Kubernetes Operator.

  • Bash v5.1 or higher for running the commands in this tutorial.

  • A MongoDB Enterprise Edition replica set running version 8.0.10 or higher for storing data.

    To learn more about deploying MongoDB Enterprise, see Deploy and Configure MongoDB Database Resources.

  • A running MongoDB Cloud Manager or Ops Manager for managing MongoDB tasks.

Before You Begin

Before you install MongoDB Search and Vector Search using the Kubernetes Operator, you must do the following:

Configure Cloud Manager or Ops Manager Parameters for MongoDB Search and Vector Search

Log in to the Cloud Manager or Ops Manager UI and perform the following steps to configure Cloud Manager or Ops Manager for MongoDB Search and Vector Search.

1

Go to your Cloud Manager or Ops Manager Deployment page.

  1. Log in to MongoDB Cloud Manager or Ops Manager.

  2. Click the Deployment tab.

  3. Select the cluster that you want to modify.

2

Modify your Cloud Manager or Ops Manager deployment configuration.

  1. Click the Modify button to open the deployment configuration editor.

  2. Click Advanced Configuration Options under the Process Configuration section.

  3. Click the Add Option button and select setParameter Startup Option from the dropdown.

  4. Add the following parameters in the fields, one by one, by clicking Add after adding the name and value:

    Parameter
    Value

    mongotHost

    Your search hostname and port. For example: search-node1.example.com:27017.

    searchIndexManagementHostAndPort

    Your search hostname and port. For example: search-node1.example.com:27017.

    skipAuthenticationToSearchIndexManagementServer

    false

    searchTLSMode

    Your configured TLS mode. For example, preferTLS, if the mongot process is configured to accept TLS connections.

3

Review and deploy your changes.

  1. Click the Review & Deploy button.

  2. Review and confirm to apply the changes.

    Cloud Manager or Ops Manager performs a rolling restart of your replica set to apply the new configuration.

Configure a Cloud Manager or Ops Manager User for MongoDB Search and Vector Search

You must create a user with the searchCoordinator role. In MongoDB versions 8.2 and later, the searchCoordinator is a built-in role. You must create a user and assign the role to the user. For MongoDB versions earlier than 8.2 and 8.0.10 or later, you must manually create the role and assign the privileges before creating the user. Select the tab that corresponds to the MongoDB version you are running to create a user with the searchCoordinator role.

MongoDB versions 8.2 or later

Complete the steps in this section if you use MongoDB versoins 8.2 or later.

To create the user and assign the user the built-in searchCoordinator role, complete the following steps by using either the Cloud Manager or Ops Manager UI or the mongosh:

1
Go to the Users page.

  1. Log in to Cloud Manager or Ops Manager UI.

  2. Go to the Security tab and click on Users.

2
Click Add New User.
3
Set the credentials for the user.
Username

Enter search-sync-source.

Password

Set a strong, secure password.

Authentication Database

Choose the admin database.

4
Assign the searchCoordinator role to the user.

In the Assign Roles section, select the built-in searchCoordinator role from the dropdown for the admin database.

5
Click Add User to create the user with the searchCoordinator role.

In mongosh, run the following commands:

1
Switch to the admin database.
use admin;
2
Run the following command after replacing the password with a secure password to create the user.
db.createUser({
   user: "search-sync-source",
   pwd: "<PASSWORD>", // Replace with your actual password
   roles: [
      { role: "searchCoordinator", db: "admin" }
   ]
});

MongoDB versions earlier than 8.2

Complete the step in this section if you use MongoDB versions earlier than 8.2.

To create the user and assign the user the built-in searchCoordinator role, complete the following steps by using either the Cloud Manager or Ops Manager UI or the mongosh:

To create the searchCoordinator role with the privileges and then add a user with the searchCoordinator role, complete the following steps in the Cloud Manager or Ops Manager UI:

1
Go to the Roles page.

  1. Log in to Cloud Manager or Ops Manager UI.

  2. Under the Security tab, go to the Roles sub-tab.

  3. Click Add New Custom Role.

2
Set the Role Name to searchCoordinator.
3
Specify the roles to inherit.

In the Role Inheritance section, add the following three roles from the admin database:

  • clusterMonitor

  • directShardOperations

  • readAnyDatabase

4
Add the database privileges to assign to the role.

  1. In the Privileges section, click Add Privilege.

  2. For Resource, enter __mdb_internal_search for the database.

    Do not enter anything in the collection field.

  3. Under Actions, add the following actions.

    • changeStream

    • cleanupStructuredEncryptionData, compactStructuredEncryptionData

    • collStats

    • convertToCapped

    • createCollection, dropCollection, listCollections, renameCollectionSameDB

    • createIndex, dropIndex, listIndexes

    • createSearchIndexes, dropSearchIndex, listSearchIndexes, updateSearchIndex

    • dbHash, dbStats

    • find, insert, remove, update

    • killCursors

    • planCacheRead

5
Configure the cluster privilege.

  1. Click Add Privilege.

  2. For Resource, toggle the resource type to cluster.

  3. For Action, select bypassDefaultMaxTimeMS.

6
Review all the settings and click Create Role.
7
Go to the Users page.

Go to the Security tab and click Users.

8
Click Add New User.
9
Set the credentials for the user.
Username

Enter search-sync-source.

Password

Set a strong, secure password.

Authentication Database

Choose the admin database.

10
Assign the searchCoordinator role to the user.

In the Assign Roles section, select the built-in searchCoordinator role from the dropdown for the admin database.

In mongosh, run the following commands:

1
Switch to the admin database.
use admin;
2
Create the custom role.
db.createRole({
   role: "searchCoordinator",
   privileges: [
      {
         resource: { db: "__mdb_internal_search", collection: "" },
         actions: [
            "changeStream", "cleanupStructuredEncryptionData", "collStats",
            "compactStructuredEncryptionData", "convertToCapped", "createCollection",
            "createIndex", "createSearchIndexes", "dbHash", "dbStats",
            "dropCollection", "dropIndex", "dropSearchIndex", "find", "insert",
            "killCursors", "listCollections", "listIndexes", "listSearchIndexes",
            "planCacheRead", "remove", "renameCollectionSameDB", "update", "updateSearchIndex"
         ]
      },
      {
         resource: { cluster: true },
         actions: [ "bypassDefaultMaxTimeMS" ]
      }
   ],
   roles: [
      { role: "clusterMonitor", db: "admin" },
      { role: "directShardOperations", db: "admin" },
      { role: "readAnyDatabase", db: "admin" }
   ]
});
3
Run the following command after replacing the password with a secure password to create the user.
db.createUser({
   user: "search-sync-source",
   pwd: "<PASSWORD>", // Replace with your actual password
   roles: [
      { role: "searchCoordinator", db: "admin" }
   ]
});

Setup Your Environment

Prepare your environment for running the sample code in this tutorial in a terminal.

1

Required. Set the environment variables.

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:

1export K8S_CTX="<your kubernetes context here>"
2
3export MDB_NS="mongodb"
4
5export MDB_VERSION="8.0.10"
6
7export MDB_ADMIN_USER_PASSWORD="admin-user-password-CHANGE-ME"
8export MDB_USER_PASSWORD="mdb-user-password-CHANGE-ME"
9export MDB_SEARCH_SYNC_USER_PASSWORD="search-sync-user-password-CHANGE-ME"
10
11export MDB_SEARCH_HOSTNAME="mdbs-search"
12
13# External MongoDB replica set members - REPLACE THESE VALUES with your actual external MongoDB hosts
14# In production, replace with your actual external MongoDB replica set members
15export MDB_EXTERNAL_HOST_0="mdbc-rs-0.mdbc-rs-svc.${MDB_NS}.svc.cluster.local:27017"
16export MDB_EXTERNAL_HOST_1="mdbc-rs-1.mdbc-rs-svc.${MDB_NS}.svc.cluster.local:27017"
17export MDB_EXTERNAL_HOST_2="mdbc-rs-2.mdbc-rs-svc.${MDB_NS}.svc.cluster.local:27017"
18
19# REPLACE with your external MongoDB keyfile secret name
20export MDB_EXTERNAL_KEYFILE_SECRET_NAME="mdbc-rs-keyfile"
21
22# REPLACE with the actual keyfile content from your external MongoDB replica set
23# For testing, this will be automatically generated by the MongoDB Community resource
24export MDB_EXTERNAL_KEYFILE_CONTENT="your-mongodb-keyfile-content-CHANGE-ME"
25
26# REPLACE with your actual external MongoDB replica set name
27export MDB_EXTERNAL_REPLICA_SET_NAME="mdbc-rs"
28
29export OPERATOR_HELM_CHART="mongodb/mongodb-kubernetes"
30export OPERATOR_ADDITIONAL_HELM_VALUES=""
31
32export MDB_CONNECTION_STRING="mongodb://mdb-user:${MDB_USER_PASSWORD}@${MDB_EXTERNAL_HOST_0}/?replicaSet=${MDB_EXTERNAL_REPLICA_SET_NAME}"
2

Conditional. Add the MongoDB Helm repository.

Helm automates the deployment and management of MongoDB instances on Kubernetes. If you have already added the Helm repository that contains the Helm chart for installing the Kubernetes Operator operator, skip this step. Otherwise, add the Helm repository.

To add, copy, paste, and run the following command:

1helm repo add mongodb https://mongodb.github.io/helm-charts
2helm repo update mongodb
3helm search repo mongodb/mongodb-kubernetes
3

Conditional. Install the MongoDB Controllers for Kubernetes Operator.

The Kubernetes Operator watches MongoDB, MongoDBOpsManager, and MongoDBSearch custom resources and manages the lifecycle of your MongoDB deployments. If you already installed the MongoDB Controllers for Kubernetes Operator, skip this step. Otherwise, install the MongoDB Controllers for Kubernetes Operator from the Helm repository you added in the previous step.

To install the MongoDB Controllers for Kubernetes Operator in the mongodb namespace, copy, paste, and run the following:

1helm upgrade --install --debug --kube-context "${K8S_CTX}" \
2  --create-namespace \
3  --namespace="${MDB_NS}" \
4  mongodb-kubernetes \
5  ${OPERATOR_ADDITIONAL_HELM_VALUES:+--set ${OPERATOR_ADDITIONAL_HELM_VALUES}} \
6  "${OPERATOR_HELM_CHART}"

The preceding command installs Kubernetes Operator in the mongodb namespace, which it creates if it doesn't already exist. After installation, the Kubernetes Operator watches for MongoDBSearch custom resources and manage the lifecycle of your MongoDB Search and Vector Search deployments.

Install MongoDB Search and Vector Search

1

Required. Create and load the MongoDB user secrets.

The mongot process requires authentication credentials to connect to your external MongoDB deployment for creating search indexes and running search queries. This step creates the following Kubernetes secrets:

  • mdb-admin-user-password - credentials for the MongoDB administrator.

  • mdb-user-password - credentials for the user authorized to perform search queries.

  • mdbc-rs-search-sync-source-password - credentials for a dedicated search user used internally by the mongot process to synchronize data and manage indexes.

Kubernetes Operator mounts these secrets into the MongoDB pods.

To create the secrets, copy, paste, and run the following in the namespace where you plan to deploy MongoDB Search and Vector Search:

1kubectl --context "${K8S_CTX}" --namespace "${MDB_NS}" \
2  create secret generic mdb-admin-user-password \
3  --from-literal=password="${MDB_ADMIN_USER_PASSWORD}"
4
5kubectl --context "${K8S_CTX}" --namespace "${MDB_NS}" \
6  create secret generic mdbc-rs-search-sync-source-password \
7  --from-literal=password="${MDB_SEARCH_SYNC_USER_PASSWORD}"
8
9kubectl --context "${K8S_CTX}" --namespace "${MDB_NS}" \
10  create secret generic mdb-user-password \
11  --from-literal=password="${MDB_USER_PASSWORD}"
2

Required. Deploy the keyfile secret to use to connect to the mongod.

To authenticate connections from your external MongoDB, the mongot process uses the same keyfile that your external MongoDB replica set members use for internal authentication between replica set members.

To create a Kubernetes secret containing the keyfile content from your external MongoDB, copy, paste, and run the following command:

1kubectl --context "${K8S_CTX}" --namespace "${MDB_NS}" \
2  create secret generic "${MDB_EXTERNAL_KEYFILE_SECRET_NAME}" \
3  --from-literal=keyfile="${MDB_EXTERNAL_KEYFILE_CONTENT}"
3

Required. Create and deploy the resource for MongoDB Search and Vector Search.

You can deploy one instance of the search node without any load balancing. To deploy, complete the following steps:

  1. Create a MongoDBSearch custom resource named mdbs.

    This resource contains the following:

    spec.source.external.hostAndPorts

    List of external MongoDB replica set members.

    spec.source.external.keyfileSecretRef

    Keyfile secret used by the external replica set members.

    spec.source.username

    Search synchronization user username.

    spec.source.passwordSecretRef

    Search synchronization user password.

    spec.resourceRequirements

    CPU and memory resource requirements for the search container.

    To learn more about the settings in this custom resource, see MongoDB Search and Vector Search Settings.

    1kubectl apply --context "${K8S_CTX}" -n "${MDB_NS}" -f - <<EOF
    2apiVersion: mongodb.com/v1
    3kind: MongoDBSearch
    4metadata:
    5  name: mdbs
    6spec:
    7  source:
    8    external:
    9      hostAndPorts:
    10        - ${MDB_EXTERNAL_HOST_0}
    11        - ${MDB_EXTERNAL_HOST_1}
    12        - ${MDB_EXTERNAL_HOST_2}
    13      keyfileSecretRef:
    14        name: ${MDB_EXTERNAL_KEYFILE_SECRET_NAME}
    15        key: keyfile
    16    username: search-sync-source
    17    passwordSecretRef:
    18      name: mdbc-rs-search-sync-source-password
    19      key: password
    20  resourceRequirements:
    21    limits:
    22      cpu: "3"
    23      memory: 5Gi
    24    requests:
    25      cpu: "2"
    26      memory: 3Gi
    27EOF

  2. Wait for the MongoDBSearch resource deployment to complete.

    When you apply the MongoDBSearch custom resource, the Kubernetes operator begins deploying the search nodes (pods). This step pauses the execution until the mdbs resource's status phase is Running, which indicates that the MongoDB Search StatefulSet is operational.

    1echo "Waiting for MongoDBSearch resource to reach Running phase..."
    2kubectl --context "${K8S_CTX}" -n "${MDB_NS}" wait \
    3  --for=jsonpath='{.status.phase}'=Running mdbs/mdbs --timeout=300s
4

Required. Configure external access for MongoDB Search and Vector Search.

To enable your external MongoDB instances to connect to the search service, you must configure external access for MongoDB Search and Vector Search. You can create a LoadBalancer Service that exposes the search pods outside the Kubernetes cluster.

This following service exposes the MongoDBSearch service on port 27027 with an external IP address or hostname that can be accessed from outside the Kubernetes cluster.

1kubectl apply --context "${K8S_CTX}" -n "${MDB_NS}" -f - <<YAML
2apiVersion: v1
3kind: Service
4metadata:
5  name: ${MDB_SEARCH_HOSTNAME}
6spec:
7  type: LoadBalancer
8  selector:
9    app: mdbs-search-svc
10  ports:
11    - name: mongot
12      port: 27027
13      targetPort: 27027
14YAML
15
16echo "Waiting for external IP to be assigned to service ${MDB_SEARCH_HOSTNAME}..."
17TIMEOUT=120  # 2 minutes timeout
18ELAPSED=0
19while [ ${ELAPSED} -lt ${TIMEOUT} ]; do
20  EXTERNAL_IP=$(kubectl get service "${MDB_SEARCH_HOSTNAME}" --context "${K8S_CTX}" -n "${MDB_NS}" -o jsonpath='{.status.loadBalancer.ingress[0].ip}' 2>/dev/null)
21  if [ -n "${EXTERNAL_IP}" ] && [ "${EXTERNAL_IP}" != "null" ]; then
22    echo "External IP assigned: ${EXTERNAL_IP}"
23    break
24  fi
25  echo "Still waiting for external IP assignment... (${ELAPSED}s/${TIMEOUT}s)"
26  sleep 5
27  ELAPSED=$((ELAPSED + 5))
28done
29
30if [ ${ELAPSED} -ge ${TIMEOUT} ]; then
31  echo "ERROR: Timeout reached (${TIMEOUT}s) while waiting for external IP assignment"
32  echo "LoadBalancer service may take longer to provision or there may be an issue"
33  exit 1
34fi
5

Optional. View all the running pods in your namespace.

View all the running pods in your namespace pods for the MongoDB replica set members, the MongoDB Controllers for Kubernetes Operator, and the Search nodes.

1echo; echo "MongoDBSearch resource"
2kubectl --context "${K8S_CTX}" -n "${MDB_NS}" get mdbs/mdbs
3echo; echo "Search pods running in cluster ${K8S_CTX}"
4kubectl --context "${K8S_CTX}" -n "${MDB_NS}" get pods -l app=mdbs-search-svc
5echo; echo "All pods in namespace ${MDB_NS}"
6kubectl --context "${K8S_CTX}" -n "${MDB_NS}" get pods

Next Steps

Now that you've successfully deployed MongoDB Search and Vector Search to use with external MongoDB Enterprise Edition, you can add data into your MongoDB cluster, create MongoDB Search and Vector Search indexes, and run queries against your data. To learn more, see MongoDB Search and Vector Search Settings.

Rate this page

On this page