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 higher on a Kubernetes cluster. The mongot process supports both MongoDB Search search Vector Search. 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 higher for running the commands in this tutorial.

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
22# minimum required MongoDB version for running MongoDB Search is 8.2.0
23export MDB_VERSION="8.2.0"
24
25# root admin user for convenience, not used here at all in this guide
26export MDB_ADMIN_USER_PASSWORD="admin-user-password-CHANGE-ME"
27# regular user performing restore and search queries on sample mflix database
28export MDB_USER_PASSWORD="mdb-user-password-CHANGE-ME"
29# user for MongoDB Search to connect to the replica set to synchronise data from
30export MDB_SEARCH_SYNC_USER_PASSWORD="search-sync-user-password-CHANGE-ME"
31
32export OPERATOR_HELM_CHART="mongodb/mongodb-kubernetes"
33# comma-separated key=value pairs for additional parameters passed to the helm-chart installing the operator
34export OPERATOR_ADDITIONAL_HELM_VALUES=""
35
36# TLS is mandatory; connection string must include tls=true
37export 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"
38
39export CERT_MANAGER_NAMESPACE="cert-manager"
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.6.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: Mon Nov 17 13:22:31 2025
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.6.0
42initAppDb:
43 name: mongodb-kubernetes-init-appdb
44 version: 1.6.0
45initDatabase:
46 name: mongodb-kubernetes-init-database
47 version: 1.6.0
48initOpsManager:
49 name: mongodb-kubernetes-init-ops-manager
50 version: 1.6.0
51managedSecurityContext: false
52mongodb:
53 appdbAssumeOldFormat: false
54 imageType: ubi8
55 name: mongodb-enterprise-server
56 repo: quay.io/mongodb
57multiCluster:
58 clusterClientTimeout: 10
59 clusters: []
60 kubeConfigSecretName: mongodb-enterprise-operator-multi-cluster-kubeconfig
61 performFailOver: true
62operator:
63 additionalArguments: []
64 affinity: {}
65 baseName: mongodb-kubernetes
66 createOperatorServiceAccount: true
67 createResourcesServiceAccountsAndRoles: true
68 deployment_name: mongodb-kubernetes-operator
69 enableClusterMongoDBRoles: true
70 enablePVCResize: true
71 env: prod
72 maxConcurrentReconciles: 1
73 mdbDefaultArchitecture: non-static
74 name: mongodb-kubernetes-operator
75 nodeSelector: {}
76 operator_image_name: mongodb-kubernetes
77 podSecurityContext:
78 runAsNonRoot: true
79 runAsUser: 2000
80 replicas: 1
81 resources:
82 limits:
83 cpu: 1100m
84 memory: 1Gi
85 requests:
86 cpu: 500m
87 memory: 200Mi
88 securityContext: {}
89 telemetry:
90 collection:
91 clusters: {}
92 deployments: {}
93 frequency: 1h
94 operators: {}
95 send:
96 frequency: 168h
97 tolerations: []
98 vaultSecretBackend:
99 enabled: false
100 tlsSecretRef: ""
101 version: 1.6.0
102 watchedResources:
103 - mongodb
104 - opsmanagers
105 - mongodbusers
106 - mongodbcommunity
107 - mongodbsearch
108 webhook:
109 installClusterRole: true
110 registerConfiguration: true
111opsManager:
112 name: mongodb-enterprise-ops-manager-ubi
113readinessProbe:
114 name: mongodb-kubernetes-readinessprobe
115 version: 1.0.23
116registry:
117 agent: quay.io/mongodb
118 database: quay.io/mongodb
119 imagePullSecrets: null
120 initAppDb: quay.io/mongodb
121 initDatabase: quay.io/mongodb
122 initOpsManager: quay.io/mongodb
123 operator: quay.io/mongodb
124 opsManager: quay.io/mongodb
125 pullPolicy: Always
126 readinessProbe: quay.io/mongodb
127 versionUpgradeHook: quay.io/mongodb
128search:
129 name: mongodb-search
130 repo: quay.io/mongodb
131 version: 0.55.0
132versionUpgradeHook:
133 name: mongodb-kubernetes-operator-version-upgrade-post-start-hook
134 version: 1.0.10
135
136HOOKS:
137MANIFEST:
138---
139# Source: mongodb-kubernetes/templates/database-roles.yaml
140apiVersion: v1
141kind: ServiceAccount
142metadata:
143 name: mongodb-kubernetes-appdb
144 namespace: mongodb
145---
146# Source: mongodb-kubernetes/templates/database-roles.yaml
147apiVersion: v1
148kind: ServiceAccount
149metadata:
150 name: mongodb-kubernetes-database-pods
151 namespace: mongodb
152---
153# Source: mongodb-kubernetes/templates/database-roles.yaml
154apiVersion: v1
155kind: ServiceAccount
156metadata:
157 name: mongodb-kubernetes-ops-manager
158 namespace: mongodb
159---
160# Source: mongodb-kubernetes/templates/operator-sa.yaml
161apiVersion: v1
162kind: ServiceAccount
163metadata:
164 name: mongodb-kubernetes-operator
165 namespace: mongodb
166---
167# Source: mongodb-kubernetes/templates/operator-roles-clustermongodbroles.yaml
168kind: ClusterRole
169apiVersion: rbac.authorization.k8s.io/v1
170metadata:
171 name: mongodb-kubernetes-operator-mongodb-cluster-mongodb-role
172rules:
173 - apiGroups:
174 - mongodb.com
175 verbs:
176 - '*'
177 resources:
178 - clustermongodbroles
179---
180# Source: mongodb-kubernetes/templates/operator-roles-telemetry.yaml
181# Additional ClusterRole for clusterVersionDetection
182kind: ClusterRole
183apiVersion: rbac.authorization.k8s.io/v1
184metadata:
185 name: mongodb-kubernetes-operator-cluster-telemetry
186rules:
187 # Non-resource URL permissions
188 - nonResourceURLs:
189 - "/version"
190 verbs:
191 - get
192 # Cluster-scoped resource permissions
193 - apiGroups:
194 - ''
195 resources:
196 - namespaces
197 resourceNames:
198 - kube-system
199 verbs:
200 - get
201 - apiGroups:
202 - ''
203 resources:
204 - nodes
205 verbs:
206 - list
207---
208# Source: mongodb-kubernetes/templates/operator-roles-webhook.yaml
209kind: ClusterRole
210apiVersion: rbac.authorization.k8s.io/v1
211metadata:
212 name: mongodb-kubernetes-operator-mongodb-webhook-cr
213rules:
214 - apiGroups:
215 - "admissionregistration.k8s.io"
216 resources:
217 - validatingwebhookconfigurations
218 verbs:
219 - get
220 - create
221 - update
222 - delete
223 - apiGroups:
224 - ""
225 resources:
226 - services
227 verbs:
228 - get
229 - list
230 - watch
231 - create
232 - update
233 - delete
234---
235# Source: mongodb-kubernetes/templates/operator-roles-clustermongodbroles.yaml
236kind: ClusterRoleBinding
237apiVersion: rbac.authorization.k8s.io/v1
238metadata:
239 name: mongodb-kubernetes-operator-mongodb-cluster-mongodb-role-binding
240roleRef:
241 apiGroup: rbac.authorization.k8s.io
242 kind: ClusterRole
243 name: mongodb-kubernetes-operator-mongodb-cluster-mongodb-role
244subjects:
245 - kind: ServiceAccount
246 name: mongodb-kubernetes-operator
247 namespace: mongodb
248---
249# Source: mongodb-kubernetes/templates/operator-roles-telemetry.yaml
250# ClusterRoleBinding for clusterVersionDetection
251kind: ClusterRoleBinding
252apiVersion: rbac.authorization.k8s.io/v1
253metadata:
254 name: mongodb-kubernetes-operator-mongodb-cluster-telemetry-binding
255roleRef:
256 apiGroup: rbac.authorization.k8s.io
257 kind: ClusterRole
258 name: mongodb-kubernetes-operator-cluster-telemetry
259subjects:
260 - kind: ServiceAccount
261 name: mongodb-kubernetes-operator
262 namespace: mongodb
263---
264# Source: mongodb-kubernetes/templates/operator-roles-webhook.yaml
265kind: ClusterRoleBinding
266apiVersion: rbac.authorization.k8s.io/v1
267metadata:
268 name: mongodb-kubernetes-operator-mongodb-webhook-crb
269roleRef:
270 apiGroup: rbac.authorization.k8s.io
271 kind: ClusterRole
272 name: mongodb-kubernetes-operator-mongodb-webhook-cr
273subjects:
274 - kind: ServiceAccount
275 name: mongodb-kubernetes-operator
276 namespace: mongodb
277---
278# Source: mongodb-kubernetes/templates/database-roles.yaml
279kind: Role
280apiVersion: rbac.authorization.k8s.io/v1
281metadata:
282 name: mongodb-kubernetes-appdb
283 namespace: mongodb
284rules:
285 - apiGroups:
286 - ''
287 resources:
288 - secrets
289 verbs:
290 - get
291 - apiGroups:
292 - ''
293 resources:
294 - pods
295 verbs:
296 - patch
297 - delete
298 - get
299---
300# Source: mongodb-kubernetes/templates/operator-roles-base.yaml
301kind: Role
302apiVersion: rbac.authorization.k8s.io/v1
303metadata:
304 name: mongodb-kubernetes-operator
305 namespace: mongodb
306rules:
307 - apiGroups:
308 - ''
309 resources:
310 - services
311 verbs:
312 - get
313 - list
314 - watch
315 - create
316 - update
317 - delete
318 - apiGroups:
319 - ''
320 resources:
321 - secrets
322 - configmaps
323 verbs:
324 - get
325 - list
326 - create
327 - update
328 - delete
329 - watch
330 - apiGroups:
331 - apps
332 resources:
333 - statefulsets
334 verbs:
335 - create
336 - get
337 - list
338 - watch
339 - delete
340 - update
341 - apiGroups:
342 - ''
343 resources:
344 - pods
345 verbs:
346 - get
347 - list
348 - watch
349 - delete
350 - deletecollection
351 - apiGroups:
352 - mongodbcommunity.mongodb.com
353 resources:
354 - mongodbcommunity
355 - mongodbcommunity/status
356 - mongodbcommunity/spec
357 - mongodbcommunity/finalizers
358 verbs:
359 - '*'
360 - apiGroups:
361 - mongodb.com
362 verbs:
363 - '*'
364 resources:
365 - mongodb
366 - mongodb/finalizers
367 - mongodbusers
368 - mongodbusers/finalizers
369 - opsmanagers
370 - opsmanagers/finalizers
371 - mongodbmulticluster
372 - mongodbmulticluster/finalizers
373 - mongodbsearch
374 - mongodbsearch/finalizers
375 - mongodb/status
376 - mongodbusers/status
377 - opsmanagers/status
378 - mongodbmulticluster/status
379 - mongodbsearch/status
380---
381# Source: mongodb-kubernetes/templates/operator-roles-pvc-resize.yaml
382kind: Role
383apiVersion: rbac.authorization.k8s.io/v1
384metadata:
385 name: mongodb-kubernetes-operator-pvc-resize
386 namespace: mongodb
387rules:
388 - apiGroups:
389 - ''
390 resources:
391 - persistentvolumeclaims
392 verbs:
393 - get
394 - delete
395 - list
396 - watch
397 - patch
398 - update
399---
400# Source: mongodb-kubernetes/templates/database-roles.yaml
401kind: RoleBinding
402apiVersion: rbac.authorization.k8s.io/v1
403metadata:
404 name: mongodb-kubernetes-appdb
405 namespace: mongodb
406roleRef:
407 apiGroup: rbac.authorization.k8s.io
408 kind: Role
409 name: mongodb-kubernetes-appdb
410subjects:
411 - kind: ServiceAccount
412 name: mongodb-kubernetes-appdb
413 namespace: mongodb
414---
415# Source: mongodb-kubernetes/templates/operator-roles-base.yaml
416kind: RoleBinding
417apiVersion: rbac.authorization.k8s.io/v1
418metadata:
419 name: mongodb-kubernetes-operator
420 namespace: mongodb
421roleRef:
422 apiGroup: rbac.authorization.k8s.io
423 kind: Role
424 name: mongodb-kubernetes-operator
425subjects:
426 - kind: ServiceAccount
427 name: mongodb-kubernetes-operator
428 namespace: mongodb
429---
430# Source: mongodb-kubernetes/templates/operator-roles-pvc-resize.yaml
431kind: RoleBinding
432apiVersion: rbac.authorization.k8s.io/v1
433metadata:
434 name: mongodb-kubernetes-operator-pvc-resize-binding
435 namespace: mongodb
436roleRef:
437 apiGroup: rbac.authorization.k8s.io
438 kind: Role
439 name: mongodb-kubernetes-operator-pvc-resize
440subjects:
441 - kind: ServiceAccount
442 name: mongodb-kubernetes-operator
443 namespace: mongodb
444---
445# Source: mongodb-kubernetes/templates/operator.yaml
446apiVersion: apps/v1
447kind: Deployment
448metadata:
449 name: mongodb-kubernetes-operator
450 namespace: mongodb
451spec:
452 replicas: 1
453 selector:
454 matchLabels:
455 app.kubernetes.io/component: controller
456 app.kubernetes.io/name: mongodb-kubernetes-operator
457 app.kubernetes.io/instance: mongodb-kubernetes-operator
458 template:
459 metadata:
460 labels:
461 app.kubernetes.io/component: controller
462 app.kubernetes.io/name: mongodb-kubernetes-operator
463 app.kubernetes.io/instance: mongodb-kubernetes-operator
464 spec:
465 serviceAccountName: mongodb-kubernetes-operator
466 securityContext:
467 runAsNonRoot: true
468 runAsUser: 2000
469 containers:
470 - name: mongodb-kubernetes-operator
471 image: "quay.io/mongodb/mongodb-kubernetes:1.6.0"
472 imagePullPolicy: Always
473 args:
474 - -watch-resource=mongodb
475 - -watch-resource=opsmanagers
476 - -watch-resource=mongodbusers
477 - -watch-resource=mongodbcommunity
478 - -watch-resource=mongodbsearch
479 - -watch-resource=clustermongodbroles
480 command:
481 - /usr/local/bin/mongodb-kubernetes-operator
482 resources:
483 limits:
484 cpu: 1100m
485 memory: 1Gi
486 requests:
487 cpu: 500m
488 memory: 200Mi
489 env:
490 - name: OPERATOR_ENV
491 value: prod
492 - name: MDB_DEFAULT_ARCHITECTURE
493 value: non-static
494 - name: NAMESPACE
495 valueFrom:
496 fieldRef:
497 fieldPath: metadata.namespace
498 - name: WATCH_NAMESPACE
499 valueFrom:
500 fieldRef:
501 fieldPath: metadata.namespace
502 - name: MDB_OPERATOR_TELEMETRY_COLLECTION_FREQUENCY
503 value: "1h"
504 - name: MDB_OPERATOR_TELEMETRY_SEND_FREQUENCY
505 value: "168h"
506 - name: CLUSTER_CLIENT_TIMEOUT
507 value: "10"
508 - name: IMAGE_PULL_POLICY
509 value: Always
510 # Database
511 - name: MONGODB_ENTERPRISE_DATABASE_IMAGE
512 value: quay.io/mongodb/mongodb-kubernetes-database
513 - name: INIT_DATABASE_IMAGE_REPOSITORY
514 value: quay.io/mongodb/mongodb-kubernetes-init-database
515 - name: INIT_DATABASE_VERSION
516 value: "1.6.0"
517 - name: DATABASE_VERSION
518 value: "1.6.0"
519 # Ops Manager
520 - name: OPS_MANAGER_IMAGE_REPOSITORY
521 value: quay.io/mongodb/mongodb-enterprise-ops-manager-ubi
522 - name: INIT_OPS_MANAGER_IMAGE_REPOSITORY
523 value: quay.io/mongodb/mongodb-kubernetes-init-ops-manager
524 - name: INIT_OPS_MANAGER_VERSION
525 value: "1.6.0"
526 # AppDB
527 - name: INIT_APPDB_IMAGE_REPOSITORY
528 value: quay.io/mongodb/mongodb-kubernetes-init-appdb
529 - name: INIT_APPDB_VERSION
530 value: "1.6.0"
531 - name: OPS_MANAGER_IMAGE_PULL_POLICY
532 value: Always
533 - name: AGENT_IMAGE
534 value: "quay.io/mongodb/mongodb-agent:108.0.12.8846-1"
535 - name: MDB_AGENT_IMAGE_REPOSITORY
536 value: "quay.io/mongodb/mongodb-agent"
537 - name: MONGODB_IMAGE
538 value: mongodb-enterprise-server
539 - name: MONGODB_REPO_URL
540 value: quay.io/mongodb
541 - name: MDB_IMAGE_TYPE
542 value: ubi8
543 - name: PERFORM_FAILOVER
544 value: 'true'
545 - name: MDB_MAX_CONCURRENT_RECONCILES
546 value: "1"
547 - name: POD_NAME
548 valueFrom:
549 fieldRef:
550 fieldPath: metadata.name
551 - name: OPERATOR_NAME
552 value: mongodb-kubernetes-operator
553 # Community Env Vars Start
554 - name: MDB_COMMUNITY_AGENT_IMAGE
555 value: "quay.io/mongodb/mongodb-agent:108.0.2.8729-1"
556 - name: VERSION_UPGRADE_HOOK_IMAGE
557 value: "quay.io/mongodb/mongodb-kubernetes-operator-version-upgrade-post-start-hook:1.0.10"
558 - name: READINESS_PROBE_IMAGE
559 value: "quay.io/mongodb/mongodb-kubernetes-readinessprobe:1.0.23"
560 - name: MDB_COMMUNITY_IMAGE
561 value: "mongodb-community-server"
562 - name: MDB_COMMUNITY_REPO_URL
563 value: "quay.io/mongodb"
564 - name: MDB_COMMUNITY_IMAGE_TYPE
565 value: "ubi8"
566 # Community Env Vars End
567 - name: MDB_SEARCH_REPO_URL
568 value: "quay.io/mongodb"
569 - name: MDB_SEARCH_NAME
570 value: "mongodb-search"
571 - name: MDB_SEARCH_VERSION
572 value: "0.55.0"
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-8d9b999b7-qvgp7 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-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.

    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 resourceRequirements:
    12 limits:
    13 cpu: "3"
    14 memory: 5Gi
    15 requests:
    16 cpu: "2"
    17 memory: 3Gi
    18EOF

  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.2.0
4
5MongoDBSearch resource
6NAME PHASE VERSION AGE
7mdbc-rs Running 0.55.0 5m11s
8
9Pods running in cluster kind-kind
10NAME READY STATUS RESTARTS AGE
11mdbc-rs-0 2/2 Running 1 (29s ago) 7m42s
12mdbc-rs-1 2/2 Running 1 (3m4s ago) 6m36s
13mdbc-rs-2 2/2 Running 1 (107s ago) 5m48s
14mdbc-rs-search-0 1/1 Running 0 5m11s
15mongodb-kubernetes-operator-8d9b999b7-qvgp7 1/1 Running 0 8m8s

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