Homelab Kubernetes Cluster

This repository contains the GitOps configuration for my homelab Kubernetes cluster. It's powered by Flux and Talos Linux

🛠 Core Components

• Talos Linux: Immutable K8s-focussed operating system.
• Flux: GitOps.
• actions-runner-controller: Self-hosted Github runners.
• cert-manager: Creates SSL certificates for services in my cluster.
• cilium: Internal Kubernetes container networking interface.
• cloudflared: Enables Cloudflare secure access to certain ingresses.
• external-dns: Automatically syncs ingress DNS records to a DNS provider.
• external-secrets: Managed Kubernetes secrets using 1Password Connect.
• ingress-nginx: Kubernetes ingress controller using NGINX as a reverse proxy and load balancer.
• rook: Distributed block storage for peristent storage.
• sops: Managed secrets for Kubernetes and Terraform which are commited to Git.
• spegel: Stateless cluster local OCI registry mirror.
• volsync: Backup and recovery of persistent volume claims.

How the cluster works

GitOps

Flux watches the clusters in my kubernetes folder (see Directories below) and makes the changes to the cluster based on the state of this Git repository.

The way Flux works for me here is it will recursively search the kubernetes/${cluster}/apps folder until it finds the most top level kustomization.yaml per directory and then apply all the resources listed in it. That aforementioned kustomization.yaml will generally only have a namespace resource and one or many Flux kustomizations (ks.yaml). Under the control of those Flux kustomizations there will be a HelmRelease or other resources related to the application which will be applied.

Renovate watches my entire repository looking for dependency updates, when they are found a PR is automatically created. When some PRs are merged Flux applies the changes to my cluster.

📂 Directories

📁 .taskfiles           # Task files for various operations
📁 kubernetes           # Main Kubernetes configurations
└─📁 main               # Main cluster configurations
  ├─📁 apps             # Application deployments
  ├─📁 bootstrap        # Cluster bootstrap configurations
  ├─📁 flux             # Flux system configurations
  └─📁 templates        # Templates for volsync and gatus

Flux Workflow

This is a high-level look how Flux deploys my applications with dependencies. Below there are 3 Flux kustomizations postgres, postgres-cluster, and atuin. postgres is the first app that needs to be running and healthy before postgres-cluster and once postgres-cluster is healthy atuin will be deployed.

graph TD;
  id1>Kustomization: cluster] -->|Creates| id2>Kustomization: cluster-apps];
  id2>Kustomization: cluster-apps] -->|Creates| id3>Kustomization: postgres];
  id2>Kustomization: cluster-apps] -->|Creates| id5>Kustomization: postgres-cluster]
  id2>Kustomization: cluster-apps] -->|Creates| id8>Kustomization: atuin]
  id3>Kustomization: postgres] -->|Creates| id4[HelmRelease: postgres];
  id5>Kustomization: postgres-cluster] -->|Depends on| id3>Kustomization: postgres];
  id5>Kustomization: postgres-cluster] -->|Creates| id10[Postgres Cluster];
  id8>Kustomization: atuin] -->|Creates| id9(HelmRelease: atuin);
  id8>Kustomization: atuin] -->|Depends on| id5>Kustomization: postgres-cluster];

Loading

🤝 Acknowledgements

This project is inspired by the Home Operations Discord community and the flux-cluster-template. Have a look at kubesearch.dev to see how other people are deploying things!