From d87f44413a67fcfd94476b7957c6eb88a8273b8f Mon Sep 17 00:00:00 2001 From: Grayson Moseley <159056490+gmoseley-MSFT@users.noreply.github.com> Date: Mon, 13 Apr 2026 19:08:24 -0500 Subject: [PATCH 1/4] Update api-management-using-with-internal-vnet.md --- ...api-management-using-with-internal-vnet.md | 75 ++++++++++++++----- 1 file changed, 57 insertions(+), 18 deletions(-) diff --git a/articles/api-management/api-management-using-with-internal-vnet.md b/articles/api-management/api-management-using-with-internal-vnet.md index e7a4682555bc7..89f6f16ef212c 100644 --- a/articles/api-management/api-management-using-with-internal-vnet.md +++ b/articles/api-management/api-management-using-with-internal-vnet.md @@ -77,18 +77,6 @@ After successful deployment, you should see your API Management service's **priv [!INCLUDE [api-management-recommended-nsg-rules](../../includes/api-management-recommended-nsg-rules.md)] -## DNS configuration - -In internal VNet mode, you have to manage your own DNS to enable inbound access to your API Management endpoints. - -We recommend: - -1. Configure an Azure [DNS private zone](../dns/private-dns-overview.md). -1. Link the Azure DNS private zone to the VNet into which you've deployed your API Management service. - -Learn how to [set up a private zone in Azure DNS](../dns/private-dns-getstarted-portal.md). - - > [!NOTE] > The API Management service does not listen to requests on its IP addresses. It only responds to requests to the hostname configured on its endpoints. These endpoints include: > * API gateway @@ -115,21 +103,72 @@ If you don't want to access the API Management service with the default host nam :::image type="content" source="media/api-management-using-with-internal-vnet/api-management-custom-domain-name.png" alt-text="Set up custom domain name"::: -### Configure DNS records +## DNS configuration for internal VNet scenarios -Create records in your DNS server to access the endpoints accessible from within your VNet. Map the endpoint records to the [private virtual IP address](#routing) for your service. +When API Management is deployed in internal VNet mode, inbound access depends on customer‑managed DNS. The API Management service responds **only** to requests addressed to its configured host names and does not listen directly on its private IP address. -For testing purposes, you might update the hosts file on a virtual machine in a subnet connected to the VNet in which API Management is deployed. Assuming the [private virtual IP address](#routing) for your service is 10.1.0.5, you can map the hosts file as follows. The hosts mapping file is at `%SystemDrive%\drivers\etc\hosts` (Windows) or `/etc/hosts` (Linux, macOS). +**DNS must be scoped carefully. Improper zone ownership can break resolution for other Azure services.** -| Internal virtual IP address | Endpoint configuration | -| ----- | ----- | +### Critical DNS design guidance + +`azure-api.net` is a **publicly owned Azure domain** used by multiple Azure services. + +Creating a **Private DNS zone or authoritative forward lookup zone for the apex domain (`azure-api.net`) is not supported** and can introduce unintended resolution failures. + +If a Private DNS zone is created for `azure-api.net`: + +- The zone becomes authoritative within the customer DNS scope +- Public records published by Azure are no longer resolvable +- Other Azure services that rely on `*.azure-api.net` may fail name resolution +- Customers must implement complex DNS forwarding to public resolvers to avoid breakage + +**Forwarding or controlling the apex domain is strongly discouraged.** + +### Recommended DNS approach + +DNS configuration should be limited to **only the exact host names required for the API Management instance**. + +Recommended approaches: + +- Create **DNS records for the full FQDNs only**, pointing directly to the API Management private virtual IP +- If using Azure Private DNS, create a zone **scoped to the specific service FQDN**, not the apex public domain +- Alternatively, use an existing corporate DNS forward lookup zone and define **explicit A records** for each endpoint + +Examples of valid scoping: + +- `contosointernalvnet.azure-api.net` +- `contosointernalvnet.portal.azure-api.net` +- `contosointernalvnet.developer.azure-api.net` +- `contosointernalvnet.management.azure-api.net` +- `contosointernalvnet.scm.azure-api.net` + +**Do not create a Private DNS Zone or Forward Lookup Zone for `azure-api.net`.** + +### DNS records for default host names + +For the default API Management host names, create explicit DNS records that map each endpoint FQDN to the service private virtual IP. + +Example: + +| Private virtual IP | Host name | +| ------------------ | --------- | | 10.1.0.5 | `contosointernalvnet.azure-api.net` | | 10.1.0.5 | `contosointernalvnet.portal.azure-api.net` | | 10.1.0.5 | `contosointernalvnet.developer.azure-api.net` | | 10.1.0.5 | `contosointernalvnet.management.azure-api.net` | | 10.1.0.5 | `contosointernalvnet.scm.azure-api.net` | -You can then access all the API Management endpoints from the virtual machine you created. +These records must be resolvable from all VNets and on‑premises networks that require access to the API Management service. + +### Access on custom domain names + +If you don't want to access the API Management service with the default host names, set up [custom domain names](configure-custom-domain.md) for all your endpoints, as shown in the following image: + +:::image type="content" source="media/api-management-using-with-internal-vnet/api-management-custom-domain-name.png" alt-text="Set up custom domain name"::: + +### Testing name resolution + +For testing purposes, you might update the hosts file on a virtual machine in a subnet connected to the VNet in which API Management is deployed. Assuming the [private virtual IP address](#routing) for your service is 10.1.0.5, you can map the hosts file as follows. The hosts mapping file is at `%SystemDrive%\drivers\etc\hosts` (Windows) or `/etc/hosts` (Linux, macOS). ## Routing From d52250c1d2d586a3f1268f25ceb350e1876cc40d Mon Sep 17 00:00:00 2001 From: Grayson Moseley <159056490+gmoseley-MSFT@users.noreply.github.com> Date: Wed, 15 Apr 2026 13:00:20 -0500 Subject: [PATCH 2/4] Update api-management-using-with-internal-vnet.md --- ...api-management-using-with-internal-vnet.md | 20 +++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/articles/api-management/api-management-using-with-internal-vnet.md b/articles/api-management/api-management-using-with-internal-vnet.md index 89f6f16ef212c..7c4fa7c87a9aa 100644 --- a/articles/api-management/api-management-using-with-internal-vnet.md +++ b/articles/api-management/api-management-using-with-internal-vnet.md @@ -103,17 +103,17 @@ If you don't want to access the API Management service with the default host nam :::image type="content" source="media/api-management-using-with-internal-vnet/api-management-custom-domain-name.png" alt-text="Set up custom domain name"::: -## DNS configuration for internal VNet scenarios +## DNS configuration for internal Virtual Network scenarios -When API Management is deployed in internal VNet mode, inbound access depends on customer‑managed DNS. The API Management service responds **only** to requests addressed to its configured host names and does not listen directly on its private IP address. +When API Management is deployed in internal VNet mode, inbound access depends on customer‑managed DNS. The API Management service responds only to requests addressed to its configured host names and does not listen directly on its private IP address. -**DNS must be scoped carefully. Improper zone ownership can break resolution for other Azure services.** +DNS must be scoped carefully. Improper zone ownership can break resolution for other Azure services. ### Critical DNS design guidance -`azure-api.net` is a **publicly owned Azure domain** used by multiple Azure services. +`azure-api.net` is a publicly owned Azure domain used by multiple Azure services. -Creating a **Private DNS zone or authoritative forward lookup zone for the apex domain (`azure-api.net`) is not supported** and can introduce unintended resolution failures. +Creating a Private DNS zone or authoritative forward lookup zone for the apex domain (`azure-api.net`) is not supported and can introduce unintended resolution failures. If a Private DNS zone is created for `azure-api.net`: @@ -126,13 +126,13 @@ If a Private DNS zone is created for `azure-api.net`: ### Recommended DNS approach -DNS configuration should be limited to **only the exact host names required for the API Management instance**. +DNS configuration should be limited to the exact host names required for the API Management instance. Recommended approaches: -- Create **DNS records for the full FQDNs only**, pointing directly to the API Management private virtual IP -- If using Azure Private DNS, create a zone **scoped to the specific service FQDN**, not the apex public domain -- Alternatively, use an existing corporate DNS forward lookup zone and define **explicit A records** for each endpoint +- Create DNS records for the full FQDNs only, pointing directly to the API Management private virtual IP +- If using Azure Private DNS, create a zone scoped to the specific service FQDN, not the apex public domain +- Alternatively, use an existing corporate DNS forward lookup zone and define explicit A records for each endpoint Examples of valid scoping: @@ -142,7 +142,7 @@ Examples of valid scoping: - `contosointernalvnet.management.azure-api.net` - `contosointernalvnet.scm.azure-api.net` -**Do not create a Private DNS Zone or Forward Lookup Zone for `azure-api.net`.** +**Do not create a Private DNS zone or forward lookup zone for `azure-api.net`.** ### DNS records for default host names From db315c8b4f799fc9fb3033d5be0aadb2f720c8ec Mon Sep 17 00:00:00 2001 From: Grayson Moseley <159056490+gmoseley-MSFT@users.noreply.github.com> Date: Wed, 15 Apr 2026 14:03:17 -0500 Subject: [PATCH 3/4] Update api-management-using-with-internal-vnet.md Updated line 114 to reflect "Azure and Microsoft services" as opposed to just Azure services --- .../api-management/api-management-using-with-internal-vnet.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/articles/api-management/api-management-using-with-internal-vnet.md b/articles/api-management/api-management-using-with-internal-vnet.md index 7c4fa7c87a9aa..2ceeb1ce3457a 100644 --- a/articles/api-management/api-management-using-with-internal-vnet.md +++ b/articles/api-management/api-management-using-with-internal-vnet.md @@ -111,7 +111,7 @@ DNS must be scoped carefully. Improper zone ownership can break resolution for o ### Critical DNS design guidance -`azure-api.net` is a publicly owned Azure domain used by multiple Azure services. +`azure-api.net` is a publicly owned Azure domain used by multiple Azure and Microsoft services. Creating a Private DNS zone or authoritative forward lookup zone for the apex domain (`azure-api.net`) is not supported and can introduce unintended resolution failures. From cc72ee4ec0786e4e3047845b4ed098b313f1be63 Mon Sep 17 00:00:00 2001 From: Grayson Moseley <159056490+gmoseley-MSFT@users.noreply.github.com> Date: Fri, 17 Apr 2026 08:38:55 -0500 Subject: [PATCH 4/4] Update articles/api-management/api-management-using-with-internal-vnet.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit These list items include trailing double spaces, which forces hard line breaks in Markdown rendering. If the line breaks aren’t intentional, remove the trailing spaces to avoid unexpected formatting differences across renderers. Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- .../api-management-using-with-internal-vnet.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/articles/api-management/api-management-using-with-internal-vnet.md b/articles/api-management/api-management-using-with-internal-vnet.md index 2ceeb1ce3457a..e29bb4585087c 100644 --- a/articles/api-management/api-management-using-with-internal-vnet.md +++ b/articles/api-management/api-management-using-with-internal-vnet.md @@ -117,10 +117,10 @@ Creating a Private DNS zone or authoritative forward lookup zone for the apex do If a Private DNS zone is created for `azure-api.net`: -- The zone becomes authoritative within the customer DNS scope -- Public records published by Azure are no longer resolvable -- Other Azure services that rely on `*.azure-api.net` may fail name resolution -- Customers must implement complex DNS forwarding to public resolvers to avoid breakage +- The zone becomes authoritative within the customer DNS scope +- Public records published by Azure are no longer resolvable +- Other Azure services that rely on `*.azure-api.net` may fail name resolution +- Customers must implement complex DNS forwarding to public resolvers to avoid breakage **Forwarding or controlling the apex domain is strongly discouraged.**