Task 02: VPN Gateway
DOCUMENT CATEGORY: Runbook
SCOPE: VPN Gateway deployment
PURPOSE: Create VPN Gateway for hybrid connectivity
MASTER REFERENCE: Microsoft Learn - VPN Gateway
Status: Active
Overview
This task deploys an Azure VPN Gateway into the GatewaySubnet created in Task 01. The gateway provides site-to-site IPsec/IKEv2 connectivity between Azure and on-premises infrastructure with BGP routing support.
The VPN Gateway takes 30–45 minutes to deploy. Do not interrupt the deployment. Plan accordingly.
Execution Target: Azure-Only (control-plane API operation) Tab Profile: 3 tabs — Azure Portal · PowerShell · Azure CLI
Module: azurelocal-toolkit
File: network.tf
Mode: Management
Components Created
| Resource | Name Pattern | Purpose |
|---|---|---|
| Public IP | pip-azrlvpng-{env}-{region}-01 | VPN Gateway public IP |
| VPN Gateway | vpng-azrl-{env}-{region}-01 | Site-to-site VPN termination |
Gateway Configuration
| Setting | Value | Source |
|---|---|---|
| SKU | VpnGw2AZ | landing_zone.connectivity.vpn_gateway.sku |
| Generation | Generation2 | no key (the script or Azure decides it) |
| Type | Route-based | Standard for Azure Local |
| Active-Active | Per config | The script or Azure decides it (Terraform route: landing_zone.connectivity.vpn_gateway.active_active, default false) |
| BGP Enabled | Per config | no key (the script or Azure decides it) |
| BGP ASN | Per config | landing_zone.connectivity.vpn_gateway.bgp_asn |
Prerequisites
- Task 01: Virtual Network completed — GatewaySubnet exists
- Public IP address not already in use
- BGP ASN confirmed by on-premises network team (must not conflict)
Values from infrastructure.yml
The script reads these keys from infrastructure.yml (schema 5). Each key, with its type, default and example, is in the variables reference.
azure.tenant_id the tenant the sign-in must belong to
azure.location the region, when the network entry has none
tags tags for the resources created (optional)
landing_zone.connectivity.vpn_gateway.name the gateway name
landing_zone.connectivity.vpn_gateway.resource_group the resource group of the gateway (else the one of the network)
landing_zone.connectivity.vpn_gateway.network the virtual network (an entry of landing_zone.networks)
landing_zone.connectivity.vpn_gateway.sku the SKU (VpnGw1AZ to VpnGw5AZ)
landing_zone.connectivity.vpn_gateway.bgp_asn the BGP ASN of the gateway
landing_zone.networks[].name, .subscription, .resource_group, .location where the network is
landing_zone.subscriptions[].name, .id the subscription that holds the network and so the gateway
The Terraform route (src/terraform/modules/networking) also reads three keys added in registry 5.0.62 (schema 5.6.28, optional):
| Key | What it is |
|---|---|
landing_zone.connectivity.vpn_gateway.public_ip_name | Name of the public IP address of the gateway (of its first instance in active-active mode) |
landing_zone.connectivity.vpn_gateway.secondary_public_ip_name | Name of the public IP address of the second instance; needed when active_active is true |
landing_zone.connectivity.vpn_gateway.active_active | Active-active mode (default false): both gateway instances carry tunnels; it needs a route-based VPN, a SKU other than Basic and two Standard static public IPs (About active-active VPN gateways) |
Single Subscription Model
Landing Zone Placement
| Field | Value | Config Path |
|---|---|---|
| Subscription | Customer subscription | landing_zone.subscriptions[].id |
| Resource Group | rg-azrlmgmt-{env}-{region}-01 | landing_zone.connectivity.vpn_gateway.resource_group |
| VPN Gateway Name | vpng-azrl-{env}-{region}-01 | landing_zone.connectivity.vpn_gateway.name |
| Public IP Name | pip-azrlvpng-{env}-{region}-01 | The script or Azure decides it (Terraform route: landing_zone.connectivity.vpn_gateway.public_ip_name) |
Execution Options
- Azure Portal
- Orchestrated Script
- Azure CLI
Azure Portal
When to use: Learning Azure Local, single deployment, prefer visual interface
Procedure
- Create Public IP:
- Search for Public IP addresses → + Create
| Field | Value | Source |
|-------|-------|--------|
| Name |
pip-azrlvpng-{env}-{region}-01| no key (the script or Azure decides it) | | SKU | Standard | Required for AZ gateway | | Assignment | Static | Required for VPN Gateway | | Availability Zone | Zone-redundant | Best practice |
- Create VPN Gateway:
- Search for Virtual network gateways → + Create
| Field | Value | Source |
|-------|-------|--------|
| Name |
vpng-azrl-{env}-{region}-01|landing_zone.connectivity.vpn_gateway.name| | Region | Your region |landing_zone.connectivity.vpn_gateway.resource_group| | Gateway type | VPN | — | | SKU | VpnGw2AZ |landing_zone.connectivity.vpn_gateway.sku| | Generation | Generation2 | no key (the script or Azure decides it) | | Virtual network | VNet from Task 01 |landing_zone.networks[].name| | Public IP | Public IP created above | no key (the script or Azure decides it) | | Enable active-active | Per config | no key (the script or Azure decides it) |
-
Configure BGP (if enabled): | Field | Value | Source | |-------|-------|--------| | Configure BGP | Yes | no key (the script or Azure decides it) | | ASN | Per config |
landing_zone.connectivity.vpn_gateway.bgp_asn| | Custom Azure APIPA BGP address | Per config | no key (the script or Azure decides it) | -
Review + create: Verify → Click Create → Wait 30–45 minutes
Validation
- VPN Gateway provisioning state shows Succeeded
- Public IP assigned and visible
- BGP settings correct (if enabled)
- Gateway associated with correct GatewaySubnet
Links
PowerShell
When to use: Run the task from a management workstation or a pipeline. The script reads
infrastructure.ymland carries no values of its own.
Script
| Script | What it does |
|---|---|
scripts/deploy/02-azure-foundation/phase-04-azure-management-infrastructure/02-manual-deployment/task-02-vpn-gateway/powershell/Deploy-VpnGateway.ps1 | Deploys the VPN gateway of the connectivity hub that infrastructure.yml describes. Supports -WhatIf. |
Requires: PowerShell 7.
Run
./Deploy-VpnGateway.ps1 -InfrastructureFile ./infrastructure.yml -WhatIf
Azure CLI
When to use: Run the task from a host that has the Azure CLI and not the Az PowerShell modules. The script is PowerShell 7 that calls
az; it readsinfrastructure.ymland carries no values of its own.
Script
| Script | What it does |
|---|---|
scripts/deploy/02-azure-foundation/phase-04-azure-management-infrastructure/02-manual-deployment/task-02-vpn-gateway/azurecli/Deploy-VpnGateway.azcli.ps1 | Deploys the VPN gateway of the connectivity hub that infrastructure.yml describes, with the Azure CLI. Supports -WhatIf. |
Requires: PowerShell 7 and the Azure CLI, signed in with az login --tenant <azure.tenant_id>.
It creates a Standard public IP address with no zones given, which Azure makes zone-redundant in a region that has availability zones and regional in one that does not, and a route-based gateway with BGP on. Only the AZ SKUs (VpnGw1AZ to VpnGw5AZ) are accepted. The gateway takes 30 to 45 minutes and the script waits for it, so run it from a session that stays open. An existing gateway is left alone; a different SKU or ASN is reported, not changed. An entry of landing_zone.networks or landing_zone.subscriptions that is not a map stops either script with exit 2.
Run
./Deploy-VpnGateway.azcli.ps1 -InfrastructureFile ./infrastructure.yml -WhatIf
./Deploy-VpnGateway.azcli.ps1 -InfrastructureFile ./infrastructure.yml
Validation
- VPN Gateway provisioning state is Succeeded
- Public IP assigned
- Gateway SKU matches config
- BGP ASN correct (if enabled)
CAF/WAF Landing Zone Model
In the CAF/WAF model, the VPN Gateway is deployed in the Connectivity subscription alongside the VNet.
Landing Zone Placement
| Field | Value | Config Path |
|---|---|---|
| Subscription | Connectivity subscription | landing_zone.subscriptions[].id |
| Resource Group | rg-azrlconn-{env}-{region}-01 | landing_zone.connectivity.vpn_gateway.resource_group |
| VPN Gateway Name | vpng-azrl-{env}-{region}-01 | landing_zone.connectivity.vpn_gateway.name |
| Public IP Name | pip-azrlvpng-{env}-{region}-01 | The script or Azure decides it (Terraform route: landing_zone.connectivity.vpn_gateway.public_ip_name) |
Execution Options
- Azure Portal
- Orchestrated Script
- Azure CLI
Azure Portal
When to use: Learning Azure Local, single deployment, prefer visual interface
Procedure
Follow the same procedure as Single Subscription → Azure Portal above, but target the Connectivity subscription and resource group:
| Field | Value |
|---|---|
| Subscription | Connectivity subscription |
| Resource group | rg-azrlconn-{env}-{region}-01 |
All other settings (SKU, generation, BGP) remain identical.
Validation
- VPN Gateway in Connectivity subscription
- Provisioning state: Succeeded
- BGP settings correct
PowerShell
When to use: Run the task from a management workstation or a pipeline. The script reads
infrastructure.ymland carries no values of its own.
Script
| Script | What it does |
|---|---|
scripts/deploy/02-azure-foundation/phase-04-azure-management-infrastructure/02-manual-deployment/task-02-vpn-gateway/powershell/Deploy-VpnGateway.ps1 | Deploys the VPN gateway of the connectivity hub that infrastructure.yml describes. Supports -WhatIf. |
Requires: PowerShell 7.
Run
./Deploy-VpnGateway.ps1 -InfrastructureFile ./infrastructure.yml -WhatIf
Azure CLI
When to use: Run the task from a host that has the Azure CLI and not the Az PowerShell modules. The script is PowerShell 7 that calls
az; it readsinfrastructure.ymland carries no values of its own.
Script
| Script | What it does |
|---|---|
scripts/deploy/02-azure-foundation/phase-04-azure-management-infrastructure/02-manual-deployment/task-02-vpn-gateway/azurecli/Deploy-VpnGateway.azcli.ps1 | Deploys the VPN gateway of the connectivity hub that infrastructure.yml describes, with the Azure CLI. Supports -WhatIf. |
Requires: PowerShell 7 and the Azure CLI, signed in with az login --tenant <azure.tenant_id>.
It creates a Standard public IP address with no zones given, which Azure makes zone-redundant in a region that has availability zones and regional in one that does not, and a route-based gateway with BGP on. Only the AZ SKUs (VpnGw1AZ to VpnGw5AZ) are accepted. The gateway takes 30 to 45 minutes and the script waits for it, so run it from a session that stays open. An existing gateway is left alone; a different SKU or ASN is reported, not changed. An entry of landing_zone.networks or landing_zone.subscriptions that is not a map stops either script with exit 2.
Run
./Deploy-VpnGateway.azcli.ps1 -InfrastructureFile ./infrastructure.yml -WhatIf
./Deploy-VpnGateway.azcli.ps1 -InfrastructureFile ./infrastructure.yml
Validation
- VPN Gateway in Connectivity subscription
- Provisioning state: Succeeded
- BGP ASN matches config
- Public IP reachable from on-premises firewall
Troubleshooting
| Issue | Root Cause | Remediation |
|---|---|---|
| Deployment fails after 45 min | Transient Azure platform issue | Retry; check Azure Status page |
| GatewaySubnet not found | Task 01 not completed | Complete Task 01 first |
| BGP ASN conflict | ASN already in use by another gateway | Choose unique ASN in Planning & Discovery |
| Public IP SKU mismatch | Basic SKU used with AZ gateway | Use Standard SKU with zone-redundant allocation |
| Active-active requires 2 PIPs | Single PIP with active-active | Create second PIP or disable active-active |
Alternatives
The procedures in this task use the methods shown in the tabs above. The toolkit is PowerShell 7 only and has no Bash scripts. A few tasks that act on Azure also have an Azure CLI script written in PowerShell. The script status page of the toolkit lists which task has which script.
Navigation
| Previous | Up | Next |
|---|---|---|
| Task 01: Virtual Network | Manual Deployment Index | Task 03: S2S VPN Connection |
Version Control
- Created: 2025-09-15 by Hybrid Cloud Solutions
- Last Updated: 2026-03-03 by Hybrid Cloud Solutions
- Version: 4.0.0
- Tags: azure-local, vpn-gateway, networking, hybrid-connectivity
- Keywords: VPN gateway, site-to-site, BGP, VpnGw2AZ, hybrid connectivity
- Author: Hybrid Cloud Solutions
Version Control
| Version | Date | Author | Changes |
|---|---|---|---|
| 1.0.0 | 2025-03-25 | Azure Local Cloud | Initial release |