Homelab

A definitely over-engineered, but good enough homelab that handles my home infrastructure and Kubernetes cluster.

Purpose

I had two goals in mind for this homelab:

1. Learn and implement enterprise-grade systems and patterns
2. Repurpose old hardware

Features

A Kubernetes cluster deployed with Talos Linux and ArgoCD using GitHub as the Git provider, 1Password to manage secrets and Tailscale as the primary way for application access.

This repository is managed by mise and pre-commit to ensure a standardized environment, alongside Renovate to automate dependency management.

Task and gomplate are used to generate Kubernetes manifests and Terragrunt HCL files for values to be centrally managed and easily modifiable.

Core Components:

• argocd
• cilium
• coredns
• external secrets
• grafana
• kubelet-serving-cert-approver
• local-path-provisioner
• metrics server
• prometheus
• reloader
• tailscale kubernetes operator
• tsidp

ArgoCD

ArgoCD is the GitOps platform for my homelab and is deployed using Kustomize and Helm.

The ApplicationSet in kubernetes/overlays/homelab/prod/argo/argocd/homelab-applicationset.yaml generates all ArgoCD Applications and must be defined there.

Terragrunt

Talos Linux is managed with Terragrunt using the official Talos Linux Terraform provider.

The talos Terraform module contains config patches that are taken from either the official Talos Linux documentation, onedr0p/cluster-template, ajaykumar4/cluster-template or specifically added for my homelab.

The talos stack bootstraps the Talos Linux instance, saves the kubeconfig and talosconfig files using hooks, then creates resources to prepare the kubernetes cluster for deployments.

Tailscale

Tailscale is used as the VPN to connect my devices and applications together. The tailscale kubernetes operator allows my devices to access services within the kubernetes cluster, so that nothing is exposed to the public.

As Tailscale can be used to authenticate users, tsidp acts as the identity provider for any application that allows for SSO.

Deploying the Cluster

Requirements

Environment Variables

Name	Description
AWS_ACCESS_KEY_ID	AWS Access Key ID
AWS_SECRET_ACCESS_KEY	AWS Secret Access Key
GRAFANA_AUTH	Grafana Service Account Token
GRAFANA_URL	Grafana URL
KUBECONFIG	Kubernetes Config File Path
OP_SERVICE_ACCOUNT_TOKEN	1Password Service Account Token
TALOSCONFIG	Talos Linux Config File Path
TG_BUCKET	AWS S3 Bucket Name for Terraform Backend

1Password Secrets

Name	Description
argocd-ssh	ArgoCD SSH Credentials for GitHub Access
op-sa-kubernetes-token	1Password Kubernetes Service Account Token
tailscale-kubernetes-operator	Tailscale Kubernetes Operator Credentials
tsidp-*	Tailscale IDP Client Credentials

Procedure

0. Fill out clusters.yaml and run task template:generate to generate all templated files.
1. Run terragrunt stack generate in terraform/homelab/prod/talos to generate the stack files.
2. Run terragrunt apply in terraform/homelab/prod/talos/generated/.terragrunt-stack/talos/.terragrunt-stack/talos once the Talos Linux instance is waiting to be bootstrapped.
   • This will create a homelab-prod.kubeconfig and homelab-prod.talosconfig in the repository's root level.
3. Once the Talos Linux instance reboots, run task kubernetes:build-apply in kubernetes/bases/namespaces to create the required namespaces.
4. Run terragrunt stack run apply in terraform/homelab/prod/talos to finish the rest of the Talos Linux deployment.
5. Run task kubernetes:build-apply in kubernetes/overlays/homelab/prod/kube-system/coredns to install CoreDNS.
6. Run task kubernetes:build-apply in kubernetes/overlays/homelab/prod/kube-system/cilium to install Cilium.
7. Run task kubernetes:build-apply in kubernetes/overlays/homelab/prod/cluster-services/kubelet-serving-cert-approver to install kubelet-serving-cert-approver.
8. Run task kubernetes:build-apply in kubernetes/overlays/homelab/prod/cluster-services/local-path-provisioner to install local-path-provisioner.
9. Run task kubernetes:build-apply in kubernetes/overlays/homelab/prod/cluster-services/external-secrets to install External Secrets.
10. Run task kubernetes:build-apply in kubernetes/overlays/homelab/prod/tailscale/tailscale-operator to install Tailscale Kubernetes Operator.
11. Run task kubernetes:build-apply in kubernetes/overlays/homelab/prod/tailscale/tsidp to install tsidp.
12. Update clusters.yaml with the new ts-dns nameserver IP address.
13. Run task kubernetes:build-apply in kubernetes/overlays/homelab/prod/argo/argocd to install ArgoCD and all other applications.

Directories

This repository uses the following directory structure that are strictly followed:

configs/                            # reusable config files
docs/                               # documentation
kubernetes/
├─ bases/                           # kustomize bases
│  ├─ applications/
├─ overlays/                        # kustomize overlays
│  ├─ cluster/
│  │  ├─ environment/
│  │  │  ├─ namespace/
│  │  │  │  ├─ applications/
│  │  │  │  │  ├─ generated/        # generated files
terraform/
├─ _modules/                        # terraform modules
├─ _stacks/                         # terragrunt stacks
├─ _units/                          # terragrunt units
├─ platform/
│  ├─ region/
│  │  ├─ applications/
│  │  │  ├─ generated/              # generated files

Hardware

Device	Specs	OS	Function
Desktop - proxmox	AMD Ryzen 5 5600X, 64GB RAM	Proxmox VE	Hypervisor
Linksys Velop	-	-	Access Points
UniFi Cloud Gateway Ultra	-	-	Router and Firewall

Node	Specs	OS	Host	Function
VM - homelab	6 CPU, 40GB RAM	Talos Linux	proxmox	Control Plane Node

Goals

• Use Terragrunt Stacks
• Argo Events to handle Webhooks
• Argo Workflows for CI/CD
• Setup Monitoring and Alerts for all Services
• Setup Homelab Development Cluster
• Setup Kargo
• Setup a NAS

Thanks

This repo is heavily based on the work of onedr0p/cluster-template and ajaykumar4/cluster-template. I highly recommend taking a look at those repos if you're interested in setting up a homelab of your own.