对于 AI 代理:可在 https://www.mongodb.com/zh-cn/docs/llms.txt 获取文档索引—通过在任何 URL 路径后添加 .md 可获取所有页面的 Markdown 版本。
Docs 菜单

安装和使用 MongoDB Community Edition

您可以使用 Kubernetes 操作符和部署 mongot 进程资源,以便在 Kubernetes 集群上与 MongoDB Community Edition v8.2.0 或更高版本一起运行。mongot 进程支持 MongoDB Search 和向量搜索。您可以选择启用和配置向量搜索,以使用支持的 Voyage AI 嵌入模型自动为集合和查询中的文本数据生成向量嵌入。

重要

自动嵌入处于预览状态。在预览期间,该功能和相应的文档可能随时更改。要学习;了解更多信息,请参阅预览功能。

以下过程演示了如何部署和配置 MongoDB Search 和向量搜索,以便与 Kubernetes 集群中的新副本集或现有副本集一起运行。部署使用 TLS 证书,用于确保 MongoDB 节点与 mongot 搜索进程之间的安全通信。

要部署MongoDB Search 和 Vector Search,您必须具备以下条件:

  • 正在运行的 Kubernetes 集群。

  • Kubernetes命令行工具 kubectl,配置为与集群通信。

  • Helm( Kubernetes的包管理器),用于安装Kubernetes Operator。

  • cert-manager 或用于 TLS 证书预配的替代证书管理解决方案。

  • Bash v5.1 或更高版本,用于运行本教程中的命令。

或者,要将向量搜索配置为自动为集合和查询中的文本数据生成向量嵌入,您必须为嵌入服务创建API密钥。我们建议创建两个键,一个用于在索引时为集合中的文本数据生成嵌入,另一个用于在查询时为查询文本生成嵌入。如果您没有密钥,可以从Atlas用户界面创建密钥。

1

设置环境变量以供本过程中的后续步骤使用。复制以下命令,更新环境的值,然后运行这些命令以加载变量:

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"

注意

如果您有API密钥来启用Vector Search 自动生成嵌入,请替换环境变量中的以下占位符值:

AUTO_EMBEDDING_API_QUERY_KEY

API用于为查询文本生成嵌入的密钥。

AUTO_EMBEDDING_API_INDEXING_KEY

用于在索引时为集合中的文本数据生成嵌入的API密钥。

PROVIDER_ENDPOINT

嵌入模型提供商的终结点。从Atlas用户界面创建的密钥的默认值为 https://ai.mongodb.com/v1/embeddings。如果您直接从 Voyage AI创建API密钥,请替换为 https://api.voyageai.com/v1/embeddings

验证是否已设立环境变量。

要验证是否已设立所有必要的环境变量,请在终端中运行以下代码:

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

Helm 自动部署和管理 Kubernetes 上的 MongoDB 实例。如果您已经拥有包含用于安装 Kubernetes 操作符的 Helm 图表的 Helm 存储库,请跳过此步骤。否则,请添加 Helm存储库。

要添加 Helm存储库,请复制、粘贴并运行以下命令:

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.10.0 MongoDB Controllers for Kubernetes translate th...
3

Kubernetes Operator 监视 MongoDBCommunity 和 MongoDBSearch 自定义资源,并管理MongoDB部署的生命周期。如果您已经安装了MongoDB Controllers for Kubernetes 操作符,请跳过此步骤。否则,请从您在上一步中添加的 Helm存储库安装MongoDB Controllers for Kubernetes Operator。

要在 mongodb 命名空间中安装 MongoDB Controllers for Kubernetes 操作符,请复制、粘贴并运行以下命令:

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

在继续MongoDB Search 和 向量搜索部署之前,确保Kubernetes Operator 完全运行。运行以下命令,验证所有操作符组件都在运行且可用。

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 2s
6
7Operator pod in mongodb namespace
8NAME READY STATUS RESTARTS AGE
9mongodb-kubernetes-operator-5594c7cd4c-dn82g 1/1 Running 0 2s
5

MongoDB需要身份验证才能安全访问权限。在此步骤中,您将创建三个Kubernetes密钥:

  • mdb-admin-user-password: MongoDB管理员的档案。

  • mdb-user-password:授权执行搜索查询的用户的档案。

  • mdbc-rs-search-sync-source-password:专用搜索用户的档案,由 mongot进程在内部用于同步数据和管理索引。

Kubernetes 操作符使用这些密钥中的密码在 MongoDB 数据库中自动创建用户。

