Amazon DocumentDB (with MongoDB compatibility) customers: Update your TLS certificates by March 5, 2020

This post was originally published on January 08, 2020 and has been updated as of February 05, 2020. Please see new dates and suggested timeline below.

If you are an Amazon DocumentDB (with MongoDB compatibility) customer, you might have received emails from AWS notifying you about rotating your TLS certificates. The TLS certificates for Amazon DocumentDB clusters will expire on March 5, 2020 as part of standard maintenance and security best practices for Amazon DocumentDB. In order to avoid interruption to your applications that use TLS, we strongly recommend that you complete your updates before February 28, 2020. This blog post gives you more details about the upcoming expiration, explains how to tell if your clusters are affected, and lets you know what you should do to maintain connectivity to your cluster.

What is going on?

The Amazon DocumentDB CA and server certificates are being updated as part of standard maintenance and security best practices. The current server certificate will expire on March 5, 2020. Your database clients and applications that use TLS to connect to an Amazon DocumentDB cluster will lose connectivity beginning March 5, 2020 if you do not update the TLS certificate on both the client and the cluster. We strongly recommend completing this change by February 28, 2020 to avoid disruption to your Amazon DocumentDB clusters.

Additionally, any new Amazon DocumentDB cluster or instance created after January 14, 2020 will have the new server certificates. All Amazon DocumentDB clusters or instances created prior to that point will have the old certificates (unless you have already updated your server certificate). If you wish to temporarily revert new instances or clusters manually to use the old certificate, you can do so using the AWS Management Console or the AWS CLI. However, as noted above, these and all other clusters and instances should be updated to use the new certificates by March 5, 2020.

Frequency asked questions

What if I have questions or issues?

If you have questions or issues, contact AWS Support.

How do I know whether I’m using TLS to connect to my Amazon DocumentDB cluster?

You can determine whether your cluster is using TLS by examining the TLS parameter for your cluster’s cluster parameter group. If the TLS parameter is set to enable, you are using the TLS certificate to connect to your cluster. For more information, see Managing Amazon DocumentDB Cluster Parameter Groups.

Why are you updating the CA and server certificates?

The Amazon DocumentDB CA and server certificates are being updated as part of standard maintenance and security best practices. The current CA and server certificates are set to expire on Thursday, March 5, 2020.

What happens if I don’t take action by March 5, 2020?

If you are using TLS to connect to your Amazon DocumentDB cluster, and you do not make the change by March 5, 2020, your applications that connect via TLS and verify that the CA certificate will no longer be able to communicate with the Amazon DocumentDB cluster.

Previously, we had communicated that between February 5 and March 5, 2020, Amazon DocumentDB would automatically stage the new certificates on Amazon DocumentDB clusters. Based on customer feedback and to give you as much time as possible to complete your updates, Amazon DocumentDB will neither stage nor update your database certificates automatically ahead of March 5, 2020. This means that you will be able to use the full time until March 5, 2020 to update your applications and clusters to use the new CA certificates.

How do I know which of my Amazon DocumentDB instances are still using the old server certificate?

To identify the Amazon DocumentDB instances that are still using the old server certificate, you can use either the Amazon DocumentDB AWS Management Console or the AWS CLI. For more detailed instructions, see Updating Your Amazon DocumentDB TLS Certificates.

Below is an example of identifying the “Certificate authority” for each instance in a particular Region. Below you can see the mix of instances using both the old “rds-ca-2015” server certificate and the new “rds-ca-2019” server certificate. Note that the scope of the instance viewed is only for the given Region. Please check all Regions in which you utilize Amazon DocumentDB.

How do I know which of my Amazon DocumentDB clusters have pending maintenance to rotate the old server certificate?

To identify the Amazon DocumentDB clusters that have pending maintenance for server certification rotation, you can use either the Amazon DocumentDB AWS Management Console or the AWS CLI. For more detailed instructions, see Updating Your Amazon DocumentDB TLS Certificates.

Below is an example of what pending “Certificate maintenance” looks like in the Amazon DocumentDB Management Console. The red circle with an “8” indicates that there are eight clusters in this Region that require certificate maintenance. Note that the scope of “Certificate maintenance” is only for the given Region. Please check all Regions in which you utilize Amazon DocumentDB.

What do I have to do to update my Application and Amazon DocumentDB Cluster in order to maintain connectivity?

Follow the steps below to update your application’s CA certificate bundle (Step 1) and your cluster’s server certificates (Step 2). Before you apply the changes to your production environments, we strongly recommend testing these steps in a development or staging environment.

Note: You must complete Steps 1 and 2 in each AWS Region in which you have Amazon DocumentDB clusters.

Step 1: Download the new CA certificate and update your application.

Download the new CA certificate and update your application to use the new CA certificate to create TLS connections to Amazon DocumentDB. Download the new CA certificate bundle from: https://s3.amazonaws.com/rds-downloads/rds-combined-ca-bundle.pem.

Next, update your applications to use the new certificate bundle. The new CA bundle contains both the old CA certificate (rds-ca-2015-root.pem) and the new CA certificate (rds-ca-2019-root.pem). Having both CA certificates in the new CA bundle enables you to update your application and cluster in two steps.

Any downloads of the CA certificate bundle after September 1, 2019 should use the new CA certificate bundle. To verify that your application is using the latest CA certificate bundle, see How can I be sure that I’m using the newest CA bundle? If you’re already using the latest CA certificate bundle in your application, you can skip to Step 2.

Step 2: Update the server certificate.

Once the application has been updated to use the new CA bundle, the next step is to update the server certificate on the Amazon DocumentDB cluster. The server certificate can be updated by applying the pending maintenance action to rotate the server certificate.

For more detailed instructions, see Updating Your Amazon DocumentDB TLS Certificates.

We strongly recommend that you complete both steps as soon as possible or, at the latest by March 5, 2020 to avoid disruption to your application.

If I’m not using TLS to connect to my cluster, do I still need to update each of my instances?

If you are not using TLS to connect to your Amazon DocumentDB clusters, no action is needed. The server certificate for your cluster will be automatically updated before March 5, 2020 during one of your regular maintenance windows.

Can the deadline be extended beyond March 5, 2020?

If your applications are connecting via TLS, the deadline cannot be extended beyond March 5, 2020.

Why do I see “RDS” in the name of the CA bundle?

For certain management features, such as certificate management, Amazon DocumentDB uses operational technology that is shared with Amazon Relational Database Service (Amazon RDS).

When will the new certificate expire?

The new server certificate will expire on August 22, 2024.

If I applied the new server certificate, can I revert it back to the old server certificate?

Yes, if you need to revert an instance to the old server certificate, it is recommended that you do so for all instances in the cluster. You can revert the server certificate for each instance in a cluster by using the AWS Management Console or the AWS CLI.

For detailed instructions on reverting the certificate, refer to Updating Your Amazon DocumentDB TLS Certificates.

If we restore from a snapshot or a point in time restore, will it have the new server certificate?

If you restore a snapshot or perform a point-in-time restore after January 14, 2020, the new cluster that is created will use the new server certificate.

If I’m not using TLS to connect to my cluster but I plan to in the future, what should I do?

If you created a cluster before November 1, 2019, follow Step 1 and Step 2 in the previous section to ensure that your application is using the updated CA bundle, and that each Amazon DocumentDB instance is using the latest server certificate. If you created a cluster after November 1, 2019, your cluster will already have the latest server certificate. To verify that your application is using the latest CA bundle, see If I’m not using TLS to connect to my cluster, do I still need to update each of my instances?

About the Author

Joseph Idziorek is a Principal Product Manager at Amazon Web Services.