MongoDB Search and Vector Search Settings

Settings for Connecting to an External Replica Set

spec.source.external.hostAndPorts

Type: array of strings

List of hostnames and ports of the external replica set. This is a host seed list to the MongoDB replica set. The mongot connects to the database in a replica set mode and gets the list of all other nodes using db.hello().

This field is mutually exclusive with spec.source.external.shardedCluster. Use hostAndPorts for replica set sources and shardedCluster for sharded cluster sources.

Example

hostAndPorts:
  - mdbc-rs-0.my-external-domain.example.com:27017
  - mdbc-rs-1.my-external-domain.example.com:27017
  - mdbc-rs-2.my-external-domain.example.com:27017

spec.source.external.tls

Type: object

TLS Settings that mongot must use when connecting to the external MongoDB database.

spec.source.external.tls.ca.name

Type: string

Name of the ConfigMap containing the trusted chain of the certificate authorities that issued the TLS certificate used by the mongod nodes.

Example

spec:
  source:
    external:
      tls:
        ca:
          name: trusted-ca

You must specify the certificate (or certificate chain) under the ca.crt key in this ConfigMap.

Example

kind: ConfigMap
apiVersion: v1
metadata:
  name: trusted-ca
data:
  ca.crt: |
    -----BEGIN CERTIFICATE-----
    MIIDBTCCAe2gAwIBAgIIH3EOUAGAsx0wDQYJKoZIhvcNAQELBQAwFTETMBEGA1UE
    [...]
    U/4rN8Ias/FONYFRtGfs9uXHmo2MP04BF+9ED2dlbNDUbat+6XCozLJj98nI4VEi
    qaV3JrVFHTgN
    -----END CERTIFICATE-----

Settings for Connecting to an External Sharded Cluster

The following settings are required only for configuring a connection to an external MongoDB sharded cluster. They extend the existing spec.source.external settings.

spec.source.external.shardedCluster

Type: object

Declares an external sharded MongoDB cluster as the data source for mongot. Contains configuration for mongos routers and per-shard replica set members.

Use this only if the MongoDB sharded cluster is deployed outside of Kubernetes and is not managed by the Kubernetes Operator. For operator-managed sharded clusters deployed with the MongoDB CRD, use spec.source.mongodbResourceRef instead. The Kubernetes Operator auto-discovers shard topology.

Example

spec:
  source:
    external:
      shardedCluster:
        router:
          hosts:
            - "mongos1.external:27017"
            - "mongos2.external:27017"
        shards:
          - shardName: "shard-0"
            hosts:
              - "shard0-node1.external:27018"
              - "shard0-node2.external:27018"
          - shardName: "shard-1"
            hosts:
              - "shard1-node1.external:27018"
              - "shard1-node2.external:27018"

spec.source.external.shardedCluster.router

Type: object

Configuration for the mongos (router) instances of the external sharded cluster.

spec.source.external.shardedCluster.router.hosts

Type: array of strings

List of endpoints for the mongos router instances in host:port format. All mongot instances connect to these routers. Specify at least one entry.

Example

router:
  hosts:
    - "mongos1.external:27017"
    - "mongos2.external:27017"

spec.source.external.shardedCluster.shards

Type: array of objects

List of all shards in the external MongoDB cluster. Each entry describes one shard's replica set. The Kubernetes Operator creates one mongot StatefulSet for each shard, where each StatefulSet contains the number of pods specified in spec.clusters[].replicas. Specify at least one shard entry.

spec.source.external.shardedCluster.shards[*].shardName

Type: string

The logical name of the shard. The Kubernetes Operator uses this name for Kubernetes resource naming (StatefulSets, Services, Secrets). The value can be different from the MongoDB shard name.

Naming constraints:

• Must be unique across all shards.

• Must conform to Kubernetes DNS label name rules (RFC 1123), which allow lowercase alphanumeric characters and hyphens (-), and require that the name start and end with an alphanumeric character. Periods (.) and underscores (_) are not allowed. The maximum length is 63 characters.

