gilgamezh
ff3e6f723c
- 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>
112 lines
4.3 KiB
Markdown
112 lines
4.3 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Repository Overview
|
|
|
|
This repository contains Kubernetes configuration files for a K3s homelab cluster running on TuringPi hardware. It includes Helm charts, values files, and manifests for deploying various self-hosted applications.
|
|
|
|
## Cluster Architecture
|
|
|
|
### Hardware Setup
|
|
- **turing1**: Control plane + worker (master node, IP: 192.168.222.237)
|
|
- **turing2**: Worker node (currently SchedulingDisabled)
|
|
- **turing3**: Worker node (also serves as NFS server at turing3.lan)
|
|
- **turing4**: Worker node
|
|
- **beelink**: Additional worker node
|
|
|
|
### Core Infrastructure
|
|
- **K3s version**: v1.31.6+k3s1
|
|
- **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 (staging/production cluster issuers)
|
|
- **Ingress**: Nginx with LAN-only restrictions
|
|
|
|
## Application Stack
|
|
|
|
### Media Services
|
|
- **Plex**: kube-plex (Kubernetes-native with dynamic transcoding pods)
|
|
- **Jellyfin**: Alternative media server
|
|
- **Sonarr/Radarr**: TV/Movie management (Bananaspliff charts)
|
|
- **Prowlarr**: Indexer management (custom chart)
|
|
- **Transmission**: BitTorrent client with OpenVPN
|
|
- **FlareSolverr**: Captcha solver service
|
|
|
|
### Other Applications
|
|
- **Actual Budget**: Personal finance (custom chart: my-actual-server/)
|
|
- **Home Assistant Voice LLMs**: AI voice integration (custom chart)
|
|
- **Ollama**: Local LLM inference
|
|
- **Prometheus**: Monitoring stack
|
|
- **PostgreSQL**: Database backend
|
|
|
|
## Common Helm Operations
|
|
|
|
### Repository Management
|
|
```bash
|
|
# Key repositories used
|
|
helm repo add metallb https://metallb.github.io/metallb
|
|
helm repo add nfs-subdir-external-provisioner https://kubernetes-sigs.github.io/nfs-subdir-external-provisioner
|
|
helm repo add jetstack https://charts.jetstack.io
|
|
helm repo add bitnami https://charts.bitnami.com/bitnami
|
|
helm repo add bananaspliff https://bananaspliff.github.io/geek-charts
|
|
helm repo add k8s-at-home https://k8s-at-home.com/charts/
|
|
helm repo add prometheus-community https://prometheus-community.github.io/helm-charts
|
|
helm repo add jellyfin https://jellyfin.github.io/jellyfin-helm
|
|
helm repo add ollama-helm https://otwld.github.io/ollama-helm/
|
|
helm repo update
|
|
```
|
|
|
|
### Application Deployment Pattern
|
|
```bash
|
|
# Standard deployment with values file
|
|
helm upgrade <release-name> <chart> -f <app>_values.yaml -i
|
|
|
|
# Examples from history:
|
|
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
|
|
helm upgrade sonarr bananaspliff/sonarr -f sonarr_values.yaml
|
|
helm upgrade prowlarr prowlarr -f prowlarr_values.yml
|
|
```
|
|
|
|
### Development Workflow
|
|
```bash
|
|
# Chart development
|
|
helm create <chart-name>
|
|
helm lint <chart-path>
|
|
helm template <chart> -f <values> | vim -
|
|
|
|
# Values inspection
|
|
helm show values <chart> > <app>_values.yaml
|
|
helm get values <release-name>
|
|
helm get manifest <release-name>
|
|
```
|
|
|
|
## File Structure Patterns
|
|
|
|
- `<app>_values.yaml` - Helm values overrides for each application
|
|
- Custom charts in subdirectories (my-actual-server/, home-assistant-voice-llms/, prowlarr/)
|
|
- `*_persistent_volume.yml` - PV definitions for applications requiring storage
|
|
- Infrastructure manifests: metallb.yml, ingress.yaml, cluster-issuer-*.yaml
|
|
|
|
## Storage Configuration
|
|
|
|
- **NFS Server**: turing3.lan serving /mnt/ssd
|
|
- **StorageClass**: nfs-client (via nfs-subdir-external-provisioner)
|
|
- **Access Mode**: ReadWriteMany for shared media access
|
|
- **PVC Pattern**: Applications create their own PVCs or reference pre-existing ones
|
|
|
|
## Network Setup
|
|
|
|
- **Pod Network**: Cluster subnet requires allowlisting in Plex for transcoding
|
|
- **Ingress**: LAN-only access enforced via limit_ingress_to_lan.yaml
|
|
- **Load Balancer**: MetalLB provides external IPs for services
|
|
- **DNS**: .lan domain for internal services
|
|
|
|
## Kube-Plex Specifics
|
|
|
|
The kube-plex/ directory contains a Go application that replaces the standard Plex transcoder:
|
|
- Creates Kubernetes pods for each transcode job
|
|
- Requires AMD64 nodes (configured via nodeSelector)
|
|
- Mounts shared NFS volumes for media access
|
|
- Environment variables: DATA_PVC, CONFIG_PVC, TRANSCODE_PVC, PMS_IMAGE, PMS_INTERNAL_ADDRESS |