Upcoming changes to IP connectivity and Certificate Authority for MongoDB Atlas

1. IPv4 address changes for AWS clusters

MongoDB Atlas will be replacing the IPv4 addresses of dedicated clusters deployed in AWS. This update will not incur any additional charges and will occur during a scheduled maintenance window if you have one configured.

If you are already using an SRV-based connection string, there should be no disruption, as SRV records will dynamically update to point to the new IP addresses. When the transition occurs, clients using SRV-based connection strings should automatically start connecting to the new IPs without manual intervention.

It is always a good practice to use the SRV connection string format (mongodb+srv://) as it provides automatic service discovery and failover handling.

Additionally, if your connection is over a private connection, such as VPC peering or Private Endpoint, it will not be impacted, as it uses private IP addresses which are not being changed. You will not need to make any adjustments in this case.

FAQs

What changes is Atlas making with respect to the public IPv4 addresses?

MongoDB Atlas will be moving to a new block of IPv4 addresses as part of efforts to mitigate IPv4 scarcity.

What is the expected timeline for the IPv4 address change?

We will begin replacing the public IP addresses for customers starting January 2025. This change will apply to all AWS dedicated clusters.

When will the changes roll out?

If you have a maintenance window configured, the replacement will be done during that time. See the documentation on how to Configure a Maintenance Window. While it is not possible to control the order in which cluster IPs are replaced, we will make every effort to minimize disruptions by prioritizing the following:

Non-production clusters: Replacements will be carried out on non-production clusters first.
Primary node replacement: The IPs for secondary nodes will be replaced first, with the primary node's IP replacement deferred until the end.

I am using the standard connection string and am unable to connect to my cluster nodes after the IPv4 maintenance. How do I resolve this?

There will be no changes to your connection strings because of the IP address changes. Both the SRV and standard connection string will automatically resolve to the new IP addresses. If you experience any issues, the first step is to flush the DNS to remove any cached IP addresses on the client machine.

We are currently using AWS Private Endpoints or AWS VPC peering for connectivity to Atlas. With the upcoming changes, do we need to reconfigure these endpoints?

Since VPC peering and Private Endpoints use private IP addresses, no additional modifications are required for connections using these methods.

Should I expect downtime during these changes?

There will be no downtime during these changes. They will occur in a rolling fashion, meaning only one node will be updated at a time.

Can the clusters be opted out of the IPv4 replacement or can an extension for the IPv4 replacement be requested?

Clusters cannot be opted out of this change and we will not be accepting any extension requests.

Will this change be applied on NVME clusters?

At this moment, NVME clusters are not impacted with these changes. Any future updates would be provided here.

Important information

Until the nodes in a cluster are migrated to the new Elastic IPs, you can view the future IP addresses for your nodes with the Atlas Admin API.

This allows you to make any configuration changes needed for the planned IP address migration.
services.clusters.futureInbound and services.clusters.futureOutbound fields are added to the returnAllIPAddresses endpoint, and each is a list of the new IP addresses for the cluster.

Example API request output:

"futureInbound": [
"string" 
],
"futureOutbound": [ 
"string" 
]

Once the nodes in a cluster have been migrated, services.clusters.futureInbound and services.clusters.futureOutbound will no longer be returned on the returnAllIPAddresses endpoint

2. Addition of Google Trust Services TLS certificate authority

MongoDB Atlas requires Transport Layer Security (TLS) encryption for customer data and intra-cluster network communications. MongoDB Atlas uses Let’s Encrypt as the Certificate Authority (CA) for TLS certificates for all clusters. To improve availability, we are adding Google Trust Services as an additional CA for Atlas clusters. You must ensure that your application recognizes certificates from both Let’s Encrypt and Google Trust Services:

Add GTS Root R1 and GTS Root R2 (from Google Trust Services) into your application’s trust store. Doing this ensures your application recognizes certificates from both CAs.

As a best practice, please avoid hardcoding or pinning specific intermediate CAs in your application. Instead, ensure your application’s trust store accepts all recognized root CAs to maintain flexibility, following best practices from MongoDB and Google Trust Services.

For your reference, the root CA certificates for the Google Trust Store can be found at https://pki.goog/repository/ under the "Root CAs" section.

How to check if the certificates are present in your environment

For Java-based applications

We suggest checking if GTS Root R1 and GTS Root R2 certificates are already listed in your Java trust store using the keytool (for Solaris, Linux or Mac OS X; or Windows). For additional details, see the Java-Security documentation.

To list the certificates in the trust store:

keytool -list -keystore $JAVA_HOME/lib/security/cacerts -storepass changeit

To ensure if GTS Root R1, GTS Root R2, and ISRG Root X1 are present by filtering the output:
```
keytool -list -keystore $JAVA_HOME/lib/security/cacerts -storepass <password> | grep -E "gts-root|isrg-root"
```
If these are not part of your trust store, you may -importcerts using the keytool.

For Python-based applications

Locate the certificate bundle:
- Python uses the certifi library for its CA bundle. You can find the location of this bundle with:
```
python -m pip show certifi python -c "import certifi; print(certifi.where())"
```
  See the PyPi certifi documentation for additional details.
Check for required certificates:
- Open the CA bundle file (located in the path printed by certifi.where()) and search for GTS Root R1, GTS Root R2, and ISRG Root X1:
```
cat <path_to_certifi_bundle> | grep -E "GTS Root R1|GTS Root R2|ISRG Root X1"
```

Retrieving root certificates in Node.js

Node.js maintains a list of trusted root certificates accessible through the tls.rootCertificates property. This property returns an array of PEM-encoded certificates. You can iterate through this array to check for specific certificates, such as GTS Root R1 and GTS Root R2.

Example script:

const tls = require('tls');
 
// Retrieve the list of root certificates const rootCerts = tls.rootCertificates; 

// Check for GTS Root R1 and GTS Root R2 
const gtsRootR1 = rootCerts.find(cert => cert.includes('GTS Root R1')); 
const gtsRootR2 = rootCerts.find(cert => cert.includes('GTS Root R2')); 

console.log(`GTS Root R1 Trusted: ${gtsRootR1 ? 'Yes' : 'No'}`); 
console.log(`GTS Root R2 Trusted: ${gtsRootR2 ? 'Yes' : 'No'}`);

See the Node.js tls.rootCertificates Property documentation for more details.

For Windows-based virtual machines

To verify certificates in the Local Machine Trusted Root Certification Authorities store on a Windows system, you can use the following PowerShell command:

Get-ChildItem -Path Cert:\LocalMachine\Root

You can also check the Trusted Root Certification Authorities Certificate Store through the Windows GUI. For detailed instructions, see the Azure documentation on Trusted Root Certification Authorities Certificate Store.

For App Services and Cloud Functions are Azure cloud offerings, we recommend reaching out to Azure support. They can provide assistance in verifying CA certificate details from the backend environment.

For AWS environment

If your application is hosted on AWS (EC2 or Lambda), you can check if the required CAs are already available in your environment by running the following command from the environment's CLI:

openssl x509 -in /etc/ssl/certs/ca-bundle.crt -text -noout | grep -A2 "GTS Root R"

Alternatively, if you're using AWS Certificate Manager, see the official AWS documentation to list the certificates.

If your application server is running inside a container (AWS ECS/EKS), you must contact AWS support to verify whether the container/pod's trust store contains the GTS Root R1 and GTS Root R2 certificates.

FAQs

What changes is Atlas making with respect to the X.509 Certificate Authority?

MongoDB is onboarding Google Trust Service (GTS) as an alternative CA for Atlas. It will be actively used with Let's Encrypt Certificate Authority at no additional cost.

What is the expected timeline?

We will start making the changes from June 2025 onwards.

Are the new CA certificates cross-signed by both Let's Encrypt and Google Trust Service?

In a cluster, TLS certificates will be signed by Let’s Encrypt for some nodes and by Google Trust Services for others. Certificates will not be cross-signed.