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