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 With MongoDB Community Edition

You can use the Kubernetes Operator and deploy the mongot process resources to run with MongoDB Community Edition v8.2.0 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:

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# MongoDBCommunity resource name referenced throughout the guide
8export MDB_RESOURCE_NAME="mdbc-rs"
9# Number of replica set members deployed in the sample MongoDBCommunity
10export MDB_MEMBERS=3
11
12# TLS-related secret names used for MongoDBCommunity and MongoDBSearch
13export MDB_TLS_CA_SECRET_NAME="${MDB_RESOURCE_NAME}-ca"
14export MDB_TLS_SERVER_CERT_SECRET_NAME="${MDB_RESOURCE_NAME}-tls"
15export MDB_SEARCH_TLS_SECRET_NAME="${MDB_RESOURCE_NAME}-search-tls"
16
17export MDB_TLS_CA_CONFIGMAP="${MDB_RESOURCE_NAME}-ca-configmap"
18export MDB_TLS_SELF_SIGNED_ISSUER="${MDB_RESOURCE_NAME}-selfsigned-cluster-issuer"
19export MDB_TLS_CA_CERT_NAME="${MDB_RESOURCE_NAME}-selfsigned-ca"
20export MDB_TLS_CA_ISSUER="${MDB_RESOURCE_NAME}-cluster-issuer"
21
22export MDB_VERSION="8.3.4"
23
24# root admin user for convenience, not used here at all in this guide
25export MDB_ADMIN_USER_PASSWORD="admin-user-password-CHANGE-ME"
26# regular user performing restore and search queries on sample mflix database
27export MDB_USER_PASSWORD="mdb-user-password-CHANGE-ME"
28# user for MongoDB Search to connect to the replica set to synchronise data from
29export MDB_SEARCH_SYNC_USER_PASSWORD="search-sync-user-password-CHANGE-ME"
30
31export OPERATOR_HELM_CHART="mongodb/mongodb-kubernetes"
32# comma-separated key=value pairs for additional parameters passed to the helm-chart installing the operator
33export OPERATOR_ADDITIONAL_HELM_VALUES=""
34
35# TLS is mandatory; connection string must include tls=true
36export 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"
37
38export CERT_MANAGER_NAMESPACE="cert-manager"
39
40# Vector Search auto embedding related configurations
41export AUTO_EMBEDDING_API_KEY_SECRET_NAME="voyage-api-keys"
42export AUTO_EMBEDDING_API_QUERY_KEY="<embedding-model-query-key>"
43export AUTO_EMBEDDING_API_INDEXING_KEY="<embedding-model-indexing-key>"
44export PROVIDER_ENDPOINT="https://ai.mongodb.com/v1/embeddings"
45export 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.

Optional

Validate that the environment variables have been set.

To verify that all necessary environment variables are set, run the following code in your terminal:

