Secure the Connection from Search to MongoDB

How mongot Authenticates to mongod

When mongot connects to mongod, it authenticates as a database client using one of two mutually exclusive modes:

You can switch modes after the fact by updating the MongoDBSearch resource and letting the Kubernetes Operator restart the mongot pods. The mongod-side identity that mongot authenticates as does not need to change if it holds the required role described in the next section.

The Role mongot Needs on mongod

Whichever mode mongot uses, the identity it authenticates as must have permission to source data and maintain the search catalog on mongod. That identity must hold the built-in searchCoordinator role, which ships with MongoDB Server 8.2 and later and grants only the privileges that mongot requires.

You always create this identity yourself; the MongoDBSearch controller never creates it for you. How you create it depends on whether the Kubernetes Operator manages the source mongod:

• Operator-managed source. Declare a user that holds the searchCoordinator role and reference a password Secret — in the users list of your MongoDBCommunity resource for Community, or as a separate MongoDBUser resource for Enterprise. The Kubernetes Operator provisions that user on mongod for you. You then reference the same user and Secret on the MongoDBSearch resource so mongot can authenticate with it.

• External source. Create the user and grant it the searchCoordinator role directly on your own mongod deployment, then reference its credentials on the MongoDBSearch resource as shown below.

The rest of this page shows how to configure each authentication mode on the MongoDBSearch resource, and how to trust the mongod server certificate over TLS.

Configure SCRAM Authentication

Provide a Kubernetes Secret that contains the password that mongot should use to authenticate to mongod. Reference the secret on the MongoDBSearch resource through spec.source.passwordSecretRef, and set the username through spec.source.username.

spec:
  source:
    username: search-sync-source
    passwordSecretRef:
      name: my-mongot-password

The referenced Secret must contain the password under a key named password by default. Override the key through spec.source.passwordSecretRef.key if you store the password under a different key.

The user identified by spec.source.username must already exist on mongod and must hold the searchCoordinator role. If you omit spec.source.username, the Kubernetes Operator assumes the username is search-sync-source.

To add network-layer mTLS on top of SCRAM, provide a Kubernetes Secret containing the client certificate and private key and reference it through spec.source.tls.clientCertificateSecretRef. The Secret must contain tls.crt and tls.key. The Kubernetes Operator presents this certificate during the TLS handshake while still authenticating through username and password.

spec:
  source:
    username: search-sync-source
    passwordSecretRef:
      name: my-mongot-password
    tls:
      clientCertificateSecretRef:
        name: my-mongot-client-cert

If the client private key is encrypted, provide the passphrase in a separate Secret and reference it through spec.source.tls.keyFilePasswordSecretRef. The Secret must contain the passphrase at the keyFilePassword key.

Configure X.509 Authentication

X.509 authentication identifies mongot to mongod through a client certificate rather than a username and password. The subject distinguished name (DN) on the certificate becomes mongot's identity on mongod.

Provide a Kubernetes Secret that contains the client certificate and private key under the tls.crt and tls.key keys, and reference it on the MongoDBSearch resource through spec.source.x509.clientCertificateSecretRef:

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

If the client private key is encrypted, provide the passphrase in a separate Secret under the keyFilePassword key, and reference it through spec.source.x509.keyFilePasswordSecretRef:

spec:
  source:
    x509:
      clientCertificateSecretRef:
        name: my-mongot-x509-cert
      keyFilePasswordSecretRef:
        name: my-mongot-key-password

The client certificate alone does not grant access: mongod must recognize its subject DN as an authorized identity. After you create the certificate secret above, authorize that certificate's subject DN on mongod as described next.

Trust the mongod Server Certificate

The settings above establish mongot's identity. Independently, when the source mongod uses TLS, mongot must trust the certificate that mongod presents when mongot connects to it. mongot is the TLS client on this connection; mongod presents its server certificate, and mongot validates that certificate against a CA that you supply.

When the source mongod is external to the Kubernetes Operator (that is, declared through spec.source.external), provide the CA that issued the mongod server certificate:

spec:
  source:
    external:
      hostAndPorts:
        - mongod-0.example.com:27017
      tls:
        ca:
          name: my-external-mongod-ca

The spec.source.external.tls.ca.name field references a Kubernetes ConfigMap that contains the CA certificate under the ca.crt key. The CA must be the one that issued the mongod server certificate.

When the source mongod is instead managed by the Kubernetes Operator (through spec.source.mongodbResourceRef), the Kubernetes Operator handles this CA trust for you, and the spec.source.external.tls.ca.name field does not apply.

Certificate Rotation

mongot reads its client certificate at process startup. To rotate the certificate, update the Secret referenced by spec.source.x509.clientCertificateSecretRef (for X.509) or spec.source.tls.clientCertificateSecretRef (for mTLS on top of SCRAM) on the MongoDBSearch resource. The Kubernetes Operator detects the change and automatically restarts the mongot pods to load the new certificate material. The same applies to the SCRAM password Secret referenced by spec.source.passwordSecretRef.

To rotate an X.509 client certificate under MCK:

Automated rotation is not configurable through the MongoDBSearch CRD. Update the Secret referenced by spec.source.x509.clientCertificateSecretRef to trigger the rotation; the Kubernetes Operator restarts the pods automatically.