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]>

bootstrap/flux/bootstrap.sh

@@ -11,7 +11,17 @@
 # WHAT THIS DOES (Phase 1, bootstrap-source method — reconciles from the LOCAL repo, no remote
 # git host exists yet per spec docs/05 + CONTRIBUTING.md):
 #
-#   1. `flux install`   — deploy the Flux controllers ONLY (source, kustomize, helm controllers).
+#   1. `flux install`   — deploy the Flux controllers. Besides the default set (source, kustomize,
+#                         helm, notification) we ALSO install the two IMAGE controllers via
+#                         `--components-extra` (see FLUX_COMPONENTS_EXTRA below): image-reflector-
+#                         controller + image-automation-controller. These register the
+#                         image.toolkit.fluxcd.io CRDs (ImageRepository/ImagePolicy/ImageUpdateAutomation)
+#                         that Phase-4 hands-off updates need (ADR-0009, R-UPD-02). They are part of the
+#                         flux-system install exactly like the other 4 controllers — NOT a reconciled
+#                         HelmRelease — so their CRDs pre-exist before the first reconcile (this is why
+#                         platform/image-automation can carry the ImageUpdateAutomation CR without the
+#                         F-MON1 controllers/configs split: the CRD is present at bootstrap, like
+#                         GitRepository/Kustomization are). WS-UPDATE (T-4.5).
 #                         We do NOT use `flux bootstrap git` in Phase 1 because that command commits
 #                         and OWNS its own gotk-sync GitRepository+Kustomization named `flux-system`.
 #                         Our entrypoints are ALREADY authored in clusters/base (flux-system.yaml =
@@ -42,6 +52,9 @@ set -euo pipefail
 FLUX_ENV_PATH="${FLUX_ENV_PATH:-clusters/dev}"     # dev is the ONLY Phase-1 build target
 FLUX_NAMESPACE="${FLUX_NAMESPACE:-flux-system}"
 SOPS_SECRET_NAME="${SOPS_SECRET_NAME:-sops-age}"
+# The two Phase-4 image-automation controllers are installed alongside the default set so their CRDs
+# exist before reconcile (ADR-0009, R-UPD-02). Override to "" to build a cluster without them.
+FLUX_COMPONENTS_EXTRA="${FLUX_COMPONENTS_EXTRA:-image-reflector-controller,image-automation-controller}"
 
 script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 repo_root="$(git -C "${script_dir}" rev-parse --show-toplevel 2>/dev/null || cd "${script_dir}/../.." && pwd)"
@@ -54,8 +67,16 @@ for bin in flux kubectl; do
 done
 
 # --- 1. install Flux controllers ---------------------------------------------
-echo "==> [1/3] flux install (controllers only)"
-flux install --namespace="${FLUX_NAMESPACE}"
+# Default controllers + the image-reflector/image-automation pair (Phase-4 hands-off updates,
+# ADR-0009). `--components-extra` regenerates flux-system with all controllers and registers the
+# image.toolkit.fluxcd.io CRDs before any reconcile — so platform/image-automation's CR applies cleanly.
+if [ -n "${FLUX_COMPONENTS_EXTRA}" ]; then
+  echo "==> [1/3] flux install (default controllers + extra: ${FLUX_COMPONENTS_EXTRA})"
+  flux install --namespace="${FLUX_NAMESPACE}" --components-extra="${FLUX_COMPONENTS_EXTRA}"
+else
+  echo "==> [1/3] flux install (default controllers only)"
+  flux install --namespace="${FLUX_NAMESPACE}"
+fi
 
 # --- 2. verify the out-of-band age key Secret exists -------------------------
 # We DO NOT create it here (it holds the private key). The operator installs it per