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.

Install and use With MongoDB Community Edition

You can use the Kubernetes Operator and deploy the mongot process resources to run with MongoDB Community Edition v8.3 or later on a Kubernetes cluster. The mongot process supports both MongoDB Search and Vector Search. Optionally, you can enable and configure Vector Search to automatically generate vector embeddings for text data in your collections and queries using a supported Voyage AI embedding model.

Important

Automated embedding is in Preview. The feature and the corresponding documentation might change at any time during the preview period. To learn more, see Preview Features.

The following procedure demonstrates how to deploy and configure MongoDB Search and Vector Search to run with a new or existing replica set in your Kubernetes cluster. The deployment uses TLS certificates to ensure secure communication between MongoDB nodes and the mongot search process.

Prerequisites

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

  • A running Kubernetes cluster.

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

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

  • cert-manager or an alternative certificate management solution for TLS certificate provisioning.

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

Optionally, to configure Vector Search to automatically generate vector embeddings for text data in your collections and queries, you must create API keys for the embedding service. We recommend creating two keys, one for generating embeddings at index-time for text data in your collection and another for generating embeddings at query-time for your query text. If you don't have the keys, you can create the keys from the Atlas UI.

Procedure

1

Required. Set the environment variables.

Set the environment variables for use in the subsequent steps in this procedure. Copy the following commands, update the values for your environment, and then run them to load the variables:

# set it to the context name of the k8s clusterexport K8S_CTX="<local cluster context>"
# the following namespace will be created if not existsexport MDB_NS="mongodb"
# MongoDBCommunity resource name referenced throughout the guideexport MDB_RESOURCE_NAME="mdbc-rs"# Number of replica set members deployed in the sample MongoDBCommunityexport MDB_MEMBERS=3
# TLS-related secret names used for MongoDBCommunity and MongoDBSearchexport MDB_TLS_CA_SECRET_NAME="${MDB_RESOURCE_NAME}-ca"export MDB_TLS_SERVER_CERT_SECRET_NAME="${MDB_RESOURCE_NAME}-tls"export MDB_SEARCH_TLS_SECRET_NAME="${MDB_RESOURCE_NAME}-search-tls"
export MDB_TLS_CA_CONFIGMAP="${MDB_RESOURCE_NAME}-ca-configmap"export MDB_TLS_SELF_SIGNED_ISSUER="${MDB_RESOURCE_NAME}-selfsigned-cluster-issuer"export MDB_TLS_CA_CERT_NAME="${MDB_RESOURCE_NAME}-selfsigned-ca"export MDB_TLS_CA_ISSUER="${MDB_RESOURCE_NAME}-cluster-issuer"
export MDB_VERSION="8.3.4"
# root admin user for convenience, not used here at all in this guideexport MDB_ADMIN_USER_PASSWORD="admin-user-password-CHANGE-ME"# regular user performing restore and search queries on sample mflix databaseexport MDB_USER_PASSWORD="mdb-user-password-CHANGE-ME"# user for MongoDB Search to connect to the replica set to synchronise data fromexport MDB_SEARCH_SYNC_USER_PASSWORD="search-sync-user-password-CHANGE-ME"
export OPERATOR_HELM_CHART="mongodb/mongodb-kubernetes"# comma-separated key=value pairs for additional parameters passed to the helm-chart installing the operatorexport OPERATOR_ADDITIONAL_HELM_VALUES=""
# TLS is mandatory; connection string must include tls=trueexport 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"
export CERT_MANAGER_NAMESPACE="cert-manager"
# Vector Search auto embedding related configurationsexport AUTO_EMBEDDING_API_KEY_SECRET_NAME="voyage-api-keys"export AUTO_EMBEDDING_API_QUERY_KEY="<embedding-model-query-key>"export AUTO_EMBEDDING_API_INDEXING_KEY="<embedding-model-indexing-key>"export PROVIDER_ENDPOINT="https://ai.mongodb.com/v1/embeddings"export EMBEDDING_MODEL="voyage-4"

Note

If you have the API keys to enable Vector Search to automatically generate embeddings, replace the following placeholder values in the environment variables:

AUTO_EMBEDDING_API_QUERY_KEY

API key for generating embeddings for the query text.

AUTO_EMBEDDING_API_INDEXING_KEY

