{"id":34955856,"url":"https://github.com/vsingh55/homelab-ops","last_synced_at":"2026-04-11T17:02:19.427Z","repository":{"id":326055657,"uuid":"1103687523","full_name":"vsingh55/homelab-ops","owner":"vsingh55","description":"A production-grade Hybrid Cloud Platform spanning On-Prem (Proxmox) and GCP. Engineered with Terraform, Ansible, K3s, and WireGuard Mesh to demonstrate Zero-Trust networking, FinOps, and SRE principles.","archived":false,"fork":false,"pushed_at":"2026-01-27T17:03:40.000Z","size":9110,"stargazers_count":1,"open_issues_count":21,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-28T03:42:06.980Z","etag":null,"topics":["ansible","automation","devops","finops","gcp","gitops","grafana","hybrid-cloud","infrastructure-as-code","kubernetes","observability","platform-engineering","proxmox","self-hosted","sre","terraform","wireguard","zero-trust"],"latest_commit_sha":null,"homepage":"https://vijaysingh.cloud/","language":"HCL","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vsingh55.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-25T07:47:40.000Z","updated_at":"2026-01-27T17:03:45.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/vsingh55/homelab-ops","commit_stats":null,"previous_names":["vsingh55/homelab-ops"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/vsingh55/homelab-ops","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vsingh55%2Fhomelab-ops","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vsingh55%2Fhomelab-ops/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vsingh55%2Fhomelab-ops/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vsingh55%2Fhomelab-ops/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vsingh55","download_url":"https://codeload.github.com/vsingh55/homelab-ops/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vsingh55%2Fhomelab-ops/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31687881,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-11T13:07:20.380Z","status":"ssl_error","status_checked_at":"2026-04-11T13:06:47.903Z","response_time":54,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ansible","automation","devops","finops","gcp","gitops","grafana","hybrid-cloud","infrastructure-as-code","kubernetes","observability","platform-engineering","proxmox","self-hosted","sre","terraform","wireguard","zero-trust"],"created_at":"2025-12-26T22:02:25.855Z","updated_at":"2026-04-11T17:02:19.414Z","avatar_url":"https://github.com/vsingh55.png","language":"HCL","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Homelab-Ops: The Evolution of a Sovereign Cloud\n\n![Platform](https://img.shields.io/badge/Platform-Hybrid%20Cloud%20(Proxmox%20%2B%20GCP)-orange?style=for-the-badge)\n![Status](https://img.shields.io/badge/Project%20Status-Active%20Development-success?style=for-the-badge)\n\n\u003e **\"This is not just a server in a closet. It is an enterprise-standard R\u0026D platform simulating real-world constraints—Data Sovereignty, CGNAT traversal, Zero-Trust Networking, and Automated Disaster Recovery.\"**\n\n---\n\n## 📖 The Engineering Journey (From Bare Metal to Hybrid Cloud)\n\nThis repository documents the complete lifecycle of building a production infrastructure from scratch. It is organized by **Engineering Phases**, showcasing how the architecture evolved to solve increasingly complex problems.\n\n### Phase 1: The Bare Metal Foundation (v1.0.0)\n**Goal:** Establish a virtualization platform and experiment with Kubernetes orchestration.\n* **The Hardware:** Sourcing a Mini PC (Intel i5, 16GB RAM) and configuring storage tiering (NVMe for OS, HDD for Backups).\n* **The Stack:** Installed **Proxmox VE** as the Type-1 Hypervisor.\n* **The Logic:** Created \"Logical Zones\" to separate Management (Ansible Control Node) from Production (K3s Cluster) and Lab (Ephemeral K8s nodes).\n* **The Limitation:** The cluster was isolated behind a home router with no public access (CGNAT).\n\n![v1 Architecture](images/v.1.0.0/HomeLab-Ops%20V1.0.0.svg)\n\n---\n### Phase 2: The Hybrid Bridge (v2.0.0)\n**Goal:** Break the CGNAT barrier and establish a public presence without exposing the home network.\n* **The Solution:** Architected a **Site-to-Site WireGuard Mesh**.\n* **Cloud Gateway:** Provisioned a Google Cloud Platform (GCP) instance in Mumbai to act as the public \"Front Door.\"\n* **Traffic Flow:** Public traffic hits GCP -\u003e Encrypted Tunnel -\u003e On-Prem Traefik Ingress.\n* **Infrastructure as Code:** Migrated manual setups to **Terraform** (GCP) and **Ansible** (On-Prem).\n\n#### **⚡ Featured Implementation: Hybrid Cloud Automation (n8n)**\n*A real-world stress test of the hybrid architecture: securely hosting a webhook-driven automation platform.*\n\n**The Mission:** Build a \"Sovereign Cloud\" alternative to Zapier. The system must run workloads On-Premises (to save costs) but accept traffic securely from the Public Internet (GitHub Webhooks).\n\n**Architecture Evolution (The path to stability):**\n1.  **Stage 1: The \"Direct Connect\" Attempt (Naive)**\n    * *Design:* Port Forwarding on Home Router.\n    * *Why Rejected:* **Security Risk.** Exposing the home network directly violated \"Zero Trust\" principles.\n2.  **Stage 2: The \"Split-Brain\" Dynamic Cloud (Experimental)**\n    * *Design:* GCP **Spot VM** as a Gateway + \"Watchdog\" scripts to auto-heal the tunnel when preempted.\n    * *Failure Mode:* **\"Zombie States.\"** When IP addresses changed, DNS propagation lag caused Webhook failures. It also created significant **Ansible Drift**, as the inventory file was constantly outdated.\n3.  **Stage 3: The \"Stable Mesh\" (Production Grade)**\n    * *Design:* Migrated to **GCP Standard VM + Static IP** in Mumbai (`asia-south1`).\n    * *Result:* Eliminated the \"Circuit Breaker\" issue. If the home lab goes down, the Gateway now serves a clean 502 error instead of a connection timeout. Latency dropped to \u003c30ms.\n\n\u003e **Technical Challenges \u0026 Solutions:** You can read the full deep-dive [here](docs/journal/project-hybrid-cloud-automation.md).\n\n![v2 Architecture](images/v.2.0.0/P1.hybrid-network/architecture-topology.png)\n![v2 Architecture](images/v.2.0.0/P1.hybrid-network/automation-pipeline.png)\n\u003e The K3s Cluster architecture incorporates several planned future upgrades.\n![v2.1 K3s Cluster](images/k3s-prod/k3s-architecture.png)\n\n---\n### Phase 3: The Platform Era (Roadmap \u0026 Active Dev)\n**Goal:** Shift from \"Building Infrastructure\" to \"Platform Engineering\"—focusing on Supply Chain Security, Event-Driven Architectures, and GreenOps using GCP services.  \n\n#### 🚧 Upcoming Implementation Specs\n\n| Feature | Architecture / Implementation Plan | GCP Services / Cloud Tech |\n| :--- | :--- | :--- |\n| **1. Serverless \"Burst\" Worker** | **Event-Driven Hybrid Pattern:**\u003cbr\u003eInstead of running heavy OCR tasks locally, MinIO upload events will trigger a container in the cloud.\u003cbr\u003e_Why? Offloads compute-heavy tasks to Google Cloud Free Tier._ | **Cloud Run**, **Eventarc**, **Pub/Sub** |\n| **2. Supply Chain Security** | **Secure Registry Pipeline:**\u003cbr\u003eImplementing image signing and vulnerability scanning before any container reaches the Production cluster. | **Artifact Registry** (Optional), Trivy, Cosign, Kyverno |\n| **3. GreenOps Automation** | **\"Eco-Mode\" Lab Manager:**\u003cbr\u003eAn **n8n** workflow that interacts with the Proxmox API to automatically freeze/thaw the 16GB \"Lab Zone\" based on study schedules. | Proxmox API, n8n |\n| **4. GitOps Transformation** | **Pull-Based State Management:**\u003cbr\u003eMigrating from Ansible-push to **ArgoCD**. The cluster will sync itself with this repo, ensuring \"Configuration Drift\" is impossible. | ArgoCD, Kustomize |\n| **5. Hybrid Identity (IAM)** | **Single Sign-On (SSO):**\u003cbr\u003eCentralizing access for service, Traefik, and SSH under one identity provider with MFA enforcement. | Keycloak, OIDC |\n\n---\n#### 📉 Architecture Evolution Plan\n\u003e *Current Focus: Moving stateful workloads (Postgres) to High-Availability Operators.*\n\n* **Now:** Static Postgres Pods (Hard to scale, manual failover).\n* **Next:** **CloudNativePG Operator** with automatic failover, Point-in-Time Recovery (PITR) to S3, and replica pooling.\n---\n\n## Technical Deep Dive\n\n### 1. Infrastructure as Code (IaC)\nI strictly adhere to the **Dry (Don't Repeat Yourself)** principle using modular design.\n* **Terraform:** Split into `infrastructure/gcp` (Cloud Edge) and `infrastructure/on-prem` (Proxmox Resources).\n* **Ansible:** Uses a \"Control Node\" pattern. The `ops-center` node bootstraps the entire fleet using Roles for Hardening, Docker, K3s, and Monitoring.\n\n### 2. The \"Hydration\" Pattern (Security)\nTo maintain **Zero Trust** and keep secrets out of Git, I developed a \"Hydration\" workflow:\n1.  Secrets are encrypted AES-256 in Ansible Vault (`vault.yml`).\n2.  A specialized playbook (`hydrate_infra.yml`) decrypts these values in memory.\n3.  It generates ephemeral `terraform.tfvars` files strictly on the deployment machine.\n4.  **Result:** Terraform plans run with full context, but no secrets ever touch the disk unencrypted.\n\n### 3. Observability \u0026 FinOps\n* **Monitoring:** Full Prometheus/Grafana stack monitoring Kubernetes metrics and Hardware thermals.\n* **Cost Control:** The entire cloud footprint is engineered to stay under minimal costs (~$5-$10/month) using reserved instances and efficient resource sizing.\n\n---\n### \u003cimg src=\"images/google-cloud.svg\" height=\"20\" alt=\"Google Cloud Logo\" style=\"vertical-align: text-bottom;\"/\u003e **Google Cloud Implementation Details** \n\n| Service | Usage in Homelab-Ops |\n| :--- | :--- |\n| **Compute Engine (GCE)** | Hosts the WireGuard Gateway acting as the public \"Front Door\" to the private lab. |\n| **VPC \u0026 Static IP** | Reserved External IP ensures 100% reliability for incoming Webhooks (GitHub -\u003e n8n). |\n| **Cloud NAT** | Provides secure outbound internet access for private cloud subnets (without exposing them). |\n| **Cloud Run** *(Planned)* | Serverless compute target for sporadic, high-intensity tasks (OCR/PDF Processing). |\n| **Eventarc** *(Planned)* | Event bus routing storage events (MinIO) to Cloud Run functions. |","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvsingh55%2Fhomelab-ops","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvsingh55%2Fhomelab-ops","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvsingh55%2Fhomelab-ops/lists"}