https://github.com/starslider/kubernetes-demo
A comprehensive home lab Kubernetes setup with GitOps, supporting multiple Linux distributions on VMs and bare metal. Includes ArgoCD, Cilium, monitoring, security, and production-ready applications.
https://github.com/starslider/kubernetes-demo
arch-linux argocd authentik automation bare-metal cert-manager cilium containerd gitops grafana homelab infrastructure-as-code kubernetes linux monitoring networking security self-hosted ubuntu virtualization
Last synced: 3 months ago
JSON representation
A comprehensive home lab Kubernetes setup with GitOps, supporting multiple Linux distributions on VMs and bare metal. Includes ArgoCD, Cilium, monitoring, security, and production-ready applications.
- Host: GitHub
- URL: https://github.com/starslider/kubernetes-demo
- Owner: Starslider
- License: mit
- Created: 2025-06-21T15:39:42.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2026-04-19T13:49:48.000Z (3 months ago)
- Last Synced: 2026-04-19T15:07:34.979Z (3 months ago)
- Topics: arch-linux, argocd, authentik, automation, bare-metal, cert-manager, cilium, containerd, gitops, grafana, homelab, infrastructure-as-code, kubernetes, linux, monitoring, networking, security, self-hosted, ubuntu, virtualization
- Language: Python
- Size: 606 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Security: SECURITY.md
Awesome Lists containing this project
README
# 🏠 Home Lab Kubernetes
[](k8s-sandbox/README.md)
A comprehensive home lab Kubernetes setup with GitOps, supporting multiple Linux distributions on VMs and bare metal
## 🎯 Overview
This repository provides a complete setup guide and configuration for deploying a production-ready Kubernetes cluster in your home lab. The setup supports various Linux distributions and deployment methods including VMs, bare metal servers, and hybrid configurations.
### ✨ Key Features
- � **Multi-Distribution Support** - Works with Arch Linux, Ubuntu, and other distributions
- 🖥️ **Flexible Deployment** - VMs, bare metal, or hybrid setups
- � **Step-by-step Guides** - Detailed installation and configuration
- 🚀 **GitOps Ready** - ArgoCD for automated deployments
- 🔐 **Security First** - Identity management with Authentik
- 🌐 **Advanced Networking** - Cilium CNI with BGP support
- � **Full Observability** - Monitoring, logging, and alerting
- 🏠 **Home Lab Optimized** - Gaming servers, automation, and more
## 🏗️ Architecture
**[View/Edit Interactive Diagram](docs/architecture-diagram.drawio)** - Open in draw.io to modify
### Deployment Options
- **Virtual Machines** - Unraid, Proxmox, VMware, VirtualBox
- **Bare Metal** - Physical servers and workstations
- **Hybrid Setup** - Mix of VMs and physical nodes
### Recommended Specs
- **Control Plane**: 4 cores, 8GB RAM minimum
- **Worker Nodes**: 2 cores, 4GB RAM minimum per node
- **Storage**: NFS, local storage, or distributed solutions
### 🌟 Included Applications
ArgoCD
GitOps Engine
Cilium
Networking
Authentik
Identity
cert-manager
Certificates
VictoriaMetrics
Monitoring
Grafana
Dashboards
External Secrets
Secrets Management
Harbor
Registry
n8n
Automation
External DNS
DNS Management
Gateway API
Ingress/Traffic
NFS Storage
Persistent Volumes
See [Applications Directory](k8s-sandbox/apps) for the complete list of available applications.
## 🚀 Getting Started
### Prerequisites
- Linux servers or VMs (Arch Linux, Ubuntu, etc.)
- Minimum 16GB total RAM (32GB+ recommended)
- Network connectivity between nodes
- Basic Linux and Kubernetes knowledge
### Quick Start
```bash
# Clone the repository
git clone https://github.com/Starslider/kubernetes-demo.git
cd kubernetes-demo
# Choose your setup guide:
# For Arch Linux VMs: k8s-sandbox/README.md
# For Ubuntu/other distros: See platform-specific docs
```
📖 **[View Full Installation Guide →](k8s-sandbox/README.md)**
## 📂 Repository Structure
```text
kubernetes-demo/
├── k8s-sandbox/ # Main Kubernetes configurations
│ ├── apps/ # ArgoCD application definitions
│ ├── argocd/ # GitOps setup and configuration
│ ├── monitoring/ # Grafana, VictoriaMetrics, alerts
│ ├── networking/ # Cilium, ingress, DNS
│ ├── security/ # Authentik, cert-manager, secrets
│ └── README.md # Detailed setup guide
├── flatcar/ # Flatcar Linux specific configs
├── scripts/ # Helper scripts and utilities
└── docs/ # Additional documentation
```
## 🛠️ Development
### Core Stack
**Platform**: Kubernetes, containerd, kubeadm
**Networking**: Cilium CNI with BGP
**GitOps**: ArgoCD for automated deployments
**Security**: Authentik SSO, cert-manager, External Secrets
**Monitoring**: VictoriaMetrics, Grafana, Prometheus ecosystem
**Storage**: NFS CSI, local storage options
### Design Principles
- **GitOps First**: All changes tracked and deployed via ArgoCD
- **Security by Default**: Zero-trust networking, encrypted communication
- **Home Lab Optimized**: Cost-effective, power-efficient configurations
- **Production Ready**: High availability and monitoring built-in
## 📚 Documentation
| Component | Description | Link |
|-----------|-------------|------|
| 🚀 **Installation** | Complete setup guide | [k8s-sandbox/README.md](k8s-sandbox/README.md) |
| 📦 **Applications** | Available apps and configs | [k8s-sandbox/apps/](k8s-sandbox/apps/) |
| 🔄 **GitOps** | ArgoCD setup and usage | [k8s-sandbox/argocd/](k8s-sandbox/argocd/) |
| 🌐 **Networking** | Cilium and network policies | [k8s-sandbox/cilium/](k8s-sandbox/cilium/) |
## 🤝 Contributing
Contributions are welcome! Please read our [Contributing Guidelines](CONTRIBUTING.md) first.
1. Fork the repository
2. Create your feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request
## 📝 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## 🙏 Acknowledgments
- [Kubernetes Documentation](https://kubernetes.io/docs/) - Official K8s docs
- [CNCF Projects](https://cncf.io/) - Cloud native ecosystem
- [Home Lab Community](https://www.reddit.com/r/homelab/) - Inspiration and support
---
Made with ❤️ by [Starslider](https://github.com/Starslider)
If you find this project helpful, please consider giving it a ⭐️