Add comprehensive documentation and automated update script

- Add README.md: Complete repository overview, architecture, and usage guide - Add update.sh: Automated K3s cluster upgrade script for all nodes - Add CLAUDE.md: Claude Code integration documentation 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
2025-07-28 14:18:07 +02:00
parent 620d757f8b
commit ff3e6f723c
4 changed files with 439 additions and 0 deletions
@@ -0,0 +1,144 @@
+# 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