MongoDB Search and Vector Search Settings

Settings for Configuring the Data Source

spec.source

Type: object

Setting that describes the MongoDB source for mongot. The source can be a replica set or a sharded cluster. This setting is required if:

• MongoDB is external

• MongoDB has a different name from MongoDBSearch

The MongoDBSearch resource must always be connected to a MongoDB deployment. If you deployed using the Kubernetes Operator with MongoDB or MongoDBCommunity CRD, and if spec.source is empty, the Kubernetes Operator uses the following based on the metadata.name to look for the database in Kubernetes:

• Find MongoDB or MongoDBCommunity resources with the same name as set for metadata.name in MongoDBSearch, in the same namespace.

• Find the password secret for the mongot user from the <MongoDBSearch.metadata.name>-search-sync-source-password secret.

spec.source.mongodbResourceRef.name

Type: string

Name of the MongoDB or MongoDBCommunity resource to associate with this MongoDB Search and Vector Search resource. The Kubernetes Operator supports both replica sets and sharded clusters. You can't have more than one MongoDBSearch resource referencing the same MongoDB or MongoDBCommunity resource. If you specify a different name, you must explicitly point to the MongoDB or MongoDBCommunity where you want to enable MongoDB Search and Vector Search.

If you reference a sharded cluster MongoDB resource, the Kubernetes Operator auto-discovers the shard topology (shard names, replica set members, mongos routers) and creates per-shard mongot StatefulSets automatically. You don't need to perform any additional external configuration.

Use this field only if your MongoDB or MongoDBCommunity resource is deployed in the same Kubernetes cluster and is in the same namespace as your MongoDBSearch resource. If you set this field, the Kubernetes Operator automatically:

• Sets proper connection strings to the database.

• Reconfigures MongoDB database deployments by setting necessary parameters to enable search functionality and configures the addresses of the search pods.

If your database is deployed outside of Kubernetes or is in a different namespace, use spec.external to configure connection to the database. This field is mutually exclusive with spec.external.

If omitted, the Kubernetes Operator looks for a MongoDB or MongoDBCommunity resource with the same name as this MongoDBSearch resource.

Setting for Configuring mongot User

spec.source.username

Type: string

Username to use to authenticate mongot with mongod. The specified user must have the searchCoordinator role. If omitted, the Kubernetes Operator assumes the username is search-sync-source.

spec.source.passwordSecretRef.name

Type: string

Name of the secret that contains the password that mongot must use to authenticate with mongod. If omitted, defaults to <MongoDBSearch.metadata.name>-search-sync-source-password.

spec.source.passwordSecretRef.key

Type: string

Key under which the password value is stored in the secret. If omitted, defaults to password.

Settings for x509 Authentication

spec.source.x509

Type: object

Configures x509 client certificate authentication for the mongot sync source connection. If you set this field, mongot authenticates to MongoDB using x509 instead of username and password.

This field is mutually exclusive with spec.source.passwordSecretRef and spec.source.username. The Kubernetes Operator rejects the configuration if you specify both x509 and password authentication.

spec.source.x509.clientCertificateSecretRef

Type: object

Secret that contains the x509 client certificate and key for authenticating to the MongoDB sync source. The Secret must contain the following keys:

• tls.crt — Client certificate (required)

• tls.key — Private key (required)

• tls.keyFilePassword — Password for the private key (optional)

You must specify this field if you set spec.source.x509.

Example

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

Settings for Connecting to External MongoDB

The following settings are required only for configuring a connection to an external MongoDB deployment.

spec.source.external

Type: object

Settings that describe the external data source. This object describes the settings for the MongoDB Search and Vector Search resource to connect to an external MongoDB. These settings should be specified only if you want to connect to an external MongoDB that wasn't deployed using the Kubernetes Operator. If specified, these settings override settings for spec.source.mongodbResourceRef.name. If you used the Kubernetes Operator to install MongoDB in the same cluster, these settings are optional.

Settings for Security

spec.security

Type: object

Security settings for mongot listen server.

spec.security.tls

Type: object

TLS settings for mongot. If omitted, mongot won't use TLS for incoming connections.

spec.security.tls.certificateKeySecretRef.name

