kubernetes/docs/DASHBOARD_SETUP.md

# 🖥️ Kubernetes Dashboard Setup

There are several ways to view and manage your Kubernetes cluster. Here are the best options:

## Option 1: Kubernetes Dashboard (Web UI) ⭐ Recommended

The official Kubernetes Dashboard provides a web-based UI for viewing and managing your cluster.

### Install Dashboard

```bash
cd kubernetes
kubectl apply -f manifests/dashboard.yaml
```

### Access Dashboard

**Method 1: Using kubectl proxy (Recommended for local access)**

```bash
# Start proxy
kubectl proxy

# Dashboard will be available at:
# http://localhost:8001/api/v1/namespaces/kubernetes-dashboard/services/https:kubernetes-dashboard:/proxy/
```

**Method 2: Port Forward (Direct access)**

```bash
# Port forward to access dashboard
kubectl port-forward -n kubernetes-dashboard service/kubernetes-dashboard 8443:443

# Or use HTTP port (9090)
kubectl port-forward -n kubernetes-dashboard service/kubernetes-dashboard 9090:9090

# Then visit: http://localhost:9090
```

**Method 3: Expose via Service (For remote access)**

```bash
# Change service type to NodePort or LoadBalancer
kubectl patch svc kubernetes-dashboard -n kubernetes-dashboard -p '{"spec":{"type":"NodePort"}}'

# Get the port
kubectl get svc -n kubernetes-dashboard
```

### Login to Dashboard

The dashboard is configured with `--enable-skip-login`, so it opens straight to the UI - no token needed to look around.

Skip-login runs as the dashboard's own `kubernetes-dashboard` ServiceAccount, which is **view-only** (get/list/watch). If you need to edit, delete, or exec into something:

1. Get an admin token:
```bash
kubectl -n kubernetes-dashboard create token admin-user
```

2. Click "Sign In" on the dashboard and paste the token.

### What You Can See

- ✅ All pods, services, deployments
- ✅ Resource usage (CPU, memory)
- ✅ Logs from pods
- ✅ Events and errors
- ✅ Namespaces
- ✅ ConfigMaps and Secrets
- ✅ Persistent volumes
- ✅ And much more!

---

## Option 2: k9s (Terminal UI) 🚀 Fast & Lightweight

k9s is a terminal-based UI that's super fast and doesn't require a browser.

### Install k9s

**On Linux:**
```bash
wget https://github.com/derailed/k9s/releases/latest/download/k9s_Linux_amd64.tar.gz
tar xvf k9s_Linux_amd64.tar.gz
sudo mv k9s /usr/local/bin/
```

**On Windows (using Chocolatey):**
```bash
choco install k9s
```

**On macOS:**
```bash
brew install k9s
```

### Use k9s

```bash
# Just run k9s - it will connect to your current kubectl context
k9s

# Or specify namespace
k9s -n nats-backend
```

### k9s Keyboard Shortcuts

- `:pods` - View pods
- `:svc` - View services
- `:deploy` - View deployments
- `:ns` - Switch namespace
- `d` - Describe resource
- `l` - View logs
- `e` - Edit resource
- `Ctrl+D` - Delete resource
- `?` - Help
- `q` - Quit

---

## Option 3: Lens (Desktop App) 💻

Lens is a powerful desktop application for Kubernetes management.

### Install Lens

Download from: https://k8slens.dev/

- **Windows:** Download installer from website
- **Linux:** Download AppImage or .deb/.rpm
- **macOS:** Download .dmg

### Connect to k3s

1. Open Lens
2. Click "Add Cluster"
3. Paste your kubeconfig (from `/etc/rancher/k3s/k3s.yaml` on server)
4. Or Lens can auto-detect k3s if running locally

---

## Option 4: Rancher UI (For k3s)

Since you're using k3s (from Rancher), you can also use Rancher UI.

### Install Rancher

```bash
# Install Rancher (optional - adds overhead)
helm repo add rancher-latest https://releases.rancher.com/server-charts/latest
helm repo update
kubectl create namespace cattle-system
helm install rancher rancher-latest/rancher \
  --namespace cattle-system \
  --set hostname=rancher.yourdomain.com
```

**Note:** Rancher is heavier and more complex. Only use if you need advanced features.

---

## Quick Comparison

| Tool | Type | Best For | Resource Usage |
|------|------|----------|----------------|
| **Kubernetes Dashboard** | Web UI | Visual overview, beginners | Medium |
| **k9s** | Terminal | Fast operations, CLI lovers | Low |
| **Lens** | Desktop | Full-featured, professional | Medium |
| **Rancher** | Web UI | Multi-cluster, enterprise | High |

---

## Recommended Setup

For your use case, I recommend:

1. **Kubernetes Dashboard** - For web-based viewing and monitoring
2. **k9s** - For quick terminal-based operations

Both can be used together!

---

## Troubleshooting

### Dashboard not loading?

```bash
# Check if dashboard is running
kubectl get pods -n kubernetes-dashboard

# Check logs
kubectl logs -n kubernetes-dashboard deployment/kubernetes-dashboard

# Restart dashboard
kubectl rollout restart deployment/kubernetes-dashboard -n kubernetes-dashboard
```

### Can't access dashboard?

- Ensure `kubectl proxy` is running (for Method 1)
- Check firewall rules if accessing remotely
- Verify port-forward is working: `kubectl get svc -n kubernetes-dashboard`

### Permission denied?

The dashboard has full cluster access via the `admin-user` service account. If you see permission errors, check:

```bash
kubectl get clusterrolebinding admin-user
kubectl get serviceaccount admin-user -n kubernetes-dashboard
```

---

## Next Steps

1. Deploy the dashboard: `kubectl apply -f manifests/dashboard.yaml`
2. Access it: `kubectl proxy` then visit the URL
3. Explore your `nats-backend` namespace!

Enjoy your Kubernetes UI! 🎉