Stay organized with collections
Save and categorize content based on your preferences.
AlloyDB for PostgreSQL offers regional and zonal instance types. To help ensure high availability (HA), every regional 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 promotes the standby node to become the new
active node.
You can test this automatic HA feature by using fault injection to abruptly
force your primary instance's active node offline. AlloyDB then
activates the emergency HA procedure that checks the primary instance's health
and then reassigns the standby node into the active-node role.
Fault injection also initiates a long-running operation that brings the former
active node back online after a brief interval. That node becomes the new
standby node of the primary instance.
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.
Simulate an outage with a fault injection
To test your primary instance's HA resiliency by abruptly shutting down its
active node, use the gcloud alloydb instances
inject-fault command.
After a long-running operation completes, AlloyDB reinstates the
node.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-08-26 UTC."],[[["\u003cp\u003eAlloyDB for PostgreSQL ensures high availability by utilizing an active and a standby node for each regional primary instance, located in separate zones.\u003c/p\u003e\n"],["\u003cp\u003eFault injection can be used to test AlloyDB's high availability feature by abruptly forcing the primary instance's active node offline.\u003c/p\u003e\n"],["\u003cp\u003eUpon detecting an active node failure, AlloyDB automatically promotes the standby node to the active role and then later brings the former active node back online as the new standby.\u003c/p\u003e\n"],["\u003cp\u003eTo perform a fault injection for HA testing, use the \u003ccode\u003egcloud alloydb instances inject-fault\u003c/code\u003e command, specifying instance, region, cluster, and project IDs.\u003c/p\u003e\n"],["\u003cp\u003eBasic instances are not applicable for fault injection testing due to the absence of a standby node for failover.\u003c/p\u003e\n"]]],[],null,["# Test a primary instance for high availability\n\nAlloyDB for PostgreSQL offers regional and zonal instance types. To help ensure high availability (HA), every regional AlloyDB primary\ninstance has both an active node and a standby node, located in two different\nzones. If the active node becomes unavailable for any reason, then\nAlloyDB automatically promotes the standby node to become the new\nactive node.\n\nYou can test this automatic HA feature by using *fault injection* to abruptly\nforce your primary instance's active node offline. AlloyDB then\nactivates the emergency HA procedure that checks the primary instance's health\nand then reassigns the standby node into the active-node role.\n\nFault injection also initiates a long-running operation that brings the former\nactive node back online after a brief interval. That node becomes the new\nstandby node of the primary instance.\n\nFor a faster method of swapping the active and standby roles of your primary\ninstance's nodes, see [Fail over a primary instance\nmanually](/alloydb/docs/instance-primary-secondary-failover).\n\n\nBefore you begin\n----------------\n\n- The Google Cloud project you are using must have been [enabled to access AlloyDB](/alloydb/docs/project-enable-access).\n- You must have one of these IAM roles in the Google Cloud project you are using:\n - `roles/alloydb.admin` (the AlloyDB Admin predefined IAM role)\n - `roles/owner` (the Owner basic IAM role)\n - `roles/editor` (the Editor basic IAM role)\n\n If you don't have any of these roles, contact your Organization Administrator to request\n access.\n\n\u003cbr /\u003e\n\nSimulate an outage with a fault injection\n-----------------------------------------\n\n| **Note:** This procedure does not apply to [basic\n| instances](/alloydb/docs/basic-instance), which do not have a standby node to fail over to.\n\nTo test your primary instance's HA resiliency by abruptly shutting down its\nactive node, use the [`gcloud alloydb instances\ninject-fault`](/sdk/gcloud/reference/alloydb/instances/inject-fault) command.\nAfter a long-running operation completes, AlloyDB reinstates the\nnode. \n\n gcloud alloydb instances inject-fault \u003cvar translate=\"no\"\u003e\u003cspan class=\"devsite-syntax-nx\"\u003eINSTANCE_ID\u003c/span\u003e\u003c/var\u003e \\\n --fault-type=stop-vm \\\n --region=\u003cvar translate=\"no\"\u003e\u003cspan class=\"devsite-syntax-nx\"\u003eREGION_ID\u003c/span\u003e\u003c/var\u003e \\\n --cluster=\u003cvar translate=\"no\"\u003e\u003cspan class=\"devsite-syntax-nx\"\u003eCLUSTER_ID\u003c/span\u003e\u003c/var\u003e \\\n --project=\u003cvar translate=\"no\"\u003e\u003cspan class=\"devsite-syntax-nx\"\u003ePROJECT_ID\u003c/span\u003e\u003c/var\u003e\n\n- \u003cvar translate=\"no\"\u003eINSTANCE_ID\u003c/var\u003e: The ID of the instance.\n- \u003cvar translate=\"no\"\u003eREGION_ID\u003c/var\u003e: The region where the instance is placed.\n- \u003cvar translate=\"no\"\u003eCLUSTER_ID\u003c/var\u003e: The ID of the cluster where the instance is placed.\n- \u003cvar translate=\"no\"\u003ePROJECT_ID\u003c/var\u003e: The ID of the project where the cluster is placed."]]