Type: string

Deprecated since version 1.8.0: Use spec.security.tls.certsSecretPrefix instead.

Name of the TLS secret in the same namespace containing the private key (tls.key) and the certificate (tls.crt). The secret can be of type kubernetes.io/tls (that is issued by cert-manager) or can be created manually.

The Kubernetes Operator still supports this field for replica set deployments for backwards compatibility. However:

• For sharded cluster deployments, the Kubernetes Operator rejects this field during validation. Use spec.security.tls.certsSecretPrefix instead, because a single secret reference cannot cover per-shard certificates.

• If you specify both certificateKeySecretRef and certsSecretPrefix, certificateKeySecretRef takes precedence for replica set deployments.

For new deployments, use spec.security.tls.certsSecretPrefix even for replica sets.

spec.security.tls.certsSecretPrefix

Type: string

Prefix that the Kubernetes Operator uses to derive TLS secret names by naming convention. If you set this field, the Kubernetes Operator looks for secrets following these patterns instead of requiring explicit secret references for each component:

Component	Secret Name Pattern
Replica set's mongot server cert	{certsSecretPrefix}-{name}-search-cert
Sharded mongot cert (per shard)	{certsSecretPrefix}-{name}-search-0-{shardName}-cert
Managed load balancer server cert	{certsSecretPrefix}-{name}-search-lb-0-cert
Managed load balancer client cert	{certsSecretPrefix}-{name}-search-lb-0-client-cert

Where:

• {name} is metadata.name of the MongoDBSearch resource

• {shardName} is the value of spec.source.external.shardedCluster.shards[*].shardName

If omitted, this field defaults to an empty string and the Kubernetes Operator uses spec.security.tls.certificateKeySecretRef instead.

Note

For sharded cluster deployments, you must use certsSecretPrefix instead of certificateKeySecretRef. The Kubernetes Operator rejects certificateKeySecretRef for sharded topologies because a single secret reference cannot cover per-shard certificates.

Example

spec:
  security:
    tls:
      certsSecretPrefix: my-prefix

Settings for Multiple Mongot Instances

spec.replicas

Type: integer

Number of mongot pods to deploy. For a replica set source, this is the total number of mongot pods. For a sharded cluster source, this is the number of mongot pods per shard.

If spec.replicas is greater than 1, you must also configure spec.loadBalancer to route traffic between mongod and the multiple mongot instances.

If omitted, defaults to 1.

Example

spec:
  replicas: 2

Settings for Load Balancing

spec.loadBalancer

Type: object

Configuration for L7 load balancing between mongod (or mongos) and mongot. This field is required if spec.replicas is greater than 1. If spec.replicas is 1, this field is optional. You can configure a load balancer even for a single mongot instance to prepare for scaling up later.

Exactly one of managed or unmanaged must be set.

The load balancer affects which TLS certificates mongod clients see and which hostnames those certificates must contain:

• Without a load balancer, mongod connects directly to mongot. The TLS certificate presented to mongod is mongot's own certificate. If the MongoDB cluster is outside of Kubernetes, the mongot service is exposed on an external domain. You must include that external domain in the mongot TLS certificate's SAN (Subject Alternative Name) field.

• With a managed load balancer (spec.loadBalancer.managed), the Envoy proxy is the only component that connects directly to mongot. Envoy reaches mongot pods using their internal headless Service FQDNs:

  • Replica set: <pod>.<name>-search-svc.<ns>.svc.cluster.local

  • Sharded cluster: <pod>.<name>-search-0-<shard>-svc.<ns>.svc.cluster.local

  Issue the mongot TLS certificate with these cluster-local domains in the SAN field. You can use a wildcard certificate to avoid re-issuing certificates when the number of mongot pods changes. External mongod processes see the Envoy proxy's TLS certificate, so include external domains in the Envoy certificate's SANs, not in the mongot certificate.

Tip

Enable a managed load balancer even if you initially deploy a single mongot pod. With the load balancer in place, the domains in your TLS certificates remain stable if you scale up spec.replicas later because the load balancer is already present between mongod and mongot.

spec.loadBalancer.managed

Type: object

