Skip to content
Open
Changes from 3 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
75 changes: 57 additions & 18 deletions articles/api-management/api-management-using-with-internal-vnet.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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 Virtual Network 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 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.
Comment thread
v-regandowner marked this conversation as resolved.

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
Comment thread
gmoseley-MSFT marked this conversation as resolved.
Outdated

**Forwarding or controlling the apex domain is strongly discouraged.**

### Recommended DNS approach

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

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":::
Comment on lines +163 to +167
Copy link

Copilot AI Apr 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The custom domain guidance and the same image appear twice (once before the new DNS section, and again under 'Access on custom domain names'). This duplication can confuse readers and increases maintenance cost. Consider keeping this content in only one place (either move it into the new DNS section, or remove the later/earlier duplicate and link to it).

Copilot uses AI. Check for mistakes.

### 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

Expand Down