Perform a blue-green deployment switchover

After you test and validate your green environment, you start a switchover to convert the green environment to become your new production read and write environment.

Before you begin

Before you initiate a switchover, ensure that you have the required permissions and that your deployment is ready for cutover.

Required roles and permissions

To get the permissions that you need to execute a switchover, ask your administrator to grant you the following IAM role on your project:

• Cloud SQL Admin (roles/cloudsql.admin)

For custom roles, ensure that you have the following permissions:

• cloudsql.blueGreenDeployments.switchover
• cloudsql.blueGreenDeployments.get
• cloudsql.instances.switchover
• cloudsql.operations.get

For more information about IAM roles and permissions in Cloud SQL, see Roles and permissions.

Pre-switchover verification

Before initiating a switchover, verify the following conditions:

1. Deployment state: the deployment must be in the SWITCHOVER_READY state.
2. Workload validation: complete all testing and validation on the green staging instance.
3. Low replication lag: ensure that replication lag between blue and green is minimal to reduce cutover time.

How switchover works

When you start a switchover, Cloud SQL performs the following automated sequence:

1. Pre-switchover validation: before the switchover operation, Cloud SQL validates that replication is not broken and performs a series of configuration checks to ensure that the deployment is ready.
2. Switchover workflow execution: during workflow execution, Cloud SQL prepares the instances for cutover. If replication lag is too high or if an active transaction blocks cutover, the switchover operation fails and your production blue environment remains online.
3. Traffic redirection: Cloud SQL swaps the connection endpoints between the blue and green instances.
4. Role conversion: the green instance becomes the active production read and write instance, and the blue instance becomes a standalone read and write instance.

During switchover, application connections experience a brief disruption (typically in seconds) before reconnecting automatically to the upgraded production instance. Switchover downtime varies based on the Cloud SQL edition:

• Cloud SQL Enterprise Plus edition: switchover downtime is typically sub-second.
• Cloud SQL Enterprise edition: switchover downtime is typically less than 60 seconds, depending on workload and replication lag. No application configuration or connection string changes are required.

Switchover lifecycle states

Before, during, and after a switchover, the deployment transitions through the following states in the state response field:

• SWITCHOVER_READY: logical replication from blue to green is healthy and the deployment is ready for switchover. The SWITCHOVER_READY status is contingent only on replication being healthy. Cloud SQL doesn't evaluate replication lag when setting this status.
• SWITCHOVER_NOT_READY: the deployment is provisioned, but switchover can't be initiated. This occurs if logical replication is broken, paused, or stopped, or if an underlying node error occurred. Cloud SQL doesn't evaluate replication lag when setting this status. Inspect errorDetail and resolve the error before attempting switchover.
• SWITCHOVER_IN_PROGRESS: the switchover command is actively executing. Cloud SQL is swapping connection endpoints and converting green to the production read and write instance.
• SWITCHOVER_COMPLETED: the switchover finished successfully. Green is now your active production database instance serving read and write traffic, and the blue instance is retained as a standalone read and write instance until you delete the deployment.

Best practices before switchover

• Schedule during low-traffic windows: although downtime is minimal (typically in seconds), start the switchover during periods of low write activity (for example, off-peak hours or maintenance windows when write queries per second [QPS] are at their lowest). This minimizes replication lag and reduces the risk of canceled transactions.
• Verify replication lag: make sure that replication lag is minimal before you start the switchover. Describing a blue-green deployment doesn't show replication lag, and Cloud SQL doesn't check replication lag before the switchover operation. However, during workflow execution, switchover fails if replication lag is too high. To monitor replication lag, check Cloud Monitoring metrics (such as replica_lag) or inspect replication status directly on the green instance. For more information, see Replication lag.
• Check active transactions: make sure that long-running DDL operations or batch writes are completed before you start the switchover.

Start a switchover

Start the switchover operation by using the Cloud de Confiance console, the gcloud CLI, or the Cloud SQL Admin API:

gcloud beta sql blue-green-deployments switchover DEPLOYMENT_NAME \
  --region=REGION \
  --async

gcloud sql operations wait OPERATION_ID

gcloud sql operations describe OPERATION_ID

POST https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/
  locations/REGION/
  blueGreenDeployments/DEPLOYMENT_NAME:switchover

POST https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/
  locations/REGION/
  blueGreenDeployments/DEPLOYMENT_NAME:switchover

Post-switchover monitoring

After the switchover completes:

1. Verify that your application reconnects successfully and production database operations resume.
2. Monitor query throughput, error logs, and replication status on the new production instance.
3. Keep the blue standalone instance intact during your initial post-upgrade verification window. After you confirm stability, delete the deployment. For more information, see Delete a blue-green deployment.

What's next

• Delete a blue-green deployment to remove deployment metadata and delete the former blue instance.
• Learn how to monitor instances.
• Learn about backup and recovery.