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 Search With MongoDB Enterprise Edition

You can use the Kubernetes Operator to deploy MongoDB Search and Vector Search resources to run with MongoDB enterprise v8.2.0 or higher on a Kubernetes cluster. This procedure demonstrates how to deploy and configure the mongot process 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 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.

  • MongoDB Ops Manager or MongoDB Cloud Manager project and API credentials.

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:

1# set it to the context name of the k8s cluster
2export K8S_CTX="<local cluster context>"
3
4# the following namespace will be created if not exists
5export MDB_NS="mongodb"
6
7# name of the MongoDB Custom Resource.
8export MDB_RESOURCE_NAME="mdb-rs"
9
10export MDB_MEMBERS=3
11# OM/CM's project name to be used to manage mongodb replica set
12export OPS_MANAGER_PROJECT_NAME="<arbitrary project name>"
13
14# URL to Cloud Manager or Ops Manager instance
15export OPS_MANAGER_API_URL="https://cloud-qa.mongodb.com"
16
17# The API key can be an Org Owner - the operator can create the project automatically then.
18# The API key can also be created in a particular project that was created manually with the Project Owner scope.
19export OPS_MANAGER_API_USER="<SET API USER>"
20export OPS_MANAGER_API_KEY="<SET API KEY>"
21export OPS_MANAGER_ORG_ID="<SET ORG ID>"
22
23# minimum required MongoDB version for running MongoDB Search is 8.2.0
24export MDB_VERSION="8.2.0-ent"
25
26# root admin user for convenience, not used here at all in this guide
27export MDB_ADMIN_USER_PASSWORD="admin-user-password-CHANGE-ME"
28# regular user performing restore and search queries on sample mflix database
29export MDB_USER_PASSWORD="mdb-user-password-CHANGE-ME"
30# user for MongoDB Search to connect to the replica set to synchronise data from
31export MDB_SEARCH_SYNC_USER_PASSWORD="search-sync-user-password-CHANGE-ME"
32
33export OPERATOR_HELM_CHART="mongodb/mongodb-kubernetes"
34# comma-separated key=value pairs for additional parameters passed to the helm-chart installing the operator
35export OPERATOR_ADDITIONAL_HELM_VALUES=""
36
37export MDB_TLS_CERT_SECRET_PREFIX="certs"
38export MDB_TLS_CA_CONFIGMAP="${MDB_RESOURCE_NAME}-ca-configmap"
39
40export CERT_MANAGER_NAMESPACE="cert-manager"
41export MDB_TLS_SELF_SIGNED_ISSUER="selfsigned-bootstrap-issuer"
42export MDB_TLS_CA_CERT_NAME="my-selfsigned-ca"
43export MDB_TLS_CA_SECRET_NAME="root-secret"
44export MDB_TLS_CA_ISSUER="my-ca-issuer"
45export MDB_TLS_SERVER_CERT_SECRET_NAME="${MDB_TLS_CERT_SECRET_PREFIX}-${MDB_RESOURCE_NAME}-cert"
46export MDB_SEARCH_TLS_SECRET_NAME="${MDB_RESOURCE_NAME}-search-tls"
47
48export MDB_CONNECTION_STRING="mongodb://mdb-user:${MDB_USER_PASSWORD}@${MDB_RESOURCE_NAME}-svc.${MDB_NS}.svc.cluster.local:27017/?replicaSet=${MDB_RESOURCE_NAME}&tls=true&tlsCAFile=/tls/ca.crt"
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}"
4

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:

1helm upgrade --install \
2  cert-manager \
3  oci://quay.io/jetstack/charts/cert-manager \
4  --kube-context "${K8S_CTX}" \
5  --namespace "${CERT_MANAGER_NAMESPACE}" \
6  --create-namespace \
7  --set crds.enabled=true
8
9for deployment in cert-manager cert-manager-cainjector cert-manager-webhook; do
10  kubectl --context "${K8S_CTX}" \
11    -n "${CERT_MANAGER_NAMESPACE}" \
12    wait --for=condition=Available "deployment/${deployment}" --timeout=300s
13done
14
15echo "cert-manager is ready in namespace ${CERT_MANAGER_NAMESPACE}."
5

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 MongoDB resources can use it.

