-
Notifications
You must be signed in to change notification settings - Fork 21.8k
Clarify DNS guidance for internal VNet API Management deployments #128418
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
base: main
Are you sure you want to change the base?
Changes from 3 commits
d87f444
d52250c
db315c8
cc72ee4
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -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 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. | ||
|
|
||
| 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 | ||
|
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
|
||
|
|
||
| ### 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 | ||
|
|
||
|
|
||
Uh oh!
There was an error while loading. Please reload this page.