• The Kubernetes Operator combines metadata.name, the cluster index, and shardName into the names of the Kubernetes resources it creates (for example, {name}-search-{clusterIndex}-{shardName}), and validates that every generated name fits within the Kubernetes DNS limits of 63 characters for labels and 253 characters for subdomain names. Keep shardName short enough for these limits.

Example

shards:
  - shardName: "shard-0"
    hosts:
      - "shard0-node1.external:27018"

spec.source.external.shardedCluster.shards[*].hosts

Type: array of strings

List of endpoints of the mongod replica set members for this shard in the host:port format. mongot instances replicate data from these hosts. Specify at least one entry.

Each replica set (shard) has its own group of mongot instances, which source data only from that replica set. Different shards never share the same mongot instances.

Example

shards:
  - shardName: "shard-0"
    hosts:
      - "shard0-node1.external:27018"
      - "shard0-node2.external:27018"
      - "shard0-node3.external:27018"

Sizing and Storage

spec.clusters[].replicas

Type: integer

Number of mongot pods to deploy in this Kubernetes cluster. 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.clusters[].replicas is greater than 1, you must also configure spec.clusters[].loadBalancer to route traffic between mongod and the multiple mongot instances.

If you set spec.clusters[].replicas to 0, the Kubernetes Operator takes the mongot deployment in this cluster offline. The Kubernetes Operator scales the StatefulSet to zero pods and keeps the MongoDBSearch resource and its other Kubernetes resources in place.

If omitted, defaults to 1.

Example

spec:
  clusters:
    - replicas: 2

spec.clusters[].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.clusters[].statefulSet.

If you do not override the JVM heap size in spec.clusters[].jvmFlags, the Kubernetes Operator sets the default heap size (-Xmx) to 50% of the memory request of the mongot container. Adjust spec.clusters[].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: 4Gi

spec.clusters[].resourceRequirements.limits

Type: object

Upper cap on the resources (CPU and memory) that the mongodb-search container can consume. By default, no limits are 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.clusters[].resourceRequirements.requests

Type: object

Amount of CPU and memory requested for the mongodb-search container. If you specify only one of cpu or memory, the Kubernetes Operator applies the default value for the other. If omitted, the Kubernetes Operator uses the following default values:

requests:
  cpu: 2
  memory: 4Gi

spec.clusters[].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 to mount. This value is expressed as an integer followed by a unit of storage in JEDEC notation. Default value is 16G. For example, if a replica set requires 60 gigabytes of storage space, set this value to 60G.
storageClass	string	Type of storage specified in a Persistent Volume Claim. You can 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 the single persistence mode, which uses one volume for all data. Although the CRD schema also contains a spec.clusters[].persistence.multiple field, the Kubernetes Operator doesn't apply it. If you omit persistence, the Kubernetes Operator sets spec.clusters[].persistence.single.storage to 16G.

Load Balancing

spec.clusters[].loadBalancer

Type: object

Configuration for L7 load balancing between mongod (or mongos) and mongot. This field is required if spec.clusters[].replicas is greater than 1. If spec.clusters[].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.

All entries in spec.clusters must agree on the load balancer mode: either every entry sets loadBalancer.managed, every entry sets loadBalancer.unmanaged, or no entry sets loadBalancer. The Kubernetes Operator rejects mixed modes. Multi-cluster deployments support only the managed mode.

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.clusters[].loadBalancer.managed), the Envoy proxy is the only component that connects directly to mongot. The Envoy proxy reaches mongot through the internal Service FQDNs:

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

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

  We recommend that you include these service FQDNs in the mongot TLS certificate's SAN field. The operator-managed Envoy proxy currently validates the mongot certificate against the certificate authority only and doesn't match SAN hostnames. 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.clusters[].replicas later because the load balancer is already present between mongod and mongot.

spec.clusters[].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.clusters[].loadBalancer.unmanaged.

For sharded cluster sources, you must also configure spec.security.tls if you use a managed load balancer. The Envoy proxy routes traffic to the correct shard using SNI, which requires TLS.

Example

spec:
  clusters:
    - loadBalancer:
        managed: {}

spec.clusters[].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 cluster sources, the value must contain a {shardName} placeholder, which the Kubernetes Operator expands per shard. Each shard gets its own 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. For replica set sources, don't use the {shardName} placeholder.

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.

