Make the MongoDB docs better! We value your opinion. Share your feedback for a chance to win $100.
Click here >
Docs Menu
Docs Home
/ /
CRDs
Docs Home
/
Management
/
Controllers for Kubernetes Operator
/
CRDs
Docs Home
/
Management
/
Controllers for Kubernetes Operator
/
CRDs

MongoDBSearch Resource Specification

The MongoDBSearch custom resource lets you deploy and configure MongoDB Search and Vector Search nodes alongside your MongoDB database deployments in Kubernetes. The MongoDBSearch resource deploys mongot processes that provide full-text and semantic search capabilities by syncing data from your MongoDB deployment.

To learn more about deploying MongoDB Search and Vector Search, see Deploy MongoDB Search and Vector Search.

Example

The following example shows a resource specification for a MongoDBSearch custom resource:

1spec:
2  source:
3    mongodbResourceRef:
4      name: mdb
5    external:
6      hostAndPorts:
7        - mdb-rs-external-0.example.com:27017
8        - mdb-rs-external-1.example.com:27017
9        - mdb-rs-external-2.example.com:27017
10      shardedCluster:
11        router:
12          hosts:
13            - mongos1.example.com:27017
14            - mongos2.example.com:27017
15        shards:
16          - shardName: shard-0
17            hosts:
18              - shard0-node1.example.com:27018
19              - shard0-node2.example.com:27018
20          - shardName: shard-1
21            hosts:
22              - shard1-node1.example.com:27018
23              - shard1-node2.example.com:27018
24      tls:
25        ca:
26          name: mdbc-rs-ca
27    username: search-sync-source
28    passwordSecretRef:
29      name: mdbc-rs-search-sync-source-password
30      key: password
31    # x509 authentication (mutually exclusive with
32    # username/passwordSecretRef)
33    x509:
34      clientCertificateSecretRef:
35        name: mongot-x509-client-cert
36  replicas: 2
37  loadBalancer:
38    # Option 1: Operator-managed Envoy load balancer
39    managed:
40      externalHostname: "search.apps.example.com"
41      resourceRequirements:
42        requests:
43          cpu: "100m"
44          memory: 128Mi
45        limits:
46          cpu: "500m"
47          memory: 512Mi
48      deployment:
49        spec:
50          template:
51            spec:
52              nodeSelector:
53                kubernetes.io/os: linux
54    # Option 2: User-provided (BYO) load balancer
55    # (mutually exclusive with managed)
56    unmanaged:
57      endpoint: "search-lb.corp.example.com:443"
58  security:
59    tls:
60      certificateKeySecretRef:
61        name: mdbs-tls-secret
62      certsSecretPrefix: my-prefix
63  resourceRequirements:
64    limits:
65      cpu: "3"
66      memory: 5Gi
67    requests:
68      cpu: "2"
69      memory: 3Gi
70  persistence:
71    single:
72      storage: 16Gi
73      storageClass: standard
74  version: "0.64.0"
75  statefulSet:
76    spec:
77      template:
78        spec:
79          nodeSelector:
80            kubernetes.io/os: linux
81  jvmFlags:
82    - -Xms2g
83    - -Xmx2g
84  autoEmbedding:
85    embeddingModelAPIKeySecret:
86      name: embedding-model-api-query-key
87    providerEndpoint: https://ai.mongodb.com/v1/embeddings
88  logLevel: INFO
89  prometheus: {}

Required MongoDBSearch Resource Settings

This section describes settings that you must use for all MongoDBSearch resources.

apiVersion

Type: string

Version of the MongoDB Kubernetes resource schema. Set the value to mongodb.com/v1.

kind

Type: string

Kind of MongoDB Kubernetes resource to create. Set this to MongoDBSearch.

metadata.namespace

Type: string

Namespace where the MongoDBSearch resource should be created. To leverage automatic configuration of MongoDBSearch and MongoDB or MongoDBCommunity resources, the MongoDBSearch resource should be created in the same namespace as the MongoDB or MongoDBCommunity resource.

