1# VPN Gateway & DNS Private Resolver Setup
2 
3Post-deployment add-on for private network templates (T10, T15–T19). Creates a point-to-site VPN Gateway and DNS Private Resolver so the user can connect from their dev machine and resolve private DNS zones.
4 
5## Assumptions
6 
7| Property | Value | Rationale |
8|----------|-------|-----------|
9| Auth | Microsoft Entra ID (AAD) only | No certificate management |
10| Tunnel | OpenVPN | Cross-platform, Azure VPN Client |
11| Gateway SKU | VpnGw1AZ | Zone-redundant, same cost as VpnGw1 |
12| GatewaySubnet | /24 recommended | Agent computes from available VNet space |
13| DNS resolver subnet | /28 minimum | Agent computes from available VNet space |
14| Client address pool | `172.16.201.0/24` | Non-overlapping with VNet |
15 
16## Subnet Layout
17 
18Adds two subnets to the existing VNet. Uses the next available range after the agent and PE subnets.
19 
20| Subnet | CIDR (default) | Purpose | Delegation |
21|--------|----------------|---------|------------|
22| `GatewaySubnet` | Computed | VPN Gateway (name is required by Azure) | None |
23| `dns-resolver-inbound` | Computed | DNS Private Resolver inbound endpoint | `Microsoft.Network/dnsResolvers` |
24 
25> ⚠️ **Warning:** `GatewaySubnet` is a reserved name — Azure requires this exact name for VPN Gateway.
26 
27## Pre-Deployment
28 
29### 1. Discover Available Subnets
30 
31List existing subnets to find free address space:
32 
33```bash
34az network vnet subnet list \
35  --resource-group <rg> --vnet-name <vnet-name> \
36  --query "[].{name:name,cidr:addressPrefix}" -o table
37```
38 
39Pick the next unused `/24` for `GatewaySubnet` and the next unused `/28` for `dns-resolver-inbound`. Both must not overlap with any existing subnet.
40 
41Example: if subnets `.0.0/24`, `.1.0/24`, `.2.0/24` are in use → use `192.168.3.0/24` for GatewaySubnet, `192.168.4.0/28` for dns-resolver-inbound.
42 
43### 2. Collect Remaining Inputs
44 
45| Parameter | Source |
46|-----------|--------|
47| `vnetName` | From main deployment |
48| `vnetResourceGroup` | Resource group containing the VNet (omit if same as deployment RG) |
49| `resourceGroupName` | Resource group for this deployment |
50| `gatewaySubnetCidr` | Computed in step 1 |
51| `dnsResolverSubnetCidr` | Computed in step 1 |
52| `suffix` | From main deployment (or generate unique) |
53| `aadTenantId` | From `az account show --query tenantId` |
54 
55### 3. Check VPN Gateway Quota
56 
57```bash
58az network list-usages --location <location> \
59  --query "[?name.value=='VirtualNetworkGateways'].{limit:limit,current:currentValue}" -o table
60```
61 
62## Bicep Template
63 
64Template: [vpn-dns-setup.bicep](vpn-dns-setup.bicep)
65 
66| Parameter | Required | Default | Description |
67|-----------|----------|---------|-------------|
68| `vnetName` | Yes | — | Name of the existing VNet |
69| `vnetResourceGroup` | No | Deployment RG | Resource group of the existing VNet (for BYO VNets in a different RG) |
70| `aadTenantId` | Yes | — | Entra ID tenant ID for VPN auth |
71| `suffix` | Yes | — | Unique suffix for resource naming |
72| `gatewaySubnetCidr` | Yes | — | GatewaySubnet CIDR (computed from VNet) |
73| `dnsResolverSubnetCidr` | Yes | — | DNS resolver inbound subnet CIDR (computed from VNet) |
74| `vpnClientAddressPool` | No | `172.16.201.0/24` | VPN client address pool |
75 
76**Creates:** GatewaySubnet, dns-resolver-inbound subnet, Public IP (zonal), VPN Gateway (VpnGw1AZ, P2S AAD/OpenVPN), DNS Private Resolver with inbound endpoint.
77 
78## Deploy
79 
80```bash
81az deployment group create \
82  --resource-group <rg> \
83  --template-file vpn-dns-setup.bicep \
84  --parameters vnetName='<vnet-name>' aadTenantId='<tenant-id>' suffix='<suffix>' \
85    gatewaySubnetCidr='<computed-cidr>' dnsResolverSubnetCidr='<computed-cidr>' \
86  --name vpn-dns-setup
87```
88 
89> ⚠️ **VPN Gateway provisioning takes 20–45 minutes.** This is normal. Do not cancel.
90 
91Monitor:
92 
93```bash
94az deployment group show \
95  --resource-group <rg> --name vpn-dns-setup \
96  --query "{state:properties.provisioningState}" -o tsv
97```
98 
99## Post-Deployment
100 
101### 1. Get DNS Resolver Inbound IP
102 
103```bash
104az network dns-resolver inbound-endpoint show \
105  --resource-group <rg> \
106  --dns-resolver-name dns-resolver-<suffix> \
107  --name inbound \
108  --query "ipConfigurations[0].privateIpAddress" -o tsv
109```
110 
111Save this IP — the VPN client needs it as custom DNS.
112 
113### 2. Connect via VPN
114 
115Provide the user with these instructions (substitute actual resource name and DNS IP):
116 
1171. Go to **Azure Portal** → `vpn-gateway-<suffix>` → **Point-to-site configuration** → **Download VPN client**
1182. Extract the ZIP → edit `AzureVPN/azurevpnconfig.xml` — replace:
119   ```xml
120   <clientconfig i:nil="true" />
121   ```
122   with:
123   ```xml
124   <clientconfig>
125     <dnsservers>
126       <dnsserver><dns-resolver-inbound-ip></dnsserver>
127     </dnsservers>
128   </clientconfig>
129   ```
1303. Open [Azure VPN Client](https://aka.ms/azvpnclientdownload) → **Import** the modified `azurevpnconfig.xml` → **Connect**
131 
132Use `AskUserQuestion`: **"Let me know when you're connected so I can verify DNS resolution."**
133 
134> Do NOT proceed to verification until the user confirms they are connected.
135 
136### 3. Verify DNS Resolution
137 
138After connecting via VPN, verify private DNS zones resolve correctly:
139 
140```bash
141nslookup <ai-account-name>.services.ai.azure.com
142nslookup <cosmos-account>.documents.azure.com
143nslookup <storage-account>.blob.core.windows.net
144```
145 
146Each should resolve to a private IP (`192.168.x.x`), not a public IP.
147 
148### 4. VPN Setup Complete
149 
150DNS resolves to private IPs — VPN is working. Return to [post-deployment-validation.md](post-deployment-validation.md) **Step 5** to run the end-to-end tests.
151 
152## Troubleshooting
153 
154| Problem | Cause | Fix |
155|---------|-------|-----|
156| VPN connects but DNS doesn't resolve | Custom DNS not set in VPN client profile | Add DNS resolver inbound IP as custom DNS server |
157| `nslookup` returns public IP | Private DNS zones not linked to VNet | Verify DNS zone VNet links: `az network private-dns zone list -g <rg>` |
158| VPN client auth fails | Wrong tenant or app not consented | Verify `tenantId`, ensure Azure VPN enterprise app is consented in the tenant |
159| Gateway deployment times out | Normal — VPN GW takes 20-45 min | Wait and re-check with `az deployment group show` |
160| Subnet conflict | CIDR overlaps with existing subnet | Use different CIDRs for `gatewaySubnetCidr` / `dnsResolverSubnetCidr` |
161| DNS resolver queries blocked | NRMS auto-deployed NSG missing DNS rules | Add inbound allow rule for UDP/TCP port 53 from VPN client address pool to the `dns-resolver-inbound` subnet NSG |
162