Connect to a MongoDB Database Resource from Outside Kubernetes

Deploy a replica set with the Kubernetes Operator.

If you haven't deployed a replica set, follow the instructions to deploy one.

You must enable TLS for the replica set by providing a value for the spec.security.certsSecretPrefix setting. The replica set must use a custom CA certificate stored with spec.security.tls.ca.

Create an external service for the MongoDB Pods.

To connect to your replica set from an external resource, configure the spec.externalAccess setting:

externalAccess: {}

This setting instructs the Kubernetes Operator to create an external LoadBalancer service for the MongoDB Pods in your replica set. The external service provides an entry point for external connections. Adding this setting with no values creates an external service with the following default values:

Optionally, if you need to add values to the service or override the default values, specify:

• Annotations specific to your cloud provider, in spec.externalAccess.externalService.annotations

• Overrides for the service specification, in spec.externalAccess.externalService.spec.

For example, the following settings override the default values for the external service to configure your replica set to create NodePort services that expose the MongoDB Pods:

externalAccess:
  externalService:
    annotations:
      # cloud-specific annotations for the service
    spec:
      type: NodePort # default is LoadBalancer
      port: 27017
      # you can specify other spec overrides if necessary

Add Subject Alternate Names to your TLS certificates.

Add each external DNS name to the certificate SAN.

Verify the external services.

In your replica set, run the following command to verify that the Kubernetes Operator created the external service for your deployment.

$ kubectl get services

The command returns a list of services similar to the following output. For each database Pod in the cluster, the Kubernetes Operator creates an external service named <pod-name>-<pod-idx>-svc-external. This service is configured according to the values and overrides you provide in the external service specification.

NAME                                  TYPE         CLUSTER-IP   EXTERNAL-IP       PORT(S)           AGE
<my-replica-set>-0-svc-external   LoadBalancer   10.102.27.116    <lb-ip-or-fqdn>   27017:27017/TCP    8m30s

Depending on your cluster configuration or cloud provider, the IP address of the LoadBalancer service is an externally accessible IP address or FQDN. You can use the IP address or FQDN to route traffic from your external domain.

Open your replica set resource YAML file.

Copy the sample replica set resource.

Change the settings of this YAML file to match your desired replica set configuration.

1
---
2
apiVersion: mongodb.com/v1
3
kind: MongoDB
4
metadata:
5
  name: <my-replica-set>
6
spec:
7
  members: 3
8
  version: "4.2.2-ent"
9
  type: ReplicaSet
10
  opsManager:
11
    configMapRef:
12
      name: <configMap.metadata.name>
13
  credentials: <mycredentials>
14
  persistent: true

15
  security:
16
    tls:
17
      enabled: true
18
  connectivity:
19
    replicaSetHorizons:
20
      - "example-website": "web1.example.com:30907"
21
      - "example-website": "web2.example.com:32350"
22
      - "example-website": "web3.example.com:31185"
23
...

Paste the copied example section into your existing replica set resource.

Open your preferred text editor and paste the object specification at the end of your resource file in the spec section.

Change the highlighted settings to your preferred values.

Confirm the external hostnames and external service values in your replica set resource.

Confirm that the external hostnames in the spec.connectivity.replicaSetHorizons setting are correct.

External hostnames should match the DNS names of Kubernetes worker nodes. These can be any nodes in the Kubernetes cluster. Kubernetes nodes use internal routing if the pod runs on another node.

Set the ports in spec.connectivity.replicaSetHorizons to the external service values.

15
  security:
16
    tls:
17
      enabled: true
18
  connectivity:
19
    replicaSetHorizons:
20
      - "example-website": "web1.example.com:30907"
21
      - "example-website": "web2.example.com:32350"
22
      - "example-website": "web3.example.com:31185"
23
...

Save your replica set config file.

Update and restart your replica set deployment.

In any directory, invoke the following Kubernetes command to update and restart your replica set:

kubectl apply -f <replica-set-conf>.yaml

Test the connection to the replica set.

In the development environment, for each host in a replica set, run the following command:

mongosh --host <my-replica-set>/web1.example.com \
      --port 30907
      --ssl \
      --sslAllowInvalidCertificates

In production, for each host in a replica set, specify the TLS certificate and the CA to securely connect to client tools or applications:

mongosh --host <my-replica-set>/web1.example.com \
  --port 30907 \
  --tls \
  --tlsCertificateKeyFile server.pem \
  --tlsCAFile ca-pem

If the connection succeeds, you should see:

Enterprise <my-replica-set> [primary]

Deploy a replica set with the Kubernetes Operator.

If you haven't deployed a replica set, follow the instructions to deploy one.

You must enable TLS for the replica set by providing a value for the spec.security.certsSecretPrefix setting. The replica set must use a custom CA certificate stored with spec.security.tls.ca.

Configure services to ensure connectivity.