API key for generating embeddings for text data in your collection at index-time.

PROVIDER_ENDPOINT

Embedding model provider's endpoint. Value defaults to https://ai.mongodb.com/v1/embeddings for keys created from the Atlas UI. Replace with https://api.voyageai.com/v1/embeddings if you created the API keys directly from Voyage AI.

2

Conditional. Add the MongoDB Helm repository.

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

To add the Helm repository, copy, paste, and run the following:

helm repo add mongodb https://mongodb.github.io/helm-chartshelm repo update mongodbhelm search repo mongodb/mongodb-kubernetes
3

Conditional. Install the MongoDB Controllers for Kubernetes Operator.

The Kubernetes Operator watches MongoDBCommunity 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 commands:

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

Optional. Wait for the operator deployment.

Ensure that the Kubernetes Operator is fully operational before proceeding with the MongoDB Search and Vector Search deployment. Run the following command to verify that all operator components are running and available.

kubectl --context "${K8S_CTX}" -n "${MDB_NS}" rollout status --timeout=2m deployment/mongodb-kubernetes-operatorecho "Operator deployment in ${MDB_NS} namespace"kubectl --context "${K8S_CTX}" -n "${MDB_NS}" get deploymentsecho; echo "Operator pod in ${MDB_NS} namespace"kubectl --context "${K8S_CTX}" -n "${MDB_NS}" get pods
5

Required. Create and load the MongoDB user secrets.

MongoDB requires authentication for secure access. In this step, you create three 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 uses passwords from those secrets to automatically create the users in the MongoDB database.

To create the secrets, copy, paste, and run the following command:

# Create admin user secretkubectl create secret generic mdb-admin-user-password \  --from-literal=password="${MDB_ADMIN_USER_PASSWORD}" \  --dry-run=client -o yaml | kubectl apply --context "${K8S_CTX}" --namespace "${MDB_NS}" -f -
# Create search sync source user secretkubectl create secret generic "${MDB_RESOURCE_NAME}-search-sync-source-password" \  --from-literal=password="${MDB_SEARCH_SYNC_USER_PASSWORD}" \  --dry-run=client -o yaml | kubectl apply --context "${K8S_CTX}" --namespace "${MDB_NS}" -f -
# Create regular user secretkubectl create secret generic mdb-user-password \  --from-literal=password="${MDB_USER_PASSWORD}" \  --dry-run=client -o yaml | kubectl apply --context "${K8S_CTX}" --namespace "${MDB_NS}" -f -
echo "User secrets created."
6

Conditional. Install the cert-manager.

The cert-manager is required for managing TLS certificates. If you already have cert-manager installed in your cluster, skip this step. Otherwise, install cert-manager using Helm.

To install cert-manager in the cert-manager namespace, run the following command in your terminal:

helm upgrade --install \  cert-manager \  oci://quay.io/jetstack/charts/cert-manager \  --kube-context "${K8S_CTX}" \  --namespace "${CERT_MANAGER_NAMESPACE}" \  --create-namespace \  --set crds.enabled=true
for deployment in cert-manager cert-manager-cainjector cert-manager-webhook; do  kubectl --context "${K8S_CTX}" \    -n "${CERT_MANAGER_NAMESPACE}" \    wait --for=condition=Available "deployment/${deployment}" --timeout=300sdone
echo "cert-manager is ready in namespace ${CERT_MANAGER_NAMESPACE}."
7

Required. Prepare certificate issuer and CA infrastructure.

Create the certificate authority infrastructure that will issue TLS certificates for MongoDB and MongoDBSearch resources. The commands perform the following actions:

  • Create a self-signed ClusterIssuer.

  • Generate a CA certificate.

  • Publish a cluster-wide CA issuer that all namespaces can use.

  • Expose the CA bundle through a ConfigMap so that MongoDB resources can use it.

