Clarify DNS guidance for internal VNet API Management deployments#128418
Conversation
Updated line 114 to reflect "Azure and Microsoft services" as opposed to just Azure services
|
@gmoseley-MSFT : Thanks for your contribution! The author(s) and reviewer(s) have been notified to review your proposed change. |
|
Learn Build status updates of commit db315c8:
|
| File | Status | Preview URL | Details |
|---|---|---|---|
| articles/api-management/api-management-howto-integrate-internal-vnet-appgateway.md | Details | ||
| articles/api-management/api-management-using-with-internal-vnet.md | Details |
articles/api-management/api-management-howto-integrate-internal-vnet-appgateway.md
- Line 246, Column 144: [Warning: bookmark-not-found - See documentation]
Cannot find bookmark '#dns-configuration' in 'articles/api-management/api-management-using-with-internal-vnet.md'.
articles/api-management/api-management-using-with-internal-vnet.md
- Line 29, Column 120: [Warning: bookmark-not-found - See documentation]
Cannot find bookmark '#dns-configuration' in 'articles/api-management/api-management-using-with-internal-vnet.md'.
For more details, please refer to the build report.
Note: Your PR may contain errors or warnings or suggestions unrelated to the files you changed. This happens when external dependencies like GitHub alias, Microsoft alias, cross repo links are updated. Please use these instructions to resolve them.
|
@gmoseley-MSFT - This pull request was opened in the public repo. Generally, changes of this breadth should be made in the private repo, per the Microsoft Docs contributor guide. We can keep this PR open for review and merge, but would you make future content updates in the private repo? Thank you! Can you review the proposed changes? IMPORTANT: When the changes are ready for publication, adding a #label:"aq-pr-triaged" |
prmerger-automator
Bot
added
the
aq-pr-triaged
|
Hello @v-regandowner I had discussed this internally with Dan and an APIM EEE which both gave their approval before I submitted this PR. In the future, when I am developing the documentation internally before posting a PR, should I use the private repo as you suggested or is the workflow I used acceptable? |
dlepow
left a comment
dlepow
left a comment
There was a problem hiding this comment.
@gmoseley-MSFT - Generally we recommend that internal users make contributions through the private repo. However, we can accept this one here. I'm going to sign off to merge now - LGTM. I believe this version is technically identical to what we reviewed previously. Thanks again!
|
#sign-off |
There was a problem hiding this comment.
Pull request overview
Note
Copilot was unable to run its full agentic suite in this review.
Updates the internal VNet API Management documentation to clarify safe DNS patterns and avoid implying customers should take ownership of the Azure-owned azure-api.net domain.
Changes:
- Replaces prior DNS sections with consolidated DNS guidance for internal VNet mode.
- Adds explicit warnings about apex-domain (
azure-api.net) DNS zone ownership and resolution conflicts. - Provides recommended DNS scoping examples and a records table for default host names.
Comments suppressed due to low confidence (2)
articles/api-management/api-management-using-with-internal-vnet.md:1
- 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).
---
articles/api-management/api-management-using-with-internal-vnet.md:1
- The Azure Private DNS guidance is ambiguous and can be interpreted in a way that doesn’t work with the listed default hostnames. In Azure Private DNS, you create zones for domains (suffixes), not for individual records; and the default endpoints are in different subdomains (e.g.,
contoso.portal.azure-api.netis not undercontoso.azure-api.net). Please clarify what scoping means operationally (for example: one Private DNS zone per endpoint FQDN such ascontosointernalvnet.portal.azure-api.netwith an apex@record, or recommend using custom domains under a customer-owned suffix to allow a single zone).
---
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| ### 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"::: |
There was a problem hiding this comment.
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).
|
I will review the above problems tomorrow morning |
…t.md 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 <[email protected]>
|
Learn Build status updates of commit cc72ee4:
|
| File | Status | Preview URL | Details |
|---|---|---|---|
| articles/api-management/api-management-howto-integrate-internal-vnet-appgateway.md | Details | ||
| articles/api-management/api-management-using-with-internal-vnet.md | Details |
articles/api-management/api-management-howto-integrate-internal-vnet-appgateway.md
- Line 246, Column 144: [Warning: bookmark-not-found - See documentation]
Cannot find bookmark '#dns-configuration' in 'articles/api-management/api-management-using-with-internal-vnet.md'.
articles/api-management/api-management-using-with-internal-vnet.md
- Line 29, Column 120: [Warning: bookmark-not-found - See documentation]
Cannot find bookmark '#dns-configuration' in 'articles/api-management/api-management-using-with-internal-vnet.md'.
For more details, please refer to the build report.
Note: Your PR may contain errors or warnings or suggestions unrelated to the files you changed. This happens when external dependencies like GitHub alias, Microsoft alias, cross repo links are updated. Please use these instructions to resolve them.
|
Hi @gmoseley-MSFT and @dlepow, PRs can't be merged with validation warnings. Can you resolve the missing bookmark issue noted in the table and sign off again? |
Summary
Clarifies DNS guidance for API Management in internal VNet mode to avoid recommending ownership of the Azure‑owned azure-api.net public domain.
Details
Replaces the DNS configuration and Configure DNS records sections with consolidated guidance
Removes implicit recommendation to create a Private DNS zone or forward lookup zone for azure-api.net
Explicitly documents risks of apex domain ownership and public DNS resolution conflicts
Clarifies supported DNS scoping using service‑specific FQDNs only
Impact
Documentation-only change. No product behavior or configuration requirements modified.
Review
Content and technical guidance reviewed and approved by Content Dev and APIM EEE