Maintaining Amazon DocumentDB

Periodically, Amazon DocumentDB performs maintenance on Amazon DocumentDB resources. Maintenance most often involves updates to the database engine (cluster maintenance) or the instance’s underlying operating system (OS) (instance maintenance).

Some maintenance items require that Amazon DocumentDB take your instance offline for a short time. Maintenance items that require an instance to be offline include required operating system or engine patching. Required patching is automatically scheduled only for patches that are related to security and instance reliability. Such patching occurs infrequently (typically once every few months) and seldom requires more than a fraction of your maintenance window. You should expect that when maintenance is performed on your cluster or instance, if the instance is a primary instance, it will fail over. For more information, see Amazon DocumentDB Failover.

Both cluster and instances maintenance have their own respective maintenance windows. By default, when you create a cluster, Amazon DocumentDB assigns a maintenance window for both a cluster and each individual instance. You can choose the maintenance window when creating a cluster or an instance. 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). This guidance is highly contextual upon the type of application and usage patterns that you experience.

Determining Pending Amazon DocumentDB Maintenance Actions

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

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

• Defer the maintenance actions.

• Apply the maintenance actions immediately.

• Schedule the maintenance actions to start during your next maintenance window.

• Take no action.

Important

Certain OS updates are marked as Required. If you defer a required update, you receive a notice from Amazon DocumentDB indicating when the update will be performed on your instance or cluster. Other updates are Available. You can defer these updates indefinitely.

The maintenance window determines when pending operations start, but it does not limit the total execution time of these operations. Maintenance operations are not guaranteed to finish before the maintenance window ends, and they can continue beyond the specified end time.

Using the AWS Management Console

If an update is available, it is indicated by the word Available or Required in the Maintenance column for the cluster on the Amazon DocumentDB console, as shown here:

Using the AWS CLI

Use the following AWS CLI operation to determine what maintenance actions are pending. The output here shows no pending maintenance actions.

aws docdb describe-pending-maintenance-actions

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

{
    "PendingMaintenanceActions": []
}

Applying Amazon DocumentDB Updates

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

Use the procedures in this topic to immediately upgrade or schedule an upgrade for your instance.

Using the AWS Management Console

You can use the console to manage updates for your Amazon DocumentDB instances and clusters.

To manage an update for an instance or cluster

1. Sign in to the AWS Management Console, and open the Amazon DocumentDB console at https://console.aws.amazon.com/docdb.

2. In the navigation pane, choose clusters.

3. In the list of clusters, choose the button next to the name of the cluster that you want to apply the maintenance operation to.

4. On the Actions menu, choose one of the following:

   • Upgrade now to immediately perform the pending maintenance tasks.

   • Upgrade at next window to perform the pending maintenance tasks during the cluster’s next maintenance window.

     Note

     If there are no pending maintenance tasks, both of the preceding options are inactive.

Using the AWS CLI

To apply a pending update to an instance or cluster, use the apply-pending-maintenance-action AWS CLI operation.

Parameters

• --resource-identifier—The Amazon DocumentDB Amazon Resource Name (ARN) of the resource that the pending maintenance action applies to.

• --apply-action—The pending maintenance action to apply to this resource.

  Valid values: system-update and db-upgrade.

• --opt-in-type—A value that specifies the type of opt-in request, or undoes an opt-in request. An opt-in request of type immediate can’t be undone.

  Valid values:

  • immediate—Apply the maintenance action immediately.

  • next-maintenance—Apply the maintenance action during the next maintenance window for the resource.

  • undo-opt-in—Cancel any existing next-maintenance opt-in requests.

For Linux, macOS, or Unix:

aws docdb apply-pending-maintenance-action \
    --resource-identifier arn:aws:rds:us-east-1:123456789012:db:docdb \
    --apply-action system-update \
    --opt-in-type immediate

For Windows:

aws docdb apply-pending-maintenance-action ^
    --resource-identifier arn:aws:rds:us-east-1:123456789012:db:docdb ^
    --apply-action system-update ^
    --opt-in-type immediate

To return a list of resources that have at least one pending update, use the describe-pending-maintenance-actions AWS CLI operation.

For Linux, macOS, or Unix:

aws docdb describe-pending-maintenance-actions \
    --resource-identifier arn:aws:rds:us-east-1:001234567890:db:docdb

For Windows:

