Fail over a primary instance manually

To help ensure high availability (HA), every AlloyDB primary instance has both an active node and a standby node, located in two different zones. If the active node becomes unavailable for any reason, then AlloyDB automatically fails over the primary instance to its standby node, making it the new active node.

You can manually fail over your primary instance to its standby node at any time, even if the active node is working normally. When you initiate a manual failover, AlloyDB takes these steps, in this order:

  1. AlloyDB takes the primary node offline.

  2. AlloyDB turns the standby node into the new active node.

  3. AlloyDB reactivates the previous active node as the new standby node.

In effect, manual failover swaps the active and standby roles of your primary instance's two nodes. You can trigger a manual failover any time that you want this exchange to occur.

For example, imagine that you have a primary instance whose active and standby nodes reside in the us-central1-a and us-central1-b zones, respectively. An outage in us-central1-a triggers an automatic failover, resulting in the us-central1-b zone hosting the active node. If you prefer to keep the active node in the us-central1-a zone, then you can initiate a manual failover to have AlloyDB swap the primary instance's nodes back to their locations from before the outage.

During maintenance operations, both an HA primary instance and a basic instance, typically experience minimal maintenance downtime of less than a second. Because manual failover is an intentional and controlled procedure, it is not intended for simulating unexpected hardware or network faults. Instead, you can test your primary instance's high availability through fault injection.

Before you begin

  • The Google Cloud project you are using must have been enabled to access AlloyDB.
  • You must have one of these IAM roles in the Google Cloud project you are using:
    • roles/alloydb.admin (the AlloyDB Admin predefined IAM role)
    • roles/owner (the Owner basic IAM role)
    • roles/editor (the Editor basic IAM role)

    If you don't have any of these roles, contact your Organization Administrator to request access.

Perform a manual failover


  1. Go to the Clusters page.

Go to Clusters

  1. In the Resource Name column, click a cluster name.

  2. In the Instances in your cluster section, open your primary instance's Instance actions menu.

  3. Click Failover.

  4. In the dialog that appears, enter the instance's ID.

  5. Click Trigger failover.


Run the gcloud alloydb instances failover command:

gcloud alloydb instances failover INSTANCE_ID \
    --region=REGION_ID \
    --cluster=CLUSTER_ID \

Replace the following:

  • INSTANCE_ID: The ID of the instance.
  • REGION_ID: The region where the instance is placed.
  • CLUSTER_ID: The ID of the cluster where the instance is placed.
  • PROJECT_ID: The ID of the project where the cluster is placed.

To confirm that the failover worked, follow these steps:

  1. Before performing the failover, note the zones of the primary instance's nodes.

  2. After running the failover, note the two nodes' new zones.

  3. Confirm that the zones of the active and standby nodes have switched places.