- Deploy and Configure MongoDB Database Resources >
- Configure the Kubernetes Operator for MongoDB Database Resources >
- Generate X.509 Client Certificates
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 Kubernetes CA to be accepted by the MongoDB deployment.
Use the procedure outlined in this document to:
- Generate an X.509 certificate.
- Get that certificate signed by the Kubernetes CA.
- Use the certificate to connect to your X.509-enabled MongoDB deployment.
Prerequisites¶
Note
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.
- To complete this tutorial, you must have the MongoDB Enterprise Kubernetes Operator installed. For instructions on installing the Kubernetes Operator, see Install the MongoDB Enterprise Kubernetes Operator.
- This tutorial assumes you have a MongoDB deployment which requires X.509 authentication. For instructions on deploying MongoDB resources, see Deploy a MongoDB Database Resource.
- This tutorial uses
CFSSL
to generate X.509 certificates.CFSSL
is a certificate generation tool built by Cloudflare. For instructions on installingCFSSL
, refer to the CFSSL GitHub page.
Procedure¶
Note
The user configuration files used in this tutorial are strictly examples. You may need to adjust the values in the examples to suit your deployment’s needs. For more information on formatting user ConfigMaps, see Manage Database Users.
Generate a Private Key and Certificate Signing Request¶
Create a new directory to complete this tutorial.¶
Run the following command to create a new directory for the configuration files used in this tutorial:
Enter your newly created directory.¶
Copy and save the following example JSON.¶
In the client-x509-certs-tutorial
directory, save the following
JSON as x509_user.json
:
Generate a key file.¶
Run the following command to pass the JSON from the previous step
to CFSSL
and generate a key file:
You should see output similar to the following:
You now have a file called x509_user_key.json
containing
a new private key.
Generate the Certificate Signing Request.¶
Run the following command to use your x509_user_key.json
key
file to generate a certificate signing request (CSR):
This command generates two files:
x509_user-key.pem
, the private key for the userx509_user.csr
, the CSR that represents the user
Submit the New CSR to the Kubernetes CA¶
Kubernetes’ own certificate authority provides the trusted CA
for the Kubernetes cluster. You need the .csr
and .pem
files
generated in the previous section to request a new certificate from
Kubernetes.
Create a CSR in Kubernetes.¶
Run the following command to create a CSR in Kubernetes:
View your CSRs.¶
Run the following command to view a list of CSRs:
You should see an output similar to the following:
Approve the CSR.¶
The CSR remains in Pending
condition
until Kubernetes approves it. Run the following command to
approve the certificate:
You should see an output similar to the following:
Verify that your certificate has been approved¶
Run the following command to verify that the Kubernetes CA has approved your certificate:
You should see an output similar to the following:
Obtain the Newly Issued Certificate from the Kubernetes CA¶
You can use the new certificate.
The status.certificate
attribute of the CSR
generated in the previous section
contains the certificate.
Concatenate the user private key and Kubernetes certificate.¶
You need both the x509_user-key.pem
and client.crt
files
to connect to the deployment. Run the following command to
concatenate the two files into the a new .pem
file:
Connect to the X.509-Enabled MongoDB Deployment¶
With the client certificate created, you can create a MongoDB user and connect to the X.509-enabled deployment.
Copy and save the following example ConfigMap.¶
Save the following ConfigMap as x509-mongodb-user.yaml
:
This ConfigMap .yaml
file describes a MongoDBUser
custom object. You
can use these custom objects to create MongoDB users.
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.
Create the X.509 MongoDB user.¶
Run the following command to apply the ConfigMap and create the X.509 MongoDB user:
You should see an output similar to the following:
Verify your newly created user¶
Run the following command to check the state of the new-x509-user
:
You should see an output similar to the following:
Use your X.509 user to connect to the MongoDB deployment¶
Once you have created your X.509 user, try to connect to the deployment using the mongo Shell:
- MongoDB 4.2
- MongoDB 4.0 and Older
Note
On Kubernetes Pods, the CA file is saved in
/var/run/secrets/kubernetes.io/serviceaccount/ca.crt
, which
is the file location used for the --sslCAFile
connection
option.