# TuringPi K3s Homelab

This repository contains Kubernetes configuration files for a K3s cluster running on TuringPi hardware. It includes Helm charts, values files, and manifests for deploying various self-hosted applications in a homelab environment.

## 🏗️ Cluster Architecture

### Hardware Setup
- **turing1**: Control plane + worker (192.168.222.237) 
- **turing2**: Worker node
- **turing3**: Worker node (NFS server at turing3.lan)
- **turing4**: Worker node  
- **beelink**: Additional x86_64 worker node

### Infrastructure Stack
- **Kubernetes**: K3s lightweight distribution
- **Storage**: NFS-backed persistent volumes from turing3.lan:/mnt/ssd
- **Load Balancer**: MetalLB for bare metal LoadBalancer services
- **SSL**: cert-manager with Let's Encrypt certificates
- **Ingress**: Nginx with LAN-only access restrictions

## 🚀 Applications

### Media Services
- **Plex**: Via kube-plex (Kubernetes-native with dynamic transcoding)
- **Jellyfin**: Alternative media server
- **Sonarr/Radarr**: TV/Movie management 
- **Prowlarr**: Indexer management
- **Transmission**: BitTorrent client with OpenVPN
- **FlareSolverr**: Captcha solver service

### Other Applications  
- **Actual Budget**: Personal finance management
- **Home Assistant Voice LLMs**: AI voice integration
- **Ollama**: Local LLM inference
- **Prometheus**: Monitoring and metrics
- **PostgreSQL**: Database backend

## 📁 Repository Structure

```
├── *_values.yaml          # Helm values overrides for applications
├── my-actual-server/       # Custom Helm chart for Actual Budget
├── home-assistant-voice-llms/  # Custom Helm chart for Voice AI
├── prowlarr/               # Custom Helm chart for Prowlarr
├── kube-plex/              # Kubernetes-native Plex implementation
├── *.yml                   # Infrastructure manifests (MetalLB, ingress, etc.)
└── persistent_volume*.yml  # Storage definitions
```

## 🔧 Common Operations

### Application Deployment
```bash
# Deploy with Helm using values files
helm upgrade <release-name> <chart> -f <app>_values.yaml -i

# Examples:
helm upgrade actual my-actual-server -f actual_values.yaml -i
helm upgrade plex kube-plex/charts/kube-plex --values plex_values.yml
helm upgrade radarr bananaspliff/radarr -f radarr_values.yaml
```

### Infrastructure Management
```bash
# Apply Kubernetes manifests
kubectl apply -f metallb.yml
kubectl apply -f ingress.yaml

# Check cluster status
kubectl get nodes
kubectl get pods --all-namespaces
```

## 🔄 K3s Cluster Updates

### Automated Update
Run the provided script to update all nodes:
```bash
./update.sh
```

### Manual Update Process

#### 1. Update Master Node (turing1)
```bash
ssh root@turing1  # password: turing
curl -sfL https://get.k3s.io | INSTALL_K3S_SKIP_DOWNLOAD=false sh -s - \
  --write-kubeconfig-mode 644 \
  --disable servicelb \
  --token torino \
  --node-ip 192.168.222.237 \
  --disable-cloud-controller \
  --disable local-storage
```

#### 2. Update Worker Nodes (turing2, turing3, turing4)
```bash
ssh root@<node>  # password: turing
curl -sfL https://get.k3s.io | INSTALL_K3S_SKIP_DOWNLOAD=false \
  K3S_URL=https://192.168.222.237:6443 \
  K3S_TOKEN=torino sh -
```

#### 3. Update Beelink Node
```bash
ssh gilgamezh@beelink.lan  # no password (SSH keys)
sudo curl -sfL https://get.k3s.io | INSTALL_K3S_SKIP_DOWNLOAD=false \
  K3S_URL=https://192.168.222.237:6443 \
  K3S_TOKEN=torino sh -
```

#### 4. Verify Update
```bash
kubectl get nodes  # Check all nodes show new version
kubectl get pods --all-namespaces | grep -v Running  # Check for issues
```

## 🔑 Access Information

- **Cluster Token**: `torino`
- **Master Node**: `192.168.222.237:6443`
- **SSH Access**: 
  - TuringPi nodes: `root@<hostname>` (password: `turing`)
  - Beelink: `gilgamezh@beelink.lan` (SSH keys)

## 📚 Additional Documentation

- See `CLAUDE.md` for detailed Claude Code integration guide
- Custom Helm charts include their own README files
- Check application-specific `*_values.yaml` files for configuration options

## 🛠️ Development

### Helm Chart Development
```bash
helm create <chart-name>
helm lint <chart-path>
helm template <chart> -f <values> | kubectl apply --dry-run=client -f -
```

### Storage Requirements
- NFS server must be running on turing3.lan
- Applications require ReadWriteMany access for shared media
- Persistent volumes are dynamically provisioned via nfs-subdir-external-provisioner