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 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 higher 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
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 2 export K8S_CTX="<local cluster context>" 3 4 # the following namespace will be created if not exists 5 export MDB_NS="mongodb" 6 7 # MongoDBCommunity resource name referenced throughout the guide 8 export MDB_RESOURCE_NAME="mdbc-rs" 9 # Number of replica set members deployed in the sample MongoDBCommunity 10 export MDB_MEMBERS=3 11 12 # TLS-related secret names used for MongoDBCommunity and MongoDBSearch 13 export MDB_TLS_CA_SECRET_NAME="${MDB_RESOURCE_NAME}-ca" 14 export MDB_TLS_SERVER_CERT_SECRET_NAME="${MDB_RESOURCE_NAME}-tls" 15 export MDB_SEARCH_TLS_SECRET_NAME="${MDB_RESOURCE_NAME}-search-tls" 16 17 export MDB_TLS_CA_CONFIGMAP="${MDB_RESOURCE_NAME}-ca-configmap" 18 export MDB_TLS_SELF_SIGNED_ISSUER="${MDB_RESOURCE_NAME}-selfsigned-cluster-issuer" 19 export MDB_TLS_CA_CERT_NAME="${MDB_RESOURCE_NAME}-selfsigned-ca" 20 export MDB_TLS_CA_ISSUER="${MDB_RESOURCE_NAME}-cluster-issuer" 21 22 export MDB_VERSION="8.2.6" 23 24 # root admin user for convenience, not used here at all in this guide 25 export MDB_ADMIN_USER_PASSWORD="admin-user-password-CHANGE-ME" 26 # regular user performing restore and search queries on sample mflix database 27 export MDB_USER_PASSWORD="mdb-user-password-CHANGE-ME" 28 # user for MongoDB Search to connect to the replica set to synchronise data from 29 export MDB_SEARCH_SYNC_USER_PASSWORD="search-sync-user-password-CHANGE-ME" 30 31 export OPERATOR_HELM_CHART="mongodb/mongodb-kubernetes" 32 # comma-separated key=value pairs for additional parameters passed to the helm-chart installing the operator 33 export OPERATOR_ADDITIONAL_HELM_VALUES="" 34 35 # TLS is mandatory; connection string must include tls=true 36 export 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 38 export CERT_MANAGER_NAMESPACE="cert-manager" 39 40 # Vector Search auto embedding related configurations 41 export AUTO_EMBEDDING_API_KEY_SECRET_NAME="voyage-api-keys" 42 export AUTO_EMBEDDING_API_QUERY_KEY="<embedding-model-query-key>" 43 export AUTO_EMBEDDING_API_INDEXING_KEY="<embedding-model-indexing-key>" 44 export PROVIDER_ENDPOINT="https://ai.mongodb.com/v1/embeddings" 45 export EMBEDDING_MODEL="voyage-4"
Note
If you have the API keys to enable Vector Search to automatically generate embeddings, replace the following placeholder values in the environment variables:
| API key for generating embeddings for the query text. |
| API key for generating embeddings for text data in your collection at index-time. |
| Embedding model provider's endpoint. Value defaults to
|
To verify that all necessary environment variables are set, run the following code in your terminal:
1 required=( 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 17 missing_req=() 18 for v in "${required[@]}"; do [[ -n "${!v:-}" ]] || missing_req+=("${v}"); done 19 20 if (( ${#missing_req[@]} )); then 21 echo "ERROR: Missing required environment variables:" >&2 22 for m in "${missing_req[@]}"; do echo " - ${m}" >&2; done 23 else 24 echo "All required environment variables present." 25 fi
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:
1 helm repo add mongodb https://mongodb.github.io/helm-charts 2 helm repo update mongodb 3 helm search repo mongodb/mongodb-kubernetes
1 "mongodb" has been added to your repositories 2 Hang tight while we grab the latest from your chart repositories... 3 ...Successfully got an update from the "mongodb" chart repository 4 Update Complete. ⎈Happy Helming!⎈ 5 NAME CHART VERSION APP VERSION DESCRIPTION 6 mongodb/mongodb-kubernetes 1.7.0 MongoDB Controllers for Kubernetes translate th...
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:
1 helm 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}"
1 Release "mongodb-kubernetes" does not exist. Installing it now. 2 NAME: mongodb-kubernetes 3 LAST DEPLOYED: Wed Apr 1 18:27:26 2026 4 NAMESPACE: mongodb 5 STATUS: deployed 6 REVISION: 1 7 TEST SUITE: None 8 USER-SUPPLIED VALUES: 9 {} 10 11 COMPUTED VALUES: 12 agent: 13 name: mongodb-agent 14 version: 108.0.12.8846-1 15 community: 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 39 database: 40 name: mongodb-kubernetes-database 41 version: 1.8.0 42 initDatabase: 43 name: mongodb-kubernetes-init-database 44 version: 1.8.0 45 initOpsManager: 46 name: mongodb-kubernetes-init-ops-manager 47 version: 1.8.0 48 managedSecurityContext: false 49 mongodb: 50 appdbAssumeOldFormat: false 51 name: mongodb-enterprise-server 52 repo: quay.io/mongodb 53 multiCluster: 54 clusterClientTimeout: 10 55 clusters: [] 56 kubeConfigSecretName: mongodb-enterprise-operator-multi-cluster-kubeconfig 57 performFailOver: true 58 operator: 59 additionalArguments: [] 60 affinity: {} 61 createOperatorServiceAccount: true 62 createResourcesServiceAccountsAndRoles: true 63 enableClusterMongoDBRoles: true 64 enablePVCResize: true 65 env: prod 66 maxConcurrentReconciles: 1 67 mdbDefaultArchitecture: non-static 68 name: mongodb-kubernetes-operator 69 nodeSelector: {} 70 operator_image_name: mongodb-kubernetes 71 podSecurityContext: 72 runAsNonRoot: true 73 runAsUser: 2000 74 replicas: 1 75 resources: 76 limits: 77 cpu: 1100m 78 memory: 1Gi 79 requests: 80 cpu: 500m 81 memory: 200Mi 82 securityContext: {} 83 telemetry: 84 collection: 85 clusters: {} 86 deployments: {} 87 frequency: 1h 88 operators: {} 89 send: 90 frequency: 168h 91 tolerations: [] 92 vaultSecretBackend: 93 enabled: false 94 tlsSecretRef: "" 95 version: 1.8.0 96 watchedResources: 97 - mongodb 98 - opsmanagers 99 - mongodbusers 100 - mongodbcommunity 101 - mongodbsearch 102 webhook: 103 installClusterRole: true 104 name: "" 105 registerConfiguration: true 106 opsManager: 107 name: mongodb-enterprise-ops-manager-ubi 108 readinessProbe: 109 name: mongodb-kubernetes-readinessprobe 110 version: 1.0.24 111 registry: 112 agent: quay.io/mongodb 113 database: quay.io/mongodb 114 imagePullSecrets: null 115 initDatabase: quay.io/mongodb 116 initOpsManager: quay.io/mongodb 117 operator: quay.io/mongodb 118 opsManager: quay.io/mongodb 119 pullPolicy: Always 120 readinessProbe: quay.io/mongodb 121 versionUpgradeHook: quay.io/mongodb 122 search: 123 envoyImage: envoyproxy/envoy:v1.37-latest 124 name: mongodb-search 125 repo: quay.io/mongodb 126 version: 0.64.0 127 versionUpgradeHook: 128 name: mongodb-kubernetes-operator-version-upgrade-post-start-hook 129 version: 1.0.10 130 131 HOOKS: 132 MANIFEST: 133 --- 134 Source: mongodb-kubernetes/templates/database-roles.yaml 135 apiVersion: v1 136 kind: ServiceAccount 137 metadata: 138 name: mongodb-kubernetes-appdb 139 namespace: mongodb 140 --- 141 Source: mongodb-kubernetes/templates/database-roles.yaml 142 apiVersion: v1 143 kind: ServiceAccount 144 metadata: 145 name: mongodb-kubernetes-database-pods 146 namespace: mongodb 147 --- 148 Source: mongodb-kubernetes/templates/database-roles.yaml 149 apiVersion: v1 150 kind: ServiceAccount 151 metadata: 152 name: mongodb-kubernetes-ops-manager 153 namespace: mongodb 154 --- 155 Source: mongodb-kubernetes/templates/operator-sa.yaml 156 apiVersion: v1 157 kind: ServiceAccount 158 metadata: 159 name: mongodb-kubernetes-operator 160 namespace: mongodb 161 --- 162 Source: mongodb-kubernetes/templates/operator-roles-clustermongodbroles.yaml 163 kind: ClusterRole 164 apiVersion: rbac.authorization.k8s.io/v1 165 metadata: 166 name: mongodb-kubernetes-operator-mongodb-cluster-mongodb-role 167 rules: 168 - apiGroups: 169 - mongodb.com 170 verbs: 171 - '*' 172 resources: 173 - clustermongodbroles 174 --- 175 Source: mongodb-kubernetes/templates/operator-roles-telemetry.yaml 176 Additional ClusterRole for clusterVersionDetection 177 kind: ClusterRole 178 apiVersion: rbac.authorization.k8s.io/v1 179 metadata: 180 name: mongodb-kubernetes-operator-cluster-telemetry 181 rules: 182 Non-resource URL permissions 183 - nonResourceURLs: 184 - "/version" 185 verbs: 186 - get 187 Cluster-scoped resource permissions 188 - apiGroups: 189 - '' 190 resources: 191 - namespaces 192 resourceNames: 193 - kube-system 194 verbs: 195 - get 196 - apiGroups: 197 - '' 198 resources: 199 - nodes 200 verbs: 201 - list 202 --- 203 Source: mongodb-kubernetes/templates/operator-roles-webhook.yaml 204 kind: ClusterRole 205 apiVersion: rbac.authorization.k8s.io/v1 206 metadata: 207 name: mongodb-kubernetes-operator-mongodb-webhook-cr 208 rules: 209 - apiGroups: 210 - "admissionregistration.k8s.io" 211 resources: 212 - validatingwebhookconfigurations 213 verbs: 214 - get 215 - create 216 - update 217 - delete 218 - apiGroups: 219 - "" 220 resources: 221 - services 222 verbs: 223 - get 224 - list 225 - watch 226 - create 227 - update 228 - delete 229 --- 230 Source: mongodb-kubernetes/templates/operator-roles-clustermongodbroles.yaml 231 kind: ClusterRoleBinding 232 apiVersion: rbac.authorization.k8s.io/v1 233 metadata: 234 name: mongodb-kubernetes-operator-mongodb-cluster-mongodb-role-binding 235 roleRef: 236 apiGroup: rbac.authorization.k8s.io 237 kind: ClusterRole 238 name: mongodb-kubernetes-operator-mongodb-cluster-mongodb-role 239 subjects: 240 - kind: ServiceAccount 241 name: mongodb-kubernetes-operator 242 namespace: mongodb 243 --- 244 Source: mongodb-kubernetes/templates/operator-roles-telemetry.yaml 245 ClusterRoleBinding for clusterVersionDetection 246 kind: ClusterRoleBinding 247 apiVersion: rbac.authorization.k8s.io/v1 248 metadata: 249 name: mongodb-kubernetes-operator-mongodb-cluster-telemetry-binding 250 roleRef: 251 apiGroup: rbac.authorization.k8s.io 252 kind: ClusterRole 253 name: mongodb-kubernetes-operator-cluster-telemetry 254 subjects: 255 - kind: ServiceAccount 256 name: mongodb-kubernetes-operator 257 namespace: mongodb 258 --- 259 Source: mongodb-kubernetes/templates/operator-roles-webhook.yaml 260 kind: ClusterRoleBinding 261 apiVersion: rbac.authorization.k8s.io/v1 262 metadata: 263 name: mongodb-kubernetes-operator-mongodb-webhook-crb 264 roleRef: 265 apiGroup: rbac.authorization.k8s.io 266 kind: ClusterRole 267 name: mongodb-kubernetes-operator-mongodb-webhook-cr 268 subjects: 269 - kind: ServiceAccount 270 name: mongodb-kubernetes-operator 271 namespace: mongodb 272 --- 273 Source: mongodb-kubernetes/templates/database-roles.yaml 274 kind: Role 275 apiVersion: rbac.authorization.k8s.io/v1 276 metadata: 277 name: mongodb-kubernetes-appdb 278 namespace: mongodb 279 rules: 280 - apiGroups: 281 - '' 282 resources: 283 - secrets 284 verbs: 285 - get 286 - apiGroups: 287 - '' 288 resources: 289 - pods 290 verbs: 291 - patch 292 - delete 293 - get 294 --- 295 Source: mongodb-kubernetes/templates/operator-roles-base.yaml 296 kind: Role 297 apiVersion: rbac.authorization.k8s.io/v1 298 metadata: 299 name: mongodb-kubernetes-operator 300 namespace: mongodb 301 rules: 302 - apiGroups: 303 - '' 304 resources: 305 - services 306 verbs: 307 - get 308 - list 309 - watch 310 - create 311 - update 312 - delete 313 - apiGroups: 314 - '' 315 resources: 316 - secrets 317 - configmaps 318 verbs: 319 - get 320 - list 321 - create 322 - update 323 - delete 324 - watch 325 - apiGroups: 326 - apps 327 resources: 328 - statefulsets 329 - deployments 330 verbs: 331 - create 332 - get 333 - list 334 - watch 335 - delete 336 - update 337 - apiGroups: 338 - '' 339 resources: 340 - pods 341 verbs: 342 - get 343 - list 344 - watch 345 - delete 346 - deletecollection 347 - apiGroups: 348 - mongodbcommunity.mongodb.com 349 resources: 350 - mongodbcommunity 351 - mongodbcommunity/status 352 - mongodbcommunity/spec 353 - mongodbcommunity/finalizers 354 verbs: 355 - '*' 356 - apiGroups: 357 - mongodb.com 358 verbs: 359 - '*' 360 resources: 361 - mongodb 362 - mongodb/finalizers 363 - mongodbusers 364 - mongodbusers/finalizers 365 - opsmanagers 366 - opsmanagers/finalizers 367 - mongodbmulticluster 368 - mongodbmulticluster/finalizers 369 - mongodbsearch 370 - mongodbsearch/finalizers 371 - mongodb/status 372 - mongodbusers/status 373 - opsmanagers/status 374 - mongodbmulticluster/status 375 - mongodbsearch/status 376 --- 377 Source: mongodb-kubernetes/templates/operator-roles-pvc-resize.yaml 378 kind: Role 379 apiVersion: rbac.authorization.k8s.io/v1 380 metadata: 381 name: mongodb-kubernetes-operator-pvc-resize 382 namespace: mongodb 383 rules: 384 - apiGroups: 385 - '' 386 resources: 387 - persistentvolumeclaims 388 verbs: 389 - get 390 - delete 391 - list 392 - watch 393 - patch 394 - update 395 --- 396 Source: mongodb-kubernetes/templates/database-roles.yaml 397 kind: RoleBinding 398 apiVersion: rbac.authorization.k8s.io/v1 399 metadata: 400 name: mongodb-kubernetes-appdb 401 namespace: mongodb 402 roleRef: 403 apiGroup: rbac.authorization.k8s.io 404 kind: Role 405 name: mongodb-kubernetes-appdb 406 subjects: 407 - kind: ServiceAccount 408 name: mongodb-kubernetes-appdb 409 namespace: mongodb 410 --- 411 Source: mongodb-kubernetes/templates/operator-roles-base.yaml 412 kind: RoleBinding 413 apiVersion: rbac.authorization.k8s.io/v1 414 metadata: 415 name: mongodb-kubernetes-operator 416 namespace: mongodb 417 roleRef: 418 apiGroup: rbac.authorization.k8s.io 419 kind: Role 420 name: mongodb-kubernetes-operator 421 subjects: 422 - kind: ServiceAccount 423 name: mongodb-kubernetes-operator 424 namespace: mongodb 425 --- 426 Source: mongodb-kubernetes/templates/operator-roles-pvc-resize.yaml 427 kind: RoleBinding 428 apiVersion: rbac.authorization.k8s.io/v1 429 metadata: 430 name: mongodb-kubernetes-operator-pvc-resize-binding 431 namespace: mongodb 432 roleRef: 433 apiGroup: rbac.authorization.k8s.io 434 kind: Role 435 name: mongodb-kubernetes-operator-pvc-resize 436 subjects: 437 - kind: ServiceAccount 438 name: mongodb-kubernetes-operator 439 namespace: mongodb 440 --- 441 Source: mongodb-kubernetes/templates/operator.yaml 442 apiVersion: apps/v1 443 kind: Deployment 444 metadata: 445 name: mongodb-kubernetes-operator 446 namespace: mongodb 447 spec: 448 replicas: 1 449 selector: 450 matchLabels: 451 app.kubernetes.io/component: controller 452 app.kubernetes.io/name: mongodb-kubernetes-operator 453 app.kubernetes.io/instance: mongodb-kubernetes-operator 454 template: 455 metadata: 456 labels: 457 app.kubernetes.io/component: controller 458 app.kubernetes.io/name: mongodb-kubernetes-operator 459 app.kubernetes.io/instance: mongodb-kubernetes-operator 460 spec: 461 serviceAccountName: mongodb-kubernetes-operator 462 securityContext: 463 runAsNonRoot: true 464 runAsUser: 2000 465 containers: 466 - name: mongodb-kubernetes-operator 467 image: "quay.io/mongodb/mongodb-kubernetes:1.8.0" 468 imagePullPolicy: Always 469 args: 470 - -watch-resource=mongodb 471 - -watch-resource=opsmanagers 472 - -watch-resource=mongodbusers 473 - -watch-resource=mongodbcommunity 474 - -watch-resource=mongodbsearch 475 - -watch-resource=clustermongodbroles 476 command: 477 - /usr/local/bin/mongodb-kubernetes-operator 478 volumeMounts: 479 - mountPath: /tmp/k8s-webhook-server/serving-certs 480 name: webhook-server-dir 481 resources: 482 limits: 483 cpu: 1100m 484 memory: 1Gi 485 requests: 486 cpu: 500m 487 memory: 200Mi 488 env: 489 - name: OPERATOR_ENV 490 value: prod 491 - name: MDB_DEFAULT_ARCHITECTURE 492 value: non-static 493 - name: NAMESPACE 494 valueFrom: 495 fieldRef: 496 fieldPath: metadata.namespace 497 - name: WATCH_NAMESPACE 498 valueFrom: 499 fieldRef: 500 fieldPath: metadata.namespace 501 - name: MDB_OPERATOR_TELEMETRY_COLLECTION_FREQUENCY 502 value: "1h" 503 - name: MDB_OPERATOR_TELEMETRY_SEND_FREQUENCY 504 value: "168h" 505 - name: CLUSTER_CLIENT_TIMEOUT 506 value: "10" 507 - name: IMAGE_PULL_POLICY 508 value: Always 509 # Database 510 - name: MONGODB_ENTERPRISE_DATABASE_IMAGE 511 value: quay.io/mongodb/mongodb-kubernetes-database 512 - name: INIT_DATABASE_IMAGE_REPOSITORY 513 value: quay.io/mongodb/mongodb-kubernetes-init-database 514 - name: INIT_DATABASE_VERSION 515 value: "1.8.0" 516 - name: DATABASE_VERSION 517 value: "1.8.0" 518 # Ops Manager 519 - name: OPS_MANAGER_IMAGE_REPOSITORY 520 value: quay.io/mongodb/mongodb-enterprise-ops-manager-ubi 521 - name: INIT_OPS_MANAGER_IMAGE_REPOSITORY 522 value: quay.io/mongodb/mongodb-kubernetes-init-ops-manager 523 - name: INIT_OPS_MANAGER_VERSION 524 value: "1.8.0" 525 - name: OPS_MANAGER_IMAGE_PULL_POLICY 526 value: Always 527 - name: AGENT_IMAGE 528 value: "quay.io/mongodb/mongodb-agent:108.0.12.8846-1" 529 - name: MDB_AGENT_IMAGE_REPOSITORY 530 value: "quay.io/mongodb/mongodb-agent" 531 - name: MONGODB_IMAGE 532 value: mongodb-enterprise-server 533 - name: MONGODB_REPO_URL 534 value: quay.io/mongodb 535 - name: PERFORM_FAILOVER 536 value: 'true' 537 - name: MDB_MAX_CONCURRENT_RECONCILES 538 value: "1" 539 - name: POD_NAME 540 valueFrom: 541 fieldRef: 542 fieldPath: metadata.name 543 - name: OPERATOR_NAME 544 value: mongodb-kubernetes-operator 545 # Community Env Vars Start 546 - name: MDB_COMMUNITY_AGENT_IMAGE 547 value: "quay.io/mongodb/mongodb-agent:108.0.2.8729-1" 548 - name: VERSION_UPGRADE_HOOK_IMAGE 549 value: "quay.io/mongodb/mongodb-kubernetes-operator-version-upgrade-post-start-hook:1.0.10" 550 - name: READINESS_PROBE_IMAGE 551 value: "quay.io/mongodb/mongodb-kubernetes-readinessprobe:1.0.24" 552 - name: MDB_COMMUNITY_IMAGE 553 value: "mongodb-community-server" 554 - name: MDB_COMMUNITY_REPO_URL 555 value: "quay.io/mongodb" 556 - name: MDB_COMMUNITY_IMAGE_TYPE 557 value: "ubi8" 558 # Community Env Vars End 559 - name: MDB_SEARCH_REPO_URL 560 value: "quay.io/mongodb" 561 - name: MDB_SEARCH_NAME 562 value: "mongodb-search" 563 - name: MDB_SEARCH_VERSION 564 value: "0.64.0" 565 - name: MDB_ENVOY_IMAGE 566 value: "envoyproxy/envoy:v1.37-latest" 567 volumes: 568 - name: webhook-server-dir 569 emptyDir: {}
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.
1 kubectl --context "${K8S_CTX}" -n "${MDB_NS}" rollout status --timeout=2m deployment/mongodb-kubernetes-operator 2 echo "Operator deployment in ${MDB_NS} namespace" 3 kubectl --context "${K8S_CTX}" -n "${MDB_NS}" get deployments 4 echo; echo "Operator pod in ${MDB_NS} namespace" 5 kubectl --context "${K8S_CTX}" -n "${MDB_NS}" get pods
1 Waiting for deployment "mongodb-kubernetes-operator" rollout to finish: 0 of 1 updated replicas are available... 2 deployment "mongodb-kubernetes-operator" successfully rolled out 3 Operator deployment in mongodb namespace 4 NAME READY UP-TO-DATE AVAILABLE AGE 5 mongodb-kubernetes-operator 1/1 1 1 3s 6 7 Operator pod in mongodb namespace 8 NAME READY STATUS RESTARTS AGE 9 mongodb-kubernetes-operator-85f6cbcf67-wmtnm 1/1 Running 0 3s
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 themongotprocess 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 2 kubectl 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 7 kubectl 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 12 kubectl 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 16 echo "User secrets created."
1 secret/mdb-admin-user-password created 2 secret/mdbc-rs-search-sync-source-password created 3 secret/mdb-user-password created
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:
1 helm 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 9 for 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 13 done 14 15 echo "cert-manager is ready in namespace ${CERT_MANAGER_NAMESPACE}."
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
ConfigMapso that MongoDB resources can use it.
1 Bootstrap a self-signed ClusterIssuer that will mint the CA material consumed by 2 the MongoDBCommunity deployment. 3 kubectl apply --context "${K8S_CTX}" -f - <<EOF_MANIFEST 4 apiVersion: cert-manager.io/v1 5 kind: ClusterIssuer 6 metadata: 7 name: ${MDB_TLS_SELF_SIGNED_ISSUER} 8 spec: 9 selfSigned: {} 10 EOF_MANIFEST 11 12 kubectl --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. 15 kubectl apply --context "${K8S_CTX}" -f - <<EOF_MANIFEST 16 apiVersion: cert-manager.io/v1 17 kind: Certificate 18 metadata: 19 name: ${MDB_TLS_CA_CERT_NAME} 20 namespace: ${CERT_MANAGER_NAMESPACE} 21 spec: 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 31 EOF_MANIFEST 32 33 kubectl --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. 36 kubectl apply --context "${K8S_CTX}" -f - <<EOF_MANIFEST 37 apiVersion: cert-manager.io/v1 38 kind: ClusterIssuer 39 metadata: 40 name: ${MDB_TLS_CA_ISSUER} 41 spec: 42 ca: 43 secretName: ${MDB_TLS_CA_SECRET_NAME} 44 EOF_MANIFEST 45 46 kubectl --context "${K8S_CTX}" wait --for=condition=Ready clusterissuer "${MDB_TLS_CA_ISSUER}" 47 48 TMP_CA_CERT="$(mktemp)" 49 50 kubectl --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. 55 kubectl --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 60 echo "Cluster-wide CA issuer ${MDB_TLS_CA_ISSUER} is ready."
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.
1 server_certificate="${MDB_RESOURCE_NAME}-server-tls" 2 search_certificate="${MDB_RESOURCE_NAME}-search-tls" 3 4 mongo_dns_names=() 5 for ((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") 8 done 9 mongo_dns_names+=( 10 "${MDB_RESOURCE_NAME}-svc.${MDB_NS}.svc.cluster.local" 11 "*.${MDB_RESOURCE_NAME}-svc.${MDB_NS}.svc.cluster.local" 12 ) 13 14 search_dns_names=( 15 "*.${MDB_RESOURCE_NAME}-search-svc.${MDB_NS}.svc.cluster.local" 16 ) 17 18 render_dns_list() { 19 local dns_list=("$@") 20 for dns in "${dns_list[@]}"; do 21 printf " - \"%s\"\n" "${dns}" 22 done 23 } 24 25 kubectl apply --context "${K8S_CTX}" -n "${MDB_NS}" -f - <<EOF_MANIFEST 26 apiVersion: cert-manager.io/v1 27 kind: Certificate 28 metadata: 29 name: ${server_certificate} 30 namespace: ${MDB_NS} 31 spec: 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 --- 46 apiVersion: cert-manager.io/v1 47 kind: Certificate 48 metadata: 49 name: ${search_certificate} 50 namespace: ${MDB_NS} 51 spec: 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[@]}") 65 EOF_MANIFEST 66 67 kubectl --context "${K8S_CTX}" -n "${MDB_NS}" wait --for=condition=Ready certificate "${server_certificate}" --timeout=300s 68 kubectl --context "${K8S_CTX}" -n "${MDB_NS}" wait --for=condition=Ready certificate "${search_certificate}" --timeout=300s 69 70 echo "MongoDB TLS certificates have been issued."
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:
Create a
MongoDBCommunitycustom resource namedmdb-rs.The resource defines CPU and memory resources for the
mongodandmongodb-agentcontainers, and sets up the following three users:mdb-userUser that can restore database and run search queries. This user uses the
mdb-user-passwordsecret to perform these operations.search-sync-sourceUser that MongoDB Search uses to connect to MongoDB database in order to manage and build indexes. This user uses
searchCoordinatorrole that the Kubernetes operator creates. This uses uses themdbc-rs-search-sync-source-passwordsecret to connectmongottomongod.admin-userDatabase 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:
1 kubectl apply --context "${K8S_CTX}" -n "${MDB_NS}" -f - <<EOF 2 apiVersion: mongodbcommunity.mongodb.com/v1 3 kind: MongoDBCommunity 4 metadata: 5 name: ${MDB_RESOURCE_NAME} 6 spec: 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 82 EOF Wait for the
MongoDBCommunityresource deployment to complete.When you apply the
MongoDBCommunitycustom resource, the Kubernetes operator begins deploying the MongoDB nodes (pods). This step pauses the execution until themdbc-rsresource's status phase isRunning, which indicates that the MongoDB Community replica set is operational.1 echo "Waiting for MongoDBCommunity resource to reach Running phase..." 2 kubectl --context "${K8S_CTX}" -n "${MDB_NS}" wait \ 3 --for=jsonpath='{.status.phase}'=Running mdbc/mdbc-rs --timeout=400s 4 echo; echo "MongoDBCommunity resource" 5 kubectl --context "${K8S_CTX}" -n "${MDB_NS}" get mdbc/mdbc-rs 6 echo; echo "Pods running in cluster ${K8S_CTX}" 7 kubectl --context "${K8S_CTX}" -n "${MDB_NS}" get pods 1 Waiting for MongoDBCommunity resource to reach Running phase... 2 mongodbcommunity.mongodbcommunity.mongodb.com/mdbc-rs condition met 3 4 MongoDBCommunity resource 5 NAME PHASE VERSION 6 mdbc-rs Running 8.2 7 8 Pods running in cluster minikube 9 NAME READY STATUS RESTARTS AGE 10 mdbc-rs-0 2/2 Running 0 2m30s 11 mdbc-rs-1 2/2 Running 0 82s 12 mdbc-rs-2 2/2 Running 0 38s 13 mongodb-kubernetes-operator-5776c8b4df-cppnf 1/1 Running 0 7m37s
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:
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.
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-rsMongoDBSearch resource's status phase isRunning, which indicates that the MongoDB Search is operational.1 echo "Waiting for MongoDBSearch resource to reach Running phase..." 2 kubectl --context "${K8S_CTX}" -n "${MDB_NS}" wait \ 3 --for=jsonpath='{.status.phase}'=Running mdbs/"${MDB_RESOURCE_NAME}" --timeout=300s
Optional. Verify the MongoDB Community resource status.
Ensure that the MongoDBCommunity resource deployment with
MongoDBSearch was successful.
1 echo "Waiting for MongoDBCommunity resource to reach Running phase..." 2 kubectl --context "${K8S_CTX}" -n "${MDB_NS}" wait \ 3 --for=jsonpath='{.status.phase}'=Running mdbc/mdbc-rs --timeout=400s 4 echo; echo "MongoDBCommunity resource" 5 kubectl --context "${K8S_CTX}" -n "${MDB_NS}" get mdbc/mdbc-rs 6 echo; echo "Pods running in cluster ${K8S_CTX}" 7 kubectl --context "${K8S_CTX}" -n "${MDB_NS}" get pods
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.
1 echo; echo "MongoDBCommunity resource" 2 kubectl --context "${K8S_CTX}" -n "${MDB_NS}" get mdbc/mdbc-rs 3 echo; echo "MongoDBSearch resource" 4 kubectl --context "${K8S_CTX}" -n "${MDB_NS}" get mdbs/mdbc-rs 5 echo; echo "Pods running in cluster ${K8S_CTX}" 6 kubectl --context "${K8S_CTX}" -n "${MDB_NS}" get pods
1 MongoDBCommunity resource 2 NAME PHASE VERSION 3 mdbc-rs Running 8.2.6 4 5 MongoDBSearch resource 6 NAME PHASE VERSION LOADBALANCER AGE 7 mdbc-rs Running 0.64.0 5m1s 8 9 Pods running in cluster kind-kind 10 NAME READY STATUS RESTARTS AGE 11 mdbc-rs-0 2/2 Running 1 (25s ago) 7m32s 12 mdbc-rs-1 2/2 Running 1 (3m ago) 6m31s 13 mdbc-rs-2 2/2 Running 1 (102s ago) 5m44s 14 mdbc-rs-search-0 1/1 Running 0 4m21s 15 mongodb-kubernetes-operator-85f6cbcf67-wmtnm 1/1 Running 0 7m54s
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.