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.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:

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.12.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: Tue Sep  8 14:51:05 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.26.9062-1
15community:
16  agent:
17    name: mongodb-agent
18    version: 108.0.26.9062-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.12.0
42initDatabase:
43  name: mongodb-kubernetes-init-database
44  version: 1.12.0
45initOpsManager:
46  name: mongodb-kubernetes-init-ops-manager
47  version: 1.12.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.12.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      - batch
352    resources:
353      - jobs
354    verbs:
355      - create
356      - get
357      - list
358      - watch
359      - delete
360  - apiGroups:
361      - ''
362    resources:
363      - pods
364    verbs:
365      - get
366      - list
367      - watch
368      - delete
369      - deletecollection
370  - apiGroups:
371      - mongodbcommunity.mongodb.com
372    resources:
373      - mongodbcommunity
374      - mongodbcommunity/status
375      - mongodbcommunity/spec
376      - mongodbcommunity/finalizers
377    verbs:
378      - '*'
379  - apiGroups:
380      - mongodb.com
381    verbs:
382      - '*'
383    resources:
384      - mongodb
385      - mongodb/finalizers
386      - mongodbusers
387      - mongodbusers/finalizers
388      - opsmanagers
389      - opsmanagers/finalizers
390      - mongodbmulticluster
391      - mongodbmulticluster/finalizers
392      - mongodbsearch
393      - mongodbsearch/finalizers
394      - mongodb/status
395      - mongodbusers/status
396      - opsmanagers/status
397      - mongodbmulticluster/status
398      - mongodbsearch/status
399  - apiGroups:
400      - ai.mongodb.com
401    verbs:
402      - '*'
403    resources:
404      - voyageais
405      - voyageais/finalizers
406      - voyageais/status
407---
408# Source: mongodb-kubernetes/templates/operator-roles-pvc-resize.yaml
409kind: Role
410apiVersion: rbac.authorization.k8s.io/v1
411metadata:
412  name: mongodb-kubernetes-operator-pvc-resize
413  namespace: mongodb
414rules:
415  - apiGroups:
416      - ''
417    resources:
418      - persistentvolumeclaims
419    verbs:
420      - get
421      - delete
422      - list
423      - watch
424      - patch
425      - update
426---
427# Source: mongodb-kubernetes/templates/database-roles.yaml
428kind: RoleBinding
429apiVersion: rbac.authorization.k8s.io/v1
430metadata:
431  name: mongodb-kubernetes-appdb
432  namespace: mongodb
433roleRef:
434  apiGroup: rbac.authorization.k8s.io
435  kind: Role
436  name: mongodb-kubernetes-appdb
437subjects:
438  - kind: ServiceAccount
439    name: mongodb-kubernetes-appdb
440    namespace: mongodb
441---
442# Source: mongodb-kubernetes/templates/operator-roles-base.yaml
443kind: RoleBinding
444apiVersion: rbac.authorization.k8s.io/v1
445metadata:
446  name: mongodb-kubernetes-operator
447  namespace: mongodb
448roleRef:
449  apiGroup: rbac.authorization.k8s.io
450  kind: Role
451  name: mongodb-kubernetes-operator
452subjects:
453  - kind: ServiceAccount
454    name: mongodb-kubernetes-operator
455    namespace: mongodb
456---
457# Source: mongodb-kubernetes/templates/operator-roles-pvc-resize.yaml
458kind: RoleBinding
459apiVersion: rbac.authorization.k8s.io/v1
460metadata:
461  name: mongodb-kubernetes-operator-pvc-resize-binding
462  namespace: mongodb
463roleRef:
464  apiGroup: rbac.authorization.k8s.io
465  kind: Role
466  name: mongodb-kubernetes-operator-pvc-resize
467subjects:
468  - kind: ServiceAccount
469    name: mongodb-kubernetes-operator
470    namespace: mongodb
471---
472# Source: mongodb-kubernetes/templates/operator.yaml
473apiVersion: apps/v1
474kind: Deployment
475metadata:
476  name: mongodb-kubernetes-operator
477  namespace: mongodb
478spec:
479  replicas: 1
480  selector:
481    matchLabels:
482      app.kubernetes.io/component: controller
483      app.kubernetes.io/name: mongodb-kubernetes-operator
484      app.kubernetes.io/instance: mongodb-kubernetes-operator
485  template:
486    metadata:
487      labels:
488        app.kubernetes.io/component: controller
489        app.kubernetes.io/name: mongodb-kubernetes-operator
490        app.kubernetes.io/instance: mongodb-kubernetes-operator
491      annotations:
492        mongodb.com/installation-method: "helm"
493    spec:
494      serviceAccountName: mongodb-kubernetes-operator
495      securityContext:
496        runAsNonRoot: true
497        runAsUser: 2000
498        seccompProfile:
499          type: RuntimeDefault
500      containers:
501        - name: mongodb-kubernetes-operator
502          image: "quay.io/mongodb/mongodb-kubernetes:1.12.0"
503          imagePullPolicy: Always
504          args:
505            - -watch-resource=mongodb
506            - -watch-resource=opsmanagers
507            - -watch-resource=mongodbusers
508            - -watch-resource=mongodbcommunity
509            - -watch-resource=mongodbsearch
510            - -watch-resource=voyageais
511            - -watch-resource=clustermongodbroles
512          command:
513            - /usr/local/bin/mongodb-kubernetes-operator
514          volumeMounts:
515            - mountPath: /tmp/k8s-webhook-server/serving-certs
516              name: webhook-server-dir
517          resources:
518            limits:
519              cpu: 1100m
520              memory: 1Gi
521            requests:
522              cpu: 500m
523              memory: 200Mi
524          securityContext:
525            allowPrivilegeEscalation: false
526            capabilities:
527              drop:
528              - ALL
529          env:
530            - name: OPERATOR_ENV
531              value: prod
532            - name: MDB_DEFAULT_ARCHITECTURE
533              value: non-static
534            - name: NAMESPACE
535              valueFrom:
536                fieldRef:
537                  fieldPath: metadata.namespace
538            # Migration dry-run job image.
539            # Optional: it can be resolved from the API server.
540            - name: MDB_OPERATOR_IMAGE
541              value: "quay.io/mongodb/mongodb-kubernetes:1.12.0"
542            - name: WATCH_NAMESPACE
543              valueFrom:
544                fieldRef:
545                  fieldPath: metadata.namespace
546            - name: MDB_OPERATOR_TELEMETRY_COLLECTION_FREQUENCY
547              value: "1h"
548            - name: MDB_OPERATOR_TELEMETRY_SEND_FREQUENCY
549              value: "168h"
550            - name: CLUSTER_CLIENT_TIMEOUT
551              value: "10"
552            - name: MDB_MEMBER_CLUSTER_REQUIRED_HEALTHY_STREAK
553              value: "5"
554            - name: IMAGE_PULL_POLICY
555              value: Always
556            # Database
557            - name: MONGODB_ENTERPRISE_DATABASE_IMAGE
558              value: quay.io/mongodb/mongodb-kubernetes-database
559            - name: INIT_DATABASE_IMAGE_REPOSITORY
560              value: quay.io/mongodb/mongodb-kubernetes-init-database
561            - name: INIT_DATABASE_VERSION
562              value: "1.12.0"
563            - name: DATABASE_VERSION
564              value: "1.12.0"
565            # Ops Manager
566            - name: OPS_MANAGER_IMAGE_REPOSITORY
567              value: quay.io/mongodb/mongodb-enterprise-ops-manager-ubi
568            - name: INIT_OPS_MANAGER_IMAGE_REPOSITORY
569              value: quay.io/mongodb/mongodb-kubernetes-init-ops-manager
570            - name: INIT_OPS_MANAGER_VERSION
571              value: "1.12.0"
572            - name: OPS_MANAGER_IMAGE_PULL_POLICY
573              value: Always
574            - name: AGENT_IMAGE
575              value: "quay.io/mongodb/mongodb-agent:108.0.26.9062-1"
576            - name: MDB_AGENT_IMAGE_REPOSITORY
577              value: "quay.io/mongodb/mongodb-agent"
578            - name: MONGODB_IMAGE
579              value: mongodb-enterprise-server
580            - name: MONGODB_REPO_URL
581              value: quay.io/mongodb
582            - name: PERFORM_FAILOVER
583              value: 'true'
584            - name: MDB_MAX_CONCURRENT_RECONCILES
585              value: "1"
586            - name: POD_NAME
587              valueFrom:
588                fieldRef:
589                  fieldPath: metadata.name
590            - name: MCK_INSTALLER
591              valueFrom:
592                fieldRef:
593                  fieldPath: metadata.annotations['mongodb.com/installation-method']
594            - name: OPERATOR_NAME
595              value: mongodb-kubernetes-operator
596            # Community Env Vars Start
597            - name: MDB_COMMUNITY_AGENT_IMAGE
598              value: "quay.io/mongodb/mongodb-agent:108.0.26.9062-1"
599            - name: VERSION_UPGRADE_HOOK_IMAGE
600              value: "quay.io/mongodb/mongodb-kubernetes-operator-version-upgrade-post-start-hook:1.0.10"
601            - name: READINESS_PROBE_IMAGE
602              value: "quay.io/mongodb/mongodb-kubernetes-readinessprobe:1.0.24"
603            - name: MDB_COMMUNITY_IMAGE
604              value: "mongodb-community-server"
605            - name: MDB_COMMUNITY_REPO_URL
606              value: "quay.io/mongodb"
607            - name: MDB_COMMUNITY_IMAGE_TYPE
608              value: "ubi8"
609            # Community Env Vars End
610            - name: MDB_SEARCH_REPO_URL
611              value: "quay.io/mongodb"
612            - name: MDB_SEARCH_NAME
613              value: "mongodb-search"
614            - name: MDB_SEARCH_VERSION
615              value: "1.70.1"
616            - name: MDB_ENVOY_IMAGE
617              value: "envoyproxy/envoy:v1.37-latest"
618            - name: MDB_SEARCH_METRICS_FORWARDER_IMAGE
619              value: "otel/opentelemetry-collector-contrib:0.152.0"
620            - name: MDB_VOYAGEAI_REPO_URL
621              value: "quay.io/mongodb/voyageai"
622      volumes:
623        - name: webhook-server-dir
624          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-6985844cb9-bm7wn   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.3
    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            5m12s
8
9Pods running in cluster kind-kind
10NAME                                           READY   STATUS    RESTARTS        AGE
11mdbc-rs-0                                      2/2     Running   1 (24s ago)     7m32s
12mdbc-rs-1                                      2/2     Running   1 (2m58s ago)   6m32s
13mdbc-rs-2                                      2/2     Running   1 (101s ago)    5m43s
14mdbc-rs-search-0-0                             1/1     Running   0               4m32s
15mongodb-kubernetes-operator-6985844cb9-bm7wn   1/1     Running   0               7m54s

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