Maintaining Amazon DocumentDB elastic clusters

Periodically, Amazon DocumentDB performs maintenance on Amazon DocumentDB elastic cluster resources. Maintenance most often involves updates to the database engine (elastic cluster maintenance) or the elastic cluster's underlying operating system (OS updates). Database engine updates are required patches and include security fixes, bug fixes, and enhancements to the database engine. While most operating system patches are optional, if you don't apply them for a while, the patch may be required and auto applied to maintain your security posture. So, we recommend that you apply operating system updates to your Amazon DocumentDB elastic clusters as soon as they are available.

Database engine patches require that you take your Amazon DocumentDB elastic clusters offline for a short time. Once available, these patches are automatically scheduled to apply during an upcoming scheduled maintenance window of your Amazon DocumentDB elastic cluster.

Elastic clusters have their own respective maintenance windows. Elastic cluster modifications that you have chosen not to apply immediately, are applied during the maintenance window. By default, when you create an elastic cluster, Amazon DocumentDB assigns a maintenance window for your elastic cluster. You can choose the maintenance window when creating an elastic cluster. You can also modify the maintenance windows at any time to fit your business schedules or practices. It is generally advised to choose maintenance windows that minimize the impact of the maintenance on your application (for example, on evenings or weekends).

Viewing pending elastic cluster maintenance actions

You can view whether a maintenance update is available for your elastic cluster by using the AWS CLI.

If an update is available, you can do one of the following:

The maintenance window determines when pending operations start, but it does not limit the total execution time of these operations.

Use the following AWS CLI operation to determine what maintenance actions are pending. List all pending maintenance actions:

aws docdb-elastic list-pending-maintenance-actions

Output from this operation looks something like the following (JSON format):

{
'ResourcePendingMaintenanceActions': [
    {
        'ResourceArn': 'string-arn',
        'PendingMaintenanceActionDetails': [
            {
                'Action': 'ENGINE_UPDATE',
                'AutoAppliedAfterDate': 'string',  
                'ForcedApplyDate': 'string', 
                'OptInStatus': 'string', 
                'CurrentApplyDate': 'string', 
                'Description': 'string'
            },
        ]
    },
],
'NextToken': 'string'
}

Get pending maintenance action (if any) on a given resourceArn:

aws docdb-elastic get-pending-maintenance-action --resource-arn string-arn

Output from this operation looks something like the following (JSON format).

{
    'ResourcePendingMaintenanceAction': {
        'ResourceArn': 'string-arn',
        'PendingMaintenanceActionDetails': [
            {
                'Action': 'ENGINE_UPDATE',
                'AutoAppliedAfterDate': 'string', 
                'ForcedApplyDate': 'string', 
                'OptInStatus': 'string', 
                'CurrentApplyDate': 'string',
                'Description': 'string'
            }
        ]
    }
}

Parameters:

Elastic cluster engine updates

With Amazon DocumentDB, you can choose when to apply maintenance operations. You can decide when Amazon DocumentDB applies updates using the AWS CLI.

Apply pending maintenance actions:

aws docdb-elastic apply-pending-maintenance-action 
--resource-arn string-arn
--apply-action string-enum
--opt-in-type string-enum 
[--apply-on string-date-range]

Parameters:

Output from this operation looks something like the following (JSON format):

{
 'ResourcePendingMaintenanceAction': {
        'ResourceArn': 'string-arn',
        'PendingMaintenanceActionDetails': [
            {
                'Action': 'SECURITY_UPDATE',
                'AutoAppliedAfterDate': 'string',
                'ForcedApplyDate': 'string', 
                'OptInStatus': 'IMMEDIATE', 
                'CurrentApplyDate': 'string', 
                'Description': 'string'
            },
        ]
 }
}

Parameters:

Apply dates

Each maintenance action has a respective apply date that you can find when describing the pending maintenance actions. When you read the output of pending maintenance actions from the AWS CLI, three dates are listed:

User-created maintenance actions

As an Amazon DocumentDBelastic cluster user, you can initiate updates to your clusters configurations.

Updating cluster primary password

aws docdb-elastic update-cluster 
--cluster-arn string-arn
[--admin-user-password string]
[--auth-type string-enum]
[--apply-method string-enum]
[--apply-on string-date-range] 
#... other parameters of the API that follow here are not relevant for this configuration

Parameters:

Output from this operation looks something like the following (JSON format):

{
 'ResourcePendingMaintenanceAction': {
        'ResourceArn': 'string-arn',
        'PendingMaintenanceActionDetails': [
            {
                'Action': 'MASTER_USER_PASSWORD_UPDATE',
                'OptInStatus': 'APPLY_ON', 
                'CurrentApplyDate': 'string', 
                'Description': 'string'
            },
        ]
 }
}

Changing your Amazon DocumentDB maintenance windows

The maintenance window should fall at the time of lowest usage and thus might need changing from time to time. Your elastic cluster is unavailable during this time only if system changes (such as a scale storage operation change) are being applied and require an outage. It is unavailable only for the minimum amount of time required to make the necessary changes.

The default is a 30-minute window selected at random from an 8-hour block of time for each Amazon Web Services Region, occurring on a random day of the week.

To change the maintenance window, see Modifying elastic cluster configurations.

Elastic cluster operating system updates

Amazon DocumentDB elastic clusters occasionally require operating system updates. Amazon DocumentDB upgrades the operating system to a newer version to improve database performance and customers’ overall security posture. Operating system updates don't change the cluster engine version of an Amazon DocumentDB elastic cluster.

Most operating system updates for Amazon DocumentDB elastic clusters are optional and don't have a set date to apply them. However, if you don't apply these updates for a while, they may eventually become required and automatically applied during your clusters maintenance window. This is to help maintain the security posture of your database. To avoid any unexpected downtime, we recommend that you apply operating system updates to your Amazon DocumentDB elastic cluster as soon as they become available and set your cluster maintenance window at a time of your convenience as per your business needs.