---
# WORKED EXAMPLE (reference only — NOT wired into a kustomization, never deployed).
# Rendered from catalog/pihole.yaml's `update` block by WS-GITOSS into apps/pihole/. Shows the exact
# ImageRepository + ImagePolicy + Deployment setter-marker shape for a container ServiceDefinition.
#
#   update:
#     channel: stable
#     range: ">=2024.0.0"
#     cadence: "0 4 * * *"
#     autoRollbackOnFailedHealth: true
#
# See ./README.md for the field-by-field contract.
# ---------------------------------------------------------------------------------------------------
apiVersion: image.toolkit.fluxcd.io/v1
kind: ImageRepository
metadata:
  name: pihole
  namespace: pihole
spec:
  image: pihole/pihole            # from source.image
  interval: 6h                    # scan schedule; nearest Flux duration to cadence "0 4 * * *" (daily-ish)
  # provider: generic             # dockerhub anon; a pull secret goes here if registry rate-limits bite
---
apiVersion: image.toolkit.fluxcd.io/v1
kind: ImagePolicy
metadata:
  name: pihole
  namespace: pihole
spec:
  imageRepositoryRef:
    name: pihole
  # STABLE-ONLY (R-UPD-01): (1) semver range from `update.range`; (2) a tag filter that admits only
  # bare X.Y.Z releases so a pre-release / `latest` / date-nightly tag can never be selected.
  filterTags:
    pattern: '^v?(?P<v>[0-9]+\.[0-9]+\.[0-9]+)$'
    extract: '$v'
  policy:
    semver:
      range: '>=2024.0.0'
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: pihole
  namespace: pihole
spec:
  replicas: 1
  # progressDeadlineSeconds bounds a bad rollout so the health gate (readiness probe) can catch it and
  # the old ReplicaSet keeps serving — the plain-Deployment auto-rollback path (R-UPD-03). A
  # HelmRelease-delivered service would instead use spec.upgrade.remediation + spec.rollback.
  progressDeadlineSeconds: 120
  selector:
    matchLabels: { app: pihole }
  template:
    metadata:
      labels: { app: pihole }
    spec:
      containers:
        - name: pihole
          # THE SETTER MARKER: image-automation writes the ImagePolicy-resolved stable tag here.
          # No human/AI ever edits this tag — the marker binds it to the pihole ImagePolicy above.
          image: pihole/pihole:2024.7.0 # {"$imagepolicy": "pihole:pihole"}
          readinessProbe:               # the health gate: a bad image never becomes Ready
            httpGet: { path: /admin/, port: 80 }
            initialDelaySeconds: 10
            periodSeconds: 5
---
# PINNED VARIANT (R-UPD-03 escape hatch) — what the SAME service renders when `update.pin: "2024.7.0"`
# is set: the image is fixed, the setter marker is ABSENT, and NO ImagePolicy/ImageRepository is
# rendered (or it is suspended). Automation cannot advance it. This is the one sanctioned human touch,
# and it STOPS automation rather than performing an update.
#
#   containers:
#     - name: pihole
#       image: pihole/pihole:2024.7.0   # pinned — no $imagepolicy marker; automation is frozen