Updated project to improve guidance

apps/headlamp/helmrelease.yaml

@@ -1,8 +1,9 @@
-# Deliberately no ingress here — the official Dashboard grants whatever the
-# logged-in identity can do, and a leaked cluster-admin token to a publicly
-# reachable Dashboard is a well-known real-world breach vector (see e.g. the
-# 2018 Tesla incident). Access is via `kubectl port-forward` only
-# (docs/SETUP.md step 12) — no standing hostname, no attack surface between
+# Deliberately no ingress here — Headlamp (like the Kubernetes Dashboard it
+# replaces, and like any cluster admin UI) grants whatever the logged-in
+# identity can do, and a leaked cluster-admin token to a publicly reachable
+# admin UI is a well-known real-world breach vector (see e.g. the 2018
+# Tesla incident). Access is via `kubectl port-forward` only
+# (docs/03-flux.md step 5) — no standing hostname, no attack surface between
 # sessions.
 apiVersion: helm.toolkit.fluxcd.io/v2
 kind: HelmRelease

apps/headlamp/helmrepository.yaml

@@ -1,3 +1,6 @@
+# Same role as apps/podinfo/helmrepository.yaml: just the chart index
+# source-controller polls, cached as an artifact for helmrelease.yaml to
+# install from.
 apiVersion: source.toolkit.fluxcd.io/v1
 kind: HelmRepository
 metadata:

apps/headlamp/kustomization.yaml

@@ -1,3 +1,5 @@
+# Inventory of this app's manifests — see apps/podinfo/kustomization.yaml
+# for why listed order here doesn't matter for apply ordering.
 apiVersion: kustomize.config.k8s.io/v1beta1
 kind: Kustomization
 resources:

apps/headlamp/rbac.yaml

@@ -1,5 +1,5 @@
 # Cluster-admin ServiceAccount + long-lived token, used both to log in to
-# the Dashboard (docs/SETUP.md step 12) and as the client identity for
+# Headlamp (docs/03-flux.md step 5) and as the client identity for
 # direct LAN kubectl access if you'd rather not manage the SSH-fetched
 # kubeconfig from step 6. Fine for a single-user homelab; split into
 # narrower-scoped accounts if more people get access later.

apps/hello-app/deployment.yaml

@@ -1,3 +1,7 @@
+# This app's own Deployment/Service/Ingress, hand-written rather than a
+# Helm chart (see README.md "Why it's structured this way") — there's no
+# upstream chart to track since the image is built by this repo's own CI
+# (.forgejo/workflows/build-hello-app.yml).
 apiVersion: apps/v1
 kind: Deployment
 metadata:
@@ -14,11 +18,16 @@ spec:
         app: hello-app
     spec:
       # Uncomment if the hello-app package is set to private in Forgejo
-      # (see docs/SETUP.md step 9).
+      # (see docs/03-flux.md step 6).
       # imagePullSecrets:
       #   - name: forgejo-registry
       containers:
         - name: hello-app
+          # Not a comment — this exact-format annotation is how Flux's
+          # image-automation "Setters" strategy (image-automation.yaml's
+          # ImageUpdateAutomation) finds this line and knows to rewrite the
+          # tag below in place, rather than needing this field templated.
+          # "hello-app:hello-app" is "<namespace>:<ImagePolicy name>".
           # {"$imagepolicy": "hello-app:hello-app"}
           image: git.boglabob.com/codegit/hello-app:latest
           ports:

apps/hello-app/kustomization.yaml

@@ -1,3 +1,5 @@
+# Inventory of this app's manifests — see apps/podinfo/kustomization.yaml
+# for why listed order here doesn't matter for apply ordering.
 apiVersion: kustomize.config.k8s.io/v1beta1
 kind: Kustomization
 resources:

apps/podinfo/helmrelease.yaml

@@ -1,13 +1,27 @@
+# First app in this repo, deliberately picked because it needs nothing
+# this project builds itself — no CI, no custom image, just a public chart
+# — so a green `flux get kustomization podinfo` here proves the whole
+# source-controller -> helm-controller -> cluster loop works before
+# hello-app adds a CI dependency on top of it.
 apiVersion: helm.toolkit.fluxcd.io/v2
 kind: HelmRelease
 metadata:
   name: podinfo
   namespace: podinfo
 spec:
+  # How often helm-controller re-checks this HelmRelease against the chart
+  # in helmrepository.yaml's cache and re-reconciles if they've drifted —
+  # independent of how often source-controller refreshes that cache (1h,
+  # see helmrepository.yaml).
   interval: 10m
   chart:
     spec:
       chart: podinfo
+      # A range, not a pin: helm-controller installs the latest version
+      # matching this constraint and re-installs on every new matching
+      # release the upstream chart repo publishes. Bump the lower bound by
+      # hand to move the floor forward; there's no CI here to do it
+      # automatically (contrast apps/hello-app's image automation).
       version: ">=6.0.0"
       sourceRef:
         kind: HelmRepository
@@ -17,9 +31,14 @@ spec:
     replicaCount: 1
     ingress:
       enabled: true
+      # k3s ships Traefik as its built-in ingress controller — this is
+      # its IngressClass name, not a choice made by this chart.
       className: traefik
       hosts:
         - host: podinfo.boglabob.com
           paths:
             - path: /
+              # Lets the chart's own Ingress template pick the matching
+              # type for its backend, rather than this repo asserting one
+              # (podinfo's chart uses this instead of a plain "Prefix").
               pathType: ImplementationSpecific

apps/podinfo/helmrepository.yaml

@@ -1,3 +1,7 @@
+# Declares where podinfo's chart index lives. On its own this does nothing
+# to the cluster — source-controller just fetches this URL every `interval`
+# and caches the resulting chart index as an artifact. helmrelease.yaml is
+# what actually asks for the chart to be installed.
 apiVersion: source.toolkit.fluxcd.io/v1
 kind: HelmRepository
 metadata:

apps/podinfo/kustomization.yaml

@@ -1,3 +1,10 @@
+# Plain kustomize, no patches/overlays — this just lists which files
+# belong to this app so `kustomize build apps/podinfo` (or Flux's own
+# `Kustomization` object of the same name in clusters/homelab/apps.yaml,
+# pointed at this directory) has one thing to apply. Order matters only in
+# that namespace.yaml has to exist before objects that reference it, but
+# kubectl/kustomize sort by kind anyway, so this is really just an
+# inventory.
 apiVersion: kustomize.config.k8s.io/v1beta1
 kind: Kustomization
 resources: