---

📖 Overview

This repository contains the complete infrastructure-as-code for my home Kubernetes cluster. Everything from bare-metal provisioning to application deployment is managed through GitOps principles using Flux CD.

The cluster runs on Talos Linux and hosts 90+ applications across 18 namespaces, including media services, home automation, monitoring, and various utilities.

⭐ Features

• Fully Automated GitOps: All cluster state managed via Flux CD with automatic reconciliation
• Immutable Infrastructure: Talos Linux provides a secure, minimal OS designed for Kubernetes
• High Availability: 3-node control plane with virtual IP for API server redundancy
• Distributed Storage: Rook-Ceph cluster for persistent storage with replication
• Secret Management: SOPS with Age encryption for secure secret storage in Git
• Automated Backups: VolSync with Kopia for application data protection
• Comprehensive Monitoring: Prometheus, Grafana, and Gatus for observability
• Self-Healing: Automated dependency updates via Renovate and health monitoring

🏗️ Architecture

Infrastructure

Component	Implementation	Purpose
OS	Talos Linux v1.11.1	Immutable Linux distribution for Kubernetes
Kubernetes	v1.34.1	Container orchestration platform
GitOps	Flux CD v2.6.4	Continuous deployment from Git
Secret Management	SOPS + Age	Encrypted secrets in Git
Storage	Rook-Ceph	Distributed block and filesystem storage
Backups	VolSync + Kopia	Automated backup and replication
Ingress	NGINX Ingress Controller	HTTP/HTTPS traffic routing
Certificates	cert-manager	Automatic TLS certificate management
DNS	External DNS + k8s-gateway	Dynamic DNS and service discovery
Monitoring	Prometheus + Grafana	Metrics, alerting, and visualization

Cluster Details

Control Plane Nodes: 3 (k8s-0, k8s-1, k8s-2)
Node Network:        10.88.0.0/24
Pod Network:         10.42.0.0/16
Service Network:     10.43.0.0/16
API Endpoint:        10.88.0.20:6443 (HA Virtual IP)

📦 Applications

Media & Entertainment (17 apps)

• Media Servers: Plex, Jellyfin
• Media Management: Radarr, Sonarr, Lidarr, Readarr, Prowlarr
• Media Requests: Jellyseerr, Overseerr
• Download Clients: qBittorrent, SABnzbd
• Media Automation: Autobrr, Cross-Seed, Unpackerr
• Media Analytics: Tautulli, Jellystat, Jellyplex-Watched
• Content: Audiobookshelf, Pinchflat

Home Automation (4 apps)

• Home Assistant
• ESPHome
• Zigbee2MQTT
• EMQX (MQTT broker)

Productivity & Utilities (8 apps)

• Actual Budget (personal finance)
• Mealie (recipe management)
• Changedetection.io (website monitoring)
• Hugo (static site generator)
• IT-Tools
• Homebox (inventory management)
• Scrypted (video/camera integration)
• Valheim (game server)

Infrastructure & System (30+ apps)

• Databases: CloudNative-PG (PostgreSQL), Dragonfly (Redis)
• Storage: Rook-Ceph, MinIO, Local-Path-Provisioner, VolSync
• Networking: External DNS, k8s-gateway, Multus, Echo Server
• Monitoring: Prometheus, Grafana, Gatus, Alertmanager
• Exporters: Smartctl, SNMP, Blackbox
• Security: cert-manager, External Secrets Operator
• System: Reloader, Descheduler, Node Feature Discovery, Intel Device Plugin
• CI/CD: GitHub Actions Runner Scale Set
• Kubernetes: Metrics Server, CoreDNS, Cilium, System Upgrade Controller

🚀 Getting Started

Prerequisites

• Hardware: 3 nodes (physical or virtual) capable of running Talos Linux
• Network: Static IP addresses, DHCP, DNS, and ability to configure a virtual IP
• Storage: Additional disks for Rook-Ceph (recommended)
• Tools:
  • talosctl - Talos CLI
  • kubectl - Kubernetes CLI
  • flux - Flux CD CLI
  • task - Task runner
  • sops and age - Secret encryption
  • helm - Kubernetes package manager

Quick Start

1. Clone the repository

   git clone https://github.com/jalim/home-operations.git
   cd home-operations
   

2. Generate Age encryption key

   task sops:age-keygen
   

3. Bootstrap Talos cluster

   task talos:bootstrap
   

4. Deploy Flux CD

   task bootstrap:flux
   

5. Deploy applications

   task bootstrap:apps
   

Note: For detailed setup instructions, see docs/GETTING-STARTED.md

🛠️ Repository Structure

📁 home-operations/
├── 📁 .github/workflows/     # CI/CD automation (Renovate, linting, releases)
├── 📁 .taskfiles/            # Task automation for operations
├── 📁 ansible/               # Ansible playbooks (if used)
├── 📁 kubernetes/
│   └── 📁 main/
│       ├── 📁 apps/          # Application deployments (90+ apps)
│       ├── 📁 bootstrap/     # Cluster initialization configs
│       ├── 📁 flux/          # Flux CD configuration
│       └── 📁 templates/     # Reusable templates
├── 📄 .sops.yaml            # SOPS encryption rules
├── 📄 Taskfile.yaml         # Main task automation entrypoint
└── 📄 README.md             # This file

📚 Documentation

Document	Description
Getting Started	Detailed bootstrap and installation guide
Architecture	System design and infrastructure overview
Applications	Complete application inventory
Operations	Day-to-day operational tasks
Maintenance	Upgrade and maintenance procedures
Disaster Recovery	Backup and recovery procedures
Troubleshooting	Common issues and solutions
Networking	Network configuration and topology
Secrets Management	Working with encrypted secrets

🔧 Common Tasks

# List all available tasks
task --list

# View cluster status
kubectl get nodes
kubectl get pods -A

# Sync Flux
flux reconcile source git flux-system

# Upgrade Talos OS
task talos:upgrade-cluster

# Upgrade Kubernetes
task talos:upgrade-k8s

# Browse PVC contents
task kubernetes:browse-pvc

# View application logs
kubectl logs -n <namespace> <pod-name>

🔐 Secret Management

Secrets are encrypted using SOPS with Age encryption and stored directly in Git. The encryption key (age.key) is stored securely outside this repository.

# Encrypt a file
task sops:encrypt FILE=path/to/secret.yaml

# View encrypted file
sops path/to/secret.sops.yaml

# Edit encrypted file
sops path/to/secret.sops.yaml

See docs/SECRETS.md for detailed instructions.

🔄 Automated Updates

Renovate runs hourly to check for updates to:

• Helm chart versions
• Container images
• Kubernetes manifests
• GitHub Actions

Updates are automatically submitted as pull requests for review.

📊 Monitoring & Observability

• Grafana: https://grafana.yourdomain.com (replace with actual URL)
• Prometheus: Metrics collection and alerting
• Gatus: Uptime monitoring at https://status.lumu.au/status/home
• Alert Manager: Alert routing and notifications

🆘 Support & Community

• Issues: GitHub Issues
• Discussions: GitHub Discussions

🙏 Acknowledgements

This repository is inspired by and built upon the excellent work of the Home Operations and k8s-at-home communities.

Special thanks to:

• onedr0p for the original template and patterns
• The k8s-at-home community for application Helm charts
• The Talos, Flux, and Rook communities for excellent tooling

📝 License

This repository is provided as-is for educational and reference purposes. See LICENSE for details.

---