Symptoms
| Error | Usually means |
|---|---|
403 Public access is disabled. Please configure private endpoint. | Name resolves to the public IP; private DNS not used |
| Connection timeout | Resolves to private IP but no network path (NSG, UDR, firewall, peering) |
Name or service not known / NXDOMAIN | DNS can't resolve at all (broken forwarder/zone) |
| Works from one VNet, fails from another | Zone not linked to that VNet, or that VNet uses a different DNS server |
Step 1: resolve from where the app runs
From the app host, pod or Function (Kudu console, kubectl exec, a test VM in the same subnet):
nslookup aoai-prod.openai.azure.com
Expected with a working private endpoint:
aoai-prod.openai.azure.com canonical name = aoai-prod.privatelink.openai.azure.com
Address: 10.20.4.7 <- private IP of the private endpoint
If you get a public IP, DNS isn't using the private zone.
Step 2: check the private DNS zone
The zone for Azure OpenAI is privatelink.openai.azure.com (Cognitive Services accounts may also use privatelink.cognitiveservices.azure.com; AI Foundry adds others such as privatelink.services.ai.azure.com). Check the private endpoint's DNS configuration to see which zones it needs.
az network private-dns record-set a list -g rg-dns -z privatelink.openai.azure.com -o table
az network private-dns link vnet list -g rg-dns -z privatelink.openai.azure.com -o table
| Finding | Fix |
|---|---|
| No A record for the account | Re-create the private endpoint's DNS zone group, or add the record |
| Zone not linked to the app's VNet (or the hub VNet that hosts DNS) | Add a virtual network link |
| Duplicate zones (one per spoke, one central) | Consolidate on one zone, linked to the DNS-resolving VNet |
az network private-dns link vnet create -g rg-dns -z privatelink.openai.azure.com \
-n link-hub --virtual-network /subscriptions/<sub>/resourceGroups/rg-hub/providers/Microsoft.Network/virtualNetworks/vnet-hub \
--registration-enabled false
Step 3: custom DNS servers
If VNets use custom DNS (domain controllers, Azure DNS Private Resolver, third-party appliances):
- The custom DNS must forward
openai.azure.com(or theprivatelinkzone) to Azure DNS (168.63.129.16) from a VNet that is linked to the private zone, typically through Azure DNS Private Resolver inbound endpoints. - On-premises clients: conditional forwarder for
openai.azure.com→ Private Resolver inbound IP.
Test the resolver path directly:
nslookup aoai-prod.openai.azure.com 10.0.0.4 # your custom DNS / resolver IP
Step 4: network path
Once DNS returns the private IP:
nc -zv 10.20.4.7 443 # or Test-NetConnection 10.20.4.7 -Port 443
Check NSGs on the app subnet (outbound 443), UDRs sending traffic to a firewall (allow the private endpoint IP), and VNet peering between spoke and the PE's VNet.
Step 5: app-side caching
Apps and runtimes cache DNS. After fixing DNS, restart app instances (App Service restart, rollout restart for pods) if they keep the old public IP.
Quick restore option
If production is down and DNS fixes take time, temporarily re-enable public network access with a firewall allowlist of the app's outbound IPs. Then fix DNS and disable it again. Record this as a temporary exception.
Warning
Each new spoke or region added later needs the same DNS path. Most "it broke after a network change" incidents are a new VNet that was never linked or forwarded.
Prevent it next time
- Central private DNS zones linked to the hub/resolver VNet, managed by Azure Policy (auto-create records for new private endpoints).
- Synthetic test from every spoke resolving and calling the AI endpoints.
- Network change checklist that includes private endpoint DNS.