Para agentes de IA: hay un índice de documentación disponible en https://www.mongodb.com/es/docs/llms.txt — versiones en markdown de todas las páginas están disponibles agregando .md a cualquier ruta URL.
Docs Menu

Instalar y usar con MongoDB Community Edition

Puedes usar el operador de Kubernetes e implementar los recursos del proceso mongot para ejecutar con MongoDB Community Edition v8.2.0 o superior en un clúster de Kubernetes. El proceso mongot es compatible con MongoDB Search y la búsqueda vectorial. El siguiente procedimiento demuestra cómo implementar y configurar MongoDB Search y la búsqueda vectorial para ejecutar con un set de réplicas nuevo o existente en tu clúster de Kubernetes. La implementación utiliza certificados TLS para garantizar una comunicación segura entre los nodos de MongoDB y el proceso de búsqueda mongot.

Para implementar MongoDB Search y búsqueda vectorial, se debe contar con lo siguiente:

  • Un clúster de Kubernetes en ejecución.

  • Herramienta de línea de comandos de Kubernetes, kubectl, configurada para comunicarse con su clúster.

  • Helm, el gestor de paquetes para Kubernetes, para instalar el Operador de Kubernetes.

  • cert-manager o una solución alternativa de gestión de certificados para el aprovisionamiento de certificados TLS.

  • Bash v5.1 o superior para ejecutar los comandos en este tutorial.

1

Configura las variables de entorno para usarlas en los pasos siguientes de este procedimiento. Copia los siguientes comandos, actualiza los valores de tu entorno y ejecútalos para cargar las variables:

1# set it to the context name of the k8s cluster
2export K8S_CTX="<local cluster context>"
3
4# the following namespace will be created if not exists
5export MDB_NS="mongodb"
6
7# MongoDBCommunity resource name referenced throughout the guide
8export MDB_RESOURCE_NAME="mdbc-rs"
9# Number of replica set members deployed in the sample MongoDBCommunity
10export MDB_MEMBERS=3
11
12# TLS-related secret names used for MongoDBCommunity and MongoDBSearch
13export MDB_TLS_CA_SECRET_NAME="${MDB_RESOURCE_NAME}-ca"
14export MDB_TLS_SERVER_CERT_SECRET_NAME="${MDB_RESOURCE_NAME}-tls"
15export MDB_SEARCH_TLS_SECRET_NAME="${MDB_RESOURCE_NAME}-search-tls"
16
17export MDB_TLS_CA_CONFIGMAP="${MDB_RESOURCE_NAME}-ca-configmap"
18export MDB_TLS_SELF_SIGNED_ISSUER="${MDB_RESOURCE_NAME}-selfsigned-cluster-issuer"
19export MDB_TLS_CA_CERT_NAME="${MDB_RESOURCE_NAME}-selfsigned-ca"
20export MDB_TLS_CA_ISSUER="${MDB_RESOURCE_NAME}-cluster-issuer"
21
22# minimum required MongoDB version for running MongoDB Search is 8.2.0
23export MDB_VERSION="8.2.0"
24
25# root admin user for convenience, not used here at all in this guide
26export MDB_ADMIN_USER_PASSWORD="admin-user-password-CHANGE-ME"
27# regular user performing restore and search queries on sample mflix database
28export MDB_USER_PASSWORD="mdb-user-password-CHANGE-ME"
29# user for MongoDB Search to connect to the replica set to synchronise data from
30export MDB_SEARCH_SYNC_USER_PASSWORD="search-sync-user-password-CHANGE-ME"
31
32export OPERATOR_HELM_CHART="mongodb/mongodb-kubernetes"
33# comma-separated key=value pairs for additional parameters passed to the helm-chart installing the operator
34export OPERATOR_ADDITIONAL_HELM_VALUES=""
35
36# TLS is mandatory; connection string must include tls=true
37export MDB_CONNECTION_STRING="mongodb://mdb-user:${MDB_USER_PASSWORD}@${MDB_RESOURCE_NAME}-0.${MDB_RESOURCE_NAME}-svc.${MDB_NS}.svc.cluster.local:27017/?replicaSet=${MDB_RESOURCE_NAME}&tls=true&tlsCAFile=/tls/ca.crt"
38
39export CERT_MANAGER_NAMESPACE="cert-manager"

Validar que las variables de entorno hayan sido establecidas.

Para verificar que todas las variables de entorno necesarias estén configuradas, ejecute el siguiente código en su terminal:

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 automatiza la implementación y la gestión de instancias de MongoDB en Kubernetes. Si ya tiene el repositorio de Helm que contiene la gráfica de Helm para instalar el operador de Kubernetes o omitir este paso. De lo contrario, añade el repositorio de Helm.

Para agregar el repositorio de Helm, copia, pega y ejecuta lo siguiente:

1helm repo add mongodb https://mongodb.github.io/helm-charts
2helm repo update mongodb
3helm search repo mongodb/mongodb-kubernetes
3

