Para agentes de IA: um índice de documentação está disponível em https://www.mongodb.com/pt-br/docs/llms.txt — as versões de markdown de todas as páginas estão disponíveis anexando .md a qualquer caminho de URL.

Instalação e uso Com o MongoDB Community Edition

Você pode usar o Kubernetes Operator e implantar os recursos de processo mongot para executar com o MongoDB Community Edition v8.3 ou posterior em um cluster do Kubernetes. O processo mongot suporta tanto o MongoDB Search quanto a pesquisa vetorial. Opcionalmente, você pode habilitar e configurar a pesquisa vetorial para gerar automaticamente embedding vetorial para dados de texto em suas coleções e query usando um modelo de embedding Voyage AI compatível.

Importante

A incorporação automática está em visualização. O recurso e a documentação correspondente podem mudar a qualquer momento durante o período de pré-visualização. Para **aprender** mais, consulte Visualizar recursos.

O procedimento a seguir demonstra como implantar e configurar o MongoDB Search e o Vector Search para serem executados com um conjunto de réplicas novo ou existente no cluster do Kubernetes. A implantação usa certificados TLS para garantir uma comunicação segura entre os nós do MongoDB e o processo de pesquisa mongot.

Para implantar o MongoDB Search e o Vector Search, você deve ter o seguinte:

  • Um cluster Kubernetes em execução.

  • A ferramenta de linha de comando do Kubernetes, kubectl, configurada para se comunicar com seu cluster.

  • Helm, o gerenciador de pacote do Kubernetes, para instalar o Operador Kubernetes.

  • cert-manager ou uma solução alternativa de gerenciamento de certificados para o provisionamento de certificados TLS.

  • Bash v5.1 ou posterior para executar os comandos neste tutorial.

Opcionalmente, para configurar a pesquisa vetorial para gerar automaticamente incorporações vetoriais para dados de texto em suas coleções e queries, você deve criar chaves de API para o serviço de incorporação. Recomendamos criar duas chaves, uma para gerar incorporações em tempo de índice para dados de texto em sua coleção e outra para gerar incorporações em tempo de query para seu texto de query. Se você não tiver as chaves, poderá criar as chaves a partir da IU do Atlas.

1

Defina as variáveis de ambiente para uso nas etapas subsequentes deste procedimento. Copie os seguintes comandos, atualize os valores do seu ambiente e execute-os para carregar as variáveis:

# set it to the context name of the k8s clusterexport K8S_CTX="<local cluster context>" # the following namespace will be created if not existsexport MDB_NS="mongodb" # MongoDBCommunity resource name referenced throughout the guideexport MDB_RESOURCE_NAME="mdbc-rs"# Number of replica set members deployed in the sample MongoDBCommunityexport MDB_MEMBERS=3 # TLS-related secret names used for MongoDBCommunity and MongoDBSearchexport MDB_TLS_CA_SECRET_NAME="${MDB_RESOURCE_NAME}-ca"export MDB_TLS_SERVER_CERT_SECRET_NAME="${MDB_RESOURCE_NAME}-tls"export MDB_SEARCH_TLS_SECRET_NAME="${MDB_RESOURCE_NAME}-search-tls" export MDB_TLS_CA_CONFIGMAP="${MDB_RESOURCE_NAME}-ca-configmap"export MDB_TLS_SELF_SIGNED_ISSUER="${MDB_RESOURCE_NAME}-selfsigned-cluster-issuer"export MDB_TLS_CA_CERT_NAME="${MDB_RESOURCE_NAME}-selfsigned-ca"export MDB_TLS_CA_ISSUER="${MDB_RESOURCE_NAME}-cluster-issuer" export MDB_VERSION="8.3.4" # root admin user for convenience, not used here at all in this guideexport MDB_ADMIN_USER_PASSWORD="admin-user-password-CHANGE-ME"# regular user performing restore and search queries on sample mflix databaseexport MDB_USER_PASSWORD="mdb-user-password-CHANGE-ME"# user for MongoDB Search to connect to the replica set to synchronise data fromexport MDB_SEARCH_SYNC_USER_PASSWORD="search-sync-user-password-CHANGE-ME" export OPERATOR_HELM_CHART="mongodb/mongodb-kubernetes"# comma-separated key=value pairs for additional parameters passed to the helm-chart installing the operatorexport OPERATOR_ADDITIONAL_HELM_VALUES="" # TLS is mandatory; connection string must include tls=trueexport 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" export CERT_MANAGER_NAMESPACE="cert-manager" # Vector Search auto embedding related configurationsexport AUTO_EMBEDDING_API_KEY_SECRET_NAME="voyage-api-keys"export AUTO_EMBEDDING_API_QUERY_KEY="<embedding-model-query-key>"export AUTO_EMBEDDING_API_INDEXING_KEY="<embedding-model-indexing-key>"export PROVIDER_ENDPOINT="https://ai.mongodb.com/v1/embeddings"export EMBEDDING_MODEL="voyage-4"

