Switching a blue/green deployment

A switchover promotes the green environment to be the new production environment. When the green DB instance has read replicas, they are also promoted. Before you switch over, production traffic is routed to the DB instance and read replicas in the blue environment. After you switch over, production traffic is routed to the DB instance and read replicas in the green environment.

Switchover timeout

You can specify a switchover timeout period between 30 seconds and 3,600 seconds (one hour). If the switchover takes longer than the specified duration, then any changes are rolled back and no changes are made to either environment. The default timeout period is 300 seconds (five minutes).

Switchover guardrails

When you start a switchover, Amazon RDS runs some basic checks to test the readiness of the blue and green environments for switchover. These checks are known as switchover guardrails. These switchover guardrails prevent a switchover if the environments aren't ready for it. Therefore, they avoid longer than expected downtime and prevent the loss of data between the blue and green environments that might result if the switchover started.

Amazon RDS runs the following guardrail checks on the green environment:

Amazon RDS runs the following guardrail checks on the blue environment:

Switchover actions

When you switch over a blue/green deployment, RDS performs the following actions:

You can monitor the status of a switchover using Amazon EventBridge. For more information, see Blue/green deployment events.

If you have tags configured in the blue environment, these tags are moved to the new production environment during switchover. The previous production environment also retains these tags. For more information about tags, see Tagging Amazon RDS resources.

If the switchover starts and then stops before finishing for any reason, then any changes are rolled back, and no changes are made to either environment.

Switchover best practices

Before you switch over, we strongly recommend that you adhere to best practices by completing the following tasks:

Verifying CloudWatch metrics before switchover

Before you switch over a blue/green deployment, we recommend that you check the values of the following metrics within Amazon CloudWatch.

For more information about these metrics, see Amazon CloudWatch metrics for Amazon RDS.

Switching over a blue/green deployment

You can switch over a blue/green deployment using the Amazon Web Services Management Console, the Amazon CLI, or the RDS API.

aws rds switchover-blue-green-deployment \
    --blue-green-deployment-identifier bgd-1234567890abcdef \
    --switchover-timeout 600

aws rds switchover-blue-green-deployment ^
    --blue-green-deployment-identifier bgd-1234567890abcdef ^
    --switchover-timeout 600

After switchover

After a switchover, the DB instances in the previous blue environment are retained. Standard costs apply to these resources. Replication between the blue and green environments stops.

RDS renames the DB instances in the blue environment by appending -oldn to the current resource name, where n is a number. The DB instances are read-only until you set the read_only parameter to 0.

Updating the parent node for consumers

After you switch over an RDS for MariaDB or RDS for MySQL blue/green deployment, if the blue DB instance had any external replicas or binary log consumers prior to switchover, you must update their parent node after switchover in order to maintain replication continuity.

After switchover, the DB instance that was previously in the green environment emits an event that contains the master log file name and master log position. For example:

aws rds describe-events --output json --source-type db-instance --source-identifier db-instance-identifier

{
    "Events": [
...
        {
            "SourceIdentifier": "db-instance-identifier",
            "SourceType": "db-instance",
            "Message": "Binary log coordinates in green environment after switchover:
             file mysql-bin-changelog.000003 and position 804",
            "EventCategories": [],
            "Date": "2023-11-10T01:33:41.911Z",
            "SourceArn": "arn:aws:rds:us-east-1:123456789012:db:db-instance-identifier"
        }
    ]
}

First, make sure that the consumer or replica has applied all binary logs from the old blue environment. Then, use the provided binary log coordinates to resume application on the consumers. For example, if you're running a MySQL replica on EC2, you can use the CHANGE MASTER TO command:

CHANGE MASTER TO MASTER_HOST='{new-writer-endpoint}', MASTER_LOG_FILE='mysql-bin-changelog.000003', MASTER_LOG_POS=804;