[docs] Pin AKS credential command to the deployment subscription

[aspire-repo-bot]

Documents changes from microsoft/aspire#19219

@mitchdenny

Targeting release/13.5 — the latest release branch on microsoft/aspire.dev — because release/13.6 (from the source PR milestone 13.6) does not exist there.

Why

The source PR fixed aspire deploy for AKS environments to always pass --subscription when fetching cluster credentials (az aks get-credentials) and when resolving the resource group (az resource list), rather than relying on the ambient az CLI default subscription. Without this, users in multi-subscription tenants or CI agents could get a confusing "cluster not found" error, or silently fetch credentials for a same-named cluster in the wrong subscription.

The PR body explicitly calls out a --subscription flag mention (triggered signal: pr_body_has_cli_flag_mention) and documents a new copy-pasteable reconnect command shown in the deploy summary output.

What changed

• Updated the Troubleshooting → AKS cluster not reachable after deploy section in deployment/kubernetes/aks.mdx to include --subscription <subscription-id> in the manual az aks get-credentials command.
• Added an Aside tip explaining why --subscription matters (multi-subscription tenants, CI agents) and pointing users to the 🔑 Connect to cluster deploy summary output for the exact reconnect command.

Files changed

• src/frontend/src/content/docs/deployment/kubernetes/aks.mdx (updated existing page)

Generated by PR Documentation Check for #19219 · auto · 40.9 AIC · ⌖ 9.05 AIC · ⊞ 19.6K · ◷

[Alistair Matthews (alistairmatthews)]

Copilot: Please address my suggestions.

[Copilot]

Pull request overview

Updates the AKS troubleshooting documentation to align with the aspire deploy behavior for multi-subscription Azure environments by explicitly pinning manual credential retrieval to the deployment subscription.

Changes:

• Updates the manual az aks get-credentials command to include --subscription <subscription-id>.
• Adds a tip explaining why explicitly setting --subscription matters and points users to the deploy summary reconnect command.

---

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

[aspire-repo-bot]

Frontend HTML artifact ready

The latest frontend build uploaded the frontend-dist artifact for PR #1476. Use the VS Code button below to open this PR with GitHub Artifacts Explorer and browse the built HTML locally.

This comment updates automatically when a new frontend build artifact is uploaded.

[David Pine (IEvangelist)]

Docs-accuracy review — automated (Phase A: claims vs. source · Phase B: doc-tester)

Phase A source of truth: microsoft/aspire @ release/13.5 · SHA 8ab6999850d96e0023670799edbd4bdc245ad63c (PR targets release/13.5; documents microsoft/aspire#19219).
Claims extracted: 2 non-narrative (+3 external Azure-CLI narrative) → verified: 2 · verified-with-nuance: 0 · unverifiable: 0 · contradicted: 0
Phase B (doc-tester): 1 page exercised (/deployment/kubernetes/aks/) · 0 critical · 0 warnings · 0 knowledge gaps.

Verdict: APPROVE. Both the source-code claim and the rendered docs check out cleanly. The core assertion — that the exact reconnect command including --subscription is printed in the deploy summary under 🔑 Connect to cluster — matches the product code exactly, and Aspire itself pins --subscription in its own internal credential fetch, which corroborates the doc's advice. The remaining statements are standard Azure CLI behavior.

---

Phase A — Claim verification

Both non-narrative claims were located in microsoft/aspire @ release/13.5. No contradicted, unverifiable, or nuance items.

✅ Verified claims (2) — evidence

Evidence paths are in microsoft/aspire @ 8ab6999850d96e0023670799edbd4bdc245ad63c.

deployment/kubernetes/aks.mdx — "AKS cluster not reachable after deploy"

• C1 (cli-surface) — the reconnect command az aks get-credentials --resource-group <resource-group> --name <cluster-name> --subscription <subscription-id>. verified — matches the exact command Aspire prints in its deploy summary: `az aks get-credentials --resource-group '{resourceGroup}' --name '{clusterName}' --subscription {subscriptionId}` (src/Aspire.Hosting.Azure.Kubernetes/AzureKubernetesEnvironmentResource.AksPipeline.cs:306). Aspire also pins --subscription in its own internal credential fetch — aks get-credentials --resource-group "..." --name "..." --file - --subscription "{subscriptionId}" (BuildGetCredentialsArguments, AksPipeline.cs:802) — which corroborates the doc's "always pass --subscription" advice.
• C2 (api-behavior / output) — "The exact reconnect command, including the --subscription option, is printed in the deploy summary output under 🔑 Connect to cluster." verified — context.Summary.Add("🔑 Connect to cluster", new MarkdownString($"az aks get-credentials ... --subscription {subscriptionId}")) (AksPipeline.cs:302-305); asserted by tests at tests/Aspire.Hosting.Azure.Kubernetes.Tests/AzureKubernetesInfrastructureTests.cs:462,547.

Narrative / external (standard Azure CLI behavior — noted, not blocking): omitting --subscription failing with "cluster not found" or silently targeting a same-named cluster in another subscription; az account show showing the default subscription; multi-subscription/CI defaults differing. These describe Azure CLI, not Aspire, so they aren't verified against Aspire source — but they're consistent with why Aspire pins --subscription internally (see AzureKubernetesEnvironmentExtensions.cs:471-473).

---

Phase B — Doc-tester results (blind new-user perspective, no source code consulted)

Served the PR head (94a368c0e9522ecf18fdede8edcd3f28f9b8edb3) locally via pnpm dev at http://localhost:4321/ and navigated with Playwright. Report reproduced verbatim:

Documentation Test Report

Focus Area: PR #1476 troubleshooting update for AKS credential reconnect guidance
Date: 2026-08-14
Tester: doc-tester agent
Served Base URL: http://localhost:4321/
Served Head SHA: 94a368c0e9522ecf18fdede8edcd3f28f9b8edb3

Routes Exercised:

• http://localhost:4321/deployment/kubernetes/aks/
• http://localhost:4321/deployment/kubernetes/aks/#aks-cluster-not-reachable-after-deploy

Summary

Category	Passed	Failed	Warnings
Content Accuracy	1	0	0
Code Examples	0	0	0
CLI Commands	1	0	0
Links	1	0	0

Critical Issues

None.

Warnings

None.

Passed Checks

• The AKS deployment page loaded successfully.
• The "AKS cluster not reachable after deploy" subsection appears in the "On this page" navigation.
• Clicking the "On this page" navigation entry navigated to #aks-cluster-not-reachable-after-deploy.
• The intro text clearly tells readers to manually fetch the right credentials and pin the request to the deployed subscription.
• The az aks get-credentials Bash code block renders with --subscription <subscription-id>.
• The code block includes a copy button.
• The Tip callout renders correctly.
• The Tip clearly explains why omitting --subscription can fail with "cluster not found" or target a same-named cluster in another subscription.
• The Tip includes az account show as a way to check the Azure CLI default subscription.
• The Tip renders the 🔑 Connect to cluster reference correctly.
• No broken anchor or obvious formatting issue was observed in the tested subsection.

Recommendations

1. Priority fixes: None.
2. Documentation gaps: None found in the tested section.
3. Product issues: None discovered from blind documentation testing.

Knowledge Gaps

None.

---

_{Automated docs-accuracy review. Phase A reads microsoft/aspire source (read-only); Phase B runs the doc-tester skill blind to source code against a local render of this PR.}