giantswarm · teemow · Sep 21, 2026 · Sep 21, 2026
@@ -9,6 +9,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- The agentgateway controller runs the Giant Swarm line's release `2.0.0` under its nested name, `gsoci.azurecr.io/giantswarm/agentgateway-upstream/controller:2.0.0`, named in full (repository and tag) in the meta chart's `agentgateway` block and mirrored in the connectivity chart; `agentgateway.proxy.image`, the controller's default data plane, names `gsoci.azurecr.io/giantswarm/agentgateway-upstream/agentgateway:2.0.0` the same way, and `components.agentgateway.versionRange` is `>=2.2.2 <3.0.0` (was `2.x`), floored at the packaging release that renders a bare `X.Y.Z` tag as written. Packaging chart 2.3.0 moved its image defaults to the nested names while this chart still overrode `controller.image.repository` with the flattened `giantswarm/agentgateway-controller`; a value wins over a chart default, the render became `agentgateway-controller:2.0.0`, a tag that exists only under the nested name, and every installation on this line rolled back to 2.2.2 (`Ready=False`, `RetriesExceeded`). The meta chart forwards the block to the connectivity release, whose `AgentgatewayParameters` render `agentgateway.proxy.image` into every data plane, so the data planes move to the same release (a rolling restart of the edge); the connectivity chart's own defaults mirror the pin. 2.0.0 is built from the upstream pin (`main@c1d24607`) the fleet's `v1.5.1-gs.4` controller already ran. `examples/customer-bom.yaml` pins `2.2.2`.
+
 - `agent-manager.agentChart.semver` is `>=0.2.1 <1.0.0` (was `x.x.x`) in both charts. Generic `agent` chart 1.0.0 (published 2026-09-11) renders the kagent API v2 shape (`kagent.dev/v1alpha3 AgentTemplate`), which no 3.x installation can install; agent-manager composes this range into the per-namespace `agent` `OCIRepository` it writes on every `create_agent`, and the meta chart's explicit forward wins over agent-manager 0.4.5's own bounded default — so an open range here pulled 1.0.0 into every new managed namespace (the ATS round trip on this branch reproduced it: `HelmRelease ats-managed-agent` InstallFailed `no matches for kind AgentTemplate`). The three pre-existing per-namespace `OCIRepository` objects were bounded by hand already; this makes every future one bounded too. **Every installation with agent-manager on rolls the agent-manager pod once** (`--agent-chart-semver` changes); nothing else in the render differs. The 4.0 line moves the range to `1.x`.
 
 ### Changed

@@ -44,10 +44,14 @@ KYVERNO_ALL := $(VM) --set components.kagent.enabled=true --set components.agent
 # selector.
 # kagent.namespaceOverride=default (the release namespace of `helm template t`) drops the kagent Namespace object from both renders: this branch
 # keeps it (helm.sh/resource-policy: keep), an intended difference to GOLDEN_REF; every other kagent object renders alike on both sides.
-KYVERNO_GOLDEN := $(VM) --set components.kagent.enabled=true --set networkPolicy.flavor=kubernetes --set kagent.fluxServiceAccountName= --set muster.muster.oauth.server.enabled=false --set kagent.serviceMonitor.enabled=false --set kagent.namespaceOverride=default
+# The fifth intended change is the data plane's image, the agentgateway line's release under its nested name (the meta chart forwards the pin, verify-agentgateway-wiring asserts it): both sides render with it set.
+KYVERNO_GOLDEN := $(VM) --set components.kagent.enabled=true --set networkPolicy.flavor=kubernetes --set kagent.fluxServiceAccountName= --set muster.muster.oauth.server.enabled=false --set kagent.serviceMonitor.enabled=false --set kagent.namespaceOverride=default --set agentgateway.proxy.image.repository=giantswarm/agentgateway-upstream/agentgateway --set agentgateway.proxy.image.tag=2.0.0
 # GOLDEN_REF's chart reads the same component toggle, so both sides render alike.
 KYVERNO_GOLDEN_REF := $(KYVERNO_GOLDEN)
-GOLDEN_REF ?= origin/main
+# On the 3.x maintenance line the golden is the line's own head: origin/main
+# is the kagent API v2 line (4.x) since 2026-09-11 and no longer renders this
+# chart's default shape.
+GOLDEN_REF ?= origin/release-v3.x
 # Any reference is enough: the assertions read the rendered exception, not the image.
 PGVECTOR_IMG := gsoci.azurecr.io/giantswarm/pgvector:0.8.2-18-bookworm
 