Observação

Se você tiver as chaves de API para permitir que a pesquisa vetorial gere automaticamente incorporações, substitua os seguintes valores de espaço reservado nas variáveis de ambiente:

AUTO_EMBEDDING_API_QUERY_KEY

Chave API para gerar incorporações para o texto da query.

AUTO_EMBEDDING_API_INDEXING_KEY

Chave de API para gerar incorporações para dados de texto em sua coleção no momento do índice.

PROVIDER_ENDPOINT

Incorporando ponto de extremidade do provedor do modelo. O valor padrão é https://ai.mongodb.com/v1/embeddings para chaves criadas a partir da IU do Atlas. Substitua por https://api.voyageai.com/v1/embeddings se você criou as chaves API diretamente da Voyage IA.

2

O Helm automatiza a implantação e o gerenciamento de instâncias do MongoDB no Kubernetes. Se você já tiver o repositório Helm que contém o gráfico Helm para instalar o operador Kubernetes, ou pule esta etapa. Caso contrário, adicione o repositório Helm.

Para adicionar o repositório Helm, copie, cole e execute o seguinte:

helm repo add mongodb https://mongodb.github.io/helm-chartshelm repo update mongodbhelm search repo mongodb/mongodb-kubernetes
3

O Operador Kubernetes observa MongoDBCommunity e os recursos personalizados do MongoDBSearch e gerencia o ciclo de vida de suas implantações do MongoDB. Se você já instalou os Controladores MongoDB para Kubernetes operador, pule esta etapa. Caso contrário, instale os Controladores MongoDB para Kubernetes operador a partir do repositório Helm que você adicionou na etapa anterior.

Para instalar os Controladores MongoDB para o operador Kubernetes no namespace mongodb, copie, cole e execute os seguintes comandos:

helm upgrade --install --debug --kube-context "${K8S_CTX}" \ --create-namespace \ --namespace="${MDB_NS}" \ mongodb-kubernetes \ ${OPERATOR_ADDITIONAL_HELM_VALUES:+--set ${OPERATOR_ADDITIONAL_HELM_VALUES}} \ "${OPERATOR_HELM_CHART}"
4

Certifique-se de que o operador Kubernetes esteja totalmente operacional antes de prosseguir com a implantação do MongoDB pesquisa e pesquisa vetorial. Execute o comando a seguir para verificar se todos os componentes do operador estão em execução e disponíveis.

kubectl --context "${K8S_CTX}" -n "${MDB_NS}" rollout status --timeout=2m deployment/mongodb-kubernetes-operatorecho "Operator deployment in ${MDB_NS} namespace"kubectl --context "${K8S_CTX}" -n "${MDB_NS}" get deploymentsecho; echo "Operator pod in ${MDB_NS} namespace"kubectl --context "${K8S_CTX}" -n "${MDB_NS}" get pods
5

O MongoDB requer autenticação para acesso seguro. Nesta etapa, você cria três segredos do Kubernetes:

  • mdb-admin-user-password: Credenciais do administrador do MongoDB .

  • mdb-user-password: Credenciais do usuário autorizado a realizar queries de pesquisa.

  • mdbc-rs-search-sync-source-password: Credenciais para um usuário de pesquisa dedicado utilizado internamente pelo processo do mongot para sincronizar dados e gerenciar índices.

O Kubernetes operador usa senhas desses segredos para criar automaticamente os usuários no banco de dados MongoDB.

