Docs Menu
Docs Home
MongoDB Enterprise Kubernetes Operator
/ /

Generate X.509 Client Certificates

On this page

The MongoDB Enterprise Kubernetes Operator can deploy MongoDB instances with X.509 authentication enabled. If X.509 authentication has been enabled for the deployment, you must generate and use an X.509 certificate to connect to the deployment. This new client certificate must be signed by the same CA that signs the server certificates for the MongoDB deployment to accept it.

Use the procedure outlined in this document to use an X.509 certificate to connect to your X.509-enabled MongoDB deployment.

If you're using HashiCorp Vault as your secret storage tool, you can Create a Vault Secret instead.


To automate certificate renewal for Ops Manager deployments, consider setting up the cert-manager integration.


A full description of Transport Layer Security (TLS), Public Key Infrastructure (PKI) certificates, and Certificate Authorities is beyond the scope of this document. This page assumes prior knowledge of TLS and X.509 authentication.

First create the client certificate. Then create a MongoDB user and connect to the X.509-enabled deployment.


For production use, your MongoDB deployment should use valid certificates generated and signed by a CA. You or your organization can generate and maintain an independent CA using Kubernetes-native tools such as cert-manager.

Obtaining and managing certificates is beyond the scope of this documentation.


You must concatenate your client's TLS certificate and the certificate's key in a .pem file. You must present this .pem file when you connect to your X.509-enabled MongoDB deployment.

To learn about the properties that your client certificates must have, see Client Certificate Requirements in the MongoDB Manual.


If you have not already, run the following command to execute all kubectl commands in the namespace you created.


If you are deploying an Ops Manager resource in a multi-Kubernetes cluster MongoDB deployment:

  • Set the context to the name of the central cluster, such as: kubectl config set context "$MDB_CENTRAL_CLUSTER_FULL_NAME".

  • Set the --namespace to the same scope that you used for your multi-Kubernetes cluster MongoDB deployment, such as: kubectl config --namespace "mongodb".

kubectl config set-context $(kubectl config current-context) --namespace=<metadata.namespace>

Save the following ConfigMap as x509-mongodb-user.yaml:

3kind: MongoDBUser
5 name: new-x509-user
7 username: "CN=my-x509-authenticated-user,OU=organizationalunit,O=organization"
8 db: "$external"
9 mongodbResourceRef:
10 name: '<name of the MongoDB resource>'
11 roles:
12 - db: "admin"
13 name: "readWriteAnyDatabase"

This ConfigMap .yaml file describes a MongoDBUser custom object. You can use these custom objects to create MongoDB users. To learn more, see MongoDB User Resource Specification.

In this example, the ConfigMap describes the user as an X.509 user that the client can use to connect to MongoDB with the corresponding X.509 certificate.


Run the following command to apply the ConfigMap and create the X.509 MongoDB user:

kubectl apply -f x509-mongodb-user.yaml

You should see an output similar to the following: created

Run the following command to check the state of the new-x509-user:

kubectl get mdbu/new-x509-user -o yaml

You should see an output similar to the following:

new-x509-user 8m

Run the following command to find where in each pod the Kubernetes Operator mounted the CA secret:

kubectl get statefulset <> -o yaml

In the output, find the secret-ca mount:

- mountPath: /opt/scripts
name: database-scripts
readOnly: true
- mountPath: /var/lib/mongodb-automation/secrets/ca
name: secret-ca
readOnly: true
- mountPath: /var/lib/mongodb-automation/secrets/certs
name: secret-certs
readOnly: true

In the following step when you connect to your database deployment, append secret-ca to the mountPath, which forms the full path:


Once you have created your X.509 user, try to connect to the deployment using the MongoDB Shell (mongosh):

mongosh --host {host} --port {port} --tls \
--tlsCAFile </path/to/secret-ca> \
--tlsCertificateKeyFile <your-cert>.pem \
--authenticationMechanism MONGODB-X509 \
--authenticationDatabase '$external'
mongosh --host {host} --port {port} --ssl \
--sslCAFile </path/to/secret-ca> \
--sslPEMKeyFile <your-cert>.pem \
--authenticationMechanism MONGODB-X509 \
--authenticationDatabase '$external'


Create One Project using a ConfigMap


Deploy a MongoDB Database Resource