El operador de Kubernetes supervisa MongoDBCommunity y los recursos personalizados MongoDBSearch y gestiona el ciclo de vida de tus implementaciones de MongoDB. Si ya ha instalado los MongoDB Controllers para Kubernetes operador, omita este paso. De lo contrario, instala los Controladores de MongoDB para el Operador de Kubernetes desde el repositorio Helm que agregaste en el paso anterior.

Para instalar los controladores de MongoDB para Kubernetes operador en el namespace mongodb, copie, pegue y ejecute los siguientes comandos:

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}"
4

Asegúrate de que el Kubernetes operador esté completamente operativo antes de proseguir con la implementación de MongoDB Search y búsqueda vectorial. Ejecute el siguiente comando para verificar que todos los componentes del operador estén en ejecución y disponibles.

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
5

MongoDB requiere autenticación para un acceso seguro. En este paso, se crean tres secretos de Kubernetes:

  • mdb-admin-user-password: Credenciales para el administrador de MongoDB.

  • mdb-user-password: Credenciales para el usuario autorizado a realizar consultas de búsqueda.

  • mdbc-rs-search-sync-source-password: Credenciales para un usuario de búsqueda dedicado usado internamente por el proceso mongot para sincronizar datos y administrar índices.

Kubernetes operador utiliza contraseñas de esos secretos para crear automáticamente a los usuarios en la base de datos de MongoDB.

Para crear los secretos, copia, pega y ejecuta el siguiente comando:

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."
6

El cert-manager es necesario para gestionar TLS certificados. Si ya tienes cert-manager instalado en tu clúster, omite este paso. De lo contrario, instala cert-manager utilizando Helm.

Para instalar cert-manager en el namespace cert-manager, ejecuta el siguiente comando en tu terminal:

1helm upgrade --install \
2 cert-manager \
3 oci://quay.io/jetstack/charts/cert-manager \
4 --kube-context "${K8S_CTX}" \
5 --namespace "${CERT_MANAGER_NAMESPACE}" \
6 --create-namespace \
7 --set crds.enabled=true
8
9for deployment in cert-manager cert-manager-cainjector cert-manager-webhook; do
10 kubectl --context "${K8S_CTX}" \
11 -n "${CERT_MANAGER_NAMESPACE}" \
12 wait --for=condition=Available "deployment/${deployment}" --timeout=300s
13done
14
15echo "cert-manager is ready in namespace ${CERT_MANAGER_NAMESPACE}."
7

Cree la infraestructura de la autoridad certificadora que emitirá certificados TLS para los recursos MongoDB y MongoDBSearch. Los comandos realizan las siguientes acciones:

  • Crear un ClusterIssuer autofirmado.

  • Genera un certificado de CA.

  • Publica un emisor de CA para todo el clúster que todos los namespaces puedan utilizar.

  • Exponga el paquete CA a través de un ConfigMap para que los recursos de MongoDB puedan usarlo.

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

Emita certificados TLS tanto para el servidor MongoDB como para el servicio MongoDBSearch. El certificado del servidor de MongoDB incluye todos los nombres DNS necesarios para la comunicación de pods y servicios. Ambos certificados admiten autenticación de servidor y cliente.

1server_certificate="${MDB_RESOURCE_NAME}-server-tls"
2search_certificate="${MDB_RESOURCE_NAME}-search-tls"
3
4mongo_dns_names=()
5for ((member = 0; member < MDB_MEMBERS; member++)); do
6 mongo_dns_names+=("${MDB_RESOURCE_NAME}-${member}")
7 mongo_dns_names+=("${MDB_RESOURCE_NAME}-${member}.${MDB_RESOURCE_NAME}-svc.${MDB_NS}.svc.cluster.local")
8done
9mongo_dns_names+=(
10 "${MDB_RESOURCE_NAME}-svc.${MDB_NS}.svc.cluster.local"
11 "*.${MDB_RESOURCE_NAME}-svc.${MDB_NS}.svc.cluster.local"
12)
13
14search_dns_names=(
15 "${MDB_RESOURCE_NAME}-search-svc.${MDB_NS}.svc.cluster.local"
16)
17
18render_dns_list() {
19 local dns_list=("$@")
20 for dns in "${dns_list[@]}"; do
21 printf " - \"%s\"\n" "${dns}"
22 done
23}
24
25kubectl apply --context "${K8S_CTX}" -n "${MDB_NS}" -f - <<EOF_MANIFEST
26apiVersion: cert-manager.io/v1
27kind: Certificate
28metadata:
29 name: ${server_certificate}
30 namespace: ${MDB_NS}
31spec:
32 secretName: ${MDB_TLS_SERVER_CERT_SECRET_NAME}
33 issuerRef:
34 name: ${MDB_TLS_CA_ISSUER}
35 kind: ClusterIssuer
36 duration: 240h0m0s
37 renewBefore: 120h0m0s
38 usages:
39 - digital signature
40 - key encipherment
41 - server auth
42 - client auth
43 dnsNames:
44$(render_dns_list "${mongo_dns_names[@]}")
45---
46apiVersion: cert-manager.io/v1
47kind: Certificate
48metadata:
49 name: ${search_certificate}
50 namespace: ${MDB_NS}
51spec:
52 secretName: ${MDB_SEARCH_TLS_SECRET_NAME}
53 issuerRef:
54 name: ${MDB_TLS_CA_ISSUER}
55 kind: ClusterIssuer
56 duration: 240h0m0s
57 renewBefore: 120h0m0s
58 usages:
59 - digital signature
60 - key encipherment
61 - server auth
62 - client auth
63 dnsNames:
64$(render_dns_list "${search_dns_names[@]}")
65EOF_MANIFEST
66
67kubectl --context "${K8S_CTX}" -n "${MDB_NS}" wait --for=condition=Ready certificate "${server_certificate}" --timeout=300s
68kubectl --context "${K8S_CTX}" -n "${MDB_NS}" wait --for=condition=Ready certificate "${search_certificate}" --timeout=300s
69
70echo "MongoDB TLS certificates have been issued."
9

Si ya implementaste MongoDB Community Edition, omite este paso. De lo contrario, implementa la versión Community Edition de MongoDB.

Para implementar la Community Edition de MongoDB, complete los siguientes pasos:

  1. Crear un recurso personalizado MongoDBCommunity denominado mdb-rs.

    El recurso define los recursos de CPU y memoria para los contenedores mongod y mongodb-agent, y configura los siguientes tres usuarios:

    mdb-user

    Usuario que puede restaurar bases de datos y ejecutar consultas de búsqueda. Este usuario utiliza el secreto mdb-user-password para realizar estas operaciones.

    search-sync-source

    Usuario que MongoDB Search utiliza para conectarse a la base de datos de MongoDB con el fin de gestionar y construir índices. Este usuario utiliza el rol searchCoordinator que crea el operador de Kubernetes. Esto utiliza el secreto mdbc-rs-search-sync-source-password para conectar mongot a mongod.

    admin-user

    Usuario administrador de base de datos.

    El Operador de Kubernetes utiliza este recurso para configurar un set de réplicas de MongoDB con 3 nodos.

    Para crear los secretos, copia, pega y ejecuta los siguientes comandos:

    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. Espera a que se complete la implementación del recurso MongoDBCommunity.

    Cuando se aplica el recurso personalizado MongoDBCommunity, el operador de Kubernetes comienza a implementar los nodos de MongoDB (pods). Este paso pausa la ejecución hasta que la fase de estado del recurso mdbc-rs sea Running, lo que indica que el conjunto de réplicas MongoDB Community está operativo.

    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
10

Puedes implementar una instancia del nodo de búsqueda sin balanceo de carga. Para implementar, completa los siguientes pasos:

  1. Crea un recurso personalizado MongoDBSearch llamado mdbc-rs.

    Este recurso especifica los requisitos de recursos de CPU y memoria para los nodos de búsqueda. Para obtener más información sobre la configuración de este recurso personalizado, consulte Configuración de MongoDB Search y búsqueda vectorial.

    1kubectl apply --context "${K8S_CTX}" -n "${MDB_NS}" -f - <<EOF
    2apiVersion: mongodb.com/v1
    3kind: MongoDBSearch
    4metadata:
    5 name: ${MDB_RESOURCE_NAME}
    6spec:
    7 security:
    8 tls:
    9 certificateKeySecretRef:
    10 name: ${MDB_SEARCH_TLS_SECRET_NAME}
    11 resourceRequirements:
    12 limits:
    13 cpu: "3"
    14 memory: 5Gi
    15 requests:
    16 cpu: "2"
    17 memory: 3Gi
    18EOF
  2. Espere a que se complete la implementación del recurso MongoDBSearch.

    Cuando aplicas el recurso personalizado MongoDBSearch, el operador de Kubernetes comienza a desplegar los nodos de búsqueda (pods). Esta fase pausa la ejecución hasta que el estado del recurso mdbc-rs MongoDBSearch esté en la fase Running, lo que indica que MongoDB Search está operativo.

    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

Asegúrese de que la implementación de recursos de MongoDBCommunity con MongoDBSearch haya sido exitosa.

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

Visualiza todos los pods en ejecución en los pods de tu namespace para los miembros del set de réplicas MongoDB, los Controladores MongoDB para Kubernetes operador y los nodos de búsqueda.

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

Ahora que ha implementado correctamente MongoDB Search y búsqueda vectorial para usarlos con MongoDB Community Edition, proceda a agregar datos a su clúster de MongoDB, cree índices de MongoDB Search y búsqueda vectorial y ejecute queries sobre sus datos. Para obtener más información, consulta Usa MongoDB Search y Búsqueda Vectorial.