This repository contains the configuration of my Kubernetes-based homelab, built to practice modern cloud-native technologies, GitOps, and Infrastructure as Code in a production-like environment while running a few always-on applications.
The platform pairs a local single-node Talos Kubernetes cluster with supporting infrastructure provisioned in Azure. Kubernetes resources are reconciled by FluxCD, while cloud resources are provisioned separately using Terraform. The repository contains configurations for two environments: Production (home-prod) and Development (home-dev).
Please note:
- This is a sanitized snapshot of a private repository; sensitive values (IPs, domains, emails) are scrubbed before publishing. See Sanitization for details.
- This repository is specific to my homelab setup and not a ready-to-use template. If you would like to build something similar, see Deployment Notes.
The design philosophy and goals for this homelab.
- GitOps first: Git is the single source of truth for both infrastructure and application configurations. FluxCD keeps the cluster state in sync with this repository.
- Infrastructure as Code: Cloud infrastructure and platform dependencies are managed declaratively using Terraform.
- Modularity: Separation between infrastructure, applications, and cluster definitions.
- Environment overlays: Multiple environments (dev, prod) are handled with Kustomize overlays, avoiding duplication of base manifests.
- Secrets management: No secrets in Git. Sensitive data is handled with SOPS and External Secrets Operator, backed by Azure Key Vault.
- Production practices: Adopts patterns suitable for real corporate environments.
- Avoid vendor lock-in: Use modular designs and decouple components so switching tools is possible.
- Kubernetes-native: Prefer Kubernetes and cloud-native APIs over custom tooling. For example, use Gateway API to define and control inbound traffic centrally.
- TLS everywhere: Use real X.509 certificates issued through cert-manager and terminated by Kong Gateway.
- Bootstrap automation: New clusters can be bootstrapped quickly with scripts provided in
kubernetes/bootstrap/. - Layered structure: CRDs, controllers, configs, and applications are separated into their own kustomizations.
- Single-node cluster: One node is reliable enough for my use case and with GitOps, replacing hardware or rebuilding the cluster is fast enough. A multi-node cluster with distributed storage (like Longhorn) would be nice, but for current needs it would be overkill and expensive.
This homelab is built on two main layers: platform components that provide the foundation, and applications that run on top of it.
Core components that make the cluster run and provide the services needed to deploy and manage applications.
| Logo | Name | Capability / Role in this homelab |
|---|---|---|
 |
Talos | Immutable, secure-by-default Kubernetes operating system. |
 |
Flannel | CNI plugin providing basic pod networking across the cluster. |
| FluxCD | GitOps controller that reconciles the desired cluster state from this repository. | |
 |
cert-manager | Automates TLS certificate issuance and renewal, including Let’s Encrypt certificates via Cloudflare DNS validation. |
 |
External Secrets Operator | Synchronizes selected secrets from Azure Key Vault into Kubernetes Secrets. |
| SOPS | Encrypts and manages secrets and sensitive configuration data stored in Git. | |
| Kong Gateway | API Gateway configured via Gateway API resources using Kong Ingress Controller. | |
 |
MetalLB | LoadBalancer implementation for bare-metal Kubernetes clusters. |
 |
CloudNativePG | PostgreSQL operator manages database cluster lifecycle and automates backups to Azure Blob Storage via Barman Cloud. |
 |
Grafana K8s Monitoring | Helm chart (v4) deploying Grafana Alloy via the Alloy Operator to collect cluster metrics, logs, and traces — forwarded to Grafana Cloud |
Core services and experimental workloads deployed in the cluster.
| Name | Description |
|---|---|
| Authentik | IdP (Identity Provider) and SSO platform (system service). |
| Pi-hole | Network-wide ad blocking and local DNS resolver. |
| Homepage | Unified dashboard for services and bookmarks. |
| Jellyfin | Media system and streaming server. |
| Omada Software Controller | Software controller for TP-Link SDN. |
| SignalK | Open-source marine data platform for aggregating boat sensor data. |
Automation and validation tools used outside the cluster to keep the repository safer, more reliable, and up to date.
| Tool | Role in this homelab |
|---|---|
| GitHub Actions | Runs repository validation workflows such as GitOps checks and secret scanning. |
| Gitleaks | Scans the repository for accidentally committed secrets. |
| Renovate | Monitors dependencies and container image versions, then creates pull requests for updates. |
| git-filter-repo | Used to sanitize the repository before pushing it to public mirror. |
The platform consists of a local single-node Kubernetes cluster running on Talos Linux paired with cloud resources provisioned in Azure using Terraform.
Cloud Infrastructure Automation:
Local Hardware Specifications The cluster runs on a compact and power-efficient Mini PC:
| Component | Details |
|---|---|
| CPU | Intel N100 (4 cores) |
| Memory | 16 GB |
| Storage | Samsung EVO 860 1TB SATA |
| Hypervisor | Ubuntu 24.04 LTS |
| Guest OS | Talos |
This environment is a work in progress. Below are areas for potential future improvement.
| Area | Idea / Improvement |
|---|---|
| Disaster Recovery | Implement Velero for cluster state and PVs |
| Security | Implement network policies to restrict pod-to-pod traffic (requires replacing Flannel). |
A quick overview of the main directories and their purpose:
| Directory | Purpose |
|---|---|
clusters/ |
Environment-specific overlays for home-prod and home-dev. |
infrastructure/ |
Cluster infrastructure components (controllers and configs). |
apps/ |
Application definitions grouped per app. |
bootstrap/ |
Scripts and instructions to bootstrap a cluster from this repo. |
| Directory | Purpose |
|---|---|
talos/ |
Talos machine configurations for home-prod and home-dev. |
terraform/ |
Terraform configurations for Azure resources. |
This repository is a sanitized public snapshot of a private homelab repository. Only sensitive values are scrubbed before publishing:
- Domains → example.com
- Emails → user@example.com
- IPs → 198.51.100.x/24 (TEST-NET-2, for documentation)
Everything else — repository structure, manifests, and GitOps workflows — is identical to the original. Because the full history is rewritten on each release, the public mirror is a point-in-time snapshot rather than a continuously synchronized fork: clone it fresh, as incremental git fetch / git pull won't produce meaningful updates.
This repository is environment-specific and cannot be deployed as-is, but it can serve as a reference for building a GitOps-managed Kubernetes environment. Before using it as a base, you will need to customize various components to match your own environment.
Note: The following list is not exhaustive and serves as a set of examples of the primary areas that require adjustment:
- Cloud Infrastructure: Update Terraform variables and Azure resource naming.
- GitOps Bootstrap: Provide a GitHub PAT for the initial FluxCD bootstrapping process.
- Cluster Networking: Adjust MetalLB IP pools, service-specific static IPs, and your own DNS domain configuration.
- DNS & TLS: This setup assumes DNS is hosted via Cloudflare; you will need a valid Cloudflare API token for automated certificate management.
- Storage Layout: Update NFS server details, static PV paths, and Talos disk selectors.
- Secrets & Identity: Configure SOPS age keys and the Authentik identity layer.
- Environment Overlays: Review domain names, IPs, and secret mappings in the cluster-specific overlays.
For detailed step-by-step instructions on how to handle these customizations, and deploy the environment, please refer to the specialized guides below:
- Talos Cluster Setup – how the underlying Talos-based Kubernetes cluster is built
- Azure Resources Setup – how to provision Azure resources with Terraform
- FluxCD Bootstrap Guide – how GitOps deployment and reconciliation are initialized
This project is licensed under the MIT License.