On-Premises DNS to ACA Internal Environment via Custom Domain¶

Configure on-premises name resolution to reach Azure Container Apps (ACA) running in an Internal Environment using a custom internal domain, when corporate DNS policy prohibits forwarding Azure-managed domains. The ACA Internal Environment exposes apps via a static private IP on the environment's internal load balancer.

Prerequisites¶

• Hub-Spoke VNet topology with Site-to-Site VPN or ExpressRoute
• ACA Internal Environment deployed in Spoke VNet (apps accessible via environment static IP)
• Azure Firewall in Hub VNet (or equivalent NVA)
• On-premises DNS server with Conditional Forwarder capability
• Custom internal domain controlled by your organization (e.g., nhinvest.local)

When to Use¶

Use this procedure when all of the following are true:

1. ACA is deployed as an Internal Environment (apps accessible via environment static IP, not public internet)
2. On-premises users/systems must reach ACA apps via private IP (not public)
3. On-premises DNS policy cannot add Conditional Forwarders for external domains like *.azurecontainerapps.io
4. Hub VNet lacks address space for a Private DNS Resolver subnet (/28)

Architecture¶

flowchart TD
    subgraph On-Premises
        PC[User / System]
        DNS_OP[On-Prem DNS Server]
    end

    subgraph Hub VNet
        VPN[VPN Gateway]
        FW[Azure Firewall]
    end

    subgraph Spoke VNet - 10.x.y.0/19
        RESOLVER[Private DNS Resolver<br/>Inbound Endpoint]
        PE[ACA Internal Environment<br/>Static IP: <aca-static-ip>]
        ZONE[Private DNS Zone<br/>nhinvest.local]
    end

    PC -->|1. DNS query<br/>app.nhinvest.local| DNS_OP
    DNS_OP -->|2. Conditional Forwarder<br/>UDP/TCP 53| VPN
    VPN --> FW
    FW -->|3. Forward to Resolver| RESOLVER
    RESOLVER -->|4. Lookup| ZONE
    ZONE -->|5. A record → <aca-static-ip>| RESOLVER
    RESOLVER -->|6. Response| FW
    FW --> VPN
    VPN -->|7. DNS response| DNS_OP
    DNS_OP -->|8. IP returned| PC
    PC -->|9. HTTPS 443| VPN
    VPN --> FW
    FW -->|10. Route to PE| PE

DNS Resolution Flow¶

flowchart LR
    A[app.nhinvest.local] -->|Conditional Forwarder| B[Resolver Inbound IP]
    B -->|Private DNS Zone link| C[A record: <aca-static-ip>]
    C -->|Response| D[On-prem client connects]

Procedure¶

az containerapp ingress update \
    --resource-group $RG \
    --name $APP_NAME \
    --type external

Step 1: Bind Custom Domain to ACA App¶

Configure a custom domain on the ACA app so it accepts traffic on the internal domain name.

az containerapp hostname add \
    --resource-group $RG \
    --name $APP_NAME \
    --hostname app.nhinvest.local

az containerapp hostname bind \
    --resource-group $RG \
    --name $APP_NAME \
    --hostname app.nhinvest.local \
    --certificate $CERT_ID \
    --environment $CONTAINER_ENV

Step 2: Create Private DNS Zone for Custom Domain¶

Create a Private DNS Zone for your internal domain and add an A record pointing to the ACA Internal Environment's static IP.

# Create the Private DNS Zone
az network private-dns zone create \
    --resource-group $RG \
    --name nhinvest.local

# Add A record pointing to ACA Internal Environment static IP
az network private-dns record-set a add-record \
    --resource-group $RG \
    --zone-name nhinvest.local \
    --record-set-name app \
    --ipv4-address <aca-static-ip>

Step 3: Link Private DNS Zone to Spoke VNet¶

The zone must be linked to the Spoke VNet so the Private DNS Resolver can resolve records from it.

az network private-dns link vnet create \
    --resource-group $RG \
    --zone-name nhinvest.local \
    --name link-spoke-aisvc \
    --virtual-network $SPOKE_VNET_ID \
    --registration-enabled false

Step 4: Deploy Private DNS Resolver in Spoke VNet¶

Deploy the resolver in the Spoke VNet since the Hub lacks available address space for the required /28 subnet.

# Create dedicated subnet for resolver inbound endpoint (/28 minimum)
az network vnet subnet create \
    --resource-group $RG \
    --vnet-name $SPOKE_VNET \
    --name snet-dns-resolver-inbound \
    --address-prefixes 10.x.y.0/28 \
    --delegations Microsoft.Network/dnsResolvers

# Create the Private DNS Resolver
az dns-resolver create \
    --resource-group $RG \
    --name dnspr-spoke-aisvc \
    --location koreacentral \
    --id $SPOKE_VNET_ID