@@ -354,7 +358,7 @@ verify-meta: ## Assert the app-of-apps meta-package render (pure renderer with t
 	@echo "ok: flux render"
 	@echo "--> agentgateway 2.x wiring: forwarded values are FLAT and carry no umbrella-only key"
 	@./tests/verify-agentgateway-wiring.py /tmp/ap-flux.out
-	@grep -q 'semver: "2.x"' /tmp/ap-flux.out || { echo "FAIL: agentgateway range is not 2.x (the flattened chart line)"; exit 1; }
+	@grep -q 'semver: ">=2.2.2 <3.0.0"' /tmp/ap-flux.out || { echo "FAIL: agentgateway range is not >=2.2.2 <3.0.0 (the flattened chart line, floored at the packaging release that renders a bare image tag as written)"; exit 1; }
 	@echo "ok: agentgateway 2.x wiring"
 	@echo "--> kagent flattened-chart wiring (0.2.0+): forwarded values are FLAT and carry no umbrella-only key"
 	@./tests/verify-kagent-wiring.py /tmp/ap-flux.out

@@ -2,6 +2,15 @@
 
 Operator action required between releases. CHANGELOG.md captures the diff; UPGRADE.md captures what an operator has to *do*.
 
+## \<current\> → \<next\> (the agentgateway controller at the line's release 2.0.0)
+
+The meta chart names the agentgateway line's release in full — `agentgateway.controller.image` `giantswarm/agentgateway-upstream/controller:2.0.0`, `agentgateway.proxy.image` `giantswarm/agentgateway-upstream/agentgateway:2.0.0` — and `components.agentgateway.versionRange` is `>=2.2.2 <3.0.0`.
+
+- **None** for an installation on the defaults: the `agentgateway` HelmRelease leaves `Ready=False RetriesExceeded` and upgrades to packaging chart 2.3.0 with `gsoci.azurecr.io/giantswarm/agentgateway-upstream/controller:2.0.0` (the upstream pin the `v1.5.1-gs.4` controller ran), and every data plane rolls onto `gsoci.azurecr.io/giantswarm/agentgateway-upstream/agentgateway:2.0.0` — a rolling restart of the edge, a quiet window of seconds.
+- **`agentgateway.controller.image` or `agentgateway.proxy.image` set in your values** (a mirror): name the nested paths `giantswarm/agentgateway-upstream/{controller,agentgateway}` and the bare tag `2.0.0` — the flattened `giantswarm/agentgateway-controller` and `giantswarm/agentgateway` carry the retagger's copies of upstream's releases only, never the line's.
+- **A BOM pin** (`components.agentgateway.versionRange` below `2.2.2`): pin `2.2.2` or higher (`examples/customer-bom.yaml`); an older packaging release prefixes a `v` to the bare tag.
+- **Recognising it worked**: `kubectl -n <gitops namespace> get helmrelease agentgateway` is `Ready=True` on `agentgateway@2.3.0` or later, and `kubectl -n <release namespace> get deploy agentgateway-controller -o jsonpath='{.spec.template.spec.containers[0].image}'` prints `gsoci.azurecr.io/giantswarm/agentgateway-upstream/controller:2.0.0`; the data-plane pods (`kubectl -n <release namespace> get pods -l gateway.networking.k8s.io/gateway-name -o jsonpath='{.items[*].spec.containers[0].image}'`) run `gsoci.azurecr.io/giantswarm/agentgateway-upstream/agentgateway:2.0.0`.
+
 ## \<current\> → \<next\> (kagent follows the wrapper's 0.x line)
 
 `components.kagent.versionRange` is `>=0.2.0 <1.0.0` (was `0.2.x`): the floor stays at the flattened chart the wiring needs, the ceiling moves to the next major, as for the other 0.x components. The `giantswarm/kagent` wrapper released 0.3.0 and 0.3.1 on 2026-09-09 from CI-only changes — a `feat(ci)` title is a minor bump to git-cliff — with a chart identical to 0.2.2 in templates, values and dependencies; the minor-holding range excluded them, and would have excluded every following wrapper release, the next fix included.

@@ -542,11 +542,11 @@ On the installation, after the cutover:
 | klausGateway.agentgatewayRoute.hostname | string | `""` |  |
 | agentgateway.fullnameOverride | string | `"agentgateway-controller"` |  |
 | agentgateway.image.registry | string | `"gsoci.azurecr.io"` |  |
-| agentgateway.image.tag | string | `"v1.2.1"` |  |
-| agentgateway.controller.image.repository | string | `"giantswarm/agentgateway-controller"` |  |
+| agentgateway.controller.image.repository | string | `"giantswarm/agentgateway-upstream/controller"` |  |
+| agentgateway.controller.image.tag | string | `"2.0.0"` |  |
 | agentgateway.proxy.image.registry | string | `"gsoci.azurecr.io"` |  |
