[docs] Add troubleshooting note for DevTunnel URL publication fix - #1570
[docs] Add troubleshooting note for DevTunnel URL publication fix#1570aspire-repo-bot[bot] wants to merge 1 commit into
Conversation
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Frontend HTML artifact readyThe latest frontend build uploaded the This comment updates automatically when a new frontend build artifact is uploaded. |
David Pine (IEvangelist)
left a comment
There was a problem hiding this comment.
🤖 Automated docs-accuracy review — PR #1570
Source of truth: microsoft/aspire@main @ 1cdf7d17248ae78ee018abbc314f772ace5e624d — confirmed to contain the source PR microsoft/aspire#19590 (f7073a8f2d, "Fix DevTunnel endpoint URL publication").
⚠️ Branch mismatch (non-blocking). This PR targetsrelease/13.6, which does not exist inmicrosoft/aspire. Verified againstmain(contains the fix). Note the version landscape below — it's directly relevant to this PR's wording.
Phase A — claims: 4 non-narrative claims → 1 verified · 3 verified-with-nuance · 0 contradicted · 0 unverifiable.
Phase B — doc-tester: exercised /integrations/devtools/dev-tunnels/ → HTTP 200, 0 console errors/warnings; Troubleshooting/See-also insertion region renders; the addition is plain H4 + prose with no new components or links. Knowledge gap: the local build predates this PR.
Verdict: 🟡 COMMENT
The fix mechanism is accurately documented and fully verified. The only thing worth flagging is the version framing — see below. No contradictions, no Phase B critical issues; nothing blocking.
Phase A — Claim verification
⚠️ Nuance worth flagging — the "13.5 bug / fixed in 13.6" version framing is imprecise
The fix mechanism is correct, but the version attribution doesn't quite match the source:
- Latest GA is
v13.4.6— there are no13.5or13.6release tags yet (both are unreleased/preview). - The regression cause (proxyless endpoint allocator, microsoft/aspire#17924) is not present in
v13.4.6, so no shipped release ever exhibited the bug — it lived only in untaggedmain/ preview builds between #17924 and the fix. release/13.5is13.5.0-preview.1and already contains the fix (backported). It's inmain(milestone 13.6) and the 13.5 line.- Consequence: "In Aspire 13.5 … could reach Running/Healthy without a URL" and "update to Aspire 13.6 or later" understate reality — a 13.5 (preview.1+) build already includes the fix, and the bug never shipped in a GA release. The guidance isn't harmful (13.6 does contain the fix), just narrower than the source shows. Consider softening to something like "fixed in Aspire 13.6 (and 13.5 servicing builds)" once versions firm up.
This is non-blocking; the reader still gets correct, actionable advice.
Claim verdicts (4) with evidence, against microsoft/aspire@1cdf7d17
| # | Type | Claim (diff line) | Verdict & evidence |
|---|---|---|---|
| N2 | api-behavior | "dev tunnel endpoints stay unallocated until the integration publishes the real tunnel endpoint" (L306-307) | verified — DcpExecutor.cs NeedsPublicPort (fix f7073a8f2d, ~L837): now (resource is IComputeResource || resource.IsContainer()) && !endpoint.IsProxied && !TryGetEffectiveFixedPublicPort(...) — comment "integration-owned endpoints publish their own addresses." Test DcpExecutorTests.ProxylessPortAllocatorOnlyAllocatesPortsForDcpWorkloads (added): with AddDevTunnel("tunnel"), asserts the tunnel endpoint's Port, TargetPort, and AllocatedEndpoint are all null; the compute endpoint still gets a port. |
| N1 | api-behavior | "In Aspire 13.5, dev tunnel resources could reach Running/Healthy … without ever publishing a public URL" (L304-305) | verified-with-nuance — the pre-fix allocator did assign a port to integration-owned endpoints (the real root cause), so the broken behavior is genuine; but the "13.5" attribution is imprecise (see above): no GA 13.5, and release/13.5 already has the fix. The exact dashboard-state symptom isn't asserted in the fix's unit tests. |
| N3 | api-behavior | "the dashboard and MCP resource snapshots now show the tunnel URL as expected" (L307-308) | verified-with-nuance — correct downstream consequence of N2 (both dashboard and MCP read the resource snapshot that now carries the real endpoint URL); the specific dashboard/MCP surfaces aren't directly asserted in the fix's changed tests. |
| N4 | package-or-version | "fixed in Aspire 13.6" / "update to Aspire 13.6 or later" (L305-306, L309) | verified-with-nuance — fix is in main (milestone 13.6) ✓, and backported to release/13.5 (13.5.0-preview.1); with no 13.5/13.6 GA (latest v13.4.6), "13.6 or later" is narrower than the source shows. |
Phase B — doc-tester report
Focus: new "Dashboard doesn't show a tunnel URL" troubleshooting subsection · Route: http://localhost:51482/integrations/devtools/dev-tunnels/#troubleshooting · Tester: doc-tester skill (blind-user; no source reading).
| Category | Passed | Failed | Warnings |
|---|---|---|---|
| Content accuracy (rendered) | n/a | 0 | 0 |
| Components / rendering | 2 | 0 | 0 |
| Links | 0 new | 0 | 0 |
Critical issues: none. Warnings: none.
Passed checks
- Page health:
GET /integrations/devtools/dev-tunnels/→ 200, title "Dev Tunnels integration | Aspire". 0 console errors, 0 warnings. - Troubleshooting section renders: H3 "Troubleshooting" (
#troubleshooting) with existing H4 subsections ("Authentication required", the "Verify that:" list). The new H4 subsection follows the same pattern → renders. - Insertion region intact: new subsection sits between the "Verify that:" list and the "## See also" H2 (
#see-also); both anchors resolve. - No new components or links: the diff adds a plain H4 + one paragraph only — zero link/component risk.
- The page already states "The tunnel URLs are shown in the Aspire dashboard," the documented behavior the fix restores — consistent framing.
Knowledge gap — running build predates PR #1570
- The local frontend doesn't contain this change (sibling worktree predating the PR), so the literal new subsection couldn't be rendered. I validated page health, the Troubleshooting/See-also anchors, and that the H4+paragraph pattern renders here, with no new links/components. Plain-prose addition ⇒ render failure effectively impossible.
Automated review · Phase A read microsoft/aspire@main 1cdf7d17 (source of truth = upstream, not the local origin fork) · Phase B via doc-tester (blind-user, Playwright).
Adam Ratzman (adamint)
left a comment
There was a problem hiding this comment.
No issues from this review.
Alistair Matthews (alistairmatthews)
left a comment
There was a problem hiding this comment.
A few minor changes. Otherwise it's good to go.
| data-zoom-off | ||
| /> | ||
|
|
||
| [Dev tunnels](https://learn.microsoft.com/azure/developer/dev-tunnels/overview) allow developers to securely share local web services across the internet. Enabling you to connect your local development environment with cloud services, share work in progress with colleagues or aid in building webhooks. Dev tunnels is for adhoc testing and development, not for production workloads. |
There was a problem hiding this comment.
We should remove this repetition:
| [Dev tunnels](https://learn.microsoft.com/azure/developer/dev-tunnels/overview) allow developers to securely share local web services across the internet. Enabling you to connect your local development environment with cloud services, share work in progress with colleagues or aid in building webhooks. |
| - Sharing a running local service (for example, a Web API) with teammates, mobile devices, or webhooks | ||
| - Testing incoming callbacks from external SaaS systems (GitHub / Stripe / etc.) without deploying | ||
| - Quickly publishing a temporary, TLS-terminated endpoint during development |
There was a problem hiding this comment.
Use periods at the end of bullet points if the points make full sentences, either on their own or with the introductory fragment:
| - Sharing a running local service (for example, a Web API) with teammates, mobile devices, or webhooks. | |
| - Testing incoming callbacks from external SaaS systems (GitHub / Stripe / etc.) without deploying. | |
| - Quickly publishing a temporary, TLS-terminated endpoint during development. |
| <Aside type="note"> | ||
| By default tunnels require authentication and are available only to the user | ||
| who created them. You can selectively enable anonymous (public) access per | ||
| tunnel or per individual port. | ||
| </Aside> |
There was a problem hiding this comment.
| <Aside type="note"> | |
| By default tunnels require authentication and are available only to the user | |
| who created them. You can selectively enable anonymous, public access per | |
| tunnel or per individual port. | |
| </Aside> |
|
|
||
| ### Allow anonymous access | ||
|
|
||
| To allow anonymous (public) access to the entire tunnel, chain a call to the `WithAnonymousAccess` method: |
There was a problem hiding this comment.
| To allow anonymous, public access to the entire tunnel, chain a call to the `WithAnonymousAccess` method: |
| - The `public` endpoint of the `api` project with anonymous access | ||
| - The `admin` endpoint of the `api` project that requires authentication |
There was a problem hiding this comment.
| - The `public` endpoint of the `api` project with anonymous access. | |
| - The `admin` endpoint of the `api` project that requires authentication. |
|
|
||
| Tunnels will expire after not being hosted for 30 days by default, so they won't be forcibly deleted when the resource or AppHost is stopped. | ||
|
|
||
| ### Troubleshooting |
There was a problem hiding this comment.
| ## Troubleshooting |
|
|
||
| ### Troubleshooting | ||
|
|
||
| #### Authentication required |
There was a problem hiding this comment.
| ### Authentication required |
| devtunnel user login | ||
| ``` | ||
|
|
||
| #### Port conflicts |
There was a problem hiding this comment.
| ### Port conflicts |
|
|
||
| If you encounter port binding issues, check that no other processes are using the same ports, or configure different ports for your endpoints. | ||
|
|
||
| #### Tunnel not accessible |
There was a problem hiding this comment.
| ### Tunnel not accessible |
| - You're using the correct tunnel URL | ||
| - Anonymous access is configured correctly if accessing without authentication | ||
|
|
||
| #### Dashboard doesn't show a tunnel URL |
There was a problem hiding this comment.
| #### Dashboard doesn't show a tunnel URL | |
| ### Dashboard doesn't show a tunnel URL |
Documents changes from microsoft/aspire#19590
@karolz-msTargeting
release/13.6based on the source PR milestone13.6.Why
microsoft/aspire#19590 fixes a regression where DevTunnel port resources could reach
Running/Healthyin the dashboard while never publishing their public tunnel URL. The proxyless endpoint allocator (introduced in #17924) was assigning a temporary localhost port to DevTunnel endpoints, which the DevTunnel integration mistakenly treated as a signal that the real endpoint had already been published. The fix limits automatic proxyless port allocation toIComputeResourceinstances and containers, leaving integration-owned endpoints (like DevTunnel ports) unallocated until the integration publishes the real endpoint.The dev tunnels docs already state that "tunnel URLs are shown in the Aspire dashboard," so this is a
bug_fix_restores_documented_behaviorcase — the regression was a discrepancy from documented behavior, not a new feature. Since users hit this specific issue on 13.5, I added a short troubleshooting entry so anyone still on 13.5 (or debugging the symptom) can find the explanation and the fix version.Changes
src/frontend/src/content/docs/integrations/devtools/dev-tunnels.mdx: added a new "Dashboard doesn't show a tunnel URL" troubleshooting subsection explaining the 13.5 regression and the 13.6 fix.No new pages were created; only the existing Troubleshooting section was extended.