1# Bootstrap a self-signed ClusterIssuer to mint the CA secret consumed by application workloads.
2kubectl apply --context "${K8S_CTX}" -f - <<EOF_MANIFEST
3apiVersion: cert-manager.io/v1
4kind: ClusterIssuer
5metadata:
6  name: ${MDB_TLS_SELF_SIGNED_ISSUER}
7spec:
8  selfSigned: {}
9EOF_MANIFEST
10
11kubectl --context "${K8S_CTX}" wait --for=condition=Ready clusterissuer "${MDB_TLS_SELF_SIGNED_ISSUER}"
12
13kubectl apply --context "${K8S_CTX}" -f - <<EOF_MANIFEST
14apiVersion: cert-manager.io/v1
15kind: Certificate
16metadata:
17  name: ${MDB_TLS_CA_CERT_NAME}
18  namespace: ${CERT_MANAGER_NAMESPACE}
19spec:
20  isCA: true
21  commonName: ${MDB_TLS_CA_CERT_NAME}
22  secretName: ${MDB_TLS_CA_SECRET_NAME}
23  privateKey:
24    algorithm: ECDSA
25    size: 256
26  issuerRef:
27    name: ${MDB_TLS_SELF_SIGNED_ISSUER}
28    kind: ClusterIssuer
29EOF_MANIFEST
30
31kubectl --context "${K8S_CTX}" wait --for=condition=Ready -n "${CERT_MANAGER_NAMESPACE}" certificate "${MDB_TLS_CA_CERT_NAME}"
32
33kubectl apply --context "${K8S_CTX}" -f - <<EOF_MANIFEST
34apiVersion: cert-manager.io/v1
35kind: ClusterIssuer
36metadata:
37  name: ${MDB_TLS_CA_ISSUER}
38spec:
39  ca:
40    secretName: ${MDB_TLS_CA_SECRET_NAME}
41EOF_MANIFEST
42
43kubectl --context "${K8S_CTX}" wait --for=condition=Ready clusterissuer "${MDB_TLS_CA_ISSUER}"
44
45TMP_CA_CERT="$(mktemp)"
46trap 'rm -f "${TMP_CA_CERT}"' EXIT
47
48kubectl --context "${K8S_CTX}" get secret "${MDB_TLS_CA_SECRET_NAME}" -n "${CERT_MANAGER_NAMESPACE}" -o jsonpath="{.data['ca\\.crt']}" | base64 --decode > "${TMP_CA_CERT}"
49
50kubectl --context "${K8S_CTX}" create configmap "${MDB_TLS_CA_CONFIGMAP}" -n "${MDB_NS}" \
51  --from-file=ca-pem="${TMP_CA_CERT}" --from-file=mms-ca.crt="${TMP_CA_CERT}" \
52  --from-file=ca.crt="${TMP_CA_CERT}" \
53  --dry-run=client -o yaml | kubectl --context "${K8S_CTX}" apply -f -
6

Required. Issue TLS certificates.

Issue TLS certificates for both the MongoDB server (${MDB_RESOURCE_NAME}-server-tls) and the MongoDBSearch service (${MDB_RESOURCE_NAME}-search-tls). The MongoDB server certificate includes all necessary DNS names for the pod and service communication. Both certificates support server and client authentication.

1server_certificate="${MDB_RESOURCE_NAME}-server-tls"
2search_certificate="${MDB_RESOURCE_NAME}-search-tls"
3
4mongo_dns_names=()
5for ((member = 0; member < MDB_MEMBERS; member++)); do
6  mongo_dns_names+=("${MDB_RESOURCE_NAME}-${member}")
7  mongo_dns_names+=("${MDB_RESOURCE_NAME}-${member}.${MDB_RESOURCE_NAME}-svc.${MDB_NS}.svc.cluster.local")
8done
9mongo_dns_names+=(
10  "${MDB_RESOURCE_NAME}-svc.${MDB_NS}.svc.cluster.local"
11  "*.${MDB_RESOURCE_NAME}-svc.${MDB_NS}.svc.cluster.local"
12)
13
14search_dns_names=(
15  "${MDB_RESOURCE_NAME}-search-svc.${MDB_NS}.svc.cluster.local"
16)
17
18render_dns_list() {
19  local dns_list=("$@")
20  for dns in "${dns_list[@]}"; do
21    printf "      - \"%s\"\n" "${dns}"
22  done
23}
24
25kubectl apply --context "${K8S_CTX}" -n "${MDB_NS}" -f - <<EOF_MANIFEST
26apiVersion: cert-manager.io/v1
27kind: Certificate
28metadata:
29  name: ${server_certificate}
30  namespace: ${MDB_NS}
31spec:
32  secretName: ${MDB_TLS_SERVER_CERT_SECRET_NAME}
33  issuerRef:
34    name: ${MDB_TLS_CA_ISSUER}
35    kind: ClusterIssuer
36  duration: 240h0m0s
37  renewBefore: 120h0m0s
38  usages:
39    - digital signature
40    - key encipherment
41    - server auth
42    - client auth
43  dnsNames:
44$(render_dns_list "${mongo_dns_names[@]}")
45---
46apiVersion: cert-manager.io/v1
47kind: Certificate
48metadata:
49  name: ${search_certificate}
50  namespace: ${MDB_NS}
51spec:
52  secretName: ${MDB_SEARCH_TLS_SECRET_NAME}
53  issuerRef:
54    name: ${MDB_TLS_CA_ISSUER}
55    kind: ClusterIssuer
56  duration: 240h0m0s
57  renewBefore: 120h0m0s
58  usages:
59    - digital signature
60    - key encipherment
61    - server auth
62    - client auth
63  dnsNames:
64$(render_dns_list "${search_dns_names[@]}")
65EOF_MANIFEST
66
67kubectl --context "${K8S_CTX}" -n "${MDB_NS}" wait --for=condition=Ready certificate "${server_certificate}" --timeout=300s
68kubectl --context "${K8S_CTX}" -n "${MDB_NS}" wait --for=condition=Ready certificate "${search_certificate}" --timeout=300s
7