-| agentgateway.proxy.image.repository | string | `"giantswarm/agentgateway"` |  |
-| agentgateway.proxy.image.tag | string | `"v1.5.1-gs.1"` |  |
+| agentgateway.proxy.image.repository | string | `"giantswarm/agentgateway-upstream/agentgateway"` |  |
+| agentgateway.proxy.image.tag | string | `"2.0.0"` |  |
 | agentgateway.podAnnotations."application.giantswarm.io/team" | string | `"bumblebee"` |  |
 | agentgateway.podSecurityContext.runAsNonRoot | bool | `true` |  |
 | agentgateway.podSecurityContext.seccompProfile.type | string | `"RuntimeDefault"` |  |

@@ -1403,20 +1403,23 @@ agentgateway:  # @schema skipProperties: true; additionalProperties: true
   fullnameOverride: agentgateway-controller
   image:
     registry: gsoci.azurecr.io
-    tag: v1.2.1
+  # One release of the Giant Swarm line of agentgateway
+  # (github.com/giantswarm/agentgateway-upstream; FORK.md there is the ledger
+  # of pin and patches), the line's own stable semver under its nested names
+  # on gsoci. proxy.image is what this chart renders into the
+  # AgentgatewayParameters of every data plane it declares, repository and
+  # tag in full; controller.image mirrors the meta chart's block, which the
+  # agentgateway release runs and which the meta chart forwards here over
+  # these defaults. Move both together.
   controller:
     image:
-      repository: giantswarm/agentgateway-controller
+      repository: giantswarm/agentgateway-upstream/controller
+      tag: "2.0.0"
   proxy:
     image:
       registry: gsoci.azurecr.io
-      repository: giantswarm/agentgateway
-      # A release of the Giant Swarm line of agentgateway
-      # (github.com/giantswarm/agentgateway-upstream, FORK.md: upstream v1.5.0
-      # rebuilt, scanned and signed there, mirrored into gsoci by the retagger)
-      # — the same release the giantswarm/agentgateway packaging chart pins for
-      # the controller; move both together.
-      tag: v1.5.1-gs.1
+      repository: giantswarm/agentgateway-upstream/agentgateway
+      tag: "2.0.0"
   podAnnotations:
     application.giantswarm.io/team: bumblebee
   podSecurityContext:

@@ -69,7 +69,7 @@ README.
 | components.muster.crds | string | `"CreateReplace"` |  |
 | components.agentgateway.chart | string | `"agentgateway"` |  |
 | components.agentgateway.repository | string | `"oci://gsoci.azurecr.io/charts/giantswarm"` |  |
-| components.agentgateway.versionRange | string | `"2.x"` |  |
+| components.agentgateway.versionRange | string | `">=2.2.2 <3.0.0"` |  |
 | components.agentgateway.valuesFrom | string | `"agentgateway"` |  |
 | components.agentgateway.enabled | bool | `false` |  |
 | components.agentgateway.crds | string | `"CreateReplace"` |  |
@@ -617,9 +617,11 @@ README.
 | klausGateway.agentgatewayRoute.hostname | string | `""` |  |
 | agentgateway.fullnameOverride | string | `"agentgateway-controller"` |  |
 | agentgateway.image.registry | string | `"gsoci.azurecr.io"` |  |
-| agentgateway.controller.image.repository | string | `"giantswarm/agentgateway-controller"` |  |
+| agentgateway.controller.image.repository | string | `"giantswarm/agentgateway-upstream/controller"` |  |
+| agentgateway.controller.image.tag | string | `"2.0.0"` |  |
 | agentgateway.proxy.image.registry | string | `"gsoci.azurecr.io"` |  |
-| agentgateway.proxy.image.repository | string | `"giantswarm/agentgateway"` |  |
+| agentgateway.proxy.image.repository | string | `"giantswarm/agentgateway-upstream/agentgateway"` |  |
+| agentgateway.proxy.image.tag | string | `"2.0.0"` |  |
 | agentgateway.podAnnotations."application.giantswarm.io/team" | string | `"bumblebee"` |  |
 | agentgateway.podSecurityContext.runAsNonRoot | bool | `true` |  |
 | agentgateway.podSecurityContext.seccompProfile.type | string | `"RuntimeDefault"` |  |

@@ -32,7 +32,7 @@ gitops:
 
 components:
   muster:                        { versionRange: "5.12.0" }
