docs: clarify FinOps hub private endpoint topology

[Brett Wilson (MSBrett)]

Summary

• Clarifies that the FinOps Toolkit exclusively owns and manages the FinOps hub virtual network, its three subnets, private DNS, routing, and related resources.
• Documents customer-managed private endpoints in the customer's own virtual network as the preferred private-access topology, with VNet peering retained as a secondary option.
• Adds the customer-managed private-endpoint architecture diagram and updates only one essential deployment sentence plus the Unreleased changelog.

Scope and issue relationship

Relates to #2156. This documentation does not fix or claim to fix the template behavior reported there. The current dev template still declares the VNet's inline subnets collection, so the implementation defect remains outside this documentation-only PR.

This replaces closed PR #2230 with a scope-audited patch. It does not change Bicep, template reference, upgrade guidance, Power BI setup, marketing pages, or page ownership metadata.

Requirements traceability matrix

ID	Requirement	Implementation	Proof
R1	State Toolkit ownership of the hub VNet and networking resources	private-networking.md: How private access works and FinOps hub virtual network	Explicit ownership of the VNet, three named subnets, private endpoints, private DNS, routing, and related resources
R2	Prohibit customer resources and configuration inside the hub VNet	private-networking.md: ownership boundary and VNet sections	Explicitly prohibits customer workloads, subnets, gateways, endpoints, DNS, route tables, and other configuration
R3	Recommend customer-managed private endpoints	private-networking.md: Preferred option: customer-managed private endpoints	New focused guidance and finops-hubs-customer-endpoints.png
R4	Keep peering as a secondary, actionable option	private-networking.md: Network peering, routing, and name resolution	Retains peering/vWAN options, A/CNAME table, private DNS zone list, FQDN guidance, and peering example
R5	Preserve cleanup and managed integration runtime guidance	private-networking.md: Removing private networking	Retains deletion order and managed IR removal steps; clarifies incremental deployment leaves billed resources
R6	Preserve subnet sizing and Power BI gateway rationale	private-networking.md: FinOps hub virtual network	Retains /28, /28, /27, /26 minimum/default, and directs Power BI VNet Data Gateway capacity to the customer VNet
R7	Add an Unreleased changelog entry	changelog.md: Unreleased → FinOps hubs → Changed	Entry links to #2156 and precedes the released v15 section
R8	Keep scope focused and ownership metadata unchanged	Four-file diff	Three Markdown files plus one PNG; author and ms.author match dev; no SVG source or implementation files

Closed PR #2230 feedback addressed

• Changelog entry is under Unreleased, not v15.
• Concrete A/CNAME and private DNS guidance for peered networks is retained.
• Cleanup order and managed integration runtime removal guidance is retained and clarified.
• New image alt text is 127 characters.
• Page ownership metadata is unchanged.
• Only the referenced PNG is added; no orphaned SVG source files are included.

Validation

• pwsh -NoProfile -Command './src/scripts/Test-PowerShell.ps1 -Docs -Lint -Unit' — 2,296 passed, 0 failed.
• Requirement-specific scope audit — PASS for changed-file allowlist, unchanged ownership metadata, required topology language, DNS/cleanup/subnet preservation, Unreleased placement, diagram hash, and no implementation changes.
• git diff --check — PASS.
• Diagram SHA-256: 42D181EE8DF106FB348E0C9C70D361281190DBCC618FF7C95A562BF97F057BCA (the corrected customer-endpoint diagram with the Toolkit-owned boundary enclosing Storage and Azure Data Explorer).

[Copilot]

Pull request overview

Documentation-only update clarifying FinOps hub private networking ownership boundaries and recommending a customer-managed private endpoint topology, aligning guidance with the known upgrade behavior described in #2156 without changing template implementation.

Changes:

• Added explicit ownership boundary language: the Toolkit owns/manages the hub VNet, subnets, private DNS, routing, and related resources.
• Documented customer-managed private endpoints (in the customer VNet) as the preferred private-access topology; kept peering as a secondary option.
• Updated deployment guidance text and added an Unreleased changelog entry referencing #2156.

Reviewed changes

Copilot reviewed 3 out of 4 changed files in this pull request and generated 1 comment.

File	Description
docs-mslearn/toolkit/hubs/private-networking.md	Adds ownership boundary + preferred customer-managed private endpoint guidance and updates related sections (enable/disable, DNS, peering).
docs-mslearn/toolkit/hubs/deploy.md	Updates private routing decision guidance to point to customer-managed endpoints/DNS first, peering second.
docs-mslearn/toolkit/changelog.md	Adds an Unreleased FinOps hubs changelog entry capturing the documentation clarification and topology recommendation.

Suppressed comments (3)

docs-mslearn/toolkit/hubs/private-networking.md:50

• This sentence uses "please refer to"; Microsoft style guidance typically prefers direct phrasing like "see" and avoids "please" in technical documentation.

Note that private networking incurs extra cost for networking resources, connectivity, and dedicated compute in Azure Data Factory. For a detailed cost estimate, please refer to the Azure pricing calculator.

docs-mslearn/toolkit/hubs/private-networking.md:186

• "domain name system" should be capitalized as the proper term "Domain Name System (DNS)".

Communication between the various FinOps hub components is encrypted using TLS. For TLS certificate validation to succeed when using private networking, reliable domain name system (DNS) name resolution is required. The Toolkit creates and manages DNS zones, private endpoints, and DNS entries that guarantee name resolution between FinOps hub components.

docs-mslearn/toolkit/hubs/private-networking.md:210

• The wording "one's corporate" is awkward/inconsistent with the rest of the page; use direct second-person phrasing.

- Allowing one's corporate firewall and VPN IP ranges access over the public internet via the storage and Data Explorer firewalls.

---

💡 Add a code-review agent skill for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Pull request overview

Copilot reviewed 3 out of 4 changed files in this pull request and generated no new comments.

Suppressed comments (3)

docs-mslearn/toolkit/hubs/private-networking.md:62

• The product name is inconsistent with other FinOps hubs docs (for example, docs-mslearn/toolkit/hubs/template.md refers to "Power BI VNet Data Gateway"). Consider using the same product name here for clarity and consistency.

If you use a Power BI virtual network data gateway, deploy it in your own virtual network and plan enough subnet address space for the gateway. Don't deploy the gateway in the FinOps hub virtual network. When you connect to Azure Data Explorer, use the fully qualified domain name (FQDN), such as `clustername.region.kusto.windows.net`, to ensure private endpoint name resolution works correctly.

docs-mslearn/toolkit/hubs/private-networking.md:175

• In this subnet description, "storage" is lowercased while the rest of the doc refers to the component as "Storage" (including the access-options table). Aligning the capitalization helps avoid ambiguity and keeps terminology consistent.

  - **private-endpoint-subnet** (**/28**) – no service delegations configured; hosts private endpoints for storage and Key Vault.

docs-mslearn/toolkit/hubs/private-networking.md:94

• This sentence implies Azure Data Explorer is always present, but earlier the page notes Data Explorer is optional ("if deployed"). Consider reflecting that here to avoid confusing readers who deploy hubs without Data Explorer.

If you need to reduce costs or simplify your FinOps hub deployment, you can switch back to public access. Redeploying with **Access** set to **Public** configures Storage, Data Explorer, and Key Vault to use public access and switches Azure Data Factory back to the public integration runtime.