Conditional. Create and deploy the MongoDB Enterprise resource.

If you have already deployed MongoDB Enterprise, skip to the next step. Otherwise, deploy the MongoDB Enterprise resource.

To deploy the MongoDB Enterprise, complete the following steps:

  1. Create the ConfigMap and secret for the MongoDB Ops Manager project if you are using MongoDB Ops Manager.

    To store the configuration and credentials for integration with MongoDB Ops Manager, copy, paste, and run the following commands:

    1kubectl --context "${K8S_CTX}" -n "${MDB_NS}" create configmap om-project \
    2  --from-literal=projectName="${OPS_MANAGER_PROJECT_NAME}" --from-literal=baseUrl="${OPS_MANAGER_API_URL}" \
    3  --from-literal=orgId="${OPS_MANAGER_ORG_ID:-}"
    4
    5kubectl --context "${K8S_CTX}" -n "${MDB_NS}" create secret generic om-credentials \
    6  --from-literal=publicKey="${OPS_MANAGER_API_USER}" \
    7  --from-literal=privateKey="${OPS_MANAGER_API_KEY}"

  2. Create a MongoDB custom resource named mdb-rs.

    The resource defines CPU and memory resources for the mongod and mongodb-agent containers and instructs the Kubernetes Operator to configure a MongoDB replica set with 3 members:

    To deploy MongoDB Enterprise, copy, paste, and run the following in the namespace:

    1kubectl apply --context "${K8S_CTX}" -n "${MDB_NS}" -f - <<EOF
    2apiVersion: mongodb.com/v1
    3kind: MongoDB
    4metadata:
    5  name: ${MDB_RESOURCE_NAME}
    6spec:
    7  members: ${MDB_MEMBERS}
    8  version: ${MDB_VERSION}
    9  type: ReplicaSet
    10  opsManager:
    11    configMapRef:
    12      name: om-project
    13  credentials: om-credentials
    14  security:
    15    authentication:
    16      enabled: true
    17      ignoreUnknownUsers: true
    18      modes:
    19      - SCRAM
    20    certsSecretPrefix: ${MDB_TLS_CERT_SECRET_PREFIX}
    21    tls:
    22      enabled: true
    23      ca: ${MDB_TLS_CA_CONFIGMAP}
    24  agent:
    25    logLevel: INFO
    26  podSpec:
    27    podTemplate:
    28      spec:
    29        containers:
    30        - name: mongodb-enterprise-database
    31          resources:
    32            limits:
    33              cpu: "2"
    34              memory: 2Gi
    35            requests:
    36              cpu: "1"
    37              memory: 1Gi
    38EOF

  3. Wait for the MongoDB resource deployment to complete.

    When you apply the MongoDB 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.

    1echo "Waiting for MongoDB resource to reach Running phase..."
    2kubectl --context "${K8S_CTX}" -n "${MDB_NS}" wait --for=jsonpath='{.status.phase}'=Running "mdb/${MDB_RESOURCE_NAME}" --timeout=400s
    3echo; echo "MongoDB resource"
    4kubectl --context "${K8S_CTX}" -n "${MDB_NS}" get "mdb/${MDB_RESOURCE_NAME}"
    5echo; echo "Pods running in cluster ${K8S_CTX}"
    6kubectl --context "${K8S_CTX}" -n "${MDB_NS}" get pods
