Task 03: Site-to-Site VPN Connection
DOCUMENT CATEGORY: Runbook
SCOPE: S2S VPN Connection deployment
PURPOSE: Establish IPsec tunnel to on-premises network
MASTER REFERENCE: Microsoft Learn - S2S VPN Connection
Status: Active
Overview
This task creates the Local Network Gateway (representing the on-premises VPN device) and the Site-to-Site VPN Connection linking the Azure VPN Gateway (Task 02) to the on-premises network. The shared key is stored in Key Vault and retrieved at deployment time.
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 |
|---|---|---|
| Local Network Gateway | lgw-{workload}-{env}-{region}-{instance} | On-prem VPN device representation |
| VPN Connection | vnc-{workload}-{env}-{region}-{instance} | IPsec/IKEv2 tunnel |
Connection Configuration
| Setting | Value | Source |
|---|---|---|
| Connection Type | IPsec | no key (the script or Azure decides it) |
| Protocol | IKEv2 | no key (the script or Azure decides it) |
| BGP Enabled | Per config | no key (the script or Azure decides it) |
| Routing Weight | Per config | no key (the script or Azure decides it) |
| Shared Key | Key Vault reference | landing_zone.connectivity.vpn_gateway.site_to_site[].shared_key |
Prerequisites
- Task 02: VPN Gateway completed — VPN Gateway is provisioned
- On-premises VPN device IP confirmed (e.g.,
landing_zone.connectivity.vpn_gateway.site_to_site[].peer_public_ip) - On-premises address prefixes confirmed (e.g.,
landing_zone.connectivity.vpn_gateway.site_to_site[].peer_address_prefixes) - Shared key stored in Key Vault at the URI in
landing_zone.connectivity.vpn_gateway.site_to_site[].shared_key - BGP ASN for on-premises device confirmed (if BGP enabled)
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, azure.location, tags
landing_zone.connectivity.vpn_gateway.name, .resource_group, .network the gateway (its resource group, else the one of the network)
landing_zone.networks[].name, .subscription, .resource_group, .location where the network, and so the gateway, is
landing_zone.subscriptions[].name, .id the subscription that holds the network
landing_zone.connectivity.vpn_gateway.site_to_site[]: connection_name, local_gateway_name, peer_public_ip, peer_address_prefixes,
peer_bgp_address, peer_asn, shared_key
Single Subscription Model
Landing Zone Placement
| Field | Value | Config Path |
|---|---|---|
| Subscription | Customer subscription | landing_zone.subscriptions[].id |
| Resource Group | rg-{workload}-{env}-{region}-01 | landing_zone.connectivity.vpn_gateway.resource_group |
| Local Gateway Name | lgw-{workload}-{env}-{region}-01 | landing_zone.connectivity.vpn_gateway.site_to_site[].local_gateway_name |
| Connection Name | vnc-{workload}-{env}-{region}-01 | landing_zone.connectivity.vpn_gateway.site_to_site[].connection_name |
Execution Options
- Azure Portal
- Orchestrated Script
- Azure CLI
Azure Portal
When to use: Learning Azure Local, single deployment, prefer visual interface
Procedure
- Create Local Network Gateway:
- Search for Local network gateways → + Create
| Field | Value | Source |
|-------|-------|--------|
| Name |
lgw-{workload}-{env}-{region}-01|landing_zone.connectivity.vpn_gateway.site_to_site[].local_gateway_name| | Resource Group | Same as VPN Gateway |landing_zone.connectivity.vpn_gateway.resource_group| | Region | Your region |azure.location| | Endpoint | IP address | — | | IP address | On-prem device IP |landing_zone.connectivity.vpn_gateway.site_to_site[].peer_public_ip| | Address Space | On-prem prefixes |landing_zone.connectivity.vpn_gateway.site_to_site[].peer_address_prefixes|
-
Configure BGP on Local Gateway (if enabled): | Field | Value | Source | |-------|-------|--------| | Configure BGP | Yes | no key (the script or Azure decides it) | | ASN | On-prem ASN |
landing_zone.connectivity.vpn_gateway.site_to_site[].peer_asn| | BGP peer address | On-prem BGP peer |landing_zone.connectivity.vpn_gateway.site_to_site[].peer_bgp_address| -
Create VPN Connection:
- Navigate to VPN Gateway → Connections → + Add
| Field | Value | Source |
|-------|-------|--------|
| Name |
vnc-{workload}-{env}-{region}-01|landing_zone.connectivity.vpn_gateway.site_to_site[].connection_name| | Connection type | Site-to-site (IPsec) | no key (the script or Azure decides it) | | Local network gateway | Select from Step 1 |landing_zone.connectivity.vpn_gateway.site_to_site[].local_gateway_name| | Shared key (PSK) | From Key Vault |landing_zone.connectivity.vpn_gateway.site_to_site[].shared_key| | IKE Protocol | IKEv2 | no key (the script or Azure decides it) | | Enable BGP | Per config | no key (the script or Azure decides it) |
-
Configure On-Premises Device: Configure the on-premises VPN device (e.g., no key (the script or Azure decides it)) with matching settings.
-
Review + create: Verify → Click OK
Validation
- Local Network Gateway provisioning state: Succeeded
- VPN Connection status: Connected
- BGP peers established (if BGP enabled)
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-03-s2s-vpn-connection/powershell/New-VpnConnection.ps1 | Creates the site-to-site VPN connections of the hub VPN gateway that infrastructure.yml describes. Supports -WhatIf. |
Requires: PowerShell 7.
Run
./New-VpnConnection.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-03-s2s-vpn-connection/azurecli/New-VpnConnection.azcli.ps1 | Creates the site-to-site VPN connections of the hub VPN gateway 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>.
The shared key is a secret reference. A keyvault://<vault>/<secret> reference is read at run time with az keyvault secret show (the vault must be listed under key_vaults; you need Key Vault Secrets User on it). The key is never written, logged or printed, but az network vpn-connection create takes it as an argument, so it is on the command line of that one az process for the seconds the call lasts. On Windows az is a batch file (az.cmd), which reads &, |, <, >, ^, % and " in an argument as commands or variables. The script refuses a secret or any value from the file that holds one of them (exit code 2) and sends nothing to Azure; choose a secret without them. -WhatIf does not read the secret.
Run
./New-VpnConnection.azcli.ps1 -InfrastructureFile ./infrastructure.yml -WhatIf
./New-VpnConnection.azcli.ps1 -InfrastructureFile ./infrastructure.yml
Validation
- Local Network Gateway provisioned
- VPN Connection status: Connected
- BGP peering established (if enabled)
- On-premises routes visible in effective routes
CAF/WAF Landing Zone Model
In the CAF/WAF model, the Local Network Gateway and VPN Connection are deployed in the Connectivity subscription alongside the VPN Gateway.
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 |
| Local Gateway Name | lgw-{workload}-{env}-{region}-01 | landing_zone.connectivity.vpn_gateway.site_to_site[].local_gateway_name |
| Connection Name | vnc-{workload}-{env}-{region}-01 | landing_zone.connectivity.vpn_gateway.site_to_site[].connection_name |
Execution Options
- Azure Portal
- Orchestrated Script
- Azure CLI
Azure Portal
When to use: Learning Azure Local, single deployment, prefer visual interface
Follow the same procedure as Single Subscription → Azure Portal above, targeting the Connectivity subscription:
| Field | Value |
|---|---|
| Subscription | Connectivity subscription |
| Resource group | rg-azrlconn-{env}-{region}-01 |
All other settings (local gateway IP, prefixes, BGP, shared key) remain identical.
Validation
- Resources in Connectivity subscription
- VPN Connection status: Connected
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-03-s2s-vpn-connection/powershell/New-VpnConnection.ps1 | Creates the site-to-site VPN connections of the hub VPN gateway that infrastructure.yml describes. Supports -WhatIf. |
Requires: PowerShell 7.
Run
./New-VpnConnection.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-03-s2s-vpn-connection/azurecli/New-VpnConnection.azcli.ps1 | Creates the site-to-site VPN connections of the hub VPN gateway 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>.
The shared key is a secret reference. A keyvault://<vault>/<secret> reference is read at run time with az keyvault secret show (the vault must be listed under key_vaults; you need Key Vault Secrets User on it). The key is never written, logged or printed, but az network vpn-connection create takes it as an argument, so it is on the command line of that one az process for the seconds the call lasts. On Windows az is a batch file (az.cmd), which reads &, |, <, >, ^, % and " in an argument as commands or variables. The script refuses a secret or any value from the file that holds one of them (exit code 2) and sends nothing to Azure; choose a secret without them. -WhatIf does not read the secret.
Run
./New-VpnConnection.azcli.ps1 -InfrastructureFile ./infrastructure.yml -WhatIf
./New-VpnConnection.azcli.ps1 -InfrastructureFile ./infrastructure.yml
Validation
- All resources in Connectivity subscription
- VPN Connection status: Connected
- BGP peering active (if enabled)
- End-to-end connectivity verified from on-premises
Troubleshooting
| Issue | Root Cause | Remediation |
|---|---|---|
| Connection stuck at Connecting | Shared key mismatch | Verify PSK matches on both sides |
| Connection stuck at Connecting | On-prem device not configured | Configure on-prem VPN device with matching settings |
| BGP peers not established | ASN mismatch or APIPA mismatch | Verify ASN and APIPA addresses match both sides |
| Cannot resolve Key Vault secret | Missing RBAC or network access | Add Key Vault Secrets User role; check firewall |
| Local gateway IP incorrect | Wrong public IP for on-prem device | Update landing_zone.connectivity.vpn_gateway.site_to_site[].peer_public_ip |
| IKE Phase 1 failure | Encryption/integrity mismatch | Align IKE parameters between Azure and on-prem device |
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 02: VPN Gateway | Manual Deployment Index | Task 04: P2S 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-connection, s2s, ipsec, networking
- Keywords: site-to-site, VPN connection, local network gateway, IPsec, IKEv2, BGP
- Author: Hybrid Cloud Solutions
Version Control
| Version | Date | Author | Changes |
|---|---|---|---|
| 1.0.0 | 2025-03-25 | Azure Local Cloud | Initial release |