aws docdb describe-pending-maintenance-actions ^
    --resource-identifier arn:aws:rds:us-east-1:001234567890:db:docdb

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

{
    "PendingMaintenanceActions": [
        {
            "ResourceIdentifier": "arn:aws:rds:us-east-1:001234567890:cluster:sample-cluster",
            "PendingMaintenanceActionDetails": [
                {
                    "Action": "system-update",
                    "CurrentApplyDate": "2019-01-11T03:01:00Z",
                    "Description": "db-version-upgrade",
                    "ForcedApplyDate": "2019-01-18T03:01:00Z",
                    "AutoAppliedAfterDate": "2019-01-11T03:01:00Z"
                }
            ]
        }
    ]
}

You can also return a list of resources for an instance or cluster by specifying the --filters parameter of the describe-pending-maintenance-actions AWS CLI operation. The format for the --filters operation is Name=`filter-name`,Values=`resource-id`,....

The following are acceptable values for the Name parameter of filter:

• db-cluster-id—Accepts a list of cluster identifiers or ARNs. The returned list only includes pending maintenance actions for the clusters identified by these identifiers or ARNs.

• db-instance-id—Accepts a list of instance identifiers or ARNs. The returned list only includes pending maintenance actions for the instances identified by these identifiers or ARNs.

The following example returns the pending maintenance actions for the sample-cluster1 and sample-cluster2 clusters.

For Linux, macOS, or Unix:

aws docdb describe-pending-maintenance-actions \
   --filters Name=db-cluster-id,Values=sample-cluster1,sample-cluster2

For Windows:

aws docdb describe-pending-maintenance-actions ^
   --filters Name=db-cluster-id,Values=sample-cluster1,sample-cluster2

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:

• CurrentApplyDate—The date the maintenance action will get applied either immediately or during the next maintenance window. If the maintenance is optional, this value can be null.

• ForcedApplyDate—The date when the maintenance will be automatically applied, independent of your maintenance window.

• AutoAppliedAfterDate—The date after which the maintenance will be applied during the cluster’s maintenance window.

User-Initiated Updates

As an Amazon DocumentDB user, you can initiate updates to your clusters or instances. For example, you can modify an instance’s class to one with more or less memory, or you can change a cluster’s parameter group. Amazon DocumentDB views these changes differently from Amazon DocumentDB initiated updates. For more information about modifying a cluster or instance, see the following:

• Modifying an Amazon DocumentDB Cluster

• Modifying an Amazon DocumentDB Instance

To see a list of pending user initiated modifications, run the following command.

To see pending user initiated changes for your instances

For Linux, macOS, or Unix:

aws docdb describe-db-instances \
    --query 'DBInstances[*].[DBClusterIdentifier,DBInstanceIdentifier,PendingModifiedValues]'

For Windows:

aws docdb describe-db-instances ^
    --query 'DBInstances[*].[DBClusterIdentifier,DBInstanceIdentifier,PendingModifiedValues]'

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

In this case, sample-cluster-instance has a pending change to a db.r5.xlarge instance class, while sample-cluster-instance-2 has no pending changes.

[
    [
        "sample-cluster",
        "sample-cluster-instance",
        {
            "DBInstanceClass": "db.r5.xlarge"
        }
    ],
    [
        "sample-cluster",
        "sample-cluster-instance-2",
        {}
    ]
]

Managing Your Amazon DocumentDB Maintenance Windows

Each instance and cluster has a weekly maintenance window during which any pending changes are applied. The maintenance window is an opportunity to control when modifications and software patching occur, in the event either are requested or required. If a maintenance event is scheduled for a given week, it is initiated during the 30-minute maintenance window that you identify. Most maintenance events also complete during the 30-minute maintenance window, although larger maintenance events might take more than 30 minutes to complete.

The 30-minute maintenance window is selected at random from an 8-hour block of time per Region. If you don’t specify a preferred maintenance window when you create the instance or cluster, Amazon DocumentDB assigns a 30-minute maintenance window on a randomly selected day of the week.

The following table lists the time blocks for each Region from which default maintenance windows are assigned.

Changing a Maintenance Window

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

For upgrades to the database engine, Amazon DocumentDB uses the cluster’s preferred maintenance window and not the maintenance window for individual instances.

To change the maintenance window

• For a cluster, see Modifying an Amazon DocumentDB Cluster.

• For an instance, see Modifying an Amazon DocumentDB Instance.