homelab-starter/infrastructure

Infrastructure

Core cluster services that apps depend on. These are installed before any apps via Flux dependsOn ordering.

Dependency Chain

MetalLB Install ──▶ MetalLB Config ──▶ Traefik Install ──▶ Routes
                                                              │
Cert-Manager Install ──▶ Cert-Manager Issuer                  │
                                                              │
                                              Apps depend on ─┘

Components

Directory	What it does
metallb-install/	Installs MetalLB via Helm — gives LoadBalancer services real LAN IPs
metallb-config/	Configures the IP address pool and L2 advertisement
traefik-install/	Installs Traefik via Helm — reverse proxy and ingress controller
cert-manager-install/	Installs cert-manager via Helm — automates TLS certificate provisioning
cert-manager-issuer/	Configures Let's Encrypt ClusterIssuer with DNS-01 challenge
routes/	Traefik IngressRoutes — one file per app defining how traffic reaches it

How Helm Releases Work Here

Each Helm-based service follows the same pattern:

1. HelmRelease (helmrelease.yaml) — Points to a chart and version from a HelmRepository defined in bootstrap/repositories/
2. ConfigMap override (*-override.yaml) — Contains chart values as a YAML string under data.values.yaml. Referenced via valuesFrom in the HelmRelease.

This pattern keeps chart values separate from the release definition, making them easier to review and modify.

Adding a New Infrastructure Service

1. Create a HelmRepository in bootstrap/repositories/ (if the chart source is new)
2. Create a directory under infrastructure/ (e.g. infrastructure/my-service-install/)
3. Add a helmrelease.yaml and optionally a ConfigMap override
4. Create a Flux Kustomization in bootstrap/kustomization/infrastructure/ pointing to your new directory
5. Set dependsOn appropriately (most infra services should depend on MetalLB being configured)
6. Commit and push — Flux handles the rest

Adding SOPS Secret Encryption

The cert-manager-issuer/secret.yaml file currently contains a plain-text secret. To encrypt it:

1. Install age and generate a key pair
2. Create a .sops.yaml at the repo root with creation rules for your paths
3. Encrypt secret files: sops --encrypt --in-place infrastructure/cert-manager-issuer/secret.yaml
4. Add spec.decryption to the relevant Flux Kustomizations in bootstrap/kustomization/
5. Create a sops-age Secret in flux-system namespace with your age private key

See the Flux SOPS guide for full instructions.