From 9857f09d856247703b438735d2c5fb1a64fabceb Mon Sep 17 00:00:00 2001
From: "aspire-repo-bot[bot]"
 <268009190+aspire-repo-bot[bot]@users.noreply.github.com>
Date: Wed, 12 Aug 2026 03:17:11 +0000
Subject: [PATCH 1/2] docs: pin AKS credential command to deployment
 subscription

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 .../src/content/docs/deployment/kubernetes/aks.mdx        | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/src/frontend/src/content/docs/deployment/kubernetes/aks.mdx b/src/frontend/src/content/docs/deployment/kubernetes/aks.mdx
index 3867dc3d6..0f46eb9f2 100644
--- a/src/frontend/src/content/docs/deployment/kubernetes/aks.mdx
+++ b/src/frontend/src/content/docs/deployment/kubernetes/aks.mdx
@@ -568,12 +568,16 @@ See [Install external Helm charts](/deployment/kubernetes/helm-charts/) for a fu
 
 ### AKS cluster not reachable after deploy
 
-After `aspire deploy` provisions the AKS cluster, your local `kubectl` context is configured automatically. If you can't reach the cluster, ensure your Azure CLI session is active and fetch credentials:
+After `aspire deploy` provisions the AKS cluster, your local `kubectl` context is configured automatically. If you can't reach the cluster, ensure your Azure CLI session is active and fetch credentials, pinning the request to the subscription you deployed to:
 
 ```bash title="Get AKS credentials"
-az aks get-credentials --resource-group <resource-group> --name <cluster-name>
+az aks get-credentials --resource-group <resource-group> --name <cluster-name> --subscription <subscription-id>
 ```
 
+<Aside type="tip">
+Always pass `--subscription` explicitly when fetching credentials manually. If your Azure CLI's default subscription (`az account show`) differs from the one Aspire deployed to — common in multi-subscription tenants or CI agents — running `az aks get-credentials` without `--subscription` can fail with a confusing "cluster not found" error, or worse, silently fetch credentials for a same-named cluster in a different subscription. The exact reconnect command, including `--subscription`, is printed in the deploy summary output under **🔑 Connect to cluster**.
+</Aside>
+
 ### Image pull failures
 
 If pods fail with `ImagePullBackOff`, verify that the AKS cluster has the correct role assignment to pull from the provisioned ACR:

From 94a368c0e9522ecf18fdede8edcd3f28f9b8edb3 Mon Sep 17 00:00:00 2001
From: David Pine <david.pine@microsoft.com>
Date: Fri, 14 Aug 2026 11:03:41 -0500
Subject: [PATCH 2/2] Apply suggestions from code review

Co-authored-by: Alistair Matthews <alistairwebdojo@live.com>
---
 src/frontend/src/content/docs/deployment/kubernetes/aks.mdx | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/frontend/src/content/docs/deployment/kubernetes/aks.mdx b/src/frontend/src/content/docs/deployment/kubernetes/aks.mdx
index 0f46eb9f2..6e4cf7957 100644
--- a/src/frontend/src/content/docs/deployment/kubernetes/aks.mdx
+++ b/src/frontend/src/content/docs/deployment/kubernetes/aks.mdx
@@ -568,14 +568,14 @@ See [Install external Helm charts](/deployment/kubernetes/helm-charts/) for a fu
 
 ### AKS cluster not reachable after deploy
 
-After `aspire deploy` provisions the AKS cluster, your local `kubectl` context is configured automatically. If you can't reach the cluster, ensure your Azure CLI session is active and fetch credentials, pinning the request to the subscription you deployed to:
+After `aspire deploy` provisions the AKS cluster, your local `kubectl` context is configured automatically. If you can't reach the cluster, ensure your Azure CLI session is active and then manually fetch the right credentials, pinning the request to the subscription you deployed to:
 
 ```bash title="Get AKS credentials"
 az aks get-credentials --resource-group <resource-group> --name <cluster-name> --subscription <subscription-id>
 ```
 
 <Aside type="tip">
-Always pass `--subscription` explicitly when fetching credentials manually. If your Azure CLI's default subscription (`az account show`) differs from the one Aspire deployed to — common in multi-subscription tenants or CI agents — running `az aks get-credentials` without `--subscription` can fail with a confusing "cluster not found" error, or worse, silently fetch credentials for a same-named cluster in a different subscription. The exact reconnect command, including `--subscription`, is printed in the deploy summary output under **🔑 Connect to cluster**.
+Always pass `--subscription` explicitly when fetching credentials manually. In multi-subscription tenants or CI agents, your Azure CLI's default subscription often differs from the one Aspire deployed to. For this reason, running `az aks get-credentials` without `--subscription` can fail with a confusing "cluster not found" error. Alternatively, it can silently fetch credentials for a same-named cluster in a different subscription, which can be even more difficult to troubleshoot. You can check your default subscription by running  `az account show`.  The exact reconnect command, including the `--subscription` option, is printed in the deploy summary output under **🔑 Connect to cluster**.
 </Aside>
 
 ### Image pull failures