docs: Add Azure VNET failover documentation for GitHub-hosted runners (#60559)

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: Steve-Glass <84886334+Steve-Glass@users.noreply.github.com>
Co-authored-by: Sunbrye Ly <56200261+sunbrye@users.noreply.github.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Author: 4 people

content/admin/configuring-settings/configuring-private-networking-for-hosted-compute-products/about-azure-private-networking-for-github-hosted-runners-in-your-enterprise.md

@@ -40,6 +40,12 @@ category:
 
 {% data reusables.actions.azure-vnet-networking-policies %}
 
+## About VNET failover
+
+{% data reusables.actions.azure-vnet-about-failover %}
+
+For more information about configuring a failover network, see [AUTOTITLE](/admin/configuring-settings/configuring-private-networking-for-hosted-compute-products/configuring-private-networking-for-github-hosted-runners-in-your-enterprise#5-optionally-add-a-failover-network-to-a-network-configuration).
+
 ## Managing network configuration policies for organizations in your enterprise
 
 You can give organization owners in your enterprise the ability to set up and maintain organization-level network configurations for {% data variables.product.company_short %}-hosted runners.

content/admin/configuring-settings/configuring-private-networking-for-hosted-compute-products/configuring-private-networking-for-github-hosted-runners-in-your-enterprise.md

@@ -119,6 +119,33 @@ You can use the following {% data variables.product.prodname_cli %} commands to
 1. To disable a network configuration, to the right of the network configuration, click {% octicon "kebab-horizontal" aria-label="Menu" %}. Then click **Disable**.
 1. To delete a network configuration, to the right of the network configuration, click {% octicon "kebab-horizontal" aria-label="Menu" %}. Then click **Delete**.
 
+### 5. Optionally, add a failover network to a network configuration
+
+{% data reusables.actions.azure-vnet-about-failover %}
+
+Before adding a failover network, ensure you have configured the Azure resources (VNET, subnet, network security group, and network settings resource) for the secondary subnet, following the same "Configuring your Azure resources" procedures above. The failover subnet can be in a different Azure region from your primary subnet.
+
+{% data reusables.enterprise-accounts.access-enterprise %}
+{% data reusables.enterprise-accounts.settings-tab %}
+1. In the left sidebar, click **Hosted compute networking**.
+1. Click the edit icon ({% octicon "pencil" aria-label="Edit a network configuration" %}) next to the network configuration you want to add a failover network to. Then click **Edit configuration**.
+1. Click **Add failover network**.
+1. In the popup window, enter the network settings resource ID for your secondary (failover) Azure subnet.
+1. Click **Add Azure Virtual Network**.
+1. You will now see two subnets listed in the network configuration: the primary and the failover, labeled accordingly.
+
+### 6. Optionally, enable or disable the failover network
+
+After adding a failover network, you can enable it to route traffic through the secondary subnet, or disable it to return to the primary subnet.
+
+{% data reusables.enterprise-accounts.access-enterprise %}
+{% data reusables.enterprise-accounts.settings-tab %}
+1. In the left sidebar, click **Hosted compute networking**.
+1. Click the edit icon ({% octicon "pencil" aria-label="Edit a network configuration" %}) next to the network configuration. Then click **Edit configuration**.
+1. To switch to the failover network, click **Enable failover VNET**. Runner traffic will be routed through the failover subnet.
+1. To switch back to the primary network, click **Disable failover VNET**. Runner traffic will return to the primary subnet.
+
+
 ## Enabling creation of network configurations for organizations
 
 You can allow organization owners in an enterprise to create their own organization-level network configurations.

content/organizations/managing-organization-settings/about-azure-private-networking-for-github-hosted-runners-in-your-organization.md

@@ -38,6 +38,12 @@ category:
 
 {% data reusables.actions.azure-vnet-networking-policies %}
 
+## About VNET failover
+
+{% data reusables.actions.azure-vnet-about-failover %}
+
+For more information about configuring a failover network, see [AUTOTITLE](/organizations/managing-organization-settings/configuring-private-networking-for-github-hosted-runners-in-your-organization#5-optionally-add-a-failover-network-to-a-network-configuration).
+
 ## Using {% data variables.product.company_short %}-hosted runners with an Azure VNET
 
 {% data reusables.actions.azure-vnet-next-steps-links %}

content/organizations/managing-organization-settings/configuring-private-networking-for-github-hosted-runners-in-your-organization.md

@@ -108,6 +108,35 @@ https://api.github.com/graphql
 1. To disable a network configuration, to the right of the network configuration, click {% octicon "kebab-horizontal" aria-label="Menu" %}. Then click **Disable**.
 1. To delete a network configuration, to the right of the network configuration, click {% octicon "kebab-horizontal" aria-label="Menu" %}. Then click **Delete**.
 
+### 5. Optionally, add a failover network to a network configuration
+
+{% data reusables.actions.azure-vnet-about-failover %}
+
+Before adding a failover network, ensure you have configured the Azure resources (VNET, subnet, network security group, and network settings resource) for the secondary subnet, following the same "Configuring your Azure resources" procedures above. The failover subnet can be in a different Azure region from your primary subnet.
+
+{% data reusables.profile.access_org %}
+{% data reusables.profile.org_settings %}
+1. In the left sidebar, click **Hosted compute networking**.
+1. Click the edit icon ({% octicon "pencil" aria-label="Edit a network configuration" %}) next to the network configuration you want to add a failover network to. Then click **Edit configuration**.
+1. Click **Add failover network**.
+1. In the popup window, enter the network settings resource ID for your secondary (failover) Azure subnet.
+1. Click **Add Azure Virtual Network**.
+1. You will now see two subnets listed in the network configuration: the primary and the failover, labeled accordingly.
+
+### 6. Optionally, enable or disable the failover network
+
+After adding a failover network, you can enable it to route traffic through the secondary subnet, or disable it to return to the primary subnet.
+
+{% data reusables.profile.access_org %}
+{% data reusables.profile.org_settings %}
+1. In the left sidebar, click **Hosted compute networking**.
+1. Click the edit icon ({% octicon "pencil" aria-label="Edit a network configuration" %}) next to the network configuration. Then click **Edit configuration**.
+1. To switch to the failover network, click **Enable failover VNET**. Runner traffic will be routed through the failover subnet.
+1. To switch back to the primary network, click **Disable failover VNET**. Runner traffic will return to the primary subnet.
+
+> [!NOTE]
+> If {% data variables.product.company_short %} enables failover automatically during a regional outage, you will be notified via audit log event and email. You must manually disable the failover to return to the primary subnet when the outage is resolved.
+
 ## Deleting a subnet
 
 {% data reusables.actions.azure-vnet-deleting-a-subnet %}

data/reusables/actions/azure-vnet-about-failover.md

@@ -0,0 +1,11 @@
+> [!NOTE]
+> VNET failover is in {% data variables.release-phases.public_preview %} and subject to change.
+
+You can configure a failover network for your network configuration. A failover network is a secondary Azure Virtual Network subnet, which can be in a different Azure region from your primary subnet. If your primary subnet becomes unavailable due to a regional outage or other disruption, you can enable the failover network to route runner traffic through the secondary subnet, maintaining continuity for your {% data variables.product.prodname_actions %} workflows.
+
+Key points about VNET failover:
+
+* The failover subnet can reside in a different Azure region than the primary subnet.
+* Switching between primary and failover subnets is a manual process. You enable or disable the failover network at your discretion.
+* Both the primary and failover subnets must be configured with the required Azure resources (VNET/subnet, network settings, etc.) before you can use failover.
+* The failover subnet must be in a [supported region](/admin/configuring-settings/configuring-private-networking-for-hosted-compute-products/about-azure-private-networking-for-github-hosted-runners-in-your-enterprise#about-supported-regions).

data/reusables/actions/azure-vnet-hosted-compute-troubleshooting.md

@@ -105,3 +105,31 @@ If you experience this error, you can see more information by running the comman
 ### Network settings configured at the wrong level
 
 If network settings were configured using an organization's `databaseId` instead of an enterprise `databaseId`, an error will occur. The error message will indicate that a private network cannot be established with the provided resource ID because it is already associated with a different enterprise or organization. To resolve this, delete the existing network settings and recreate them using the enterprise `databaseId`.
+
+### Failover network not switching traffic
+
+> [!NOTE]
+> VNET failover is in {% data variables.release-phases.public_preview %} and subject to change.
+> [!IMPORTANT]
+> Switching between the primary and failover networks is a gradual process. During the transition, runners may be running on both networks simultaneously. Based on testing, the full transition takes approximately 15 minutes. Ensure both subnets remain accessible during this period.
+
+If enabling the failover network does not appear to reroute runner traffic, check the following:
+
+* Ensure the failover subnet's Azure resources (VNET/subnet, NSG/firewall, network settings) are correctly configured. Follow the same "Configuring your Azure resources" procedures used for your primary subnet.
+* Confirm the failover network was added to the correct network configuration and that the configuration is associated with the appropriate runner group.
+
+### Failover subnet not reachable
+
+If runners cannot connect after enabling the failover network, the issue is likely with the Azure resources configured for the failover subnet.
+
+* Ensure the failover subnet has the correct NSG or firewall rules applied, matching the requirements listed in the [AUTOTITLE](/enterprise-cloud@latest/admin/configuring-settings/configuring-private-networking-for-hosted-compute-products/configuring-private-networking-for-github-hosted-runners-in-your-enterprise) procedures.
+* Verify that the failover subnet has sufficient IP address space for the expected runner concurrency.
+
+### Cannot switch back to primary after GitHub-initiated failover
+
+
+1. Navigate to your network configuration in the **Hosted compute networking** settings.
+1. Click the edit icon next to the network configuration. Then click **Edit configuration**.
+1. Click **Disable failover VNET** to return runner traffic to the primary subnet.
+
+If you are unable to disable the failover, ensure the primary subnet's Azure resources are healthy and accessible. Verify there are no ongoing outages in the primary subnet's Azure region.