In multi-cluster deployments, each cluster entry typically uses a distinct hostname. However, the Kubernetes Operator permits sharing one hostname across clusters, for example if a failover proxy that spans availability zones fronts the Envoy proxies of multiple clusters.

Example

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

spec.clusters[].loadBalancer.managed.routerHostname

Type: string

Endpoint that mongos routers use to reach this cluster's mongot instances through the managed Envoy load balancer, in the host:port format. The Kubernetes Operator uses the hostname for SNI matching on the cluster-level routing chain, so the Envoy TLS server certificate must include this hostname in its SANs.

This field is required if you use a managed load balancer with an external sharded MongoDB source (spec.source.external.shardedCluster). The Kubernetes Operator ignores this field for replica set sources and for operator-managed MongoDB.

Unlike externalHostname, the Kubernetes Operator uses this value verbatim, so the value must not contain a {shardName} placeholder. This endpoint is the shard-agnostic entry point for mongos.

In multi-cluster deployments, each cluster entry typically uses a distinct value. However, the Kubernetes Operator permits sharing one value across clusters, for example if a failover proxy that spans availability zones fronts the Envoy proxies of multiple clusters.

Example

spec:
  clusters:
    - loadBalancer:
        managed:
          externalHostname: "{shardName}.search.example.com"
          routerHostname: "search-router.example.com:27028"

spec.clusters[].loadBalancer.managed.replicas

Type: integer

Number of Envoy proxy pods to deploy in this Kubernetes cluster. The value must be 1 or greater. If omitted, defaults to 1.

spec.clusters[].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:
  clusters:
    - loadBalancer:
        managed:
          resourceRequirements:
            requests:
              cpu: "200m"
              memory: "256Mi"
            limits:
              cpu: "1"
              memory: "1Gi"

spec.clusters[].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:
  clusters:
    - loadBalancer:
        managed:
          deployment:
            spec:
              template:
                spec:
                  nodeSelector:
                    kubernetes.io/os: linux

spec.clusters[].loadBalancer.managed.retryPolicy

Type: object

Retry behavior that the Envoy proxy applies to individual gRPC streams to the upstream mongot instances. The Envoy proxy sends each retry attempt to a different mongot host than the failed attempt.

If you omit this field, the Envoy proxy retries with the default values: 2 retries with a per-try timeout of 60s.

Example

spec:
  clusters:
    - loadBalancer:
        managed:
          retryPolicy:
            numRetries: 2
            perTryTimeout: "60s"

spec.clusters[].loadBalancer.managed.retryPolicy.numRetries

Type: integer

Maximum number of retries per request. The value must be 1 or greater. If omitted, defaults to 2, which allows three total attempts for each request.

spec.clusters[].loadBalancer.managed.retryPolicy.perTryTimeout

Type: string

Timeout for each individual attempt, including the original request, expressed as a duration string (for example, "30s"). If omitted, defaults to "60s".

spec.clusters[].loadBalancer.managed.minMongotReadyReplicas

Type: integer

Minimum number of ready mongot replicas that a mongot group (for example, the mongot instances of one shard) must have before the Envoy proxy routes traffic to it. While a group is below this threshold, the Envoy proxy forwards the traffic intended for that group to a healthy mongot group and marks the requests with the routed_from_another_shard header. These requests return empty results instead of errors.

The value must be 1 or greater. If omitted, defaults to 1.

spec.clusters[].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.clusters[].loadBalancer.managed. Multi-cluster deployments don't support unmanaged load balancers.

spec.clusters[].loadBalancer.unmanaged.endpoint

Type: string

The endpoint of the BYO load balancer in host:port format. You must specify this field if you configure spec.clusters[].loadBalancer.unmanaged.

If the Kubernetes Operator manages the MongoDB deployment (using spec.source.mongodbResourceRef), the Kubernetes Operator writes this value into the mongod configuration as mongotHost and searchIndexManagementHostAndPort. If MongoDB is external, you configure the mongod parameters yourself using the same value.

For external sharded cluster sources, the value must contain a {shardName} placeholder that the Kubernetes Operator expands per shard, and it must contain more than just the placeholder. For external replica set sources, the value must not contain a {shardName} placeholder.