Para criar os segredos, copie, cole e execute o seguinte comando:

# Create admin user secretkubectl create secret generic mdb-admin-user-password \ --from-literal=password="${MDB_ADMIN_USER_PASSWORD}" \ --dry-run=client -o yaml | kubectl apply --context "${K8S_CTX}" --namespace "${MDB_NS}" -f - # Create search sync source user secretkubectl create secret generic "${MDB_RESOURCE_NAME}-search-sync-source-password" \ --from-literal=password="${MDB_SEARCH_SYNC_USER_PASSWORD}" \ --dry-run=client -o yaml | kubectl apply --context "${K8S_CTX}" --namespace "${MDB_NS}" -f - # Create regular user secretkubectl create secret generic mdb-user-password \ --from-literal=password="${MDB_USER_PASSWORD}" \ --dry-run=client -o yaml | kubectl apply --context "${K8S_CTX}" --namespace "${MDB_NS}" -f - echo "User secrets created."
6

O cert-manager é necessário para gerenciar certificados TLS. Se você já tiver o cert-manager instalado em seu cluster, pule esta etapa. Caso contrário, instale o cert-manager usando o Helm.

Para instalar o cert-manager no namespace cert-manager, execute o seguinte comando em seu terminal:

helm upgrade --install \ cert-manager \ oci://quay.io/jetstack/charts/cert-manager \ --kube-context "${K8S_CTX}" \ --namespace "${CERT_MANAGER_NAMESPACE}" \ --create-namespace \ --set crds.enabled=true for deployment in cert-manager cert-manager-cainjector cert-manager-webhook; do kubectl --context "${K8S_CTX}" \ -n "${CERT_MANAGER_NAMESPACE}" \ wait --for=condition=Available "deployment/${deployment}" --timeout=300sdone echo "cert-manager is ready in namespace ${CERT_MANAGER_NAMESPACE}."
7

Criar a infraestrutura da autoridade de certificação que emitirá certificados TLS para os recursos MongoDB e MongoDBSearch. Os comandos executam as seguintes ações:

  • Crie um ClusterIssuer autoassinado.

  • Gere um certificado CA.

  • Publique um emissor de CA em todo o cluster que todos os namespaces possam usar.

  • Exponha o pacote CA por meio de um ConfigMap para que os recursos do MongoDB possam usá-lo.

# Bootstrap a self-signed ClusterIssuer that will mint the CA material consumed by# the MongoDBCommunity deployment.kubectl apply --context "${K8S_CTX}" -f - <<EOF_MANIFESTapiVersion: cert-manager.io/v1kind: ClusterIssuermetadata: name: ${MDB_TLS_SELF_SIGNED_ISSUER}spec: selfSigned: {}EOF_MANIFEST kubectl --context "${K8S_CTX}" wait --for=condition=Ready clusterissuer "${MDB_TLS_SELF_SIGNED_ISSUER}" # Create the CA certificate and secret in the cert-manager namespace.kubectl apply --context "${K8S_CTX}" -f - <<EOF_MANIFESTapiVersion: cert-manager.io/v1kind: Certificatemetadata: name: ${MDB_TLS_CA_CERT_NAME} namespace: ${CERT_MANAGER_NAMESPACE}spec: isCA: true commonName: ${MDB_TLS_CA_CERT_NAME} secretName: ${MDB_TLS_CA_SECRET_NAME} privateKey: algorithm: ECDSA size: 256 issuerRef: name: ${MDB_TLS_SELF_SIGNED_ISSUER} kind: ClusterIssuerEOF_MANIFEST kubectl --context "${K8S_CTX}" wait --for=condition=Ready -n "${CERT_MANAGER_NAMESPACE}" certificate "${MDB_TLS_CA_CERT_NAME}" # Publish a cluster-scoped issuer that fronts the generated CA secret so all namespaces can reuse it.kubectl apply --context "${K8S_CTX}" -f - <<EOF_MANIFESTapiVersion: cert-manager.io/v1kind: ClusterIssuermetadata: name: ${MDB_TLS_CA_ISSUER}spec: ca: secretName: ${MDB_TLS_CA_SECRET_NAME}EOF_MANIFEST kubectl --context "${K8S_CTX}" wait --for=condition=Ready clusterissuer "${MDB_TLS_CA_ISSUER}" TMP_CA_CERT="$(mktemp)" kubectl --context "${K8S_CTX}" \ get secret "${MDB_TLS_CA_SECRET_NAME}" -n "${CERT_MANAGER_NAMESPACE}" \ -o jsonpath="{.data['ca\\.crt']}" | base64 --decode > "${TMP_CA_CERT}" # Expose the CA bundle through a ConfigMap for workloads and the MongoDBCommunity resource.kubectl --context "${K8S_CTX}" create configmap "${MDB_TLS_CA_CONFIGMAP}" -n "${MDB_NS}" \ --from-file=ca-pem="${TMP_CA_CERT}" --from-file=mms-ca.crt="${TMP_CA_CERT}" \ --from-file=ca.crt="${TMP_CA_CERT}" \ --dry-run=client -o yaml | kubectl --context "${K8S_CTX}" apply -f - echo "Cluster-wide CA issuer ${MDB_TLS_CA_ISSUER} is ready."
8

