您可以使用Kubernetes Operator 并部署mongot进程资源,以便在Kubernetes集群上与MongoDB Community Edition v8.3 或更高版本一起运行。 mongot进程支持MongoDB Search 和 Vector Search。或者,您可以启用和配置 Vector Search,使用支持的 Voyage AI嵌入模型为集合和查询中的文本数据自动生成向量嵌入。
重要
自动嵌入处于预览状态。在预览期间,该功能和相应的文档可能随时更改。要学习;了解更多信息,请参阅预览功能。
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.
先决条件
要部署MongoDB Search 和 Vector Search,您必须具备以下条件:
正在运行的 Kubernetes 集群。
Kubernetes命令行工具
kubectl,配置为与集群通信。Helm( Kubernetes的包管理器),用于安装Kubernetes Operator。
cert-manager 或用于 TLS 证书预配的替代证书管理解决方案。
Bash v5.1 或更高版本,用于运行本教程中的命令。
或者,要将向量搜索配置为自动为集合和查询中的文本数据生成向量嵌入,您必须为嵌入服务创建API密钥。我们建议创建两个键,一个用于在索引时为集合中的文本数据生成嵌入,另一个用于在查询时为查询文本生成嵌入。如果您没有密钥,可以从Atlas用户界面创建密钥。
步骤
必填。设置环境变量。
设置环境变量以供本过程中的后续步骤使用。复制以下命令,更新环境的值,然后运行这些命令以加载变量:
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.3.4" 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"
注意
如果您有API密钥来启用向量搜索自动生成嵌入,请替换环境变量中的以下占位符值:
| 用于为查询文本生成嵌入的API密钥。 |
| 在索引时为集合中的文本数据生成嵌入的API密钥。 |
| 嵌入模型提供商的终结点。从Atlas用户界面创建的密钥的默认值为 |
要验证是否已设立所有必要的环境变量,请在终端中运行以下代码:
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
有条件。添加MongoDB Helm存储库。
Helm 自动部署和管理 Kubernetes 上的 MongoDB 实例。如果您已经拥有包含用于安装 Kubernetes 操作符的 Helm 图表的 Helm 存储库,请跳过此步骤。否则,请添加 Helm存储库。
要添加 Helm存储库,请复制、粘贴并运行以下命令:
1 helm repo add mongodb https://mongodb.github.io/helm-charts 2 helm repo update mongodb 3 helm search repo mongodb/mongodb-kubernetes
有条件。为Kubernetes Operator 安装MongoDB控制器。
Kubernetes Operator 监视 MongoDBCommunity 和 MongoDBSearch 自定义资源,并管理MongoDB部署的生命周期。如果您已经安装了MongoDB Controllers for Kubernetes 操作符,请跳过此步骤。否则,请从您在上一步中添加的 Helm存储库安装MongoDB Controllers for Kubernetes Operator。
要在 mongodb 命名空间中安装 MongoDB Controllers for Kubernetes 操作符,请复制、粘贴并运行以下命令:
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}"
可选。等待操作符部署。
在继续MongoDB Search 和 向量搜索部署之前,确保Kubernetes Operator 完全运行。运行以下命令,验证所有操作符组件都在运行且可用。
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
必需。创建并加载MongoDB用户密钥。
MongoDB需要身份验证才能安全访问权限。在此步骤中,您将创建三个Kubernetes密钥:
mdb-admin-user-password: MongoDB管理员的档案。mdb-user-password:授权执行搜索查询的用户的档案。mdbc-rs-search-sync-source-password:专用搜索用户的档案,由mongot进程在内部用于同步数据和管理索引。
Kubernetes 操作符使用这些密钥中的密码在 MongoDB 数据库中自动创建用户。
要创建密钥,请复制、粘贴并运行以下命令:
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."
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.
要在 cert-manager命名空间中安装 cert-manager,请在终端中运行以下命令:
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}."
必需。准备证书颁发者和 CA 基础架构。
Create the certificate authority infrastructure that will issue TLS certificates for MongoDB and MongoDBSearch resources. The commands perform the following actions:
创建自签名
ClusterIssuer。生成 CA 证书。
发布所有命名空间都可以使用的集群范围的 CA 颁发者。
通过
ConfigMap公开 CA 捆绑包,以便MongoDB资源可以使用它。
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."
必需。颁发 TLS 证书。
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-0-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."
有条件。创建和部署MongoDB Community资源。
如果您已经部署了MongoDB Community Edition,请跳过此步骤。否则,部署MongoDB Community Edition。
要部署MongoDB Community Edition,请完成以下步骤:
创建名为
mdb-rs的MongoDBCommunity自定义资源。该资源定义了
mongod和mongodb-agent容器的 CPU 和内存资源,并设置了以下三个用户:mdb-user可以恢复数据库和运行搜索查询的用户。该用户使用
mdb-user-password密钥来执行这些操作。search-sync-sourceMongoDB 搜索用于连接到 MongoDB 数据库以管理和构建索引的用户。此用户使用Kubernetes 操作符创建的
searchCoordinator角色。这会使用mdbc-rs-search-sync-source-password密钥将mongot连接到mongod。admin-user数据库管理员用户。
Kubernetes 操作符使用此资源配置具有 3 个成员的 MongoDB 副本集。
要创建密钥,请复制、粘贴并运行以下命令:
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 等待
MongoDBCommunity资源部署完成。当您应用
MongoDBCommunity自定义资源时, Kubernetes 操作符开始部署MongoDB节点 (Pod)。此步骤会暂停执行,直到mdbc-rs资源的状态阶段为Running,这表示MongoDB Community副本集可操作。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
必需。为MongoDB Search 和 Vector Search 创建并部署资源。
您可以部署一个搜索节点实例,而无需任何负载均衡。
要部署,请完成以下步骤:
创建名为
mdbc-rs的 MongoDBSearch 自定义资源。此资源指定搜索节点的 CPU 和内存资源要求。要学习;了解有关此自定义资源中设置的更多信息,请参阅MongoDB搜索和向量搜索设置。
等待 MongoDBSearch资源部署完成。
当您应用MongoDBSearch 自定义资源时, Kubernetes 操作符开始部署搜索节点 (pod)。此步骤会暂停执行,直到
mdbc-rsMongoDB搜索 资源的状态阶段为Running(表示MongoDB搜索 正在运行)。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
可选。验证MongoDB Community资源状态。
确保使用 MongoDBSearch 的 MongoDBCommunity资源部署成功。
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
可选。查看命名空间中所有运行的Pod。
查看MongoDB副本集成员、 Kubernetes Operator 的MongoDB控制器以及搜索节点的命名空间Pod 中运行的所有 Pod。
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
验证部署
程序完成后,在运行查询之前确认部署正常。
检查点 | 验证步骤 |
|---|---|
MongoDB Community 资源运行中 | 运行 |
MongoDB Search 资源运行中 | 运行 |
所有 Pod 健康 | 运行 |
搜索查询成功 | 连接到副本集合并运行 MongoDB Search 或向量搜索查询,以确认搜索索引可访问。 |
后续步骤
使用 MongoDB Community Edition 部署 MongoDB Search 和向量搜索后,您可以:
添加数据并运行查询:将数据加载到 MongoDB 集群中,创建 MongoDB Search 和向量搜索索引,并对数据运行查询。要了解更多信息,请参阅使用 MongoDB Search 和向量搜索。
配置搜索设置:调整搜索部署的资源设置。要学习更多信息,请参阅 MongoDB Search 和向量搜索设置。