Navigation
This documentation refers to the on-premises edition of MongoDB Charts. Read the Atlas service documentation to learn how to use MongoDB Charts with your Atlas project.

Configure TLS/SSL for Metadata Clusters

This document explains how to use a TLS/SSL-enabled MongoDB deployment as your Charts metadata database. This document also demonstrates connecting MongoDB Charts to a deployment using x.509 client authentication.

Prerequisites

Note

A full description of TLS/SSL, PKI (Public Key Infrastructure) certificates, and Certificate Authority is beyond the scope of this document. This page assumes prior knowledge of TLS/SSL as well as access to valid certificates.

If you have created a Docker secret for your Charts metadata database, you must remove it prior to this procedure.

  1. If Charts is running in the Docker stack, remove it using the following command:

    docker stack rm mongodb-charts
    
  2. Run the following command to remove the old Docker secret:

    docker secret rm charts-mongodb-uri
    

Use a TLS/SSL-Enabled Deployment without Client Certificate Validation

You can use a TLS/SSL-enabled MongoDB deployment as your metadata database. If the deployment is running with TLS/SSL enabled, configuring your metadata database depends on whether the deployment’s certificate is:

  • Signed by a trusted root certificate authority, or
  • Self-signed or issued by an internal certificate authority.

Note

MongoDB deployments should use TLS/SSL 1.1 or later.

Select the appropriate tab based on how the deployment’s certificate is signed:

If your MongoDB deployment uses a certificate signed by a trusted root certificate authority, append the ssl=true option to the Connection String URI when you create the Docker secret for the metadata database:

echo "mongodb://<username>:<password>@myhost.com?ssl=true" | docker secret create charts-mongodb-uri -

If your MongoDB deployment uses a self-signed certificate or a certificate issued by an internal certificate authority, you must copy the certificate to the Docker volume.

1

Copy the certificates to the Charts Docker volume.

The certificate must be in the .pem format and will be either:

  • the self-signed certificate used by the MongoDB deployment, or
  • the CA’s root certificate, if the certificate used by the MongoDB deployment was issued by a CA.

Choose the appropriate tab based on your operating system:

The following command copies certificates in the C:\path\to\certs directory to the Charts host:

docker run -it -v mongodb-charts_db-certs:/volume -v /c/path/to/certs:/localcerts alpine sh -c 'cp /localcerts/*.pem /volume'

Note

This Docker command uses Unix-style paths on Windows.

The following command copies certificates in the /path/to/certs directory to the Charts host:

docker run -it -v mongodb-charts_db-certs:/volume -v /path/to/certs:/localcerts alpine sh -c 'cp /localcerts/*.pem /volume'

The following command copies certificates in the /path/to/certs directory to the Charts host:

docker run -it -v mongodb-charts_db-certs:/volume -v /path/to/certs:/localcerts alpine sh -c 'cp /localcerts/*.pem /volume'
2

Create the Docker secret for the metadata database.

Run the following command to create the Docker secret for the metadata database, specifying ssl=true as a connection string option.

echo "mongodb://<username>:<password>@myhost.com?ssl=true" | docker secret create charts-mongodb-uri -
3

Launch the Charts container.

Launch the Charts container as a Docker Stack using the Compose file:

docker stack deploy -c charts-docker-swarm-19.09.yml mongodb-charts

Note

If you are using a different version of Charts, replace 19.09 with the version number of your release.

Use a TLS/SSL-Enabled Deployment with Client Certificate Validation/x.509

Use this procedure to if the MongoDB deployment you wish to use for your metadata database requires Client Certificate Validation.

The process to configure your metadata database depends on whether the deployment’s certificate is:

  • Signed by a trusted root certificate authority, or
  • Self-signed or issued by an internal certificate authority.

Note

MongoDB deployments should use TLS/SSL 1.1 or later.

Select the appropriate tab based on how the deployment’s certificate is signed:

If your MongoDB deployment uses a certificate signed by a trusted root certificate authority, you must copy the client certificate to the Docker volume.

1

Copy the client certificate to the Charts Docker volume.

The following command copies certificates in the C:\path\to\certs directory to the Charts host:

docker run -it -v mongodb-charts_db-certs:/volume -v /c/path/to/certs:/localcerts alpine sh -c 'cp /localcerts/*.pem /volume'