Configures an operator-managed Envoy load balancer. The Kubernetes Operator deploys and manages the Envoy proxy with correct routing, mTLS, and HTTP/2+gRPC stream pinning. Set this field to an empty object ({}) to use the defaults.

This field is mutually exclusive with spec.loadBalancer.unmanaged.

Example

spec:
  loadBalancer:
    managed: {}

spec.loadBalancer.managed.externalHostname

Type: string

Hostname that the Envoy proxy expects for SNI matching on incoming requests. The Kubernetes Operator uses this value to configure routing rules that match the TLS SNI field from incoming mongod connections. The Envoy TLS server certificate must include this hostname in its SAN (Subject Alternative Name) field.

For sharded clusters, the value must contain a {shardName} placeholder that the Kubernetes Operator expands per shard. Each shard gets a unique hostname, and the Envoy TLS server certificate must include all expanded shard hostnames in its SANs. You can use a wildcard certificate to cover all shards with a single certificate and avoid re-issuing when shards are added.

This field is required if MongoDB is externally managed (not deployed by the Kubernetes Operator). If MongoDB is operator-managed in the same cluster, omit this field because the Kubernetes Operator auto-configures routing.

Example

# 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

Type: core/v1/ResourceRequirements

CPU and memory that the Envoy container can request and be limited to. If you specify this setting, the Kubernetes Operator replaces the defaults entirely.

If omitted, the Kubernetes Operator uses the following default values:

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

Example

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

spec.loadBalancer.managed.deployment

Type: object

Overrides that the Kubernetes Operator merges into the operator-created Envoy Deployment. Follows the same convention as spec.statefulSet on MongoDB resources. If omitted, the Kubernetes Operator uses defaults for the Envoy Deployment.

This object contains two fields:

• metadata — contains labels and annotations fields that the Kubernetes Operator merges into the Envoy Deployment metadata.

• spec — an apps/v1/DeploymentSpec object. The Kubernetes Operator merges these overrides into the Envoy Deployment spec.

Example

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

spec.loadBalancer.unmanaged

Type: object

Configures a user-provided (Bring Your Own) L7 load balancer. You are responsible for deploying and configuring the load balancer externally.

This field is mutually exclusive with spec.loadBalancer.managed.

spec.loadBalancer.unmanaged.endpoint

Type: string

The endpoint of the BYO load balancer in host:port format. The Kubernetes Operator writes this value into the mongod configuration as mongotHost and searchIndexManagementHostAndPort.

This field is required only when the Kubernetes Operator manages the MongoDB deployment (using spec.source.mongodbResourceRef), because the Kubernetes Operator needs the endpoint to configure mongod parameters. If both the load balancer and MongoDB are external (not managed by the Kubernetes Operator), this field is not required because you configure mongod parameters yourself.

For sharded clusters, the value must contain a {shardName} placeholder that the Kubernetes Operator expands per shard.

Example

# 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"

Settings for Provisioning Resources

spec.resourceRequirements

Type: core/v1/ResourceRequirements

CPU and memory that the mongodb-search container can request and be limited to. We recommend using this field to customize resource allocations instead of overriding it with spec.statefulSet.

If you do not override the JVM heap size in spec.jvmFlags, the Kubernetes Operator sets the default heap size (-Xmx) to 50% of the memory available to the mongot pod. Adjust spec.resourceRequirements accordingly to control both pod resources and JVM heap size.

If omitted, the Kubernetes Operator uses the following default values:

requests:
  cpu: 2
  memory: 2G

spec.resourceRequirements.limits

Type: object

Upper cap on the resource, CPU and memory, that the mongodb-search container can consume. By default, there are no limits set. If omitted, the pod isn't restricted and so, might use all the resources on the node. We recommend setting limits based on your workload.

spec.resourceRequirements.requests

Type: object

Amount of CPU and memory requested for the mongodb-search container. If omitted, the Kubernetes Operator uses the following default values:

requests:
  cpu: 2
  memory: 2G

spec.persistence.single

Type: object

Storage configuration for MongoDB Search and Vector Search persistence volume where MongoDB Search and Vector Search indexes are stored. Each search instance (pod) has its own independent storage to maintain indexes, which isn't shared with the MongoDB database. Only index metadata (definitions) are stored in the database itself.

Scalar	Data Type	Description
labelSelector	string	Tag used to bind mounted volumes to directories.
storage	string	Minimum size of Persistent Volume that should be mounted. This value is expressed as an integer followed by a unit of storage in JEDEC notation. Default value is 16Gi. For example, if replica set requires 60 gigabytes of storage space, set this value to 60Gi.
storageClass	string	Type of storage specified in a Persistent Volume Claim. You may create this storage type as a StorageClass object before using it in this object specification. Make sure to set the StorageClass reclaimPolicy to Retain. This ensures that data is retained when a Persistent Volume Claim is removed.

MongoDBSearch supports only single persistence field. If omitted, the Kubernetes Operator sets spec.persistence.single.storage to 10GB.

Settings for Logging

spec.logLevel

Type: string

Verbosity of the mongot logs. Value can be one of the following:

• TRACE

• DEBUG

• INFO

• WARN

• ERROR

If omitted, defaults to INFO.

Settings for Metrics

spec.prometheus

Type: object

This is available only in v1.6 and later.

Configuration to enable Prometheus metrics endpoint. If omitted, the metrics endpoint in mongot is disabled. To enable Prometheus metrics endpoint on the default port (9946), specify an empty {} object in the spec.prometheus field. To change the port, set it in spec.prometheus.port field.

spec.prometheus.port

Type: string

Port on which to enable Prometheus metrics endpoint. By default, Prometheus metrics endpoint is enabled on port 9946.

Settings for Automated Embedding

spec.autoEmbedding

Type: Object

Configuration for Automated Embedding for text data in your collection.

spec.autoEmbedding.embeddingModelAPIKeySecret

Type: Object

Configuration for the embedding model provider API keys. To enable Automated Embedding, you must create two keys, one for generating embeddings at index-time for data in your collection and another for generating embeddings at query-time for the query text. If you don't already have the keys, we recommend that you create keys from two Atlas projects. To learn more about creating keys for the Atlas projects from the Atlas UI, see Manage API Keys.

spec.autoEmbedding.embeddingModelAPIKeySecret.name

Type: string

Name of the secret that contains the embedding model API keys that mongot must use to generate embeddings at index- and query-time.

spec.autoEmbedding.providerEndpoint

Type: string

Embedding model endpoint URL for generating embeddings. Value varies based on whether you create the keys from the Atlas UI (recommended) or directly from the embedding service (Voyage AI). For keys created from:

• Atlas UI, value is https://ai.mongodb.com/v1/embeddings (default)

• Voyage AI, value is https://api.voyageai.com/v1/embeddings

Settings for JVM Configuration

spec.jvmFlags

Type: array of strings

JVM flags passed to the mongot process. The Kubernetes Operator includes the flags without modification in the mongot startup command using --jvm-flags "<all flags space-separated>".

If you don't specify -Xms or -Xmx in this field, the Kubernetes Operator auto-calculates heap size by setting both to half of spec.resourceRequirements.requests.memory. If you don't specify resource requirements, the Kubernetes Operator uses a default of 4Gi memory request, yielding approximately -Xmx2048m -Xms2048m.

If you provide your own -Xms or -Xmx values, the Kubernetes Operator uses them and does not override the values. The Kubernetes Operator always appends the flags you provide after the operator-computed flags.

To learn more, see Hardware Sizing for mongot.

Example

spec:
  jvmFlags:
    - -Xms2g
    - -Xmx2g

Other Settings

spec.version

Type: string

Version of mongodb-search docker image. If omitted, the Kubernetes Operator automatically chooses the newest version of MongoDBSearch. You can set it explicitly to prevent automatic upgrades when the Kubernetes Operator version is upgraded.

spec.statefulSet

Type: apps/v1/StatefulSet

Specification for the StatefulSet, created for deploying mongot pods, that overwrites the settings that the Kubernetes Operator applies. The overrides are always applied last. Supports both the spec.statefulSet.spec and spec.statefulSet.metadata fields.

Note

Don't set resource requirements or persistence settings using spec.statefulSet. Instead, use the spec.resourceRequirements and spec.persistence fields respectively.