Emitir certificados TLS para o servidor MongoDB e para o serviço MongoDBSearch. O certificado do servidor MongoDB inclui todos os nomes DNS necessários para a comunicação do pod e do serviço. Ambos os certificados suportam autenticação de servidor e cliente.

server_certificate="${MDB_RESOURCE_NAME}-server-tls"search_certificate="${MDB_RESOURCE_NAME}-search-tls" mongo_dns_names=()for ((member = 0; member < MDB_MEMBERS; member++)); do mongo_dns_names+=("${MDB_RESOURCE_NAME}-${member}") mongo_dns_names+=("${MDB_RESOURCE_NAME}-${member}.${MDB_RESOURCE_NAME}-svc.${MDB_NS}.svc.cluster.local")donemongo_dns_names+=( "${MDB_RESOURCE_NAME}-svc.${MDB_NS}.svc.cluster.local" "*.${MDB_RESOURCE_NAME}-svc.${MDB_NS}.svc.cluster.local") search_dns_names=( "*.${MDB_RESOURCE_NAME}-search-0-svc.${MDB_NS}.svc.cluster.local") render_dns_list() { local dns_list=("$@") for dns in "${dns_list[@]}"; do printf " - \"%s\"\n" "${dns}" done} kubectl apply --context "${K8S_CTX}" -n "${MDB_NS}" -f - <<EOF_MANIFESTapiVersion: cert-manager.io/v1kind: Certificatemetadata: name: ${server_certificate} namespace: ${MDB_NS}spec: secretName: ${MDB_TLS_SERVER_CERT_SECRET_NAME} issuerRef: name: ${MDB_TLS_CA_ISSUER} kind: ClusterIssuer duration: 240h0m0s renewBefore: 120h0m0s usages: - digital signature - key encipherment - server auth - client auth dnsNames:$(render_dns_list "${mongo_dns_names[@]}")---apiVersion: cert-manager.io/v1kind: Certificatemetadata: name: ${search_certificate} namespace: ${MDB_NS}spec: secretName: ${MDB_SEARCH_TLS_SECRET_NAME} issuerRef: name: ${MDB_TLS_CA_ISSUER} kind: ClusterIssuer duration: 240h0m0s renewBefore: 120h0m0s usages: - digital signature - key encipherment - server auth - client auth dnsNames:$(render_dns_list "${search_dns_names[@]}")EOF_MANIFEST kubectl --context "${K8S_CTX}" -n "${MDB_NS}" wait --for=condition=Ready certificate "${server_certificate}" --timeout=300skubectl --context "${K8S_CTX}" -n "${MDB_NS}" wait --for=condition=Ready certificate "${search_certificate}" --timeout=300s echo "MongoDB TLS certificates have been issued."
9

Se você já tiver implantado a MongoDB Community Edition, pule esta etapa. Caso contrário, implante o MongoDB Community Edition.

