Initial commit

infrastructure/README.md

@@ -0,0 +1,54 @@
+# 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](https://github.com/FiloSottile/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](https://fluxcd.io/flux/guides/mozilla-sops/) for full instructions.