Example

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

Per-Shard Overrides

spec.clusters[].shardOverrides

Type: array of objects

Overrides that size specific shards within this cluster entry differently from the cluster defaults. Use this field to give individual shards more or fewer mongot replicas, resources, or storage than the rest of the cluster.

You can use this field only with an external sharded cluster source (spec.source.external.shardedCluster). Each shard name that you reference must exist in spec.source.external.shardedCluster.shards[*].shardName, and you can override each shard at most once per cluster entry.

If you set replicas, resourceRequirements, persistence, or jvmFlags in an override, they replace the cluster value for the named shards. The Kubernetes Operator deep-merges statefulSet onto the cluster value. Fields that you don't set inherit the cluster value.

Example

spec:
  clusters:
    - replicas: 2
      shardOverrides:
        - shardNames:
            - shard-0
          replicas: 3
          resourceRequirements:
            requests:
              cpu: "4"
              memory: 8Gi

spec.clusters[].shardOverrides[*].shardNames

Type: array of strings

Names of the shards within this cluster entry that the override applies to. This field is required and must contain at least one entry.

spec.clusters[].shardOverrides[*].replicas

Type: integer

Replaces the cluster's mongot replica count for the named shards. A value of 0 takes the mongot instances for these shards offline.

spec.clusters[].shardOverrides[*].resourceRequirements

Type: core/v1/ResourceRequirements

Replaces the cluster's CPU and memory requests and limits for the named shards.

spec.clusters[].shardOverrides[*].persistence

Type: object

Replaces the cluster's persistent volume configuration for the named shards. Uses the same schema as spec.clusters[].persistence.

spec.clusters[].shardOverrides[*].statefulSet

Type: object

StatefulSet overrides for the named shards. Unlike the other override fields, the Kubernetes Operator deep-merges this value onto the cluster's spec.clusters[].statefulSet value instead of replacing it.

spec.clusters[].shardOverrides[*].jvmFlags

Type: array of strings

Replaces the cluster's spec.clusters[].jvmFlags for the named shards if you set it to a non-empty list. The format rules for spec.clusters[].jvmFlags also apply to this field.

Sync Source Selection

spec.clusters[].syncSourceSelector

Type: object

Selects which mongod nodes the mongot instances in this cluster entry sync data from.

spec.clusters[].syncSourceSelector.matchTagSets

Type: array of objects

Ordered list of replica set tag sets that selects the sync source mongod nodes by their replica set tags. The Kubernetes Operator passes the list to the mongot configuration. mongot syncs from the nodes that the first matching tag set selects, and prefers secondary nodes.

Each entry is a map of tag names to tag values. An empty document ({}) matches any node, so you can append a trailing {} entry as a match-any fallback if no earlier tag set matches. You can specify at most 50 entries.

Example

spec:
  clusters:
    - syncSourceSelector:
        matchTagSets:
          - region: us-east-1
            workload: search
          - {}

JVM Flags

spec.clusters[].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>".

Each flag must start with -X, -XX:, or -D, must not contain spaces, and can contain only alphanumeric characters and the ., _, +, :, -, and = characters. The Kubernetes Operator rejects flags that don't match these rules.

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.clusters[].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:
  clusters:
    - jvmFlags:
        - -Xms2g
        - -Xmx2g

StatefulSet Overrides

spec.clusters[].statefulSet

Type: object

Overrides for the StatefulSet that the Kubernetes Operator creates for deploying mongot pods. The Kubernetes Operator always applies the overrides last, so they overwrite the settings that the Kubernetes Operator computes.

This object contains two fields:

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

• spec — an apps/v1/StatefulSetSpec object. The Kubernetes Operator merges these overrides into the StatefulSet spec.

Note

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

Advanced mongot Settings

spec.clusters[].advancedMongotConfigs

Type: object

Advanced mongot settings for this cluster entry. The Kubernetes Operator renders the value verbatim under the advancedConfigs key of the mongot configuration file, without reading or modifying it. This field doesn't affect the settings that the Kubernetes Operator generates elsewhere in the mongot configuration.

Use this field only for mongot settings that the MongoDBSearch resource doesn't expose as first-class fields.