# Bootstrap a self-signed ClusterIssuer that will mint the CA material consumed by# the MongoDBCommunity deployment.kubectl apply --context "${K8S_CTX}" -f - <<EOF_MANIFESTapiVersion: cert-manager.io/v1kind: ClusterIssuermetadata:  name: ${MDB_TLS_SELF_SIGNED_ISSUER}spec:  selfSigned: {}EOF_MANIFEST
kubectl --context "${K8S_CTX}" wait --for=condition=Ready clusterissuer "${MDB_TLS_SELF_SIGNED_ISSUER}"
# Create the CA certificate and secret in the cert-manager namespace.kubectl apply --context "${K8S_CTX}" -f - <<EOF_MANIFESTapiVersion: cert-manager.io/v1kind: Certificatemetadata:  name: ${MDB_TLS_CA_CERT_NAME}  namespace: ${CERT_MANAGER_NAMESPACE}spec:  isCA: true  commonName: ${MDB_TLS_CA_CERT_NAME}  secretName: ${MDB_TLS_CA_SECRET_NAME}  privateKey:    algorithm: ECDSA    size: 256  issuerRef:    name: ${MDB_TLS_SELF_SIGNED_ISSUER}    kind: ClusterIssuerEOF_MANIFEST
kubectl --context "${K8S_CTX}" wait --for=condition=Ready -n "${CERT_MANAGER_NAMESPACE}" certificate "${MDB_TLS_CA_CERT_NAME}"
# Publish a cluster-scoped issuer that fronts the generated CA secret so all namespaces can reuse it.kubectl apply --context "${K8S_CTX}" -f - <<EOF_MANIFESTapiVersion: cert-manager.io/v1kind: ClusterIssuermetadata:  name: ${MDB_TLS_CA_ISSUER}spec:  ca:    secretName: ${MDB_TLS_CA_SECRET_NAME}EOF_MANIFEST
kubectl --context "${K8S_CTX}" wait --for=condition=Ready clusterissuer "${MDB_TLS_CA_ISSUER}"
TMP_CA_CERT="$(mktemp)"
kubectl --context "${K8S_CTX}" \  get secret "${MDB_TLS_CA_SECRET_NAME}" -n "${CERT_MANAGER_NAMESPACE}" \  -o jsonpath="{.data['ca\\.crt']}" | base64 --decode > "${TMP_CA_CERT}"
# Expose the CA bundle through a ConfigMap for workloads and the MongoDBCommunity resource.kubectl --context "${K8S_CTX}" create configmap "${MDB_TLS_CA_CONFIGMAP}" -n "${MDB_NS}" \  --from-file=ca-pem="${TMP_CA_CERT}" --from-file=mms-ca.crt="${TMP_CA_CERT}" \  --from-file=ca.crt="${TMP_CA_CERT}" \  --dry-run=client -o yaml | kubectl --context "${K8S_CTX}" apply -f -
echo "Cluster-wide CA issuer ${MDB_TLS_CA_ISSUER} is ready."
8

Required. Issue TLS certificates.

Issue TLS certificates for both the MongoDB server and the MongoDBSearch service. The MongoDB server certificate includes all necessary DNS names for the pod and service communication. Both certificates support server and client authentication.

server_certificate="${MDB_RESOURCE_NAME}-server-tls"search_certificate="${MDB_RESOURCE_NAME}-search-tls"
mongo_dns_names=()for ((member = 0; member < MDB_MEMBERS; member++)); do  mongo_dns_names+=("${MDB_RESOURCE_NAME}-${member}")  mongo_dns_names+=("${MDB_RESOURCE_NAME}-${member}.${MDB_RESOURCE_NAME}-svc.${MDB_NS}.svc.cluster.local")donemongo_dns_names+=(  "${MDB_RESOURCE_NAME}-svc.${MDB_NS}.svc.cluster.local"  "*.${MDB_RESOURCE_NAME}-svc.${MDB_NS}.svc.cluster.local")
search_dns_names=(  "*.${MDB_RESOURCE_NAME}-search-0-svc.${MDB_NS}.svc.cluster.local")
render_dns_list() {  local dns_list=("$@")  for dns in "${dns_list[@]}"; do    printf "      - \"%s\"\n" "${dns}"  done}
kubectl apply --context "${K8S_CTX}" -n "${MDB_NS}" -f - <<EOF_MANIFESTapiVersion: cert-manager.io/v1kind: Certificatemetadata:  name: ${server_certificate}  namespace: ${MDB_NS}spec:  secretName: ${MDB_TLS_SERVER_CERT_SECRET_NAME}  issuerRef:    name: ${MDB_TLS_CA_ISSUER}    kind: ClusterIssuer  duration: 240h0m0s  renewBefore: 120h0m0s  usages:    - digital signature    - key encipherment    - server auth    - client auth  dnsNames:$(render_dns_list "${mongo_dns_names[@]}")---apiVersion: cert-manager.io/v1kind: Certificatemetadata:  name: ${search_certificate}  namespace: ${MDB_NS}spec:  secretName: ${MDB_SEARCH_TLS_SECRET_NAME}  issuerRef:    name: ${MDB_TLS_CA_ISSUER}    kind: ClusterIssuer  duration: 240h0m0s  renewBefore: 120h0m0s  usages:    - digital signature    - key encipherment    - server auth    - client auth  dnsNames:$(render_dns_list "${search_dns_names[@]}")EOF_MANIFEST
kubectl --context "${K8S_CTX}" -n "${MDB_NS}" wait --for=condition=Ready certificate "${server_certificate}" --timeout=300skubectl --context "${K8S_CTX}" -n "${MDB_NS}" wait --for=condition=Ready certificate "${search_certificate}" --timeout=300s
echo "MongoDB TLS certificates have been issued."
9

