docs: clarify FinOps hub private endpoint topology

[Brett Wilson (MSBrett)]

Summary

• Documents the FinOps hub private-network security posture, including default-deny service firewalls, trusted-service Cost Management export writes, Azure portal management, and private data-plane traffic.
• Defines customer-managed private endpoints as the preferred topology, including required Storage and Azure Data Explorer subresources, cloud-specific DNS guidance, and a corrected peering alternative.
• Corrects subnet, retained-resource, cleanup, billing, integration-runtime, Key Vault, and deployment-script Storage guidance.
• Rebuilds all four networking diagrams with Microsoft Azure Architecture Icons V24 and consistent network boundaries, connectors, legends, and accessible alt text.

Scope and issue relationship

Relates to #2156. This documentation describes the current dev implementation and doesn't change Bicep or deployment behavior.

This replaces closed PR #2230 with a scope-audited documentation update. The PR changes eight files: .gitignore, three Markdown files, and four PNG diagrams. No SVG source or implementation files are included.

Requirements traceability

ID	Requirement	Implementation
R1	Explain the private-network security posture and ownership boundary	private-networking.md: How private access works, Security posture, and FinOps hub virtual network
R2	Recommend customer-managed private endpoints	private-networking.md: Preferred option: customer-managed private endpoints and finops-hubs-customer-endpoints.png
R3	Document exact endpoint and DNS requirements	Storage blob and dfs; Data Explorer cluster and requiredZoneNames; Azure cloud-specific suffix guidance
R4	Keep peering actionable and secondary	Corrected DNS resolver, private DNS zone, gateway, firewall, route table, and pairwise peering guidance and diagram
R5	Preserve accurate removal and cost guidance	Retained resources, charge behavior, and dependency-ordered cleanup are documented separately
R6	Correct subnet and runtime behavior	/28, /28, and /27 subnet purposes; deployment-script Storage file endpoint; default and managed Azure integration runtimes
R7	Record the change under Unreleased	changelog.md: Unreleased > FinOps hubs > Changed
R8	Keep the change documentation-only	Eight-file diff; no Bicep, template, or SVG source changes

Validation

• Invoke-Pester for MsLearnDocs.Tests.ps1 and DocsLinks.Tests.ps1 — 2,282 passed, 0 failed.
• git diff --check — PASS.
• All four diagrams are 1600 × 1000 and use official Microsoft Azure Architecture Icons V24.
• Diagram alt text lengths: 103, 104, 124, and 118 characters.
• SHA-256:
  • Public routing: 652c95fe5e78adbcf6f62d23c81db8fed27b0f0ae64f330664af2d2c49ef413f
  • Private routing: 68a9cce2649842e4b34c0864a134c99c8a125e4231e14edc0f4af53cda382156
  • Customer-managed endpoints: 70e7a8627d9b8e558d332cdd003ecc7ae8d10d2c07f937fa739c1a68ff77fa6b
  • Peered access: 0a1ac9c10697ca6907425ed2cf347825920f931f7fcf3ea4af1046de7ca743c3

[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.