From 9204c8da47f42b73048b144a53c04f3e503ba5ef Mon Sep 17 00:00:00 2001
From: Timo Derstappen <teemow@gmail.com>
Date: Thu, 10 Sep 2026 21:35:48 +0200
Subject: [PATCH] feat(substrate): install Substrate from the Giant Swarm line
 (ghcr.io/giantswarm/substrate)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The lab's Substrate — charts and images — comes from giantswarm/substrate,
branch giantswarm: the upstream release the dev channel's kagent pins in its
go.mod (kagent-dev/substrate v0.0.26) plus the cherry-picked
kagent-dev/substrate#33, published by the fork as multi-arch images and charts
under ghcr.io/giantswarm/substrate with dev versions
<next upstream patch>-dev.giantswarm.<date>.<time>.h<sha7>. The pinned version
is 0.0.27-dev.giantswarm.2026-09-10.19-33-37.h734ec53; the fork tags images
with the bare version, so the preloaded worker image drops the v prefix.
docs/platform.md and the config comments name the line; the CA/JWT bootstrap
port is unchanged.
---
 docs/platform.md                              | 18 +++++---
 internal/config/config.go                     |  4 +-
 internal/lab/substrate.go                     | 42 ++++++++++++-------
 .../lab/templates/substrate-values.yaml.tmpl  |  3 +-
 4 files changed, 43 insertions(+), 24 deletions(-)

diff --git a/docs/platform.md b/docs/platform.md
index ffa7051..dc77cf2 100644
--- a/docs/platform.md
+++ b/docs/platform.md
@@ -203,7 +203,10 @@ semverFilter: agent-platform-connectivity 3.22.1-dev…, …)`).
 ### Substrate
 
 The dev channel's kagent (kagent main, API v2) runs every agent as an actor
-on [Substrate](https://github.com/kagent-dev/substrate) — sandboxed (gVisor)
+on Substrate — the Giant Swarm line of
+[kagent-dev/substrate](https://github.com/kagent-dev/substrate), published from
+[giantswarm/substrate](https://github.com/giantswarm/substrate) (its `FORK.md`
+records the pin, the carried patches and the published versions) — sandboxed (gVisor)
 worker pods of a `WorkerPool`, an API server, a per-node agent (`atelet`) and
 the actors' ingress/egress data plane (`atenet`) — and its controller does
 not start without it. The lab installs Substrate as cluster infrastructure
@@ -232,11 +235,14 @@ What `agentlab up` (and `platform`) does, idempotently:
    between two `helm install`s; the lab embeds a Go port of the two commands
    (`substratepools.go`, from substrate 0.0.26) and creates everything first,
    so one waited install suffices (HACKS.md U22);
-3. installs `substrate-crds` and `substrate` 0.0.26 from
-   `oci://ghcr.io/kagent-dev/substrate/helm` into `ate-system` with the
+3. installs `substrate-crds` and `substrate` at the line's pinned version
+   (`substrateVersion` in `internal/lab/substrate.go`: today upstream 0.0.26
+   plus kagent-dev/substrate#33, as a `0.0.27-dev.giantswarm.…` build) from
+   `oci://ghcr.io/giantswarm/substrate/helm` into `ate-system` with the
    chart's own values (`state/substrate-values.yaml`), the images
-   side-loaded like the platform's plus the gVisor worker image the
-   `WorkerPool` names, and waits for ate-api-server, atelet and atenet;
+   (`ghcr.io/giantswarm/substrate/*`) side-loaded like the platform's plus the
+   gVisor worker image the `WorkerPool` names, and waits for ate-api-server,
+   atelet and atenet;
 4. checks the `SandboxConfig gvisor-default` the chart ships is there. The
    `WorkerPool` and the `Harness`es come with the dev channel's kagent.
 
@@ -492,7 +498,7 @@ data the page reads — see [The muster plugin](backstage.md#the-muster-plugin).
 | `kagent.ui.service.type: NodePort`, nodePort 30880 pinned by the kagent `postRenderers` patch | On a real MC the UI sits behind the agentgateway edge; this lab publishes it through the kind port mapping instead (host side `platform.agentsPort`, default 8081). The chart's Service template renders no `nodePort` field, so the fixed node port is a patch (HACKS.md U9). |
 | `components.flux.enabled: true`, `gitops.self.enabled: false` | The lab shape (see [The agent platform](#the-agent-platform-muster--kubernetes-mcp)): a management cluster runs its own Flux and installs the chart through it; the lab has none, so the chart brings the engine — and must not adopt its own release, because the lab installs charts and images that are not released. |
 | The chart pinned to an exact release (`platform.chartVersion`) | Component versions are the chart's own ranges, resolved by its Flux at reconcile time (the fleet's dogfooding track). The chart itself never floats in the lab: two runs install the same thing, and a bump is a deliberate edit with a lab run behind it. |
-| Substrate 0.0.26 installed by the lab ahead of the platform, bootstrap included (`platform.substrate.enabled`, implied by the dev channel) | The dev channel's kagent runs its agents as Substrate actors and cannot start without it, and Substrate is not a meta-chart component yet: its CA/JWT bootstrap is imperative (`kubectl-ate admin make-ca-pool`). The lab ports the two bootstrap commands, creates every object before one waited install and needs the apiserver gates its kind config turns on. See [Dev channel](#dev-channel). |
+| Substrate (the Giant Swarm line of kagent-dev/substrate, `ghcr.io/giantswarm/substrate`, pinned in `substrate.go`) installed by the lab ahead of the platform, bootstrap included (`platform.substrate.enabled`, implied by the dev channel) | The dev channel's kagent runs its agents as Substrate actors and cannot start without it, and Substrate is not a meta-chart component yet: its CA/JWT bootstrap is imperative (`kubectl-ate admin make-ca-pool`). The lab ports the two bootstrap commands, creates every object before one waited install and needs the apiserver gates its kind config turns on. See [Dev channel](#dev-channel). |
 | `mcp-prometheus` as a lab-rendered Flux `HelmRelease` | The one release the lab installs outside the chart rides the same engine, as the same tenant identity, so its lab-only sidecar is a `postRenderers` patch like the others and there is exactly one Helm writer (the embedded Helm, for the chart) and one Flux engine on the cluster. |
 
 ## Platform gotchas
diff --git a/internal/config/config.go b/internal/config/config.go
index 6f80d20..059a8bc 100644
--- a/internal/config/config.go
+++ b/internal/config/config.go
@@ -184,8 +184,8 @@ type Platform struct {
 	// keeps running the build under test until `agentlab platform --pin=false`
 	// (or the key is dropped). Meaningless without chartBranch.
 	ChartPinned bool `yaml:"chartPinned,omitempty"`
-	// Substrate installs kagent's actor runtime (kagent-dev/substrate) on the
-	// cluster before the platform — the kagent of the dev channel (kagent
+	// Substrate installs kagent's actor runtime (the Giant Swarm line of
+	// kagent-dev/substrate, giantswarm/substrate) on the cluster before the platform — the kagent of the dev channel (kagent
 	// main, API v2) runs its agents as Substrate actors and cannot start
 	// without it; the released kagent ignores it. Left unset, it follows the
 	// channel: on with chartBranch (while agents are on), off otherwise.
diff --git a/internal/lab/substrate.go b/internal/lab/substrate.go
index 57385c7..202556d 100644
--- a/internal/lab/substrate.go
+++ b/internal/lab/substrate.go
@@ -15,15 +15,24 @@ import (
 	"github.com/giantswarm/agentlab/internal/config"
 )
 
-// Substrate (kagent-dev/substrate) is kagent's actor runtime: WorkerPools of
-// sandboxed (gVisor) worker pods that ate-controller schedules actors onto,
-// ate-api-server as their control plane, atelet as the per-node agent and
-// atenet as the actors' ingress/egress data plane. The dev channel's kagent
-// (kagent main, API v2) runs every agent as a Substrate actor and cannot
-// start without it, so the lab installs Substrate as cluster infrastructure
-// ahead of the platform when platform.substrate.enabled says so
-// (config.SubstrateEnabled — implied by the dev channel); the released
-// kagent ignores it. docs/platform.md "Dev channel".
+// Substrate is kagent's actor runtime: WorkerPools of sandboxed (gVisor)
+// worker pods that ate-controller schedules actors onto, ate-api-server as
+// their control plane, atelet as the per-node agent and atenet as the actors'
+// ingress/egress data plane. The dev channel's kagent (kagent main, API v2)
+// runs every agent as a Substrate actor and cannot start without it, so the
+// lab installs Substrate as cluster infrastructure ahead of the platform when
+// platform.substrate.enabled says so (config.SubstrateEnabled — implied by
+// the dev channel); the released kagent ignores it. docs/platform.md "Dev
+// channel".
+//
+// The lab consumes the Giant Swarm line of Substrate — giantswarm/substrate,
+// branch `giantswarm`: the upstream (kagent-dev/substrate) release the
+// platform's kagent pins in its go.mod plus cherry-picked upstream fixes,
+// published by the fork's own workflow as multi-arch images and charts under
+// ghcr.io/giantswarm/substrate with dev versions
+// `<next upstream patch>-dev.giantswarm.<date>.<time>.h<sha7>` (no `v`
+// prefix on the tags). Its FORK.md is the ledger: pin, carried patches,
+// re-pin procedure, published digests.
 //
 // Not a meta-chart component (yet): Substrate needs an imperative bootstrap
 // the chart does not render — the CA and JWT pools its signers and
@@ -38,11 +47,13 @@ import (
 // config for every cluster (kind-config.yaml.tmpl).
 //
 // Pinned like the observability charts: Go consts, bumped deliberately, with
-// a lab run.
+// a lab run. The version is an exact published version of the line (the
+// fork's publish workflow names it in its run summary); it moves only
+// together with kagent's Substrate pin.
 const (
-	substrateVersion       = "0.0.26"
-	substrateChartsRepo    = "oci://ghcr.io/kagent-dev/substrate/helm"
-	substrateImageRegistry = "ghcr.io/kagent-dev/substrate"
+	substrateVersion       = "0.0.27-dev.giantswarm.2026-09-10.19-33-37.h734ec53"
+	substrateChartsRepo    = "oci://ghcr.io/giantswarm/substrate/helm"
+	substrateImageRegistry = "ghcr.io/giantswarm/substrate"
 )
 
 // The namespaces and releases. ate-system is hardcoded in the chart
@@ -99,8 +110,9 @@ const podCertificateAPIPath = "/apis/certificates.k8s.io/v1beta1"
 // ateomGVisorImage is the worker image the WorkerPool the dev channel's
 // kagent creates names (`workerImage:`, no `image:` line in any render), so
 // the preload lists it explicitly — pulled once here instead of at the first
-// actor's boot.
-const ateomGVisorImage = substrateImageRegistry + "/ateom-gvisor:v" + substrateVersion
+// actor's boot. The line tags its images with the bare version (upstream's
+// carry a `v`).
+const ateomGVisorImage = substrateImageRegistry + "/ateom-gvisor:" + substrateVersion
 
 // The SandboxConfig the chart ships, which every gVisor WorkerPool names.
 const (
diff --git a/internal/lab/templates/substrate-values.yaml.tmpl b/internal/lab/templates/substrate-values.yaml.tmpl
index 8493986..7fb0e5c 100644
--- a/internal/lab/templates/substrate-values.yaml.tmpl
+++ b/internal/lab/templates/substrate-values.yaml.tmpl
@@ -1,5 +1,6 @@
 # ---------------------------------------------------------------------------
-# kagent-dev/substrate — kagent's actor runtime — in this kind lab.
+# Substrate — kagent's actor runtime, from the Giant Swarm line of
+# kagent-dev/substrate (giantswarm/substrate) — in this kind lab.
 #
 # The chart's own defaults, on purpose: the dev channel's kagent creates its
 # WorkerPool against this Substrate exactly as a management cluster's would,