-  agentgateway:                  { versionRange: "2.0.7" }
+  agentgateway:                  { versionRange: "2.2.2" }
   valkey:                        { versionRange: "0.1.4" }
   agent-platform-mcps:         { versionRange: "0.9.0" }
   kagent:                        { versionRange: "0.2.0" }

@@ -303,8 +303,12 @@ components:  # @schema additionalProperties: true
     repository: oci://gsoci.azurecr.io/charts/giantswarm
     # 2.0.0 flattened the chart: upstream keys moved from `agentgateway.*` to the
     # chart root, so the forwarded block is no longer nested (no valuesKey) and
-    # the 1.x range cannot be used with this wiring.
-    versionRange: "2.x"
+    # the 1.x range cannot be used with this wiring. The floor is the packaging
+    # release that renders the controller's image tag as written (through
+    # 2.2.1 the chart prefixed a `v` to a bare X.Y.Z, and the agentgateway line
+    # publishes no such tag): the agentgateway block below names the line's
+    # release in full, so a packaging release cannot move the images.
+    versionRange: ">=2.2.2 <3.0.0"
     valuesFrom: agentgateway
     enabled: false
     # App-owned CRDs: the wrapper chart ships the agentgateway.dev CRDs (with
@@ -2083,13 +2087,27 @@ agentgateway:  # @schema skipProperties: true; additionalProperties: true
   fullnameOverride: agentgateway-controller
   image:
     registry: gsoci.azurecr.io
+  # The controller and its default data plane run one release of the Giant Swarm
+  # line of agentgateway (github.com/giantswarm/agentgateway-upstream; FORK.md
+  # there is the ledger of pin and patches), the line's own stable semver under
+  # its nested names gsoci.azurecr.io/giantswarm/agentgateway-upstream/{controller,
+  # agentgateway}, named IN FULL here — repository and tag — so a packaging
+  # release cannot move the images (a value wins over a chart default, and a
+  # default that moved alone to the nested names rendered a tag that existed
+  # only there). The flattened giantswarm/agentgateway{,-controller} carry the
+  # retagger's copies of upstream's releases only, never the line's. The block
+  # is forwarded to the connectivity release too, whose AgentgatewayParameters
+  # render proxy.image into every data plane it declares: the controller and
+  # the data planes move together, here.
   controller:
     image:
-      repository: giantswarm/agentgateway-controller
+      repository: giantswarm/agentgateway-upstream/controller
+      tag: "2.0.0"
   proxy:
     image:
       registry: gsoci.azurecr.io
-      repository: giantswarm/agentgateway
+      repository: giantswarm/agentgateway-upstream/agentgateway
+      tag: "2.0.0"
   podAnnotations:
     application.giantswarm.io/team: bumblebee
   podSecurityContext:

@@ -14,6 +14,7 @@
 has no PyYAML.
 """
 
+import re
 import sys
 
 VALUES_INDENT = "    "
@@ -49,8 +50,20 @@ def main(path: str) -> int:
         sys.exit("FAIL: agentgateway values still nested under an agentgateway key; the 2.x chart is flat")
     if "enabled" in values:
         sys.exit("FAIL: `enabled` forwarded to the agentgateway chart, whose schema is additionalProperties:false")
-    if "repository: giantswarm/agentgateway-controller" not in values.get("controller", []):
-        sys.exit("FAIL: agentgateway values lost controller.image.repository")
+    images = {}
+    for name in ("controller", "proxy"):
+        block = values.get(name, [])
+        repo = next((l.split(": ", 1)[1] for l in block if l.startswith("repository: ")), None)
+        tag = next((l.split(": ", 1)[1].strip("\"'") for l in block if l.startswith("tag: ")), None)
+        images[name] = (repo, tag)
+    for name, want in (("controller", "giantswarm/agentgateway-upstream/controller"), ("proxy", "giantswarm/agentgateway-upstream/agentgateway")):
+        repo, tag = images[name]
+        if repo != want:
+            sys.exit(f"FAIL: agentgateway {name}.image.repository is {repo!r}, not {want!r}: the agentgateway line's image under its nested name")
+        if not tag or not re.fullmatch(r"\d+\.\d+\.\d+", tag):
+            sys.exit(f"FAIL: agentgateway {name}.image.tag is {tag!r}, not a release of the line's stable semver (a bare X.Y.Z — no v, no -gs.N): the meta chart names the release in full so the packaging chart's defaults cannot move it")
+    if images["controller"][1] != images["proxy"][1]:
+        sys.exit(f"FAIL: the controller ({images['controller'][1]}) and its default data plane ({images['proxy'][1]}) name different releases of the line; they move together")
     return 0