Note

This Docker command uses Unix-style paths on Windows.

The following command copies certificates in the /path/to/certs directory to the Charts host:

docker run -it -v mongodb-charts_db-certs:/volume -v /path/to/certs:/localcerts alpine sh -c 'cp /localcerts/*.pem /volume'

The following command copies certificates in the /path/to/certs directory to the Charts host:

docker run -it -v mongodb-charts_db-certs:/volume -v /path/to/certs:/localcerts alpine sh -c 'cp /localcerts/*.pem /volume'
2

Create the Docker secret for the metadata database.

Run the following command to create the Docker secret for the metadata database, specifying the following connection string options.

Option Value
ssl true
sslclientcertificatekeyfile Path to your client certificate.

The following example connects to the deployment using SCRAM authentication. Replace the certificate file values in the following command with the locations of your certificate files:

echo "mongodb://<user>:<password>@<server:port>?ssl=true&sslclientcertificatekeyfile=/mongodb-charts/volumes/db-certs/client.pem" | docker secret create charts-mongodb-uri -

Alternatively, to use x.509 Client Authentication you must:

  • Remove the <user> and <password>,
  • Specify the authMechanism=MONGODB-X509 option.
echo "mongodb://<server:port>?ssl=true&sslclientcertificatekeyfile=/mongodb-charts/volumes/db-certs/client.pem&authMechanism=MONGODB-X509" | docker secret create charts-mongodb-uri -
3

Launch the Charts container.

Launch the Charts container as a Docker Stack using the Compose file:

docker stack deploy -c charts-docker-swarm-19.09.yml mongodb-charts

Note

If you are using a different version of Charts, replace 19.09 with the version number of your release.

If your MongoDB deployment uses a self-signed certificate or a certificate issued by an internal certificate authority, you must copy the certificate to the Docker volume.

1

Copy the client and CA certificates to the Charts Docker volume.

You must upload two certificate files to the Charts Docker volume:

  • The client certificate, including the private key.
  • The certificate for the deployment’s CA. You do not need to include the private key with this certificate.

The following command copies certificates in the C:\path\to\certs directory to the Charts host:

docker run -it -v mongodb-charts_db-certs:/volume -v /c/path/to/certs:/localcerts alpine sh -c 'cp /localcerts/*.pem /volume'

Note

This Docker command uses Unix-style paths on Windows.

The following command copies certificates in the /path/to/certs directory to the Charts host:

docker run -it -v mongodb-charts_db-certs:/volume -v /path/to/certs:/localcerts alpine sh -c 'cp /localcerts/*.pem /volume'

The following command copies certificates in the /path/to/certs directory to the Charts host:

docker run -it -v mongodb-charts_db-certs:/volume -v /path/to/certs:/localcerts alpine sh -c 'cp /localcerts/*.pem /volume'
2

Create the Docker secret for the metadata database.

Run the following command to create the Docker secret for the metadata database, specifying the following connection string options.

Option Value
ssl true
sslclientcertificatekeyfile Path to your client certificate.
sslcertificateauthorityfile Path to your certificate authority certificate.

The following example connects to the deployment using SCRAM authentication. Replace the certificate file values in the following command with the locations of your certificate files:

echo "mongodb://<user>:<password>@<server:port>?ssl=true&sslclientcertificatekeyfile=/mongodb-charts/volumes/db-certs/client.pem&sslcertificateauthorityfile=/mongodb-charts/volumes/db-certs/ca.pem" | docker secret create charts-mongodb-uri -

Alternatively, to use x.509 Client Authentication you must:

  • Remove the <user> and <password>,
  • Specify the authMechanism=MONGODB-X509 option.
echo "mongodb://<server:port>?ssl=true&sslclientcertificatekeyfile=/mongodb-charts/volumes/db-certs/client.pem&sslcertificateauthorityfile=/mongodb-charts/volumes/db-certs/ca.pem&authMechanism=MONGODB-X509" | docker secret create charts-mongodb-uri -
3

Launch the Charts container.

Launch the Charts container as a Docker Stack using the Compose file:

docker stack deploy -c charts-docker-swarm-19.09.yml mongodb-charts

Note

If you are using a different version of Charts, replace 19.09 with the version number of your release.