要创建密钥,请复制、粘贴并运行以下命令:

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

管理TLS证书需要 cert-manager。如果您已在集群中安装 cert-manager,请跳过此步骤。否则,请使用Helm 安装 cert-manager

要在 cert-manager命名空间中安装 cert-manager,请在终端中运行以下命令:

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

创建证书颁发机构基础架构,为 MongoDBMongoDBSearch 资源颁发 TLS 证书。这些命令执行以下操作:

  • 创建自签名 ClusterIssuer

  • 生成 CA 证书。

  • 发布所有命名空间都可以使用的集群范围的 CA 颁发者。

  • 通过 ConfigMap 公开 CA 捆绑包,以便MongoDB资源可以使用它。

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

MongoDB 服务器和 MongoDBSearch 服务颁发 TLS 证书。MongoDB服务器证书包括 Pod 和服务通信所需的所有 DNS 名称。这两种证书都支持服务器和客户端身份验证。

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

如果您已经部署了MongoDB Community Edition,请跳过此步骤。否则,部署MongoDB Community Edition。

要部署MongoDB Community Edition,请完成以下步骤:

  1. 创建名为 mdb-rsMongoDBCommunity 自定义资源。

    该资源定义了 mongodmongodb-agent 容器的 CPU 和内存资源,并设置了以下三个用户:

    mdb-user

    可以恢复数据库和运行搜索查询的用户。该用户使用 mdb-user-password 密钥来执行这些操作。

    search-sync-source

    MongoDB 搜索用于连接到 MongoDB 数据库以管理和构建索引的用户。此用户使用Kubernetes 操作符创建的 searchCoordinator角色。这会使用 mdbc-rs-search-sync-source-password 密钥将 mongot 连接到 mongod

    admin-user

    数据库管理员用户。

    Kubernetes 操作符使用此资源配置具有 3 个成员的 MongoDB 副本集。

    要创建密钥,请复制、粘贴并运行以下命令:

    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. 等待 MongoDBCommunity资源部署完成。

    当您应用MongoDBCommunity 自定义资源时, Kubernetes 操作符开始部署MongoDB节点 (Pod)。此步骤会暂停执行,直到 mdbc-rs 资源的状态阶段为 Running,这表示MongoDB Community副本集可操作。

    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

您可以部署一个搜索节点实例,而无需任何负载均衡。

要部署,请完成以下步骤:

  1. 创建名为 mdbc-rs 的 MongoDBSearch 自定义资源。

    此资源指定搜索节点的 CPU 和内存资源要求。要学习;了解有关此自定义资源中设置的更多信息,请参阅MongoDB搜索和向量搜索设置。

    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

    注意

    由于Kubernetes Operator 仅部署MongoDB Search 的单个实例,因此该实例会自动配置为嵌入式物化视图编写器。

    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. 等待 MongoDBSearch资源部署完成。

    当您应用MongoDBSearch 自定义资源时, Kubernetes 操作符开始部署搜索节点 (pod)。此步骤会暂停执行,直到 mdbc-rs MongoDB搜索 资源的状态阶段为 Running(表示MongoDB搜索 正在运行)。

    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

确保使用 MongoDBSearch 的 MongoDBCommunity资源部署成功。

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

查看MongoDB副本集成员、 Kubernetes Operator 的MongoDB控制器以及搜索节点的命名空间Pod 中运行的所有 Pod。

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 (27s ago) 7m43s
12mdbc-rs-1 2/2 Running 1 (3m1s ago) 6m42s
13mdbc-rs-2 2/2 Running 1 (104s ago) 5m56s
14mdbc-rs-search-0-0 1/1 Running 0 4m32s
15mongodb-kubernetes-operator-5594c7cd4c-dn82g 1/1 Running 0 8m4s

程序完成后,在运行查询之前确认部署正常。

检查点
验证步骤

MongoDB Community 资源运行中

运行 kubectl get mongodbcommunity -n <your-namespace>,并确认 MongoDBCommunity 资源显示 Running 阶段。

MongoDB Search 资源运行中

运行 kubectl get mongodbsearch -n <your-namespace>,并确认 MongoDBSearch 资源显示 Running 阶段。

所有 Pod 健康

运行 kubectl get pods -n <your-namespace>,并确认所有副本集节点和搜索节点均显示 Running 状态,且所有容器均已就绪。

搜索查询成功

连接到副本集合并运行 MongoDB Search 或向量搜索查询,以确认搜索索引可访问。

使用 MongoDB Community Edition 部署 MongoDB Search 和向量搜索后,您可以: