Configuraciones de MongoDB Search y búsqueda vectorial

Configuraciones para la configuración de la fuente de datos

spec.source

Tipo: Objeto

Configuración que describe la fuente de MongoDB para mongot. La fuente puede ser un set de réplicas o un clúster particionado. Esta configuración es obligatoria si:

• MongoDB es externo

• MongoDB tiene un nombre diferente de MongoDBSearch

El recurso MongoDBSearch siempre debe estar conectado a una implementación de MongoDB. Si realizó la implementación usando el operador de Kubernetes con MongoDB o MongoDBCommunity CRD, y si spec.source está vacío, el operador de Kubernetes utiliza lo siguiente según el metadata.name para buscar la base de datos en Kubernetes:

• Encuentra MongoDB o MongoDBCommunity recursos con el mismo nombre que se establece para metadata.name en MongoDBSearch, en el mismo namespace.

• Encuentra el secreto de la contraseña para el usuario mongot del secreto <MongoDBSearch.metadata.name>-search-sync-source-password.

spec.source.mongodbResourceRef.name

Tipo: string

Nombre del recurso MongoDB o MongoDBCommunity para asociar con este recurso de MongoDB Search y búsqueda vectorial. El operador de Kubernetes admite tanto los sets de réplicas como los clústeres. No puede tener más de un recurso MongoDBSearch que haga referencia al mismo recurso MongoDB o MongoDBCommunity. Si especifica un nombre diferente, debe señalar explícitamente el MongoDB o MongoDBCommunity donde desea habilitar MongoDB Search y la búsqueda vectorial.

Si hace referencia a un recurso MongoDB de clúster particionado, el operador de Kubernetes autodetecta la topología de partición (nombres de partición, miembros del conjunto de réplicas, enrutadores mongos) y crea automáticamente conjuntos de estado mongot por partición. No es necesario realizar ninguna configuración externa adicional.

Este campo solo se debe utilizar si el recurso de MongoDB o MongoDBCommunity está implementado en el mismo clúster de Kubernetes y en el mismo espacio de nombres que el recurso de MongoDBSearch. Si configura este campo, el Operador de Kubernetes automáticamente:

• Establece las cadenas de conexión adecuadas a la base de datos.

• Reconfigura las implementaciones de la base de datos MongoDB estableciendo los parámetros necesarios para habilitar la funcionalidad de búsqueda y configurando las direcciones de los pods de búsqueda.

Si tu base de datos está implementada fuera de Kubernetes o se encuentra en un diferente namespace, usa spec.external para configurar la conexión a la base de datos. Este campo es excluyente con spec.external.

Si se omite, el Operador de Kubernetes busca un recurso MongoDB o MongoDBCommunity con el mismo nombre que este recurso MongoDBSearch.

Ajuste para configurar usuarios mongot

spec.source.username

Tipo: string

Nombre de usuario para usar para autenticar mongot con mongod. El usuario especificado debe tener el rol de searchCoordinator. Si se omite, el Operador Kubernetes asume que el nombre de usuario es search-sync-source.

spec.source.passwordSecretRef.name

Tipo: string

Nombre del secreto que contiene la contraseña que mongot debe utilizar para autenticar{se} con mongod. Si se omite, el valor por defecto es <MongoDBSearch.metadata.name>-search-sync-source-password.

spec.source.passwordSecretRef.key

Tipo: string

Clave bajo la cual se almacena el valor de la contraseña en el secreto. Si se omite, el valor por defecto es password.

Configuración para la autenticación x509

spec.source.x509

Tipo: Objeto

Configura la autenticación mediante certificado de cliente x509 para la conexión de sincronización mongot. Si configuras este campo, mongot se autenticará en MongoDB usando x509 en lugar de nombre de usuario y contraseña.

Este campo es mutuamente exclusivo con spec.source.passwordSecretRef y spec.source.username. El operador de Kubernetes rechaza la configuración si se especifican tanto x509 como la autenticación por contraseña.

spec.source.x509.clientCertificateSecretRef

Tipo: Objeto

Secreto que contiene el certificado de cliente x509 y la clave para la autenticación en la fuente de sincronización de MongoDB. El secreto debe contener las siguientes claves:

• tls.crt — Certificado de cliente (obligatorio)

• tls.key — Llave privada (obligatoria)

• tls.keyFilePassword — Contraseña para la clave privada (opcional)

Debe especificar este campo si configura spec.source.x509.

Ejemplo

spec:
  source:
    x509:
      clientCertificateSecretRef:
        name: mongot-x509-client-cert

Configuraciones para conectar con MongoDB externo

Las siguientes configuraciones solo son necesarias para configurar una conexión a una implementación externa de MongoDB.

spec.source.external

Tipo: Objeto

Configuraciones que describen la fuente de datos externa. Este objeto describe la configuración del recurso de MongoDB Search y búsqueda vectorial para conectarse a un MongoDB externo. Estos ajustes solo deben especificarse si deseas conectarte a una MongoDB externa que no fue implementada mediante el Operador de Kubernetes. Si se especifica, estas configuraciones anulan las configuraciones para spec.source.mongodbResourceRef.name. Si usaste el Operador de Kubernetes para instalar MongoDB en el mismo clúster, estas configuraciones son opcionales.

Ajustes para la Seguridad

spec.security

Tipo: Objeto

Configuración de seguridad del servidor de escucha mongot.

spec.security.tls

Tipo: Objeto

TLS configuración para mongot. Si se omite, mongot no utilizará TLS para conexiones entrantes.

spec.security.tls.certificateKeySecretRef.name

Tipo: string

Obsoleto desde la versión 1.8.0: Utiliza spec.security.tls.certsSecretPrefix en su lugar.

Nombre del secreto TLS en el mismo namespace que contiene la llave privada (tls.key) y el certificado (tls.crt). El secreto puede ser de tipo kubernetes.io/tls (emitido por cert-manager) o puede crearse manualmente.

El Operador de Kubernetes sigue admitiendo este campo para las implementaciones de conjuntos de réplicas por motivos de compatibilidad con versiones anteriores. Sin embargo:

• Para implementaciones de clúster segmentado, el operador de Kubernetes rechaza este campo durante la validación. Utilice spec.security.tls.certsSecretPrefix en su lugar, porque una referencia individual de secreto no puede cubrir certificados por partición.

• Si especificas tanto certificateKeySecretRef como certsSecretPrefix, certificateKeySecretRef tiene prioridad para los despliegues en conjuntos de réplicas.

Para nuevas implementaciones, usa spec.security.tls.certsSecretPrefix incluso para set de réplicas.

spec.security.tls.certsSecretPrefix

Tipo: string

Prefijo que el Operador de Kubernetes utiliza para derivar los nombres de los secretos TLS según la convención de nomenclatura. Si configuras este campo, el operador de Kubernetes busca secretos que siguen estos patrones en lugar de requerir referencias explícitas de secretos para cada componente:

Componente	Patrón de nombre secreto
Certificado del set de réplicas mongot servidor	{certsSecretPrefix}-{name}-search-cert
Certificado particionado mongot (por partición)	{certsSecretPrefix}-{name}-search-0-{shardName}-cert
Certificado del servidor de balanceador de carga administrado	{certsSecretPrefix}-{name}-search-lb-0-cert
Certificado de cliente de balanceador de carga gestionado	{certsSecretPrefix}-{name}-search-lb-0-client-cert

Dónde:

• {name} es metadata.name del recurso MongoDBSearch

• {shardName} es el valor que spec.source.external.shardedCluster.shards[*].shardName

Si se omite, este campo se restablece a una string vacía y el operador Kubernetes utiliza spec.security.tls.certificateKeySecretRef en su lugar.

Nota

Para implementaciones de clúster particionado, debes usar certsSecretPrefix en lugar de certificateKeySecretRef. El operador de Kubernetes rechaza certificateKeySecretRef para las topologías particionadas porque una única referencia de secreto no puede cubrir los certificados por partición.

Ejemplo

spec:
  security:
    tls:
      certsSecretPrefix: my-prefix

Configuración para múltiples instancias de Mongot

spec.replicas

Tipo: entero

Número de pods mongot a desplegar. Para una fuente de set de réplicas, este es el número total de pods mongot. Para una fuente de clúster con partición, este es el número de pods mongot por partición.

Si spec.replicas es mayor que 1, debe configurar también spec.loadBalancer para enrutar el tráfico entre mongod y las múltiples instancias de mongot.

Si se omite, es por defecto 1.

Ejemplo

spec:
  replicas: 2

Configuración para balanceo de carga

spec.loadBalancer

Tipo: Objeto

Configuración para el balanceo de carga L7 entre mongod (u mongos) y mongot. Este campo es obligatorio si spec.replicas es mayor que 1. Si spec.replicas es 1, este campo es opcional. Puedes configurar un balanceador de carga incluso para una sola instancia mongot para prepararte para un escalado posterior.

Se debe establecer exactamente solo uno de managed o unmanaged.

El equilibrador de carga afecta el tipo de certificados TLS que ven los clientes de mongod y los nombres de host que deben contener esos certificados:

• Sin un balanceador de carga, mongod se conecta directamente a mongot. El certificado TLS presentado a mongod es el propio certificado de mongot. Si el clúster de MongoDB está fuera de Kubernetes, el servicio mongot está expuesto en un dominio externo. Debe incluir ese dominio externo en el campo SAN (Nombre Alternativo del Sujeto) del certificado TLS mongot.

• Con un balanceador de carga gestionado (spec.loadBalancer.managed), el proxy Envoy es el único componente que se conecta directamente a mongot. Envoy accede a mongot pods utilizando sus FQDN internos de Servicio sin cabeza:

  • set de réplicas: <pod>.<name>-search-svc.<ns>.svc.cluster.local

  • clúster particionado: <pod>.<name>-search-0-<shard>-svc.<ns>.svc.cluster.local

  Emita el certificado TLS mongot con estos dominios locales del clúster en el campo SAN. Puede usar un certificado wildcard para evitar la reemisión de certificados cuando cambie el número de pods mongot. Los procesos externos mongod ven el certificado TLS del proxy Envoy, por lo que deben incluir dominos externos en los SANs del certificado Envoy y no en el certificado mongot.

Tip

Permite un balanceador de carga administrado incluso si inicialmente implementas un solo pod mongot. Con el balanceador de carga en funcionamiento, los dominios en tus certificados TLS se mantienen estables si más adelante escalas spec.replicas porque el balanceador de carga ya está presente entre mongod y mongot.

spec.loadBalancer.managed

Tipo: Objeto

Configura un Envoy balanceador de carga gestionado por el operador. El Operador Kubernetes despliega y gestiona el proxy Envoy con un enrutamiento correcto, mTLS y fijación de flujos HTTP/2+ gRPC. Configura este campo a un objeto vacío ({}) para usar los valores por defecto.

Este campo es excluyente con spec.loadBalancer.unmanaged.

Ejemplo

spec:
  loadBalancer:
    managed: {}

spec.loadBalancer.managed.externalHostname

Tipo: string

Nombre de host que el proxy Envoy espera para la coincidencia SNI en las solicitudes entrantes. El Operador de Kubernetes utiliza este valor para configurar reglas de enrutamiento que coincidan con el campo TLS SNI de las conexiones entrantes mongod. El certificado de servidor Envoy TLS debe incluir este nombre de host en su campo SAN (Nombre Alternativo del Sujeto).

Para clústeres segmentados, el valor debe contener un marcador de posición {shardName} que el Operador de Kubernetes amplía por partición. Cada partición recibe un nombre de host único y el certificado del servidor Envoy TLS debe incluir todos los nombres de host ampliados de las particiones en sus SANs. Puedes utilizar un certificado comodín para abarcar todas las particiones con un solo certificado y evitar tener que volver a emitirlo cuando se añadan nuevas particiones.

Este campo es obligatorio si MongoDB se gestiona externamente (no implementado por el Operador de Kubernetes). Si MongoDB está gestionado por el operador en el mismo clúster, omita este campo porque el Operador de Kubernetes configura automáticamente el enrutamiento.

Ejemplo

# Replica set with external MongoDB
spec:
  loadBalancer:
    managed:
      externalHostname: "search.apps.example.com"
# Sharded cluster with external MongoDB
spec:
  loadBalancer:
    managed:
      externalHostname: "{shardName}.search.example.com"

spec.loadBalancer.managed.resourceRequirements

Tipo: core/v1/ResourceRequirements

CPU y memoria que el contenedor Envoy puede solicitar y limitar. Si especifica esta configuración, el operador de Kubernetes reemplaza por completo los valores por defecto.

Si se omite, el Operador de Kubernetes utiliza los siguientes valores por defecto:

requests:
  cpu: 100m
  memory: 128Mi
limits:
  cpu: 500m
  memory: 512Mi

Ejemplo

spec:
  loadBalancer:
    managed:
      resourceRequirements:
        requests:
          cpu: "200m"
          memory: "256Mi"
        limits:
          cpu: "1"
          memory: "1Gi"

spec.loadBalancer.managed.deployment

Tipo: Objeto

Anulaciones que el Operador de Kubernetes fusiona en la Implementación de Envoy creada por el operador. Sigue la misma convención que spec.statefulSet en recursos de MongoDB. Si se omite, el Operador de Kubernetes utiliza los valores por defecto para el Despliegue de Envoy.

