Skip to main content

Task 03: Site-to-Site VPN Connection

Runbook Azure

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.

Task Classification

Execution Target: Azure-Only (control-plane API operation) Tab Profile: 3 tabs — Azure Portal · PowerShell · Azure CLI

Terraform Reference

Module: azurelocal-toolkit File: network.tf Mode: Management

Components Created​

ResourceName PatternPurpose
Local Network Gatewaylgw-{workload}-{env}-{region}-{instance}On-prem VPN device representation
VPN Connectionvnc-{workload}-{env}-{region}-{instance}IPsec/IKEv2 tunnel

Connection Configuration​

SettingValueSource
Connection TypeIPsecno key (the script or Azure decides it)
ProtocolIKEv2no key (the script or Azure decides it)
BGP EnabledPer configno key (the script or Azure decides it)
Routing WeightPer configno key (the script or Azure decides it)
Shared KeyKey Vault referencelanding_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​

FieldValueConfig Path
SubscriptionCustomer subscriptionlanding_zone.subscriptions[].id
Resource Grouprg-{workload}-{env}-{region}-01landing_zone.connectivity.vpn_gateway.resource_group
Local Gateway Namelgw-{workload}-{env}-{region}-01landing_zone.connectivity.vpn_gateway.site_to_site[].local_gateway_name
Connection Namevnc-{workload}-{env}-{region}-01landing_zone.connectivity.vpn_gateway.site_to_site[].connection_name

Execution Options​

Azure Portal​

When to use: Learning Azure Local, single deployment, prefer visual interface

Procedure​

  1. 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 |
  1. 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 |

  2. 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) |
  1. Configure On-Premises Device: Configure the on-premises VPN device (e.g., no key (the script or Azure decides it)) with matching settings.

  2. Review + create: Verify → Click OK

Validation​

  • Local Network Gateway provisioning state: Succeeded
  • VPN Connection status: Connected
  • BGP peers established (if BGP enabled)

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​

FieldValueConfig Path
SubscriptionConnectivity subscriptionlanding_zone.subscriptions[].id
Resource Grouprg-azrlconn-{env}-{region}-01landing_zone.connectivity.vpn_gateway.resource_group
Local Gateway Namelgw-{workload}-{env}-{region}-01landing_zone.connectivity.vpn_gateway.site_to_site[].local_gateway_name
Connection Namevnc-{workload}-{env}-{region}-01landing_zone.connectivity.vpn_gateway.site_to_site[].connection_name

Execution Options​

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:

FieldValue
SubscriptionConnectivity subscription
Resource grouprg-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

Validation​

  • All resources in Connectivity subscription
  • VPN Connection status: Connected
  • BGP peering active (if enabled)
  • End-to-end connectivity verified from on-premises

Troubleshooting​

IssueRoot CauseRemediation
Connection stuck at ConnectingShared key mismatchVerify PSK matches on both sides
Connection stuck at ConnectingOn-prem device not configuredConfigure on-prem VPN device with matching settings
BGP peers not establishedASN mismatch or APIPA mismatchVerify ASN and APIPA addresses match both sides
Cannot resolve Key Vault secretMissing RBAC or network accessAdd Key Vault Secrets User role; check firewall
Local gateway IP incorrectWrong public IP for on-prem deviceUpdate landing_zone.connectivity.vpn_gateway.site_to_site[].peer_public_ip
IKE Phase 1 failureEncryption/integrity mismatchAlign 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.

PreviousUpNext
Task 02: VPN GatewayManual Deployment IndexTask 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​

VersionDateAuthorChanges
1.0.02025-03-25Azure Local CloudInitial release