[Documentation] How-To Publish PowerBI (ADX) Reports with a Privately Configured Hub Instance

[AErmie]

⚠️ Problem

When following the How to publish Power BI reports with a privately configured hub instance article, it only provides guidance on configuring the PowerBI report's Semantic Model's data sources for Web, and AzureDataLakeStorage, but not ADX.

🛠️ Solution

Please also provide guidance on publishing the PowerBI (KQL) reports, that use Azure Data Explorer (ADX) as it's data source.

ℹ️ Additional context

Additionally, please include the How to publish Power BI reports with a privately configured hub instance article (along with ADX related content), in the official documentation as well.

🙋‍♀️ Ask for the community

We could use your help:

1. Please vote this issue up (👍) to prioritize it.
2. Leave comments to help us solidify the vision.

[flanakin]

@ro100e Can you take a look at this?

[robbdi]

Publishing FinOps Hub ADX (Kusto) Power BI Reports Behind a Private VNet (need assistance verifying steps)

Scope
Close GitHub Issue #1487 by documenting how to publish and refresh KQL-based reports when the FinOps Hub and its Azure Data Explorer (ADX) cluster are locked down behind a VNet.

---

1 Why the Existing Guide Falls Short

The Tech Community article covers mapping Web and Azure Data Lake Storage sources, but FinOps Toolkit reports also rely on “Kusto” connections that query the hub’s ADX cluster.
Without mapping this third source, dataset refreshes fail after publishing to the Power BI Service.

---

2 End-to-End Workflow for ADX (Kusto) Reports

Phase	Action	Location
A · Prepare the cluster	- Ensure the hub-adx-<region> cluster is reachable via a Private Endpoint. - Grant the refresh identity AllDatabasesViewer (or narrower) permissions.	Azure portal → ADX
B · Create / edit PBIX	1. Get Data → Azure Data Explorer (Kusto). 2. Cluster URI = https://<cluster>.<region>.kusto.windows.net or the Private Link FQDN. 3. Choose DirectQuery (recommended) or Import. 4. Build visuals → Publish to a workspace backed by Premium/Fabric capacity that uses the same VNet Data Gateway.	Power BI Desktop
C · Provision the VNet Data Gateway	- Re-use the existing gateway for Web/ADLS if present. - If not: Power BI Service → Manage Connections & Gateways → Virtual network data gateways → New. - Select the delegated subnet (Microsoft.PowerPlatform/vnetaccesslinks), capacity, subscription → Save.	Power BI Service
D · Register the ADX connection	1. Connections → + New. 2. Type = Virtual network; Data source = Azure Data Explorer (Kusto). 3. Enter exact cluster URI. 4. Auth = Service Principal, Managed Identity, or OAuth → Create.	Power BI Service
E · Map dataset sources to gateway	Workspace → Semantic Model → Settings → Gateway & cloud connections. - Toggle Use an on-premises or VNet data gateway ON. - Three sources should appear: Web, AzureDataLakeStorage, AzureDataExplorer. - For each, select Maps to → <ADX connection> → Apply.	Power BI Service
F · Test & schedule	- Click Refresh now → confirm Completed. - Configure a refresh schedule that meets SLA.	Power BI Service

---

3 Documentation Pull-Request Checklist

1. File: docs/powerbi/how-to-publish-reports-privatenet.md
2. New subsection: “Publishing Kusto (ADX) reports”
   • Brief explanation of the missing mapping step.
   • Condensed bullet version of Section 2 steps.
   • Two screenshots:
     • Create ADX connection dialog
     • Gateway & Cloud Connections pane showing three mapped sources
3. Cross-links:
   • Use Azure Data Explorer data in Power BI (Microsoft Learn)
   • Connect a cluster behind a private endpoint to Power BI
4. Validation:
   • Run docfx locally (lint pass)
   • Execute pbi-tools check to ensure credentials aren’t embedded
5. PR metadata:
   • Title – “Add ADX gateway steps to private-hub Power BI publishing guide”
   • Labels – Tool: Power BI, docs

---

4 Common Troubleshooting

Symptom	Likely Cause	Resolution
“Cannot find a gateway with connection …”	Cluster URI in PBIX ≠ URI in gateway connection	Re-enter the ADX connection using the precise FQDN (no trailing slash).
“Timeout waiting for gateway”	VNet Data Gateway subnet not delegated to Microsoft.PowerPlatform/vnetaccesslinks	Delegate subnet → restart gateway.
Refresh succeeds in Desktop but credentials prompt after publish	Using personal OAuth; service refresh runs with different principal	Switch to Service Principal or Managed Identity authentication.

---

5 Next Steps for FinOps Toolkit Maintainers

• Add a PBIDS file for Kusto templates to pre-fill cluster/database in Desktop.
• Expose gateway health (status, last refresh) in the Hub Admin blade for better observability.

---