A comprehensive, production-ready Kubernetes homelab infrastructure built with Infrastructure as Code (IaC) and GitOps practices. This repository provides a complete solution for deploying and managing a self-hosted Kubernetes cluster with modern DevOps tools and best practices.
- Automated Bare Metal Provisioning: PXE-based installation of Fedora Server across multiple nodes
- Kubernetes Cluster: Deployed using kubespray for production-grade configuration
- GitOps Workflow: ArgoCD for continuous deployment and configuration management
- Infrastructure as Code: Everything defined declaratively with Ansible, Terraform, and Kubernetes manifests
- Container Registry: Private container registry with Harbor
- CI/CD Pipeline: Woodpecker CI for automated builds and deployments
- Git Repository: Self-hosted Gitea for source code management
- Identity Management: Kanidm for authentication and authorization
- Monitoring Stack: Grafana, Prometheus, and Loki for observability
- Certificate Management: Automated SSL/TLS certificates with cert-manager and Let's Encrypt
- Distributed Storage: Rook Ceph for reliable block and object storage
- Load Balancing: NGINX Ingress Controller for traffic routing
- DNS Management: External DNS integration with Cloudflare
- Secure Tunneling: Cloudflare Tunnel for secure external access
- Terraform Automation: Automated setup of external access infrastructure
- Cloudflare Integration: DNS management, tunnel configuration, and SSL certificates
- Monitoring Alerts: ntfy integration for system notifications
- Secret Management: External Secrets Operator with encrypted storage
- Network Policies: Cilium for network security and observability
- Automated Updates: Renovate for dependency management
- Backup Solutions: Automated backup strategies for data protection
┌─────────────────────────────────────────────────────────────┐
│ Hardware Layer │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │ Node 1 │ │ Node 2 │ │ Node 3 │ │ Node N │ │
│ │(Master) │ │(Worker) │ │(Worker) │ │(Worker) │ │
│ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │
└─────────────────────────────────────────────────────────────┘
│
┌─────────────────────────────────────────────────────────────┐
│ Infrastructure Layer │
│ Fedora Server + kubespray + Kubernetes + Rook Ceph │
└─────────────────────────────────────────────────────────────┘
│
┌─────────────────────────────────────────────────────────────┐
│ Platform Services │
│ ArgoCD │ Gitea │ Woodpecker │ Harbor │ Kanidm │ Grafana │
└─────────────────────────────────────────────────────────────┘
│
┌─────────────────────────────────────────────────────────────┐
│ Application Layer │
│ Homepage │ Jellyfin │ Matrix │ Paperless │ Custom Apps │
└─────────────────────────────────────────────────────────────┘
Comprehensive documentation is available at k8s-gitops.fullstackjam.com, including:
- Installation Guide: Step-by-step setup instructions
- Architecture Overview: Detailed system architecture
- Concepts: Key concepts and design decisions
- How-to Guides: Common tasks and configurations
- Roadmap: Current status and future plans
For production deployment, see the Production Installation Guide.
- Operating System: Fedora Server
- Container Orchestration: Kubernetes (deployed with kubespray)
- Infrastructure Automation: Ansible
- External Access Setup: Terraform (Cloudflare Tunnel, DNS, certificates)
- GitOps: ArgoCD
- Storage: Rook Ceph
- Load Balancer: NGINX Ingress Controller
- Network Security: Cilium CNI
- DNS: External DNS + Cloudflare
- Tunneling: Cloudflare Tunnel
- Version Control: Gitea
- CI/CD: Woodpecker CI
- Container Registry: Harbor
- Identity Management: Kanidm
- Monitoring: Grafana + Prometheus + Loki
- Certificate Management: cert-manager + Let's Encrypt
- Secret Management: External Secrets Operator
- Dependency Updates: Renovate
- Documentation: MkDocs Material
- Configuration Management: Helm Charts
k8s-gitops/
├── docs/ # Documentation
│ ├── concepts/ # Core concepts and explanations
│ ├── how-to-guides/ # Step-by-step guides
│ ├── installation/ # Installation instructions
│ └── reference/ # Technical reference
├── kubernetes/ # Kubernetes manifests
│ ├── apps/ # Application deployments
│ ├── platform/ # Platform services
│ └── system/ # System components
├── metal/ # Bare metal provisioning (Ansible)
│ └── kubespray/ # Kubernetes deployment with [kubespray](https://github.com/fullstackjam/kubespray) (submodule)
├── external/ # External access setup with Terraform
├── scripts/ # Utility scripts
└── test/ # Integration tests
We welcome contributions! Please see our Contributing Guide for details.
- Fork the repository
- Create a feature branch from
upstream/master - Make your changes
- Test your changes locally
- Submit a pull request
Current Status: Alpha
This project is currently in alpha phase. While functional, it's primarily designed for learning and experimentation. See our Roadmap for planned features and stability improvements.
This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.
Important: By using this project, you agree to:
- Use the same GPL v3 license for any derived works
- Keep your project open-source
- Include proper attribution
- Inspired by khuedoan/homelab
- Built with modern DevOps tools and practices
- Community contributions and feedback
⭐ If you find this project helpful, please give it a star!