From e644b0b8ca746c0ad5544064697f6e703f0530c8 Mon Sep 17 00:00:00 2001
From: mik-tf <mik-tf@users.noreply.github.com>
Date: Tue, 4 Nov 2025 10:54:08 -0500
Subject: [PATCH] docs: Expand kubeconfig setup instructions with multiple
 methods and troubleshooting

---
 README.md | 85 ++++++++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 81 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index c6c587d..234b7f3 100644
--- a/README.md
+++ b/README.md
@@ -50,11 +50,88 @@ Mycelium Cloud uses peer-to-peer networking that enables:
 
 ### 3. Access Your Cluster
 
-#### Download Kubeconfig
+#### Download and Configure Kubeconfig
 
-1. Go to dashboard → Clusters → Click download icon (⬇️)
-2. Set kubeconfig: `export KUBECONFIG=/path/to/config`
-3. Test: `kubectl get nodes`
+**Method 1: Direct to Default Location (Recommended)**
+```bash
+# 1. Download kubeconfig from dashboard → Clusters → Click download (⬇️)
+# 2. Copy to kubectl's default location
+mkdir -p ~/.kube
+cp ~/Downloads/kubeconfig.yaml ~/.kube/config
+
+# 3. Verify connection
+kubectl get nodes
+```
+
+**Method 2: Environment Variable (Multi-cluster)**
+```bash
+# 1. Download kubeconfig and save to a specific location
+# 2. Set environment variable (temporary)
+export KUBECONFIG=/path/to/your/kubeconfig.yaml
+
+# 3. Verify connection
+kubectl get nodes
+```
+
+**Method 3: Merge with Existing Config (Advanced)**
+```bash
+# 1. Download kubeconfig
+# 2. Merge with existing kubeconfig (preserves other clusters)
+KUBECONFIG=~/.kube/config:/path/to/downloaded/config.yaml kubectl config view --flatten > ~/.kube/config-temp
+mv ~/.kube/config-temp ~/.kube/config
+
+# 3. Switch between clusters
+kubectl config use-context mycelium-cluster
+```
+
+**Method 4: Named Context (Best Practice)**
+```bash
+# 1. Download kubeconfig
+# 2. Add as named context
+kubectl config --kubeconfig=/path/to/downloaded/config.yaml set-context mycelium-cloud --cluster=my-cluster --user=default
+
+# 3. Use specific context
+kubectl config use-context mycelium-cloud
+kubectl get nodes
+```
+
+**Test your setup:**
+```bash
+# Verify cluster connectivity
+kubectl cluster-info
+
+# Check nodes
+kubectl get nodes
+
+# View current context
+kubectl config current-context
+```
+
+**Troubleshooting Kubeconfig:**
+
+```bash
+# Check kubectl version and config location
+kubectl version --client
+echo $KUBECONFIG
+
+# View current config
+kubectl config view
+
+# List all contexts
+kubectl config get-contexts
+
+# Check if nodes are accessible
+kubectl get nodes --v=6  # Verbose output for debugging
+
+# Test API server connectivity
+curl -k https://<cluster-api-server>:6443/version
+```
+
+**Common Issues:**
+- **Permission denied**: `chmod 600 ~/.kube/config`
+- **Context not found**: `kubectl config use-context <context-name>`
+- **Multiple kubeconfig files**: `KUBECONFIG=path1:path2 kubectl get nodes`
+- **Expired certificates**: Re-download kubeconfig from dashboard
 
 #### SSH Access