feat(updates): install Flux image controllers + cluster-wide write-back engine (R-UPD-02)

Install image-reflector-controller + image-automation-controller as part of the
flux-system install (bootstrap.sh --components-extra) so the image.toolkit CRDs
pre-exist before reconcile — no F-MON1 split needed for the ImageUpdateAutomation CR.
Refine the cluster-wide ImageUpdateAutomation for machine-authored git write-back
(setter strategy, path ./apps) reusing the flux-system GitRepository secretRef, and
document the operator git-write-credential hand-off + SOPS secret template
(gitea-image-automation-credentials). image-automation stays deferred in
platform/kustomization.yaml until that credential is provisioned.

Co-Authored-By: Claude Opus 4.8 <[email protected]>

platform/image-automation/image-update-automation.yaml

@@ -1,39 +1,57 @@
 ---
 # Flux image-update-automation — the CLUSTER-WIDE write-back engine for hands-off image tag advances
-# (ADR-0009, R-UPD-02). It scans registries per each service's ImagePolicy and commits the resolved
-# version back to git — no human/AI authors the bump. Phase 0 STUB.
+# (ADR-0009, R-UPD-02). image-reflector-controller scans each per-service ImageRepository on its
+# interval; image-automation-controller resolves each ImagePolicy and writes the advanced tag back to
+# git at the `# {"$imagepolicy": "..."}` setter markers. The commit is MACHINE-authored under the
+# operator's once-declared policy — no human/AI edits a tag (R-UPD-01/02).
 #
-# SCOPE: this dir holds ONLY the cluster-wide ImageUpdateAutomation + git write-back settings.
-# Per-service `ImageRepository`/`ImagePolicy` are rendered from each ServiceDefinition's `update`
-# block (WS-GITOPS/WS-UPDATE) and live with apps/ — NOT here. (Contract: roadmap/workstreams.md
-# "Update policy contract".)
+# SCOPE (contract, roadmap/workstreams.md "Update policy contract"): this dir holds ONLY the
+# cluster-wide ImageUpdateAutomation + git write-back settings. PER-SERVICE ImageRepository/ImagePolicy
+# are rendered from each ServiceDefinition's `update` block (renderer-contract §update) and live NEXT
+# TO each app's Deployment/HelmRelease under apps/ — see ./per-service/ for the render contract + a
+# worked example. Helm CHART / dependency bumps are Renovate's job (renovate.json), not this controller.
+#
+# CONTROLLERS: image-reflector-controller + image-automation-controller are installed as part of the
+# flux-system install (bootstrap/flux/bootstrap.sh `--components-extra`), so the image.toolkit CRDs
+# pre-exist before reconcile — this CR applies cleanly without the F-MON1 controllers/configs split
+# (the CRD is present at bootstrap, exactly like GitRepository/Kustomization are). See README.md.
 apiVersion: image.toolkit.fluxcd.io/v1beta2
 kind: ImageUpdateAutomation
 metadata:
   name: flux-image-automation
   namespace: flux-system
 spec:
-  interval: 30m                 # the "schedule" on which stable versions are picked up (R-UPD-02)
+  # The scan/apply schedule (R-UPD-02). image-reflector scans registries continuously per
+  # ImageRepository.spec.interval; this interval bounds how often resolved tags are written back.
+  interval: 30m
   sourceRef:
     kind: GitRepository
     name: flux-system
+    # ^ Write-back auth REUSES this GitRepository's `.spec.secretRef` (image-automation-controller has
+    #   no independent secretRef). The Phase-1 flux-system source is currently anonymous/read-only
+    #   (public host-Gitea clone). For write-back the operator must attach a WRITE credential to the
+    #   flux-system GitRepository — see README.md "Operator hand-off: git write credential" and the
+    #   SOPS template bootstrap/sops/secret-templates/gitea-image-automation-credentials.yaml.example.
   git:
     checkout:
       ref:
-        branch: main            # TODO(WS-UPDATE): confirm write-back branch (may open PRs instead)
+        branch: main            # reconciled branch (matches clusters/base/flux-system.yaml)
     commit:
       author:
-        name: fluxcdbot         # machine author — the auditable, intended write-back (ADR-0009)
+        # Machine author — the auditable, intended write-back (ADR-0009). No human/AI authors the bump.
+        name: fluxcdbot
         email: [email protected]
       messageTemplate: |
-        chore(images): automated update
+        chore(images): automated stable update [ci skip]
 
-        Machine-authored image tag advance per ImagePolicy (R-UPD-02, ADR-0009).
+        Machine-authored image tag advance under the declared per-service ImagePolicy
+        (R-UPD-01 stable-only, R-UPD-02 no human/AI authoring). ADR-0009.
+        {{ range .Changed.Changes -}}
+        - {{ .OldValue }} -> {{ .NewValue }} ({{ .Setter }})
+        {{ end -}}
     push:
-      branch: main
+      branch: main             # push straight to the tracked branch (default write-back strategy,
+                               # ADR-0009). Renovate handles PR-style bumps for charts/deps separately.
   update:
-    strategy: Setters           # image-automation setter markers in per-service manifests (apps/)
-    path: ./apps
-# TODO(WS-UPDATE, Phase 4): safety rails are acceptance gates (ADR-0009) — stable-only, health-gated
-#   rollout, auto-rollback on failed health, pin escape hatch, alert on update failure. Prove a test
-#   service auto-advances with no human/AI edit; a bad update auto-rolls-back + alerts (R-UPD-01/02/03).
+    strategy: Setters          # advance the `$imagepolicy` setter markers in per-service manifests
+    path: ./apps               # only apps/ carries per-service image markers (platform charts = Renovate)