socktop-webterm/kubernetes/KUBECTL-SETUP.md

# Setting Up kubectl for k3s

Since your kubectl config is empty, you need to configure it to connect to your k3s cluster.

## Quick Setup (Automated)

```bash
cd kubernetes
./setup-kubectl.sh
```

The script will:
1. Ask for your k3s server IP
2. Retrieve the kubeconfig from the server via SSH
3. Modify it to use the correct server IP
4. Save it to your local machine
5. Test the connection

### Example Run:

```bash
$ ./setup-kubectl.sh

Enter k3s server IP address: 192.168.1.101
Enter SSH username for k3s server (default: ubuntu): ubuntu

Fetching kubeconfig from k3s server...
✓ Retrieved kubeconfig from server

Choose how to save the kubeconfig:
  1) Replace ~/.kube/config
  2) Save as ~/.kube/config-k3s (separate file, safer)
  3) Merge with existing ~/.kube/config

Enter choice (1/2/3, default: 2): 2

✓ Saved to ~/.kube/config-k3s

To use this config, run:
  export KUBECONFIG=~/.kube/config-k3s
```

## Manual Setup

If you prefer to do it manually:

### Step 1: Get kubeconfig from k3s server

```bash
# SSH to your k3s server node
ssh ubuntu@192.168.1.101  # use your server IP

# View the kubeconfig
sudo cat /etc/rancher/k3s/k3s.yaml
```

### Step 2: Copy to your local machine

```bash
# On your local machine
mkdir -p ~/.kube

# Copy the config (replace 192.168.1.101 with your k3s server IP)
scp ubuntu@192.168.1.101:/tmp/k3s-config.yaml ~/.kube/config-k3s

# Or manually copy the content
nano ~/.kube/config-k3s
# Paste the content from previous step
```

### Step 3: Modify server IP

Edit the file and change the server IP from `127.0.0.1` to your actual k3s server IP:

```bash
nano ~/.kube/config-k3s
```

Change:
```yaml
server: https://127.0.0.1:6443
```

To:
```yaml
server: https://192.168.1.101:6443  # use your actual IP
```

### Step 4: Set KUBECONFIG

```bash
export KUBECONFIG=~/.kube/config-k3s
```

Make it permanent by adding to your shell config:

**For bash (~/.bashrc):**
```bash
echo 'export KUBECONFIG=~/.kube/config-k3s' >> ~/.bashrc
source ~/.bashrc
```

**For zsh (~/.zshrc):**
```bash
echo 'export KUBECONFIG=~/.kube/config-k3s' >> ~/.zshrc
source ~/.zshrc
```

**For fish (~/.config/fish/config.fish):**
```fish
echo 'set -gx KUBECONFIG ~/.kube/config-k3s' >> ~/.config/fish/config.fish
```

### Step 5: Test connection

```bash
kubectl get nodes
```

You should see your k3s nodes listed!

## Verify Setup

After configuration, verify everything works:

```bash
# Check contexts
kubectl config get-contexts

# Should show something like:
# CURRENT   NAME      CLUSTER   AUTHINFO   NAMESPACE
# *         default   default   default    

# Check nodes
kubectl get nodes

# Should show your k3s nodes:
# NAME            STATUS   ROLES                  AGE   VERSION
# rpi-master      Ready    control-plane,master   30d   v1.28.2+k3s1
# rpi-worker-1    Ready    <none>                 30d   v1.28.2+k3s1
# rpi-worker-2    Ready    <none>                 30d   v1.28.2+k3s1

# Check cluster info
kubectl cluster-info
```

## Troubleshooting

### Cannot connect to k3s server

**Error:** `Unable to connect to the server: dial tcp 192.168.1.101:6443: i/o timeout`

**Fix:**
- Verify the IP address is correct
- Check if port 6443 is accessible: `nc -zv 192.168.1.101 6443`
- Check firewall rules on k3s server
- Ensure k3s is running: `ssh ubuntu@192.168.1.101 'sudo systemctl status k3s'`

### Permission denied

**Error:** `error: You must be logged in to the server (Unauthorized)`

**Fix:**
- The kubeconfig may not have been copied correctly
- Re-run the setup script or manually copy the config again

### Wrong server IP

If you need to change the server IP:

```bash
nano ~/.kube/config-k3s
# Change the server: line to the correct IP
```

## Next Steps

Once kubectl is configured:

```bash
# 1. Configure registry on all k3s nodes
./setup-registry.sh

# 2. Deploy Socktop WebTerm
./deploy.sh
```

## Complete Workflow Example

```bash
# Setup kubectl
cd kubernetes
./setup-kubectl.sh
# Enter: 192.168.1.101 (your k3s server IP)
# Choose option 2 (save as separate file)

# Set environment variable for current session
export KUBECONFIG=~/.kube/config-k3s

# Verify connection
kubectl get nodes

# Configure registry
./setup-registry.sh
# Enter all node IPs

# Deploy
./deploy.sh
# Choose namespace: default

# Check status
kubectl get pods -l app=socktop-webterm

# Done!
```