metadata.name

Type: string

Unique identifier of the MongoDBSearch resource.

Resource names must be 44 characters or less.

Optional MongoDBSearch Resource Settings

The MongoDBSearch custom resource can use the following settings:

Data Source Settings

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.

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.

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.

x509 Authentication Settings

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.

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)

External MongoDB Settings

spec.source.external

Type: object

Settings that describe the external data source. Specify these settings only if you want to connect to an external MongoDB that wasn't deployed using the Kubernetes Operator.

spec.source.external.hostAndPorts

Type: array of strings

List of hostnames and ports of the external replica set. This field is mutually exclusive with spec.source.external.shardedCluster.

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.

spec.source.external.shardedCluster.router.hosts

Type: array of strings

List of endpoints for the mongos router instances in host:port format.

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.

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

Type: string

The logical name of the shard.

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.

spec.source.external.tls.ca.name

Type: string

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

Security Settings

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).

spec.security.tls.certsSecretPrefix

Type: string

Prefix that the Kubernetes Operator uses to derive TLS secret names by naming convention.

Replica and Load Balancer Settings

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.

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.

Exactly one of managed or unmanaged must be set.

spec.loadBalancer.managed

Type: object

Configures an operator-managed Envoy load balancer. This field is mutually exclusive with spec.loadBalancer.unmanaged.

spec.loadBalancer.managed.externalHostname

Type: string

Hostname that the Envoy proxy expects for SNI matching on incoming requests.

spec.loadBalancer.managed.resourceRequirements

Type: core/v1/ResourceRequirements

CPU and memory that the Envoy container can request and be limited to.

spec.loadBalancer.managed.deployment

Type: object

Overrides that the Kubernetes Operator merges into the operator-created Envoy Deployment.

spec.loadBalancer.unmanaged

Type: object

Configures a user-provided (Bring Your Own) L7 load balancer. 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.

Resource Settings

spec.resourceRequirements

Type: core/v1/ResourceRequirements

CPU and memory that the mongodb-search container can request and be limited to.

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.

spec.resourceRequirements.requests

Type: object

Amount of CPU and memory requested for the mongodb-search container.

Persistence Settings

spec.persistence.single

Type: object

Storage configuration for MongoDB Search and Vector Search persistence volume where indexes are stored. Each search instance (pod) has its own independent storage.

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. Default value is 10GB.

storageClass

string

Type of storage specified in a Persistent Volume Claim.

Logging Settings

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.

Metrics Settings

spec.prometheus

Type: object

Configuration to enable Prometheus metrics endpoint. If omitted, the metrics endpoint in mongot is disabled.

spec.prometheus.port

Type: string

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

Automated Embedding Settings

Important

Automated embedding is available as a Preview feature for only MongoDB Community Edition deployment. The feature and corresponding documentation might change at any time during the Preview period. To learn more, see Preview Features.

spec.autoEmbedding

Type: object

Configuration for automated embedding for text data in your collection.

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.

JVM Configuration Settings

spec.jvmFlags

Type: array of strings

JVM flags passed to the mongot process. 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.

Other Settings

spec.version

Type: string

Version of mongodb-search docker image. If omitted, the Kubernetes Operator automatically chooses the newest version of MongoDBSearch.

spec.statefulSet

Type: apps/v1/StatefulSet

Specification for the StatefulSet created for deploying mongot pods, that overwrites the settings that the Kubernetes Operator applies.

Note

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

Status Fields

The Kubernetes Operator reports status information under the status field of the MongoDBSearch resource.

status.loadBalancer

Type: object

Status of the operator-managed load balancer (Envoy). This field is present only when spec.loadBalancer.managed is set.

status.loadBalancer.phase

Type: string

Current phase of the managed load balancer. Possible values include Pending, Running, and Failed.

Back

CRD Log Rotation Settings

Next

MongoDBCommunity

On this page