Add troubleshooting guidance for kubectl, cluster setup, and ACR deployment

content/00-pre-reqs/index.md

@@ -111,15 +111,24 @@ To have `.bashrc` changes take affect in your current terminal, you must reload
 
 ## ✅ Verify installation
 
-Double check that everything in installed and working correctly with:
+Double check that everything is installed and working correctly with:
 
 ```bash
+# Verify Azure CLI and Helm are working
 # Try commands with tab completion
-k get pods -A
-helm
 az
+helm
 ```
 
+Now test kubectl - this will verify kubectl is properly installed:
+
+```bash
+# Test kubectl installation
+k get pods -A
+```
+
+<div class="troubleshoot"> This command may fail with a <strong>connection refused error</strong> if no Kubernetes cluster is configured yet (for example, when starting fresh) or if your kubeconfig still points to an old or expired cluster from a different project. This is expected behaviour, we'll create and connect to a new cluster in the next section.</div>
+
 ## 🔐 Login to Azure
 
 The rest of this workshop assumes you have access to an Azure subscription, and have the Azure CLI working & signed into

content/01-cluster/index.md

@@ -30,15 +30,37 @@ az aks create --resource-group $RES_GROUP \
   --no-ssh-key
 ```
 
-In case you get an error when creating cluster, `Version x.xx.x is not supported in this region` run the following to
-get the supported Kubernetes versions
+<div class="troubleshoot">Unsupported Kubernetes Version
+
+If you get error "Version x.xx.x is not supported in this region", run the following to get the supported Kubernetes
+versions
 
 ```bash
 az aks get-versions --location $REGION -o table
 ```
 
 And re-run the create cluster command with a supported version number.
 
+</div>
+
+<div class="troubleshoot">Missing Subscription Registration
+
+If you get error `MissingSubscriptionRegistration`, run the following to register the provider:
+
+```bash
+az provider register --namespace Microsoft.ContainerService
+```
+
+You can check the status with:
+
+```bash
+az provider show --namespace Microsoft.ContainerService --query registrationState
+```
+
+Once the status is Registered, re-run the cluster creation command.
+
+</div>
+
 This should take around 5 minutes to complete, and creates a new AKS cluster with the following characteristics:
 
 - Two small B-Series _Nodes_ in a single node pool. _Nodes_ are what your workloads will be running on. This is about as

content/02-container-registry/index.md

@@ -29,6 +29,25 @@ az acr create --name $ACR_NAME --resource-group $RES_GROUP \
 > When you pick a name for the resource with `$ACR_NAME`, this has to be **globally unique**, and not contain any
 > underscores, dots or hyphens. Name must also be in lowercase.
 
+<div class="troubleshoot">Missing Subscription Registration
+
+If you see the error `MissingSubscriptionRegistration`, your Azure subscription isn't yet registered to create Container
+Registry resources. Register the required provider:
+
+```bash
+az provider register --namespace Microsoft.ContainerRegistry
+```
+
+You can check the status with:
+
+```bash
+az provider show --namespace Microsoft.ContainerRegistry --query registrationState
+```
+
+Once the status is Registered, retry creating the registry.
+
+</div>
+
 ## 📥 Importing Images
 
 For the sake of speed and maintaining the focus on Kubernetes we will import pre-built images from another public
@@ -62,7 +81,7 @@ az acr import --name $ACR_NAME --resource-group $RES_GROUP \
 ```
 
 If you wish to check and see imported images, you can go over to the ACR resource in the Azure portal, and into the
-'Repositories' section.
+'Services' > 'Repositories' section.
 
 ## 🔌 Connect AKS to ACR - as Azure Subscription Owner
 

content/_includes/main.css

@@ -14,6 +14,9 @@
   --border-color: #0ea2e6;
   --shadow-color: rgba(0, 0, 0, 0.15);
   --blockquote-bg: #edf2f7;
+  --troubleshoot-bg: #fff3cd;
+  --troubleshoot-border: #ffc107;
+  --troubleshoot-text: #856404;
 }
 
 /* Dark theme colors */
@@ -32,6 +35,9 @@
     --border-color: #0ea2e6;
     --shadow-color: rgba(0, 0, 0, 0.6);
     --blockquote-bg: #283031;
+    --troubleshoot-bg: #3a3a2f;
+    --troubleshoot-border: #ffc107;
+    --troubleshoot-text: #ffd43b;
   }
 }
 
@@ -50,6 +56,9 @@
   --border-color: #0ea2e6;
   --shadow-color: rgba(0, 0, 0, 0.15);
   --blockquote-bg: #edf2f7;
+  --troubleshoot-bg: #fff3cd;
+  --troubleshoot-border: #ffc107;
+  --troubleshoot-text: #856404;
 }
 
 [data-theme="dark"] {
@@ -66,6 +75,9 @@
   --border-color: #0ea2e6;
   --shadow-color: rgba(0, 0, 0, 0.6);
   --blockquote-bg: #283031;
+  --troubleshoot-bg: #3a3a2f;
+  --troubleshoot-border: #ffc107;
+  --troubleshoot-text: #ffd43b;
 }
 
 body {
@@ -247,6 +259,31 @@ blockquote code {
   font-style: normal;
 }
 
+/* Troubleshooting note style */
+.troubleshoot {
+  margin: 30px 20px;
+  padding: 15px;
+  color: var(--troubleshoot-text);
+  background-color: var(--troubleshoot-bg);
+  border-left: 5px solid var(--troubleshoot-border);
+  border-radius: 4px;
+  line-height: 150%;
+  transition:
+    color 0.3s ease,
+    background-color 0.3s ease,
+    border-color 0.3s ease;
+}
+
+.troubleshoot::before {
+  content: "⚠️ ";
+  font-style: normal;
+}
+
+.troubleshoot code {
+  background-color: rgba(0, 0, 0, 0.1);
+  color: inherit;
+}
+
 abbr {
   text-decoration: none;
   border-bottom: 1px dotted var(--text-secondary);