8

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 mounts these secrets into the MongoDB pods.

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

1# admin user with root role
2kubectl --context "${K8S_CTX}" --namespace "${MDB_NS}" \
3  create secret generic mdb-admin-user-password \
4  --from-literal=password="${MDB_ADMIN_USER_PASSWORD}"
5
6kubectl apply --context "${K8S_CTX}" -n "${MDB_NS}" -f - <<EOF
7apiVersion: mongodb.com/v1
8kind: MongoDBUser
9metadata:
10  name: mdb-admin
11spec:
12  username: mdb-admin
13  db: admin
14  mongodbResourceRef:
15    name: ${MDB_RESOURCE_NAME}
16  passwordSecretKeyRef:
17    name: mdb-admin-user-password
18    key: password
19  roles:
20  - name: root
21    db: admin
22EOF
23
24# user used by MongoDB Search to connect to MongoDB database to synchronize data from
25# For MongoDB <8.2, the operator will be creating the searchCoordinator custom role automatically
26# From MongoDB 8.2, searchCoordinator role will be a built-in role.
27kubectl --context "${K8S_CTX}" --namespace "${MDB_NS}" \
28  create secret generic "${MDB_RESOURCE_NAME}-search-sync-source-password" \
29  --from-literal=password="${MDB_SEARCH_SYNC_USER_PASSWORD}"
30kubectl apply --context "${K8S_CTX}" -n "${MDB_NS}" -f - <<EOF
31apiVersion: mongodb.com/v1
32kind: MongoDBUser
33metadata:
34  name: search-sync-source-user
35spec:
36  username: search-sync-source
37  db: admin
38  mongodbResourceRef:
39    name: ${MDB_RESOURCE_NAME}
40  passwordSecretKeyRef:
41    name: ${MDB_RESOURCE_NAME}-search-sync-source-password
42    key: password
43  roles:
44  - name: searchCoordinator
45    db: admin
46EOF
47
48# user performing search queries
49kubectl --context "${K8S_CTX}" --namespace "${MDB_NS}" \
50  create secret generic mdb-user-password \
51  --from-literal=password="${MDB_USER_PASSWORD}"
52kubectl apply --context "${K8S_CTX}" -n "${MDB_NS}" -f - <<EOF
53apiVersion: mongodb.com/v1
54kind: MongoDBUser
55metadata:
56  name: mdb-user
57spec:
58  username: mdb-user
59  db: admin
60  mongodbResourceRef:
61    name: ${MDB_RESOURCE_NAME}
62  passwordSecretKeyRef:
63    name: mdb-user-password
64    key: password
65  roles:
66  - name: readWrite
67    db: sample_mflix
68EOF
9

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.

    1kubectl apply --context "${K8S_CTX}" -n "${MDB_NS}" -f - <<EOF
    2apiVersion: mongodb.com/v1
    3kind: MongoDBSearch
    4metadata:
    5  name: ${MDB_RESOURCE_NAME}
    6spec:
    7  # no need to specify source.mongodbResourceRef if MongoDBSearch CR has the same name as MongoDB CR
    8  # the operator infer it automatically
    9  security:
    10    tls:
    11      certificateKeySecretRef:
    12        name: ${MDB_SEARCH_TLS_SECRET_NAME}
    13  resourceRequirements:
    14    limits:
    15      cpu: "3"
    16      memory: 5Gi
    17    requests:
    18      cpu: "2"
    19      memory: 3Gi
    20EOF

  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 resource's status phase is Running, which indicates that the MongoDB Community replica set is operational.

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

Optional. Verify the MongoDB Enterprise resource status.

Ensure that the MongoDB resource deployment with MongoDBSearch was successful.

1echo "Waiting for MongoDB resource to reach Running phase..."
2kubectl --context "${K8S_CTX}" -n "${MDB_NS}" wait --for=jsonpath='{.status.phase}'=Running "mdb/${MDB_RESOURCE_NAME}" --timeout=400s
11

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 "MongoDB resource"
2kubectl --context "${K8S_CTX}" -n "${MDB_NS}" get "mdb/${MDB_RESOURCE_NAME}"
3echo; echo "MongoDBSearch resource"
4kubectl --context "${K8S_CTX}" -n "${MDB_NS}" get "mdbs/${MDB_RESOURCE_NAME}"
5echo; echo "Pods running in cluster ${K8S_CTX}"
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 MongoDB Enterprise Edition, you can add data in 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