Conditional. Create and deploy the MongoDB Community resource.

If you've already deployed the MongoDB Community Edition, skip this step. Otherwise, deploy the MongoDB Community Edition.

To deploy the MongoDB Community Edition, complete the following steps:

  1. Create a MongoDBCommunity custom resource named mdb-rs.

    The resource defines CPU and memory resources for the mongod and mongodb-agent containers, and sets up the following three users:

    mdb-user

    User that can restore database and run search queries. This user uses the mdb-user-password secret to perform these operations.

    search-sync-source

    User that MongoDB Search uses to connect to MongoDB database in order to manage and build indexes. This user uses searchCoordinator role that the Kubernetes operator creates. This uses uses the mdbc-rs-search-sync-source-password secret to connect mongot to mongod.

    admin-user

    Database admin user.

    The Kubernetes Operator uses this resource to configure a MongoDB replica set with 3 members.

    To create the secrets, copy, paste, and run the following commands:

    kubectl apply --context "${K8S_CTX}" -n "${MDB_NS}" -f - <<EOFapiVersion: mongodbcommunity.mongodb.com/v1kind: MongoDBCommunitymetadata:  name: ${MDB_RESOURCE_NAME}spec:  version: ${MDB_VERSION}  type: ReplicaSet  members: ${MDB_MEMBERS}  security:    tls:      enabled: true      certificateKeySecretRef:        name: ${MDB_TLS_SERVER_CERT_SECRET_NAME}      caConfigMapRef:        name: ${MDB_TLS_CA_CONFIGMAP}    authentication:      ignoreUnknownUsers: true      modes:        - SCRAM  agent:    logLevel: DEBUG  statefulSet:    spec:      template:        spec:          containers:            - name: mongod              resources:                limits:                  cpu: "2"                  memory: 2Gi                requests:                  cpu: "1"                  memory: 1Gi            - name: mongodb-agent              resources:                limits:                  cpu: "1"                  memory: 2Gi                requests:                  cpu: "0.5"                  memory: 1Gi  users:    # admin user with root role    - name: mdb-admin      db: admin      # a reference to the secret containing user password      passwordSecretRef:        name: mdb-admin-user-password      scramCredentialsSecretName: mdb-admin-user      roles:        - name: root          db: admin    # user performing search queries    - name: mdb-user      db: admin      # a reference to the secret containing user password      passwordSecretRef:        name: mdb-user-password      scramCredentialsSecretName: mdb-user-scram      roles:        - name: restore          db: sample_mflix        - name: readWrite          db: sample_mflix    # user used by MongoDB Search to connect to MongoDB database to    # synchronize data from.    # For MongoDB <8.2, the operator will be creating the    # searchCoordinator custom role automatically.    # From MongoDB 8.2, searchCoordinator role will be a    # built-in role.    - name: search-sync-source      db: admin      # a reference to the secret that will be used to generate the user's password      passwordSecretRef:        name: ${MDB_RESOURCE_NAME}-search-sync-source-password      scramCredentialsSecretName: ${MDB_RESOURCE_NAME}-search-sync-source      roles:        - name: searchCoordinator          db: adminEOF

  2. Wait for the MongoDBCommunity resource deployment to complete.

    When you apply the MongoDBCommunity custom resource, the Kubernetes operator begins deploying the MongoDB nodes (pods). This step pauses the execution until the mdbc-rs resource's status phase is Running, which indicates that the MongoDB Community replica set is operational.

    echo "Waiting for MongoDBCommunity resource to reach Running phase..."kubectl --context "${K8S_CTX}" -n "${MDB_NS}" wait \  --for=jsonpath='{.status.phase}'=Running mdbc/mdbc-rs --timeout=400secho; echo "MongoDBCommunity resource"kubectl --context "${K8S_CTX}" -n "${MDB_NS}" get mdbc/mdbc-rsecho; echo "Pods running in cluster ${K8S_CTX}"kubectl --context "${K8S_CTX}" -n "${MDB_NS}" get pods