# Create inbound endpoint
az dns-resolver inbound-endpoint create \
    --resource-group $RG \
    --dns-resolver-name dnspr-spoke-aisvc \
    --name inbound-endpoint \
    --location koreacentral \
    --ip-configurations "[{\"private-ip-allocation-method\":\"Dynamic\",\"id\":\"$INBOUND_SUBNET_ID\"}]"

az dns-resolver inbound-endpoint show \
    --resource-group $RG \
    --dns-resolver-name dnspr-spoke-aisvc \
    --name inbound-endpoint \
    --query "ipConfigurations[0].privateIpAddress" \
    --output tsv

Step 5: Configure Azure Firewall Rules (Hub)¶

Allow DNS traffic from on-premises to the resolver, and HTTPS traffic to the ACA Internal Environment's static IP.

Step 6: Configure UDR for Forward Traffic (Hub → Firewall)¶

In the lab simulation, the on-premises VM sits in a Hub subnet. By default, Hub-to-Spoke traffic uses the VNet peering path directly, bypassing Azure Firewall. To force on-prem traffic through the firewall, create a UDR on the on-premises VM subnet.

# Create route table for on-prem simulation subnet
az network route-table create \
    --resource-group $RG \
    --name rt-onprem-to-spoke \
    --location koreacentral

# Route Spoke-bound traffic through Firewall
az network route-table route create \
    --resource-group $RG \
    --route-table-name rt-onprem-to-spoke \
    --name route-to-spoke \
    --address-prefix <spoke-cidr> \
    --next-hop-type VirtualAppliance \
    --next-hop-ip-address $HUB_FIREWALL_IP

# Associate with on-prem simulation subnet
az network vnet subnet update \
    --resource-group $RG \
    --vnet-name $HUB_VNET \
    --name snet-onprem \
    --route-table rt-onprem-to-spoke

Step 7: Configure UDR for Return Traffic (Spoke)¶

Ensure response traffic from the Spoke routes back through Hub Firewall to reach on-premises via VPN.

# Create route table
az network route-table create \
    --resource-group $RG \
    --name rt-spoke-to-onprem \
    --location koreacentral

# Add route for on-premises network
az network route-table route create \
    --resource-group $RG \
    --route-table-name rt-spoke-to-onprem \
    --name route-to-onprem \
    --address-prefix <on-prem-cidr> \
    --next-hop-type VirtualAppliance \
    --next-hop-ip-address $HUB_FIREWALL_IP

# Associate with all relevant Spoke subnets
az network vnet subnet update \
    --resource-group $RG \
    --vnet-name $SPOKE_VNET \
    --name snet-dns-resolver-inbound \
    --route-table rt-spoke-to-onprem

az network vnet subnet update \
    --resource-group $RG \
    --vnet-name $SPOKE_VNET \
    --name snet-aca-infra \
    --route-table rt-spoke-to-onprem

Step 8: Configure On-Premises DNS Conditional Forwarder¶

On the on-premises DNS server, add a Conditional Forwarder for the internal domain only:

zone "nhinvest.local" {
    type forward;
    forward only;
    forwarders { <resolver-inbound-ip>; };
};

sudo systemctl restart named

Verification¶

DNS Resolution Test (from on-premises)¶

nslookup app.nhinvest.local
# Expected: <aca-static-ip>

dig app.nhinvest.local +short
# Expected: <aca-static-ip>

Connectivity Test (from on-premises)¶

curl --insecure https://app.nhinvest.local
# Expected: HTTP response from ACA app

# Or test TCP connectivity with timeout
curl --insecure --silent --head --max-time 5 https://app.nhinvest.local
# Expected: HTTP/2 200 (or similar success status)

From Azure (Spoke VNet VM)¶

# Verify Private DNS Zone resolution
nslookup app.nhinvest.local
# Expected: <aca-static-ip>

# Verify ACA default domain still works internally
nslookup app.<default-domain>.koreacentral.azurecontainerapps.io
# Expected: <aca-static-ip> (via environment's built-in DNS)

Rollback / Troubleshooting¶

Validated Results¶

See Also¶

• Private Endpoints
• VNet Integration
• Custom Domains — Managed Certificates
• Custom Domains — BYO Certificates
• Networking Best Practices
• Internal DNS and Private Endpoint Failure (Troubleshooting)

Sources¶

• Custom domain names and certificates in Azure Container Apps (Microsoft Learn)
• Networking in Azure Container Apps environment (Microsoft Learn)
• What is Azure DNS Private Resolver? (Microsoft Learn)
• Internal ingress with VNet integration (Microsoft Learn)
• Hub-spoke network topology in Azure (Microsoft Learn)
• Azure Private DNS zone scenarios (Microsoft Learn)