Este objeto contiene dos campos:

• metadata — contiene los campos labels y annotations que el Operador de Kubernetes fusiona en los metadatos de la implementación de Envoy.

• spec — un objeto apps/v1/DeploymentSpec. El operador de Kubernetes fusiona estos valores anulados en la especificación de implementación de Envoy.

Ejemplo

spec:
  loadBalancer:
    managed:
      deployment:
        spec:
          template:
            spec:
              nodeSelector:
                kubernetes.io/os: linux

spec.loadBalancer.unmanaged

Tipo: Objeto

Configura un balanceador de carga L7 proporcionado por el usuario (Bring Your Own). Tú eres responsable de implementar y configurar el balanceador de carga externamente.

Este campo es excluyente con spec.loadBalancer.managed.

spec.loadBalancer.unmanaged.endpoint

Tipo: string

El endpoint del balanceador de carga BYO en el formato host:port. El Kubernetes operador escribe este valor en la configuración mongod como mongotHost y searchIndexManagementHostAndPort.

Este campo solo es obligatorio cuando el Operador de Kubernetes gestiona la implementación de MongoDB (utilizando spec.source.mongodbResourceRef), porque el Operador de Kubernetes necesita el endpoint para configurar los parámetros de mongod. Si tanto el balanceador de carga como MongoDB son externos (no gestionados por el Operador de Kubernetes), este campo no es obligatorio porque usted mismo configura los parámetros mongod.

Para clústeres fragmentados, el valor debe contener un marcador de posición {shardName} que el Operador de Kubernetes expanda por partición.

Ejemplo

# Replica set example
spec:
  loadBalancer:
    unmanaged:
      endpoint: "search-lb.corp.example.com:443"
# Sharded cluster example
spec:
  loadBalancer:
    unmanaged:
      endpoint: "{shardName}-lb.corp.example.com:443"

Configuraciones para el provisionamineto de recursos

spec.resourceRequirements

Tipo: core/v1/ResourceRequirements

CPU y memoria que el contenedor mongodb-search puede solicitar y tener limitados. Recomendamos utilizar este campo para personalizar las asignaciones de recursos en lugar de sobrescribirlo con spec.statefulSet.

Si no anulas el tamaño del heap de la JVM en spec.jvmFlags, el Operador de Kubernetes establece el tamaño por defecto del heap (-Xmx) en el 50% de la memoria disponible para el pod mongot. Ajuste spec.resourceRequirements en consecuencia para controlar tanto los recursos del pod como el tamaño del heap de la JVM.

Si se omite, el Operador de Kubernetes utiliza los siguientes valores por defecto:

requests:
  cpu: 2
  memory: 2G

spec.resourceRequirements.limits

Tipo: Objeto

Límite superior en el recurso, CPU y memoria, que el contenedor mongodb-search puede consumir. Por defecto, no se establecen límites. Si se omite, el pod no está restringido y, por lo tanto, podría usar todos los recursos del nodo. Recomendamos establecer límites según su carga de trabajo.

spec.resourceRequirements.requests

Tipo: Objeto

Cantidad de CPU y memoria solicitada para el contenedor mongodb-search. En ausencia de valores especificados, el Operador de Kubernetes utilizará los siguientes valores por defecto:

requests:
  cpu: 2
  memory: 2G

spec.persistence.single

Tipo: Objeto

Configuración de almacenamiento para el volumen persistente de MongoDB Search y búsqueda vectorial donde se almacenan los índices de MongoDB Search y búsqueda vectorial. Cada instancia de búsqueda (pod) tiene su propio almacenamiento independiente para mantener índices, que no se comparte con la base de datos MongoDB. Solo los metadatos del índice (definiciones) se almacenan en la propia base de datos.

Escalar	Tipo de dato	Descripción
labelSelector	string	Etiqueta utilizada para vincular volúmenes montados a directorios.
storage	string	Tamaño mínimo de Volumen Persistente que debe montarse. Este valor se expresa como un número entero seguido de una unidad de almacenamiento en notación JEDEC. El valor por defecto es 16 Gi. Por ejemplo, si set de réplicas requiere 60 gigabytes de espacio de almacenamiento, establece este valor en 60Gi.
storageClass	string	Tipo de almacenamiento especificado en un Reclamo de volumen persistente. Puede crear este tipo de almacenamiento como un objeto StorageClass antes de usarlo en esta especificación de objeto. Asegúrate de establecer el StorageClass reclaimPolicy como Retain. Esto garantiza que los datos se conserven cuando se elimine una Solicitud de Volumen Persistente.

