Note
This information only applies to users in the GovCloud (US-West) region.
Updating Your Application and Amazon DocumentDB Cluster
Follow the steps in this section 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 Amazon Web Services Region in which you have Amazon DocumentDB clusters.
Step 1: Download the New CA Certificate and Update Your Application
For examples of using a CA bundle with your application, see Encrypting Data in Transit and Connecting with TLS Enabled.
Note
Currently, the MongoDB Go Driver 1.2.1 only accepts one CA server certificate in
sslcertificateauthorityfile
. Please see Connecting with TLS Enabled for connecting to Amazon
DocumentDB using Go when TLS is enabled.
Step 2: Update the Server Certificate
After the application has been updated to use the new CA bundle, the next step is to update the server certificate by modifying each instance in an Amazon DocumentDB cluster. To modify instances to use the new server certificate, see the following instructions.
Note
Updating your instances requires a reboot, which might cause service disruption. Before updating the server certificate, ensure that you have completed Step 1.
Frequently Asked Questions
The following are answers to some common questions about TLS certificates.
What if I have questions or issues?
If you have questions or issues, contact Amazon Web Services 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 enabled
, 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?
What happens if I don't take any action by the expiration date?
If you are using TLS to connect to your Amazon DocumentDB cluster and you do not make the change by May 18, 2022, your applications that connect via TLS will no longer be able to communicate with the Amazon DocumentDB cluster.
Amazon DocumentDB will not rotate your database certificates automatically before expiration. You must update your applications and clusters to use the new CA certificates before or after the expiration date.
How do I know which of my Amazon DocumentDB instances are using the old/new server certificate?
To identify the Amazon DocumentDB instances that still use the old server certificate, you can use either the Amazon DocumentDB Amazon Web Services Management Console or the Amazon CLI.
To identify the instances in your clusters that are using the older certificate
Sign in to the Amazon Web Services Management Console, and open the Amazon DocumentDB console at https://console.amazonaws.cn/docdb
. -
In the list of Regions in the upper-right corner of the screen, choose the Amazon Web Services Region in which your instances reside.
-
In the navigation pane on the left side of the console, choose Instances.
-
-
Choose the Settings icon.
-
Under the list of visible columns, choose the Certificate authority column.
-
Choose Confirm to save your changes.
-
To identify the instances in your clusters that are using the older server
certificate, use the describe-db-clusters
command with the following
.
aws docdb describe-db-instances \ --filters Name=engine,Values=docdb \ --query 'DBInstances[*].{CertificateVersion:CACertificateIdentifier,InstanceID:DBInstanceIdentifier}'
How do I modify individual instances in my Amazon DocumentDB cluster to update the server certificate?
We recommend that you update server certificates for all instances in a given cluster at the same time. To modify the instances in your cluster, you can use either the console or the Amazon CLI.
Note
Updating your instances requires a reboot, which might cause service disruption. Before updating the server certificate, ensure that you have completed Step 1.
Sign in to the Amazon Web Services Management Console, and open the Amazon DocumentDB console at https://console.amazonaws.cn/docdb
. -
In the list of Regions in the upper-right corner of the screen, choose the Amazon Web Services Region in which your clusters reside.
-
In the navigation pane on the left side of the console, choose Instances.
-
The Certificate authority column (hidden by default) shows which instances are still on the old server certificate (
rds-ca-2017
). To show the Certificate authority column, do the following:-
Choose the Settings icon.
-
Under the list of visible columns, choose the Certificate authority column.
-
Choose Confirm to save your changes.
-
-
Select an instance to modify.
-
Choose Actions and then choose Modify.
-
You can see a summary of the changes on the next page. Note that there is an extra alert to remind you to ensure that your application is using the latest certificate CA bundle before modifying the instance to avoid causing an interruption in connectivity.
-
You can choose to apply the modification during your next maintenance window or apply immediately.
-
Choose Modify instance to complete the update.
Complete the following steps to identify and rotate the old server certificate for your existing Amazon DocumentDB instances using the Amazon CLI.
-
To modify the instances immediately, execute the following command for each instance in the cluster.
-
To modify the instances in your clusters to use the new CA certificate during your cluster’s next maintenance window, execute the following command for each instance in the cluster.
What happens if I add a new instance to an existing cluster?
What happens if there is an instance replacement or failover on my cluster?
If there is an instance replacement in your cluster, the new instance that is created continues to use the same server certificate that the instance was previously using. We recommend that you update server certificates for all instances at the same time. If a failover occurs in the cluster, the server certificate on the new primary is used.
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.
If I'm not using TLS to connect to my cluster but I plan to in the future, what should I do?
How can I be sure that I'm using the newest CA bundle?
For compatibility reasons, both old and new CA bundle files are named
us-gov-west-1-bundle.pem
. You can also use tools like
openssl
or keytool
to inspect the CA bundle.
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).
If I applied the new server certificate, can I revert it back to the old server certificate?
If you need to revert an instance to the old server certificate, we recommend 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 Amazon Web Services Management Console or the Amazon CLI.
Sign in to the Amazon Web Services Management Console, and open the Amazon DocumentDB console at https://console.amazonaws.cn/docdb
. -
In the list of Regions in the upper-right corner of the screen, choose the Amazon Web Services Region in which your clusters reside.
-
In the navigation pane on the left side of the console, choose Instances.
-
Select an instance to modify. Choose Actions, and then choose Modify.
-
Choose Continue to view a summary of your modifications.
-
In this resulting page, you can choose to schedule your modifications to be applied in the next maintenance window or apply your modifications immediately. Make your selection, and choose Modify instance.
Note
If you choose to apply your modifications immediately, any changes in the pending modifications queue are also applied. If any of the pending modifications require downtime, choosing this option can cause unexpected downtime.
If you choose --no-apply-immediately
, the changes will be applied
during the cluster’s next maintenance window.
If I restore from a snapshot or a point in time restore, will it have the new server certificate ?
What if I’m having issues connecting directly to my Amazon DocumentDB cluster from Mac OS X Catalina?
Mac OS X Catalina has updated the requirements for trusted certificates. Trusted
certificates must now be valid for 825 days or fewer (see https://support.apple.com/en-us/HT210176
To connect to an Amazon DocumentDB cluster from OS X Catalina using the Amazon CLI, use the
tlsAllowInvalidCertificates
parameter.
mongo --tls --host <hostname> --username <username> --password <password> --port 27017 --tlsAllowInvalidCertificates