Home Infrastructure

---

📖 Overview

This repository contains my home infrastructure-as-code, managing Kubernetes clusters, cloud resources, and on-premises virtualization using GitOps principles. Flux watches this repository and applies changes automatically to maintain desired state across my infrastructure.

This is a multi-cloud, multi-environment setup supporting home automation, media services, monitoring, and infrastructure experiments.

Related Repositories:

• anthr76/snowflake - System-level configuration (NixOS, routers, nodes)

---

⛵ Kubernetes

Core Components

• Flux - GitOps operator for Kubernetes
• Cilium - eBPF-based container networking (CNI)
• Rook Ceph - Distributed storage for persistent volumes
• VolSync - Asynchronous PVC replication to rsync.net
• CloudNative-PG - PostgreSQL operator

Automation & Security

• Renovate - Automated dependency updates
• External Secrets - Secret synchronization (migrating to Bitwarden Secrets Manager)
• Reloader - Automatic pod restarts on config changes

GitOps Workflow

Flux monitors this Git repository and recursively applies Kustomizations in k8s/clusters/<cluster-name>/. Applications are deployed as HelmReleases with dependency management. Renovate watches for updates to container images, Helm charts, and Terraform modules, automatically creating pull requests.

---

📂 Repository Structure

.
├── armature/prod/          # Production infrastructure (Terraform)
│   ├── cloud-dns/          # Cloudflare DNS management
│   ├── gcp/                # Google Cloud Platform (phasing out)
│   ├── scr1/               # Primary on-premises site (migrating to qgr1)
│   ├── nwk1/               # Secondary network site
│   └── b2/                 # Backblaze B2 storage
├── k8s/                    # Kubernetes manifests
│   ├── base/               # Base configs (namespace = directory name)
│   │   ├── flux-system/    # Flux and HelmRepositories
│   │   ├── home/           # Home automation (Home Assistant, ESPHome)
│   │   ├── media/          # Media services (Plex, qBittorrent)
│   │   ├── monitoring/     # Prometheus, Grafana, Alert Manager
│   │   ├── database/       # PostgreSQL, Redis, CouchDB
│   │   └── ...             # Other namespaces
│   └── clusters/           # Cluster-specific overlays
│       ├── qgr1-cluster-0/ # Primary on-prem cluster
│       └── civo-mgmt-0/    # Management cluster
├── docs/                   # Documentation
└── hack/                   # Utilities and scripts

Key Principles:

• Each directory under k8s/base/ maps 1:1 to a Kubernetes namespace
• All HelmRepository resources live in k8s/base/flux-system/helm-chart-repositories/
• Cluster-specific overrides use Kustomize overlays in k8s/clusters/

---

☁️ Cloud Dependencies

While this infrastructure is primarily self-hosted, it relies on some cloud services:

Service	Use Case	Cost (Approx)
Cloudflare	DNS, CDN, tunnels	~$50/yr
rsync.net	Off-site PVC backups (VolSync)	Variable
Terraform Cloud	Remote state management	Free tier
Bitwarden	Secrets management (migrating to)	~$40/yr

---

🔧 Infrastructure Stack

Development & Automation

• devenv - Nix-based development environments
• just - Task automation (preferred over scripts)
• pre-commit - Git hooks for YAML linting and secret detection

Virtualization & OS

• NixOS - Declarative Linux distribution for infrastructure nodes

Monitoring & Observability

• Prometheus - Metrics collection
• Grafana - Visualization and dashboards
• Alert Manager - Alert routing and management

Applications

• Home Automation: Home Assistant, ESPHome, Zigbee2MQTT, Z-Wave JS UI
• Media: Plex, qBittorrent, cross-seed
• Networking: Unifi Controller
• Databases: PostgreSQL (CloudNative-PG), Redis, CouchDB

---

🚀 Getting Started

Prerequisites

This repository uses devenv for consistent tooling across environments:

# Install devenv (if not already installed)
# See: https://devenv.sh/getting-started/

# Enter development environment (automatically installs all tools)
devenv shell

# Or use direnv for automatic activation
direnv allow

Common Tasks

# List all available automation tasks
just --list

# Reconcile all Flux resources
just flux-reconcile

# Sync Flux GitRepos, Kustomizations, and HelmReleases
just flux-sync

# Suspend/resume Flux resources (useful for maintenance)
just flux-suspend
just flux-resume

Working with Kubernetes

# Check Flux status
flux get all -A

# Manually reconcile a resource
flux reconcile source git flux-system
flux reconcile kustomization <name>

# View Flux logs
flux logs --all-namespaces

---

🔄 Active Migrations

This infrastructure is undergoing several significant transitions:

1. Secret Management → Bitwarden Secrets Manager

Migrating from External Secrets (GCP Secret Manager) to Bitwarden Secrets Manager for all Kubernetes secrets.

2. Terraform Removal

Infrastructure provisioning moving away from Terraform to configurations managed in anthr76/snowflake.

3. OS Migration: NixOS Transition

Infrastructure nodes migrated to NixOS. Legacy Fedora CoreOS and Talos Linux configurations deprecated.

4. GCP Phase-out

Google Cloud Platform resources (GKE, Secret Manager) being migrated away.

5. Site Rename: scr1 → qg1

Primary site designation changing from scr1 to qgr1 due to physical relocation. This affects DNS, certificates, cluster names, and monitoring.

---

📚 Documentation

• CLAUDE.md - Guidance for Claude Code when working with this repository
• docs/ - Additional setup guides and documentation
• .github/instructions/ - Comprehensive coding standards and guidelines

---

🤝 Community & Inspiration

Feel free to open a GitHub issue if you have questions!

Join the community:

• k8s@home Discord

Inspiration from these amazing repositories:

• onedr0p/home-ops
• bjw-s/k8s-gitops
• xUnholy/k8s-gitops
• billimek/k8s-gitops
• carpenike/k8s-gitops
• blackjid/homelab-gitops
• IronicBadger/infra

---