Upgrade Runbook GA

README.md

@@ -250,7 +250,7 @@ We provide several sample applications demonstrating Agent Substrate's capabilit
 * [Egress Traffic](docs/egress-traffic.md): Which protocols an Actor may reach the outside world with and which are blocked.
 * [Enabling man-in-the-middle (MITM) interception for Actor Egress policy](docs/egress-trust-bundle.md): Egress policies such as header injection depend on MITM interception of Actor traffic. This guide explains how an Actor should be configured to enable interception.
 * [Request Parking](docs/request-parking.md): How the router parks requests through transient worker-pool saturation.
-* [Rolling Upgrade Runbook](docs/upgrade.md): Upgrade a running substrate node by node without losing actor state.
+* [Upgrade Runbook](docs/upgrade.md): Upgrade a running install to a newer supported release, and roll back if needed.
 * [Security Guide](docs/security.md): Security overview, security principles, and threat modeling.
 * [Roadmap](docs/roadmap.md): Current limitations and what is planned next.
 * [Benchmarking Guide](benchmarking/README.md): Locust-based load tests, monitoring stack, and the orchestrated benchmark harness.

cmd/atecontroller/internal/controllers/workerpool_apply.go

@@ -126,15 +126,13 @@ func buildDeploymentApplyConfig(wp *atev1alpha1.WorkerPool, otel ateomOTelSettin
 		"--atunnel-client-identity=" + installdefaults.SPIFFEID(systemNamespace, routerServiceAccount),
 	}
 
-	// --atunnel-broker-identity is newer than the oldest ateom a rolling
-	// upgrade still has running. docs/upgrade.md keeps the outgoing worker pool
-	// serving alongside the new one, and that pool's Deployment is reconciled
-	// by this controller while still pinned to its old image, which exits on an
-	// unrecognized flag. An ateom without the flag hardcodes the canonical
-	// identity, and an ateom with it defaults to the same, so omitting the flag
-	// when it carries that value is equivalent for both and keeps the upgrade
-	// intact. A relocated or renamed install passes something else and needs an
-	// image new enough to accept it, which it necessarily has.
+	// --atunnel-broker-identity is newer than the oldest ateom a WorkerPool
+	// may still pin, and an ateom exits on an unrecognized flag. An ateom
+	// without the flag hardcodes the canonical identity, and an ateom with it
+	// defaults to the same, so omitting the flag when it carries that value is
+	// equivalent for both. A relocated or renamed install passes something
+	// else and needs an image new enough to accept it, which it necessarily
+	// has.
 	if brokerIdentity := installdefaults.SPIFFEID(systemNamespace, ateletServiceAccount); brokerIdentity != installdefaults.AteletSPIFFEID(installdefaults.SystemNamespace) {
 		args = append(args, "--atunnel-broker-identity="+brokerIdentity)
 	}

cmd/atecontroller/internal/controllers/workerpool_apply_test.go

@@ -999,12 +999,9 @@ func TestBuildDeploymentAtunnelIdentitiesPrefixedServiceAccounts(t *testing.T) {
 }
 
 // TestBuildDeploymentOmitsBrokerIdentityForCanonicalInstall pins the flag's
-// absence, which is what keeps a rolling upgrade working. docs/upgrade.md runs
-// the outgoing worker pool alongside the new one, and this controller
-// reconciles that pool's Deployment while it is still pinned to its old image.
-// An ateom from before --atunnel-broker-identity existed exits on the
-// unrecognized flag, so passing it would crashloop every old worker the moment
-// the control plane rolled out.
+// absence. A WorkerPool may still pin an ateom from before
+// --atunnel-broker-identity existed, which exits on the unrecognized flag, so
+// passing it would crashloop that pool's workers.
 func TestBuildDeploymentOmitsBrokerIdentityForCanonicalInstall(t *testing.T) {
 	c := buildDeploymentApplyConfig(testWorkerPoolApplyConfig(nil), ateomOTelSettings{},
 		installdefaults.SystemNamespace, installdefaults.AteletServiceAccount, installdefaults.RouterServiceAccount, egresspolicy.DNSEgressPolicyEnforceInAtunnel).

cmd/atenet/README.md

@@ -37,9 +37,11 @@ likely be split in the future for better scalability.)
   Envoy container's `preStop` hook waits for the router's drain-complete
   marker on a pod-shared emptyDir — so established connections and parked
   requests finish instead of resetting. The whole sequence must fit within
-  `terminationGracePeriodSeconds` (see the manifest comments). Upgrades are
-  whole-system swaps (#473) rather than per-Deployment rolling updates; the
-  drain is what makes the old system's termination lossless.
+  `terminationGracePeriodSeconds` (see the manifest comments). An upgrade
+  rolls the router as an ordinary Deployment update (see
+  [docs/upgrade.md](../../docs/upgrade.md)). The drain lets each old pod's
+  requests finish, except one still open about 15 seconds after the drain
+  starts, which is cut.
 
 RBAC permissions:
 * get, list, watch on ate-system EndpointSlices