10

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 mdbc-rs.

    This resource specifies the CPU and memory resource requirements for the search nodes. To learn more about the settings in this custom resource, see MongoDB Search and Vector Search Settings.

    # create a Kubernetes secret that would have embedding model's API Keyskubectl create secret generic "${AUTO_EMBEDDING_API_KEY_SECRET_NAME}" \  --from-literal=query-key="${AUTO_EMBEDDING_API_QUERY_KEY}" \  --from-literal=indexing-key="${AUTO_EMBEDDING_API_INDEXING_KEY}" --context "${K8S_CTX}" -n "${MDB_NS}"
# create MongoDBSearch resource, enabling the auto embedding using the API Keys provided abovekubectl apply --context "${K8S_CTX}" -n "${MDB_NS}" -f - <<EOFapiVersion: mongodb.com/v1kind: MongoDBSearchmetadata:  name: ${MDB_RESOURCE_NAME}spec:  security:    tls:      certificateKeySecretRef:        name: ${MDB_SEARCH_TLS_SECRET_NAME}  autoEmbedding:    providerEndpoint: ${PROVIDER_ENDPOINT}    embeddingModelAPIKeySecret:      name: ${AUTO_EMBEDDING_API_KEY_SECRET_NAME}  clusters:    - resourceRequirements:        limits:          cpu: "3"          memory: 5Gi        requests:          cpu: "2"          memory: 3GiEOF

    Note

    Since the Kubernetes Operator only deploys single instance of MongoDB Search, that instance is automatically configured as the embedding materialized View writer.

  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 mdbc-rs MongoDBSearch resource's status phase is Running, which indicates that the MongoDB Search is operational.

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

Optional. Verify the MongoDB Community resource status.

Ensure that the MongoDBCommunity resource deployment with MongoDBSearch was successful.

echo "Waiting for MongoDBCommunity resource to reach Running phase..."kubectl --context "${K8S_CTX}" -n "${MDB_NS}" wait \  --for=jsonpath='{.status.phase}'=Running mdbc/mdbc-rs --timeout=400secho; echo "MongoDBCommunity resource"kubectl --context "${K8S_CTX}" -n "${MDB_NS}" get mdbc/mdbc-rsecho; echo "Pods running in cluster ${K8S_CTX}"kubectl --context "${K8S_CTX}" -n "${MDB_NS}" get pods
12

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.

echo; echo "MongoDBCommunity resource"kubectl --context "${K8S_CTX}" -n "${MDB_NS}" get mdbc/mdbc-rsecho; echo "MongoDBSearch resource"kubectl --context "${K8S_CTX}" -n "${MDB_NS}" get mdbs/mdbc-rsecho; echo "Pods running in cluster ${K8S_CTX}"kubectl --context "${K8S_CTX}" -n "${MDB_NS}" get pods

Verify the Deployment

After the procedure completes, confirm the deployment is healthy before running queries.

Checkpoint
Verification Step

MongoDB Community resource running

Run kubectl get mongodbcommunity -n <your-namespace> and confirm the MongoDBCommunity resource shows the Running phase.

MongoDB Search resource running

Run kubectl get mongodbsearch -n <your-namespace> and confirm the MongoDBSearch resource shows the Running phase.

All pods healthy

Run kubectl get pods -n <your-namespace> and confirm all replica set member pods and search pods show a Running status with all containers ready.

Search queries succeed

Connect to the replica set and run a MongoDB Search or Vector Search query to confirm the search index is reachable.

Next Steps

After you deploy MongoDB Search and Vector Search with MongoDB Community Edition, you can:

Rate this page

On this page