1required=(
2  K8S_CTX
3  MDB_NS
4  MDB_RESOURCE_NAME
5  MDB_VERSION
6  MDB_MEMBERS
7  CERT_MANAGER_NAMESPACE
8  MDB_TLS_CA_SECRET_NAME
9  MDB_TLS_SERVER_CERT_SECRET_NAME
10  MDB_SEARCH_TLS_SECRET_NAME
11  MDB_ADMIN_USER_PASSWORD
12  MDB_SEARCH_SYNC_USER_PASSWORD
13  MDB_USER_PASSWORD
14  OPERATOR_HELM_CHART
15)
16
17missing_req=()
18for v in "${required[@]}"; do [[ -n "${!v:-}" ]] || missing_req+=("${v}"); done
19
20if (( ${#missing_req[@]} )); then
21  echo "ERROR: Missing required environment variables:" >&2
22  for m in "${missing_req[@]}"; do echo "  - ${m}" >&2; done
23else
24  echo "All required environment variables present."
25fi
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:

1helm repo add mongodb https://mongodb.github.io/helm-charts
2helm repo update mongodb
3helm search repo mongodb/mongodb-kubernetes
1"mongodb" has been added to your repositories
2Hang tight while we grab the latest from your chart repositories...
3...Successfully got an update from the "mongodb" chart repository
4Update Complete. ⎈Happy Helming!⎈
5NAME                      	CHART VERSION	APP VERSION	DESCRIPTION                                       
6mongodb/mongodb-kubernetes	1.9.0        	           	MongoDB Controllers for Kubernetes translate th...
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:

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}"
1Release "mongodb-kubernetes" does not exist. Installing it now.
2NAME: mongodb-kubernetes
3LAST DEPLOYED: Wed Jul  1 06:32:31 2026
4NAMESPACE: mongodb
5STATUS: deployed
6REVISION: 1
7TEST SUITE: None
8USER-SUPPLIED VALUES:
9{}
10
11COMPUTED VALUES:
12agent:
13  name: mongodb-agent
14  version: 108.0.12.8846-1
15community:
16  agent:
17    name: mongodb-agent
18    version: 108.0.2.8729-1
19  mongodb:
20    imageType: ubi8
21    name: mongodb-community-server
22    repo: quay.io/mongodb
23  registry:
24    agent: quay.io/mongodb
25  resource:
26    members: 3
27    name: mongodb-replica-set
28    tls:
29      caCertificateSecretRef: tls-ca-key-pair
30      certManager:
31        certDuration: 8760h
32        renewCertBefore: 720h
33      certificateKeySecretRef: tls-certificate
34      enabled: false
35      sampleX509User: false
36      useCertManager: true
37      useX509: false
38    version: 4.4.0
39database:
40  name: mongodb-kubernetes-database
41  version: 1.9.0
42initDatabase:
43  name: mongodb-kubernetes-init-database
44  version: 1.9.0
45initOpsManager:
46  name: mongodb-kubernetes-init-ops-manager
47  version: 1.9.0
48managedSecurityContext: false
49mongodb:
50  appdbAssumeOldFormat: false
51  name: mongodb-enterprise-server
52  repo: quay.io/mongodb
53multiCluster:
54  clusterClientTimeout: 10
55  clusters: []
56  kubeConfigSecretName: mongodb-enterprise-operator-multi-cluster-kubeconfig
57  memberClusterRequiredHealthyStreak: 5
58  performFailOver: true
59operator:
60  additionalArguments: []
61  affinity: {}
62  clusterIdentity:
63    clusterName: ""
64  createOperatorServiceAccount: true
65  createResourcesServiceAccountsAndRoles: true
66  enableClusterMongoDBRoles: true
67  enablePVCResize: true
68  env: prod
69  maxConcurrentReconciles: 1
70  mdbDefaultArchitecture: non-static
71  name: mongodb-kubernetes-operator
72  nodeSelector: {}
73  operator_image_name: mongodb-kubernetes
74  podSecurityContext:
75    runAsNonRoot: true
76    runAsUser: 2000
77    seccompProfile:
78      type: RuntimeDefault
79  replicas: 1
80  resources:
81    limits:
82      cpu: 1100m
83      memory: 1Gi
84    requests:
85      cpu: 500m
86      memory: 200Mi
87  securityContext:
88    allowPrivilegeEscalation: false
89    capabilities:
90      drop:
91      - ALL
92  telemetry:
93    collection:
94      clusters: {}
95      deployments: {}
96      frequency: 1h
97      operators: {}
98    send:
99      frequency: 168h
100  tolerations: []
101  vaultSecretBackend:
102    enabled: false
103    tlsSecretRef: ""
104  version: 1.9.0
105  watchedResources:
106  - mongodb
107  - opsmanagers
108  - mongodbusers
109  - mongodbcommunity
110  - mongodbsearch
111  - voyageais
112  webhook:
113    installClusterRole: true
114    name: ""
115    registerConfiguration: true
116opsManager:
117  name: mongodb-enterprise-ops-manager-ubi
118readinessProbe:
119  name: mongodb-kubernetes-readinessprobe
120  version: 1.0.24
121registry:
122  agent: quay.io/mongodb
123  database: quay.io/mongodb
124  imagePullSecrets: null
125  initDatabase: quay.io/mongodb
126  initOpsManager: quay.io/mongodb
127  operator: quay.io/mongodb
128  opsManager: quay.io/mongodb
129  pullPolicy: Always
130  readinessProbe: quay.io/mongodb
131  versionUpgradeHook: quay.io/mongodb
132search:
133  envoyImage: envoyproxy/envoy:v1.37-latest
134  metricsForwarderImage: otel/opentelemetry-collector-contrib:0.152.0
135  name: mongodb-search
136  repo: quay.io/mongodb
137  version: 1.70.1
138versionUpgradeHook:
139  name: mongodb-kubernetes-operator-version-upgrade-post-start-hook
140  version: 1.0.10
141voyageai:
142  repo: quay.io/mongodb/voyageai
143
144HOOKS:
145MANIFEST:
146---
147# Source: mongodb-kubernetes/templates/database-roles.yaml
148apiVersion: v1
149kind: ServiceAccount
150metadata:
151  name: mongodb-kubernetes-appdb
152  namespace: mongodb
153---
154# Source: mongodb-kubernetes/templates/database-roles.yaml
155apiVersion: v1
156kind: ServiceAccount
157metadata:
158  name: mongodb-kubernetes-database-pods
159  namespace: mongodb
160---
161# Source: mongodb-kubernetes/templates/database-roles.yaml
162apiVersion: v1
163kind: ServiceAccount
164metadata:
165  name: mongodb-kubernetes-ops-manager
166  namespace: mongodb
167---
168# Source: mongodb-kubernetes/templates/operator-sa.yaml
169apiVersion: v1
170kind: ServiceAccount
171metadata:
172  name: mongodb-kubernetes-operator
173  namespace: mongodb
174---
175# Source: mongodb-kubernetes/templates/operator-roles-clustermongodbroles.yaml
176kind: ClusterRole
177apiVersion: rbac.authorization.k8s.io/v1
178metadata:
179  name: mongodb-kubernetes-operator-mongodb-cluster-mongodb-role
180rules:
181  - apiGroups:
182      - mongodb.com
183    verbs:
184      - '*'
185    resources:
186      - clustermongodbroles
187---
188# Source: mongodb-kubernetes/templates/operator-roles-telemetry.yaml
189# Additional ClusterRole for clusterVersionDetection
190kind: ClusterRole
191apiVersion: rbac.authorization.k8s.io/v1
192metadata:
193  name: mongodb-kubernetes-operator-cluster-telemetry
194rules:
195  # Non-resource URL permissions
196  - nonResourceURLs:
197      - "/version"
198    verbs:
199      - get
200  # Cluster-scoped resource permissions
201  - apiGroups:
202      - ''
203    resources:
204      - namespaces
205    resourceNames:
206      - kube-system
207    verbs:
208      - get
209  - apiGroups:
210      - ''
211    resources:
212      - nodes
213    verbs:
214      - list
215---
216# Source: mongodb-kubernetes/templates/operator-roles-webhook.yaml
217kind: ClusterRole
218apiVersion: rbac.authorization.k8s.io/v1
219metadata:
220  name: mongodb-kubernetes-operator-mongodb-webhook-cr
221rules:
222  - apiGroups:
223      - "admissionregistration.k8s.io"
224    resources:
225      - validatingwebhookconfigurations
226    verbs:
227      - get
228      - create
229      - update
230      - delete
231  - apiGroups:
232      - ""
233    resources:
234      - services
235    verbs:
236      - get
237      - list
238      - watch
239      - create
240      - update
241      - delete
242---
243# Source: mongodb-kubernetes/templates/operator-roles-clustermongodbroles.yaml
244kind: ClusterRoleBinding
245apiVersion: rbac.authorization.k8s.io/v1
246metadata:
247  name: mongodb-kubernetes-operator-mongodb-cluster-mongodb-role-binding
248roleRef:
249  apiGroup: rbac.authorization.k8s.io
250  kind: ClusterRole
251  name: mongodb-kubernetes-operator-mongodb-cluster-mongodb-role
252subjects:
253  - kind: ServiceAccount
254    name: mongodb-kubernetes-operator
255    namespace: mongodb
256---
257# Source: mongodb-kubernetes/templates/operator-roles-telemetry.yaml
258# ClusterRoleBinding for clusterVersionDetection
259kind: ClusterRoleBinding
260apiVersion: rbac.authorization.k8s.io/v1
261metadata:
262  name: mongodb-kubernetes-operator-mongodb-cluster-telemetry-binding
263roleRef:
264  apiGroup: rbac.authorization.k8s.io
265  kind: ClusterRole
266  name: mongodb-kubernetes-operator-cluster-telemetry
267subjects:
268  - kind: ServiceAccount
269    name: mongodb-kubernetes-operator
270    namespace: mongodb
271---
272# Source: mongodb-kubernetes/templates/operator-roles-webhook.yaml
273kind: ClusterRoleBinding
274apiVersion: rbac.authorization.k8s.io/v1
275metadata:
276  name: mongodb-kubernetes-operator-mongodb-webhook-crb
277roleRef:
278  apiGroup: rbac.authorization.k8s.io
279  kind: ClusterRole
280  name: mongodb-kubernetes-operator-mongodb-webhook-cr
281subjects:
282  - kind: ServiceAccount
283    name: mongodb-kubernetes-operator
284    namespace: mongodb
285---
286# Source: mongodb-kubernetes/templates/database-roles.yaml
287kind: Role
288apiVersion: rbac.authorization.k8s.io/v1
289metadata:
290  name: mongodb-kubernetes-appdb
291  namespace: mongodb
292rules:
293  - apiGroups:
294      - ''
295    resources:
296      - secrets
297    verbs:
298      - get
299  - apiGroups:
300      - ''
301    resources:
302      - pods
303    verbs:
304      - patch
305      - delete
306      - get
307---
308# Source: mongodb-kubernetes/templates/operator-roles-base.yaml
309kind: Role
310apiVersion: rbac.authorization.k8s.io/v1
311metadata:
312  name: mongodb-kubernetes-operator
313  namespace: mongodb
314rules:
315  - apiGroups:
316      - ''
317    resources:
318      - services
319    verbs:
320      - get
321      - list
322      - watch
323      - create
324      - update
325      - delete
326  - apiGroups:
327      - ''
328    resources:
329      - secrets
330      - configmaps
331    verbs:
332      - get
333      - list
334      - create
335      - update
336      - delete
337      - watch
338  - apiGroups:
339      - apps
340    resources:
341      - statefulsets
342      - deployments
343    verbs:
344      - create
345      - get
346      - list
347      - watch
348      - delete
349      - update
350  - apiGroups:
351      - ''
352    resources:
353      - pods
354    verbs:
355      - get
356      - list
357      - watch
358      - delete
359      - deletecollection
360  - apiGroups:
361      - mongodbcommunity.mongodb.com
362    resources:
363      - mongodbcommunity
364      - mongodbcommunity/status
365      - mongodbcommunity/spec
366      - mongodbcommunity/finalizers
367    verbs:
368      - '*'
369  - apiGroups:
370      - mongodb.com
371    verbs:
372      - '*'
373    resources:
374      - mongodb
375      - mongodb/finalizers
376      - mongodbusers
377      - mongodbusers/finalizers
378      - opsmanagers
379      - opsmanagers/finalizers
380      - mongodbmulticluster
381      - mongodbmulticluster/finalizers
382      - mongodbsearch
383      - mongodbsearch/finalizers
384      - mongodb/status
385      - mongodbusers/status
386      - opsmanagers/status
387      - mongodbmulticluster/status
388      - mongodbsearch/status
389  - apiGroups:
390      - ai.mongodb.com
391    verbs:
392      - '*'
393    resources:
394      - voyageais
395      - voyageais/finalizers
396      - voyageais/status
397---
398# Source: mongodb-kubernetes/templates/operator-roles-pvc-resize.yaml
399kind: Role
400apiVersion: rbac.authorization.k8s.io/v1
401metadata:
402  name: mongodb-kubernetes-operator-pvc-resize
403  namespace: mongodb
404rules:
405  - apiGroups:
406      - ''
407    resources:
408      - persistentvolumeclaims
409    verbs:
410      - get
411      - delete
412      - list
413      - watch
414      - patch
415      - update
416---
417# Source: mongodb-kubernetes/templates/database-roles.yaml
418kind: RoleBinding
419apiVersion: rbac.authorization.k8s.io/v1
420metadata:
421  name: mongodb-kubernetes-appdb
422  namespace: mongodb
423roleRef:
424  apiGroup: rbac.authorization.k8s.io
425  kind: Role
426  name: mongodb-kubernetes-appdb
427subjects:
428  - kind: ServiceAccount
429    name: mongodb-kubernetes-appdb
430    namespace: mongodb
431---
432# Source: mongodb-kubernetes/templates/operator-roles-base.yaml
433kind: RoleBinding
434apiVersion: rbac.authorization.k8s.io/v1
435metadata:
436  name: mongodb-kubernetes-operator
437  namespace: mongodb
438roleRef:
439  apiGroup: rbac.authorization.k8s.io
440  kind: Role
441  name: mongodb-kubernetes-operator
442subjects:
443  - kind: ServiceAccount
444    name: mongodb-kubernetes-operator
445    namespace: mongodb
446---
447# Source: mongodb-kubernetes/templates/operator-roles-pvc-resize.yaml
448kind: RoleBinding
449apiVersion: rbac.authorization.k8s.io/v1
450metadata:
451  name: mongodb-kubernetes-operator-pvc-resize-binding
452  namespace: mongodb
453roleRef:
454  apiGroup: rbac.authorization.k8s.io
455  kind: Role
456  name: mongodb-kubernetes-operator-pvc-resize
457subjects:
458  - kind: ServiceAccount
459    name: mongodb-kubernetes-operator
460    namespace: mongodb
461---
462# Source: mongodb-kubernetes/templates/operator.yaml
463apiVersion: apps/v1
464kind: Deployment
465metadata:
466  name: mongodb-kubernetes-operator
467  namespace: mongodb
468spec:
469  replicas: 1
470  selector:
471    matchLabels:
472      app.kubernetes.io/component: controller
473      app.kubernetes.io/name: mongodb-kubernetes-operator
474      app.kubernetes.io/instance: mongodb-kubernetes-operator
475  template:
476    metadata:
477      labels:
478        app.kubernetes.io/component: controller
479        app.kubernetes.io/name: mongodb-kubernetes-operator
480        app.kubernetes.io/instance: mongodb-kubernetes-operator
481      annotations:
482        mongodb.com/installation-method: "helm"
483    spec:
484      serviceAccountName: mongodb-kubernetes-operator
485      securityContext:
486        runAsNonRoot: true
487        runAsUser: 2000
488        seccompProfile:
489          type: RuntimeDefault
490      containers:
491        - name: mongodb-kubernetes-operator
492          image: "quay.io/mongodb/mongodb-kubernetes:1.9.0"
493          imagePullPolicy: Always
494          args:
495            - -watch-resource=mongodb
496            - -watch-resource=opsmanagers
497            - -watch-resource=mongodbusers
498            - -watch-resource=mongodbcommunity
499            - -watch-resource=mongodbsearch
500            - -watch-resource=voyageais
501            - -watch-resource=clustermongodbroles
502          command:
503            - /usr/local/bin/mongodb-kubernetes-operator
504          volumeMounts:
505            - mountPath: /tmp/k8s-webhook-server/serving-certs
506              name: webhook-server-dir
507          resources:
508            limits:
509              cpu: 1100m
510              memory: 1Gi
511            requests:
512              cpu: 500m
513              memory: 200Mi
514          securityContext:
515            allowPrivilegeEscalation: false
516            capabilities:
517              drop:
518              - ALL
519          env:
520            - name: OPERATOR_ENV
521              value: prod
522            - name: MDB_DEFAULT_ARCHITECTURE
523              value: non-static
524            - name: NAMESPACE
525              valueFrom:
526                fieldRef:
527                  fieldPath: metadata.namespace
528            - name: WATCH_NAMESPACE
529              valueFrom:
530                fieldRef:
531                  fieldPath: metadata.namespace
532            - name: MDB_OPERATOR_TELEMETRY_COLLECTION_FREQUENCY
533              value: "1h"
534            - name: MDB_OPERATOR_TELEMETRY_SEND_FREQUENCY
535              value: "168h"
536            - name: CLUSTER_CLIENT_TIMEOUT
537              value: "10"
538            - name: MDB_MEMBER_CLUSTER_REQUIRED_HEALTHY_STREAK
539              value: "5"
540            - name: IMAGE_PULL_POLICY
541              value: Always
542            # Database
543            - name: MONGODB_ENTERPRISE_DATABASE_IMAGE
544              value: quay.io/mongodb/mongodb-kubernetes-database
545            - name: INIT_DATABASE_IMAGE_REPOSITORY
546              value: quay.io/mongodb/mongodb-kubernetes-init-database
547            - name: INIT_DATABASE_VERSION
548              value: "1.9.0"
549            - name: DATABASE_VERSION
550              value: "1.9.0"
551            # Ops Manager
552            - name: OPS_MANAGER_IMAGE_REPOSITORY
553              value: quay.io/mongodb/mongodb-enterprise-ops-manager-ubi
554            - name: INIT_OPS_MANAGER_IMAGE_REPOSITORY
555              value: quay.io/mongodb/mongodb-kubernetes-init-ops-manager
556            - name: INIT_OPS_MANAGER_VERSION
557              value: "1.9.0"
558            - name: OPS_MANAGER_IMAGE_PULL_POLICY
559              value: Always
560            - name: AGENT_IMAGE
561              value: "quay.io/mongodb/mongodb-agent:108.0.12.8846-1"
562            - name: MDB_AGENT_IMAGE_REPOSITORY
563              value: "quay.io/mongodb/mongodb-agent"
564            - name: MONGODB_IMAGE
565              value: mongodb-enterprise-server
566            - name: MONGODB_REPO_URL
567              value: quay.io/mongodb
568            - name: PERFORM_FAILOVER
569              value: 'true'
570            - name: MDB_MAX_CONCURRENT_RECONCILES
571              value: "1"
572            - name: POD_NAME
573              valueFrom:
574                fieldRef:
575                  fieldPath: metadata.name
576            - name: MCK_INSTALLER
577              valueFrom:
578                fieldRef:
579                  fieldPath: metadata.annotations['mongodb.com/installation-method']
580            - name: OPERATOR_NAME
581              value: mongodb-kubernetes-operator
582            # Community Env Vars Start
583            - name: MDB_COMMUNITY_AGENT_IMAGE
584              value: "quay.io/mongodb/mongodb-agent:108.0.2.8729-1"
585            - name: VERSION_UPGRADE_HOOK_IMAGE
586              value: "quay.io/mongodb/mongodb-kubernetes-operator-version-upgrade-post-start-hook:1.0.10"
587            - name: READINESS_PROBE_IMAGE
588              value: "quay.io/mongodb/mongodb-kubernetes-readinessprobe:1.0.24"
589            - name: MDB_COMMUNITY_IMAGE
590              value: "mongodb-community-server"
591            - name: MDB_COMMUNITY_REPO_URL
592              value: "quay.io/mongodb"
593            - name: MDB_COMMUNITY_IMAGE_TYPE
594              value: "ubi8"
595            # Community Env Vars End
596            - name: MDB_SEARCH_REPO_URL
597              value: "quay.io/mongodb"
598            - name: MDB_SEARCH_NAME
599              value: "mongodb-search"
600            - name: MDB_SEARCH_VERSION
601              value: "1.70.1"
602            - name: MDB_ENVOY_IMAGE
603              value: "envoyproxy/envoy:v1.37-latest"
604            - name: MDB_SEARCH_METRICS_FORWARDER_IMAGE
605              value: "otel/opentelemetry-collector-contrib:0.152.0"
606            - name: MDB_VOYAGEAI_REPO_URL
607              value: "quay.io/mongodb/voyageai"
608      volumes:
609        - name: webhook-server-dir
610          emptyDir: {}
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.

1kubectl --context "${K8S_CTX}" -n "${MDB_NS}" rollout status --timeout=2m deployment/mongodb-kubernetes-operator
2echo "Operator deployment in ${MDB_NS} namespace"
3kubectl --context "${K8S_CTX}" -n "${MDB_NS}" get deployments
4echo; echo "Operator pod in ${MDB_NS} namespace"
5kubectl --context "${K8S_CTX}" -n "${MDB_NS}" get pods
1Waiting for deployment "mongodb-kubernetes-operator" rollout to finish: 0 of 1 updated replicas are available...
2deployment "mongodb-kubernetes-operator" successfully rolled out
3Operator deployment in mongodb namespace
4NAME                          READY   UP-TO-DATE   AVAILABLE   AGE
5mongodb-kubernetes-operator   1/1     1            1           3s
6
7Operator pod in mongodb namespace
8NAME                                           READY   STATUS    RESTARTS   AGE
9mongodb-kubernetes-operator-75fffbb5f4-nnrd5   1/1     Running   0          3s
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:

1# Create admin user secret
2kubectl create secret generic mdb-admin-user-password \
3  --from-literal=password="${MDB_ADMIN_USER_PASSWORD}" \
4  --dry-run=client -o yaml | kubectl apply --context "${K8S_CTX}" --namespace "${MDB_NS}" -f -
5
6# Create search sync source user secret
7kubectl create secret generic "${MDB_RESOURCE_NAME}-search-sync-source-password" \
8  --from-literal=password="${MDB_SEARCH_SYNC_USER_PASSWORD}" \
9  --dry-run=client -o yaml | kubectl apply --context "${K8S_CTX}" --namespace "${MDB_NS}" -f -
10
11# Create regular user secret
12kubectl create secret generic mdb-user-password \
13  --from-literal=password="${MDB_USER_PASSWORD}" \
14  --dry-run=client -o yaml | kubectl apply --context "${K8S_CTX}" --namespace "${MDB_NS}" -f -
15
16echo "User secrets created."
1secret/mdb-admin-user-password created
2secret/mdbc-rs-search-sync-source-password created
3secret/mdb-user-password 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:

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}."
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.

1# Bootstrap a self-signed ClusterIssuer that will mint the CA material consumed by
2# the MongoDBCommunity deployment.
3kubectl apply --context "${K8S_CTX}" -f - <<EOF_MANIFEST
4apiVersion: cert-manager.io/v1
5kind: ClusterIssuer
6metadata:
7  name: ${MDB_TLS_SELF_SIGNED_ISSUER}
8spec:
9  selfSigned: {}
10EOF_MANIFEST
11
12kubectl --context "${K8S_CTX}" wait --for=condition=Ready clusterissuer "${MDB_TLS_SELF_SIGNED_ISSUER}"
13
14# Create the CA certificate and secret in the cert-manager namespace.
15kubectl apply --context "${K8S_CTX}" -f - <<EOF_MANIFEST
16apiVersion: cert-manager.io/v1
17kind: Certificate
18metadata:
19  name: ${MDB_TLS_CA_CERT_NAME}
20  namespace: ${CERT_MANAGER_NAMESPACE}
21spec:
22  isCA: true
23  commonName: ${MDB_TLS_CA_CERT_NAME}
24  secretName: ${MDB_TLS_CA_SECRET_NAME}
25  privateKey:
26    algorithm: ECDSA
27    size: 256
28  issuerRef:
29    name: ${MDB_TLS_SELF_SIGNED_ISSUER}
30    kind: ClusterIssuer
31EOF_MANIFEST
32
33kubectl --context "${K8S_CTX}" wait --for=condition=Ready -n "${CERT_MANAGER_NAMESPACE}" certificate "${MDB_TLS_CA_CERT_NAME}"
34
35# Publish a cluster-scoped issuer that fronts the generated CA secret so all namespaces can reuse it.
36kubectl apply --context "${K8S_CTX}" -f - <<EOF_MANIFEST
37apiVersion: cert-manager.io/v1
38kind: ClusterIssuer
39metadata:
40  name: ${MDB_TLS_CA_ISSUER}
41spec:
42  ca:
43    secretName: ${MDB_TLS_CA_SECRET_NAME}
44EOF_MANIFEST
45
46kubectl --context "${K8S_CTX}" wait --for=condition=Ready clusterissuer "${MDB_TLS_CA_ISSUER}"
47
48TMP_CA_CERT="$(mktemp)"
49
50kubectl --context "${K8S_CTX}" \
51  get secret "${MDB_TLS_CA_SECRET_NAME}" -n "${CERT_MANAGER_NAMESPACE}" \
52  -o jsonpath="{.data['ca\\.crt']}" | base64 --decode > "${TMP_CA_CERT}"
53
54# Expose the CA bundle through a ConfigMap for workloads and the MongoDBCommunity resource.
55kubectl --context "${K8S_CTX}" create configmap "${MDB_TLS_CA_CONFIGMAP}" -n "${MDB_NS}" \
56  --from-file=ca-pem="${TMP_CA_CERT}" --from-file=mms-ca.crt="${TMP_CA_CERT}" \
57  --from-file=ca.crt="${TMP_CA_CERT}" \
58  --dry-run=client -o yaml | kubectl --context "${K8S_CTX}" apply -f -
59
60echo "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.

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-0-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
69
70echo "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:

    1kubectl apply --context "${K8S_CTX}" -n "${MDB_NS}" -f - <<EOF
    2apiVersion: mongodbcommunity.mongodb.com/v1
    3kind: MongoDBCommunity
    4metadata:
    5  name: ${MDB_RESOURCE_NAME}
    6spec:
    7  version: ${MDB_VERSION}
    8  type: ReplicaSet
    9  members: ${MDB_MEMBERS}
    10  security:
    11    tls:
    12      enabled: true
    13      certificateKeySecretRef:
    14        name: ${MDB_TLS_SERVER_CERT_SECRET_NAME}
    15      caConfigMapRef:
    16        name: ${MDB_TLS_CA_CONFIGMAP}
    17    authentication:
    18      ignoreUnknownUsers: true
    19      modes:
    20        - SCRAM
    21  agent:
    22    logLevel: DEBUG
    23  statefulSet:
    24    spec:
    25      template:
    26        spec:
    27          containers:
    28            - name: mongod
    29              resources:
    30                limits:
    31                  cpu: "2"
    32                  memory: 2Gi
    33                requests:
    34                  cpu: "1"
    35                  memory: 1Gi
    36            - name: mongodb-agent
    37              resources:
    38                limits:
    39                  cpu: "1"
    40                  memory: 2Gi
    41                requests:
    42                  cpu: "0.5"
    43                  memory: 1Gi
    44  users:
    45    # admin user with root role
    46    - name: mdb-admin
    47      db: admin
    48      # a reference to the secret containing user password
    49      passwordSecretRef:
    50        name: mdb-admin-user-password
    51      scramCredentialsSecretName: mdb-admin-user
    52      roles:
    53        - name: root
    54          db: admin
    55    # user performing search queries
    56    - name: mdb-user
    57      db: admin
    58      # a reference to the secret containing user password
    59      passwordSecretRef:
    60        name: mdb-user-password
    61      scramCredentialsSecretName: mdb-user-scram
    62      roles:
    63        - name: restore
    64          db: sample_mflix
    65        - name: readWrite
    66          db: sample_mflix
    67    # user used by MongoDB Search to connect to MongoDB database to
    68    # synchronize data from.
    69    # For MongoDB <8.2, the operator will be creating the
    70    # searchCoordinator custom role automatically.
    71    # From MongoDB 8.2, searchCoordinator role will be a
    72    # built-in role.
    73    - name: search-sync-source
    74      db: admin
    75      # a reference to the secret that will be used to generate the user's password
    76      passwordSecretRef:
    77        name: ${MDB_RESOURCE_NAME}-search-sync-source-password
    78      scramCredentialsSecretName: ${MDB_RESOURCE_NAME}-search-sync-source
    79      roles:
    80        - name: searchCoordinator
    81          db: admin
    82EOF

  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.

    1echo "Waiting for MongoDBCommunity resource to reach Running phase..."
    2kubectl --context "${K8S_CTX}" -n "${MDB_NS}" wait \
    3  --for=jsonpath='{.status.phase}'=Running mdbc/mdbc-rs --timeout=400s
    4echo; echo "MongoDBCommunity resource"
    5kubectl --context "${K8S_CTX}" -n "${MDB_NS}" get mdbc/mdbc-rs
    6echo; echo "Pods running in cluster ${K8S_CTX}"
    7kubectl --context "${K8S_CTX}" -n "${MDB_NS}" get pods
    1Waiting for MongoDBCommunity resource to reach Running phase...
    2mongodbcommunity.mongodbcommunity.mongodb.com/mdbc-rs condition met
    3
    4MongoDBCommunity resource
    5NAME      PHASE     VERSION
    6mdbc-rs   Running   8.2
    7
    8Pods running in cluster minikube
    9NAME                                           READY   STATUS    RESTARTS   AGE
    10mdbc-rs-0                                      2/2     Running   0          2m30s
    11mdbc-rs-1                                      2/2     Running   0          82s
    12mdbc-rs-2                                      2/2     Running   0          38s
    13mongodb-kubernetes-operator-5776c8b4df-cppnf   1/1     Running   0          7m37s
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.

    1# create a Kubernetes secret that would have embedding model's API Keys
    2kubectl create secret generic "${AUTO_EMBEDDING_API_KEY_SECRET_NAME}" \
    3  --from-literal=query-key="${AUTO_EMBEDDING_API_QUERY_KEY}" \
    4  --from-literal=indexing-key="${AUTO_EMBEDDING_API_INDEXING_KEY}" --context "${K8S_CTX}" -n "${MDB_NS}"
    5
    6# create MongoDBSearch resource, enabling the auto embedding using the API Keys provided above
    7kubectl apply --context "${K8S_CTX}" -n "${MDB_NS}" -f - <<EOF
    8apiVersion: mongodb.com/v1
    9kind: MongoDBSearch
    10metadata:
    11  name: ${MDB_RESOURCE_NAME}
    12spec:
    13  security:
    14    tls:
    15      certificateKeySecretRef:
    16        name: ${MDB_SEARCH_TLS_SECRET_NAME}
    17  autoEmbedding:
    18    providerEndpoint: ${PROVIDER_ENDPOINT}
    19    embeddingModelAPIKeySecret:
    20      name: ${AUTO_EMBEDDING_API_KEY_SECRET_NAME}
    21  clusters:
    22    - resourceRequirements:
    23        limits:
    24          cpu: "3"
    25          memory: 5Gi
    26        requests:
    27          cpu: "2"
    28          memory: 3Gi
    29EOF

    Note

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

    1kubectl apply --context "${K8S_CTX}" -n "${MDB_NS}" -f - <<EOF
    2apiVersion: mongodb.com/v1
    3kind: MongoDBSearch
    4metadata:
    5  name: ${MDB_RESOURCE_NAME}
    6spec:
    7  security:
    8    tls:
    9      certificateKeySecretRef:
    10        name: ${MDB_SEARCH_TLS_SECRET_NAME}
    11  clusters:
    12    - resourceRequirements:
    13        limits:
    14          cpu: "3"
    15          memory: 5Gi
    16        requests:
    17          cpu: "2"
    18          memory: 3Gi
    19EOF

  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.

    1echo "Waiting for MongoDBSearch resource to reach Running phase..."
    2kubectl --context "${K8S_CTX}" -n "${MDB_NS}" wait \
    3  --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.

1echo "Waiting for MongoDBCommunity resource to reach Running phase..."
2kubectl --context "${K8S_CTX}" -n "${MDB_NS}" wait \
3  --for=jsonpath='{.status.phase}'=Running mdbc/mdbc-rs --timeout=400s
4echo; echo "MongoDBCommunity resource"
5kubectl --context "${K8S_CTX}" -n "${MDB_NS}" get mdbc/mdbc-rs
6echo; echo "Pods running in cluster ${K8S_CTX}"
7kubectl --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.

1echo; echo "MongoDBCommunity resource"
2kubectl --context "${K8S_CTX}" -n "${MDB_NS}" get mdbc/mdbc-rs
3echo; echo "MongoDBSearch resource"
4kubectl --context "${K8S_CTX}" -n "${MDB_NS}" get mdbs/mdbc-rs
5echo; echo "Pods running in cluster ${K8S_CTX}"
6kubectl --context "${K8S_CTX}" -n "${MDB_NS}" get pods
1MongoDBCommunity resource
2NAME      PHASE     VERSION
3mdbc-rs   Running   8.3.4
4
5MongoDBSearch resource
6NAME      PHASE     VERSION   LOADBALANCER   METRICSFORWARDER   AGE
7mdbc-rs   Running   1.70.1                   Running            5m2s
8
9Pods running in cluster kind-kind
10NAME                                           READY   STATUS    RESTARTS       AGE
11mdbc-rs-0                                      2/2     Running   1 (34s ago)    7m32s
12mdbc-rs-1                                      2/2     Running   1 (3m9s ago)   6m30s
13mdbc-rs-2                                      2/2     Running   1 (111s ago)   5m44s
14mdbc-rs-search-0-0                             1/1     Running   0              4m20s
15mongodb-kubernetes-operator-75fffbb5f4-nnrd5   1/1     Running   0              7m52s

Next Steps

Now that you've successfully deployed MongoDB Search and Vector Search to use with MongoDB Community Edition, proceed to add data into your MongoDB cluster, create MongoDB Search and Vector Search indexes, and run queries agaist your data. To learn more, see Use MongoDB Search and Vector Search.

On this page