MongoDBSearch solo admite el campo de persistencia single. Si se omite, el Kubernetes operador establece spec.persistence.single.storage a 10GB.

Configuraciones para registros

spec.logLevel

Tipo: string

Nivel de verbosidad de los registros de mongot. El valor puede ser uno de los siguientes:

• TRACE

• DEBUG

• INFO

• WARN

• ERROR

Si se omite, es por defecto INFO.

Configuración para métricas

spec.prometheus

Tipo: Objeto

Esta función sólo está disponible en la versión v1.6 y posteriores.

Configuración para habilitar el endpoint de métricas de Prometheus. Si se omite, se desactiva el endpoint de métricas en mongot. Para habilitar el endpoint de métricas de Prometheus en el puerto por defecto (9946), especifica un objeto {} vacío en el campo spec.prometheus. Para cambiar el puerto, configúralo en el campo spec.prometheus.port.

spec.prometheus.port

Tipo: string

Puerto en el que habilitar el endpoint de métricas de Prometheus. De forma predeterminada, el endpoint de métricas de Prometheus está habilitado en el puerto 9946.

Configuraciones para incrustación automatizada

spec.autoEmbedding

Tipo: Objeto

Configuración para Incrustación automátizada para datos de texto en tu colección.

spec.autoEmbedding.embeddingModelAPIKeySecret

Tipo: Objeto

Configuración para el proveedor de modelos de incrustación API keys. Para habilitar la Embedding Automatizada, debes crear dos claves, una para generar embedding en el momento del índice para los datos de tu colección y otra para generar embedding en el momento de la query para el texto de la query. Si no tienes ya las llaves, te recomendamos que crees llaves a partir de dos proyectos de Atlas. Para obtener más información sobre la creación de claves para los proyectos Atlas desde la Interfaz de Usuario de Atlas, consulte Gestionar claves API.

spec.autoEmbedding.embeddingModelAPIKeySecret.name

Tipo: string

Nombre del secreto que contiene las llaves de la API del modelo de incrustación que mongot debe utilizar para generar incrustaciones en el momento del índice y de la query.

spec.autoEmbedding.providerEndpoint

Tipo: string

URL de endpoint del modelo de incrustaciones para generar incrustaciones. El valor varía según si creas las claves desde la Interfaz de usuario de Atlas (recomendado) o directamente desde el servicio de incrustaciones (Voyage IA). Para las claves creadas a partir de:

• Atlas Interfaz de Usuario, el valor es https://ai.mongodb.com/v1/embeddings (por defecto)

• Voyage IA, el valor es https://api.voyageai.com/v1/embeddings

Configuración para JVM

spec.jvmFlags

Tipo: arreglo de cadenas

Señales de JVM pasadas al proceso mongot. El operador de Kubernetes incluye las banderas sin modificaciones en el comando de inicio mongot usando --jvm-flags "<all flags space-separated>".

Si no especifica -Xms o -Xmx en este campo, el Operador de Kubernetes calcula automáticamente el tamaño del heap configurando ambos en la mitad de spec.resourceRequirements.requests.memory. Si no se especifican los requisitos de recursos, el Operador de Kubernetes utiliza un valor predeterminado de 4Gi de solicitud de memoria, lo que genera aproximadamente -Xmx2048m -Xms2048m.

Si proporciona sus propios valores de -Xms o -Xmx, el operador de Kubernetes los utiliza y no los anula. El Operador de Kubernetes siempre añade los parámetros que usted proporciona después de los parámetros calculados por el operador.

Para más información, consulte Dimensionamiento del hardware para mongot.

Ejemplo

spec:
  jvmFlags:
    - -Xms2g
    - -Xmx2g

Otros ajustes

spec.version

Tipo: string

Versión de mongodb-search imagen docker. Si se omite, el Operador de Kubernetes elige automáticamente la versión más reciente de MongoDBSearch. Puedes establecerlo explícitamente para evitar actualizaciones automáticas cuando se actualice la versión del Operador de Kubernetes.

spec.statefulSet

Tipo: apps/v1/StatefulSet

Especificación para el StatefulSet, creado para la implementación de mongot pods que sobrescribe la configuración aplicada por el operador de Kubernetes. Las sobrescrituras siempre se aplican al final. Admite tanto los campos spec.statefulSet.spec como spec.statefulSet.metadata.

Nota

No establezcas requisitos de recursos o configuraciones de persistencia usando spec.statefulSet. En su lugar, utilice los campos spec.resourceRequirements y spec.persistence respectivamente.