1. Paste the following example services into a text editor:

   1
   ---
   2
   kind: Service
   3
   apiVersion: v1
   4
   metadata:
   5
     name: my-external-0
   6
   spec:
   7
     ports:
   8
       - name: mongodb
   9
         protocol: TCP
   10
         port: 443
   11
         targetPort: 27017
   12
     selector:
   13
       statefulset.kubernetes.io/pod-name: my-external-0
   14
   15
   ---
   16
   kind: Service
   17
   apiVersion: v1
   18
   metadata:
   19
     name: my-external-1
   20
   spec:
   21
     ports:
   22
       - name: mongodb
   23
         protocol: TCP
   24
         port: 443
   25
         targetPort: 27017
   26
     selector:
   27
       statefulset.kubernetes.io/pod-name: my-external-1
   28
   29
   ---
   30
   kind: Service
   31
   apiVersion: v1
   32
   metadata:
   33
     name: my-external-2
   34
   spec:
   35
     ports:
   36
       - name: mongodb
   37
         protocol: TCP
   38
         port: 443
   39
         targetPort: 27017
   40
     selector:
   41
       statefulset.kubernetes.io/pod-name: my-external-2
   42
   43
   ...

   Note

   If the spec.selector has entries that target headless services or applications, OpenShift may create a software firewall rule explicitly dropping connectivity. Review the selectors carefully and consider targeting the stateful set pod members directly as seen in the example. Routes in OpenShift offer port 80 or port 443. This example service uses port 443.

2. Change the settings to your preferred values.

3. Save this file with a .yaml file extension.

4. To create the services, invoke the following kubectl command on the services file you created:

   kubectl apply -f <my-external-services>.yaml

Configure routes to ensure TLS terminination passthrough.

1. Paste the following example routes into a text editor:

   1
   ---
   2
   apiVersion: v1
   3
   kind: Route
   4
   metadata:
   5
     name: my-external-0
   6
   spec:
   7
     host: my-external-0.{redacted}
   8
     to:
   9
       kind: Service
   10
       name: my-external-0
   11
     tls:
   12
       termination: passthrough
   13
   ---
   14
   apiVersion: v1
   15
   kind: Route
   16
   metadata:
   17
     name: my-external-1
   18
   spec:
   19
     host: my-external-1.{redacted}
   20
     to:
   21
       kind: Service
   22
       name: my-external-1
   23
     tls:
   24
       termination: passthrough
   25
   ---
   26
   apiVersion: v1
   27
   kind: Route
   28
   metadata:
   29
     name: my-external-2
   30
   spec:
   31
     host: my-external-2.{redacted}
   32
     to:
   33
       kind: Service
   34
       name: my-external-2
   35
     tls:
   36
       termination: passthrough
   37
   38
   ...
   39
    

   Note

   To ensure the TLS SNI negotiation with mongod necessary for mongod to respond with the correct horizon replica set topology for the drivers to use, you must set TLS termination passthrough.

2. Change the settings to your preferred values.

3. Save this file with a .yaml file extension.

4. To create the routes, invoke the following kubectl command on the routes file you created:

   kubectl apply -f <my-external-routes>.yaml

Add Subject Alternate Names to your TLS certificates.

Add each external DNS name to the certificate SAN.

Open your replica set resource YAML file.

Configure your replica set resource YAML file.

Use the following example to edit your replica set resource YAML file:

1
---
2
apiVersion: mongodb.com/v1
3
kind: MongoDB
4
metadata:
5
  name: my-external
6
  namespace: mongodb
7
spec:
8
  type: ReplicaSet
9
  members: 3
10
  version: 4.2.2-ent
11
  opsManager:
12
    configMapRef:
13
      name: {redacted}
14
  credentials: {redacted}
15
  persistent: false
16
  security:
17
    tls:
18
      # TLS must be enabled to allow external connectivity
19
      enabled: true
20
    authentication:
21
      enabled: true
22
      modes: ["SCRAM","X509"]
23
  connectivity:
24
    # The "localhost" routes are included to enable the creation of localhost
25
    # TLS SAN in the CSR, per OpenShift route requirements.
26
    # "ocroute" is the configured route in OpenShift.
27
    replicaSetHorizons:
28
      - "ocroute": "my-external-0.{redacted}:443"
29
        "localhost": "localhost:27017"
30
      - "ocroute": "my-external-1.{redacted}:443"
31
        "localhost": "localhost:27018"
32
      - "ocroute": "my-external-2.{redacted}:443"
33
        "localhost": "localhost:27019"
34
35
...

Change the settings to your preferred values.

Save your replica set config file.

Create the necessary TLS certificates and Kubernetes secrets.

Configure TLS for your replica set. Create one secret for the MongoDB replica set and one for the certificate authority. The Kubernetes Operator uses these secrets to place the TLS files in the pods for MongoDB to use.

Update and restart your replica set deployment.

In any directory, invoke the following Kubernetes command to update and restart your replica set:

kubectl apply -f <replica-set-conf>.yaml

Test the connection to the replica set.

The Kubernetes Operator should deploy the MongoDB replica set, configured with the horizon routes created for ingress. After the Kubernetes Operator completes the deployment, you may connect with the horizon using TLS connectivity. If the certificate authority is not present on your workstation, you can view and copy it from a MongoDB pod using the following command:

oc exec -it my-external-0 -- cat /mongodb-automation/ca.pem

To test the connections, run the following command:

mongosh --host my-external/my-external-0.{redacted} \
      --port 443
      --ssl \
      --tlsAllowInvalidCertificates

In production, for each host in a replica set, specify the TLS certificate and the CA to securely connect to client tools or applications:

mongosh --host my-external/my-external-0.{redacted} \
  --port 443 \
  --tls \
  --tlsCertificateKeyFile server.pem \
  --tlsCAFile ca-pem

If the connection succeeds, you should see:

Enterprise <my-replica-set> [primary]