Para implantar a MongoDB Community Edition, complete as seguintes etapas:

  1. Crie um recurso personalizado do MongoDBCommunity denominado mdb-rs.

    O recurso define os recursos de memória e CPU para os contêineres mongod e mongodb-agent e configura os três usuários a seguir:

    mdb-user

    Usuário que pode restaurar banco de dados e executar query de pesquisa. Este usuário utiliza o segredo mdb-user-password para executar estas operações.

    search-sync-source

    Usuário que o MongoDB Pesquisa usa para se conectar ao banco de dados MongoDB para gerenciar e construir índices. Este usuário usa a função searchCoordinator que o operador Kubernetes cria. Isso usa o segredo mdbc-rs-search-sync-source-password para conectar mongot a mongod.

    admin-user

    Usuário administrador do banco de dados.

    O operador Kubernetes utiliza este recurso para configurar um conjunto de réplicas MongoDB com 3 membros.

    Para criar os segredos, copie, cole e execute os seguintes comandos:

    kubectl apply --context "${K8S_CTX}" -n "${MDB_NS}" -f - <<EOFapiVersion: mongodbcommunity.mongodb.com/v1kind: MongoDBCommunitymetadata: name: ${MDB_RESOURCE_NAME}spec: version: ${MDB_VERSION} type: ReplicaSet members: ${MDB_MEMBERS} security: tls: enabled: true certificateKeySecretRef: name: ${MDB_TLS_SERVER_CERT_SECRET_NAME} caConfigMapRef: name: ${MDB_TLS_CA_CONFIGMAP} authentication: ignoreUnknownUsers: true modes: - SCRAM agent: logLevel: DEBUG statefulSet: spec: template: spec: containers: - name: mongod resources: limits: cpu: "2" memory: 2Gi requests: cpu: "1" memory: 1Gi - name: mongodb-agent resources: limits: cpu: "1" memory: 2Gi requests: cpu: "0.5" memory: 1Gi users: # admin user with root role - name: mdb-admin db: admin # a reference to the secret containing user password passwordSecretRef: name: mdb-admin-user-password scramCredentialsSecretName: mdb-admin-user roles: - name: root db: admin # user performing search queries - name: mdb-user db: admin # a reference to the secret containing user password passwordSecretRef: name: mdb-user-password scramCredentialsSecretName: mdb-user-scram roles: - name: restore db: sample_mflix - name: readWrite db: sample_mflix # user used by MongoDB Search to connect to MongoDB database to # synchronize data from. # For MongoDB <8.2, the operator will be creating the # searchCoordinator custom role automatically. # From MongoDB 8.2, searchCoordinator role will be a # built-in role. - name: search-sync-source db: admin # a reference to the secret that will be used to generate the user's password passwordSecretRef: name: ${MDB_RESOURCE_NAME}-search-sync-source-password scramCredentialsSecretName: ${MDB_RESOURCE_NAME}-search-sync-source roles: - name: searchCoordinator db: adminEOF
  2. Aguarde a conclusão do sistema de recursos MongoDBCommunity.

    Quando você aplica o recurso personalizado do MongoDBCommunity, o operador Kubernetes começa a distribuir os nós MongoDB (Pods). Essa etapa pausa a execução até que a fase de status do recurso mdbc-rs seja Running, o que indica que o conjunto de réplicas da MongoDB Community está operacional.

    echo "Waiting for MongoDBCommunity resource to reach Running phase..."kubectl --context "${K8S_CTX}" -n "${MDB_NS}" wait \ --for=jsonpath='{.status.phase}'=Running mdbc/mdbc-rs --timeout=400secho; echo "MongoDBCommunity resource"kubectl --context "${K8S_CTX}" -n "${MDB_NS}" get mdbc/mdbc-rsecho; echo "Pods running in cluster ${K8S_CTX}"kubectl --context "${K8S_CTX}" -n "${MDB_NS}" get pods
10

Você pode implantar uma instância do nó de pesquisa sem nenhum balanceamento de carga.

