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

# 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

# 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:

./update.sh

Manual Update Process

1. Update Master Node (turing1)

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)

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

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

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

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