Para implantar, conclua as seguintes etapas:

  1. Crie um recurso personalizado do MongoDBSearch denominado mdbc-rs.

    Este recurso especifica os requisitos de recursos de CPU e memória para os nós de pesquisa. Para saber mais sobre as configurações neste recurso personalizado, consulte Configurações de pesquisa do MongoDB e Vector Search.

    # create a Kubernetes secret that would have embedding model's API Keyskubectl create secret generic "${AUTO_EMBEDDING_API_KEY_SECRET_NAME}" \ --from-literal=query-key="${AUTO_EMBEDDING_API_QUERY_KEY}" \ --from-literal=indexing-key="${AUTO_EMBEDDING_API_INDEXING_KEY}" --context "${K8S_CTX}" -n "${MDB_NS}" # create MongoDBSearch resource, enabling the auto embedding using the API Keys provided abovekubectl apply --context "${K8S_CTX}" -n "${MDB_NS}" -f - <<EOFapiVersion: mongodb.com/v1kind: MongoDBSearchmetadata: name: ${MDB_RESOURCE_NAME}spec: security: tls: certificateKeySecretRef: name: ${MDB_SEARCH_TLS_SECRET_NAME} autoEmbedding: providerEndpoint: ${PROVIDER_ENDPOINT} embeddingModelAPIKeySecret: name: ${AUTO_EMBEDDING_API_KEY_SECRET_NAME} clusters: - resourceRequirements: limits: cpu: "3" memory: 5Gi requests: cpu: "2" memory: 3GiEOF

    Observação

    Como o operador Kubernetes implanta apenas uma única instância do MongoDB Search, essa instância é configurada automaticamente como o gravador de visualizações materializadas de incorporação.

  2. Aguarde a conclusão da implantação do recurso MongoDBSearch.

    Quando você aplica o recurso personalizado MongoDBSearch, o operador Kubernetes começa a implantar os nós de pesquisa (Pods). Essa etapa pausa a execução até que a fase de status do recurso mdbc-rs MongoDBSearch seja Running, o que indica que a pesquisa do MongoDB está operacional.

    echo "Waiting for MongoDBSearch resource to reach Running phase..."kubectl --context "${K8S_CTX}" -n "${MDB_NS}" wait \ --for=jsonpath='{.status.phase}'=Running mdbs/"${MDB_RESOURCE_NAME}" --timeout=300s
11

Certifique-se de que a implantação do recurso MongoDBCommunity com o MongoDBSearch tenha sido bem-sucedida.

echo "Waiting for MongoDBCommunity resource to reach Running phase..."kubectl --context "${K8S_CTX}" -n "${MDB_NS}" wait \ --for=jsonpath='{.status.phase}'=Running mdbc/mdbc-rs --timeout=400secho; echo "MongoDBCommunity resource"kubectl --context "${K8S_CTX}" -n "${MDB_NS}" get mdbc/mdbc-rsecho; echo "Pods running in cluster ${K8S_CTX}"kubectl --context "${K8S_CTX}" -n "${MDB_NS}" get pods
12

Visualize todos os pods em execução nos pods do seu namespace para os nós do conjunto de réplicas do MongoDB , o operador do MongoDB Controladores for Kubernetes e os nós de pesquisa.

echo; echo "MongoDBCommunity resource"kubectl --context "${K8S_CTX}" -n "${MDB_NS}" get mdbc/mdbc-rsecho; echo "MongoDBSearch resource"kubectl --context "${K8S_CTX}" -n "${MDB_NS}" get mdbs/mdbc-rsecho; echo "Pods running in cluster ${K8S_CTX}"kubectl --context "${K8S_CTX}" -n "${MDB_NS}" get pods

Após a conclusão do procedimento, confirme se a implantação está saudável antes de executar as queries.

checkpoint
Etapa de verificação

MongoDB Community recurso em execução

Execute kubectl get mongodbcommunity -n <your-namespace> e confirme se o recurso MongoDBCommunity mostra a fase Running.

Recurso do MongoDB Search em execução

Execute kubectl get mongodbsearch -n <your-namespace> e confirme se o recurso MongoDBSearch mostra a fase Running.

Todos os pods estão saudáveis

Execute kubectl get pods -n <your-namespace> e confirme se todos os pods de nós do conjunto de réplicas e os pods de pesquisa mostram um status Running com todos os contêineres prontos.

query de pesquisa bem-sucedida

Conecte-se ao conjunto de réplicas e execute uma query de pesquisa do MongoDB ou uma query de pesquisa vetorial para confirmar se o índice de pesquisa está acessível.

Depois de implantar o MongoDB Search e a pesquisa vetorial com o MongoDB Community Edition, você pode: