api: move the pause image from ActorTemplate to SandboxConfig

benchmarking/workloads/manifests/full_workloads.yaml.tmpl

@@ -46,7 +46,6 @@ metadata:
   name: sleep
   namespace: benchmark-workloads
 spec:
-  pauseImage: "gcr.io/gke-release/pause@sha256:bcbd57ba5653580ec647b16d8163cdd1112df3609129b01f912a8032e48265da"
   containers:
   - name: sleep
     image: busybox@sha256:1487d0af5f52b4ba31c7e465126ee2123fe3f2305d638e7827681e7cf6c83d5e
@@ -65,7 +64,6 @@ metadata:
   name: usermem
   namespace: benchmark-workloads
 spec:
-  pauseImage: "gcr.io/gke-release/pause@sha256:bcbd57ba5653580ec647b16d8163cdd1112df3609129b01f912a8032e48265da"
   containers:
   - name: usermem
     image: containerstack/alpine-stress:latest
@@ -84,7 +82,6 @@ metadata:
   name: kernelmem
   namespace: benchmark-workloads
 spec:
-  pauseImage: "gcr.io/gke-release/pause@sha256:bcbd57ba5653580ec647b16d8163cdd1112df3609129b01f912a8032e48265da"
   containers:
   - name: kernelmem
     image: containerstack/alpine-stress:latest
@@ -103,7 +100,6 @@ metadata:
   name: glutton
   namespace: benchmark-workloads
 spec:
-  pauseImage: "gcr.io/gke-release/pause@sha256:bcbd57ba5653580ec647b16d8163cdd1112df3609129b01f912a8032e48265da"
   containers:
   - name: glutton
     image: ko://github.com/agent-substrate/substrate/cmd/benchmarking/glutton

benchmarking/workloads/manifests/workloads.yaml.tmpl

@@ -42,7 +42,6 @@ metadata:
 spec:
   # Must match the WorkerPool's sandboxClass so snapshots stay within a class.
   sandboxClass: ${SANDBOX_CLASS}
-  pauseImage: "gcr.io/gke-release/pause@sha256:bcbd57ba5653580ec647b16d8163cdd1112df3609129b01f912a8032e48265da"
   containers:
   - name: sleep
     image: busybox@sha256:1487d0af5f52b4ba31c7e465126ee2123fe3f2305d638e7827681e7cf6c83d5e
@@ -62,7 +61,6 @@ metadata:
   namespace: benchmark-workloads
 spec:
   sandboxClass: ${SANDBOX_CLASS}
-  pauseImage: "gcr.io/gke-release/pause@sha256:bcbd57ba5653580ec647b16d8163cdd1112df3609129b01f912a8032e48265da"
   containers:
   - name: glutton
     image: ko://github.com/agent-substrate/substrate/cmd/benchmarking/glutton

cmd/ateapi/internal/controlapi/create_actor_test.go

@@ -213,7 +213,6 @@ func TestCreateActor_RejectsSnapshotWithExternalVolumes(t *testing.T) {
 	template, err := tc.substrateClient.ApiV1alpha1().ActorTemplates(ns).Create(context.Background(), &atev1alpha1.ActorTemplate{
 		ObjectMeta: metav1.ObjectMeta{Name: "tmpl1", Namespace: ns},
 		Spec: atev1alpha1.ActorTemplateSpec{
-			PauseImage:      "pause@sha256:abc",
 			SnapshotsConfig: atev1alpha1.SnapshotsConfig{Location: "gs://snapshots"},
 			Containers: []atev1alpha1.Container{{
 				Name: "main", Image: "main@sha256:abc", VolumeMounts: []atev1alpha1.VolumeMount{{Name: "data", MountPath: "/data"}},

cmd/ateapi/internal/controlapi/functional_test.go

@@ -525,7 +525,6 @@ func createTemplateWithContainersAndVolumes(t *testing.T, tc *testContext, ns st
 			Namespace: ns,
 		},
 		Spec: atev1alpha1.ActorTemplateSpec{
-			PauseImage: "pause@sha256:abc",
 			SnapshotsConfig: atev1alpha1.SnapshotsConfig{
 				Location: "gs://fake-fake-fake",
 			},
@@ -574,6 +573,10 @@ func createTemplateWithContainersAndVolumes(t *testing.T, tc *testContext, ns st
 	}
 }
 
+// testPauseImage is the pause image the default test SandboxConfig carries;
+// it is what a resolved WorkloadSpec's sandbox assets should name.
+const testPauseImage = "pause@sha256:abc"
+
 // ensureDefaultGvisorSandboxConfig creates the cluster-scoped default gvisor
 // SandboxConfig (idempotently) and waits for it to appear in the lister.
 func ensureDefaultGvisorSandboxConfig(t *testing.T, tc *testContext) {
@@ -584,6 +587,7 @@ func ensureDefaultGvisorSandboxConfig(t *testing.T, tc *testContext) {
 		Spec: atev1alpha1.SandboxConfigSpec{
 			SandboxClass: atev1alpha1.SandboxClassGvisor,
 			Default:      true,
+			PauseImage:   testPauseImage,
 			Assets: map[string]map[string]atev1alpha1.AssetFile{
 				"amd64": {"runsc": {
 					URL:    "gs://gvisor/releases/nightly/2026-05-19/x86_64/runsc",
@@ -643,7 +647,6 @@ func createTemplateWithSelector(t *testing.T, tc *testContext, ns string, name s
 			Namespace: ns,
 		},
 		Spec: atev1alpha1.ActorTemplateSpec{
-			PauseImage: "pause@sha256:abc",
 			SnapshotsConfig: atev1alpha1.SnapshotsConfig{
 				Location: "gs://fake-fake-fake",
 			},

cmd/ateapi/internal/controlapi/sandbox_assets.go

@@ -23,10 +23,11 @@ import (
 	"k8s.io/apimachinery/pkg/labels"
 )
 
-// resolveSandboxAssets determines the sandbox binaries an actor should boot with
-// and projects them onto the ateletpb.SandboxAssets atelet fetches. It takes the
-// SandboxClass (default gvisor) of a given worker pool, then picks the SandboxConfig
-// named by the pool — or, if none is named, the cluster default SandboxConfig for that class.
+// resolveSandboxAssets determines the sandbox binaries and pause image an actor
+// should boot with and projects them onto the ateletpb.SandboxAssets atelet
+// fetches. It takes the SandboxClass (default gvisor) of a given worker pool,
+// then picks the SandboxConfig named by the pool — or, if none is named, the
+// cluster default SandboxConfig for that class.
 func resolveSandboxAssets(
 	workerPoolLister listersv1alpha1.WorkerPoolLister,
 	sandboxConfigLister listersv1alpha1.SandboxConfigLister,
@@ -89,6 +90,7 @@ func defaultSandboxConfig(lister listersv1alpha1.SandboxConfigLister, class atev
 func sandboxAssetsProto(class atev1alpha1.SandboxClass, sc *atev1alpha1.SandboxConfig) *ateletpb.SandboxAssets {
 	out := &ateletpb.SandboxAssets{
 		SandboxClass: string(class),
+		PauseImage:   sc.Spec.PauseImage,
 		Assets:       make(map[string]*ateletpb.ArchAssets, len(sc.Spec.Assets)),
 	}
 	for arch, files := range sc.Spec.Assets {

cmd/ateapi/internal/controlapi/sandbox_assets_test.go

@@ -0,0 +1,103 @@
+// Copyright 2026 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package controlapi
+
+import (
+	"testing"
+
+	atev1alpha1 "github.com/agent-substrate/substrate/pkg/api/v1alpha1"
+	listersv1alpha1 "github.com/agent-substrate/substrate/pkg/client/listers/api/v1alpha1"
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+	"k8s.io/client-go/tools/cache"
+)
+
+// listerFor builds listers over the given objects, using the same key
+// functions the informers use.
+func listersFor(t *testing.T, pools []*atev1alpha1.WorkerPool, configs []*atev1alpha1.SandboxConfig) (listersv1alpha1.WorkerPoolLister, listersv1alpha1.SandboxConfigLister) {
+	t.Helper()
+	poolIdx := cache.NewIndexer(cache.MetaNamespaceKeyFunc, cache.Indexers{cache.NamespaceIndex: cache.MetaNamespaceIndexFunc})
+	for _, p := range pools {
+		if err := poolIdx.Add(p); err != nil {
+			t.Fatalf("adding WorkerPool: %v", err)
+		}
+	}
+	configIdx := cache.NewIndexer(cache.MetaNamespaceKeyFunc, cache.Indexers{})
+	for _, c := range configs {
+		if err := configIdx.Add(c); err != nil {
+			t.Fatalf("adding SandboxConfig: %v", err)
+		}
+	}
+	return listersv1alpha1.NewWorkerPoolLister(poolIdx), listersv1alpha1.NewSandboxConfigLister(configIdx)
+}
+
+func testAssets() map[string]map[string]atev1alpha1.AssetFile {
+	return map[string]map[string]atev1alpha1.AssetFile{
+		"amd64": {"gvisor": {URL: "gs://bucket/gvisor.tar.bz2", SHA256: "abc"}},
+	}
+}
+
+// TestResolveSandboxAssetsCarriesPauseImage pins that the pause image travels
+// with the sandbox binaries — it is resolved from the pool's SandboxConfig, not
+// from the ActorTemplate — for both the named and the class-default config.
+func TestResolveSandboxAssetsCarriesPauseImage(t *testing.T) {
+	const (
+		defaultPause = "registry.k8s.io/pause@sha256:default"
+		namedPause   = "gcr.io/gke-release/pause@sha256:named"
+	)
+	defaultConfig := &atev1alpha1.SandboxConfig{
+		ObjectMeta: metav1.ObjectMeta{Name: "gvisor-default"},
+		Spec: atev1alpha1.SandboxConfigSpec{
+			SandboxClass: atev1alpha1.SandboxClassGvisor,
+			Default:      true,
+			PauseImage:   defaultPause,
+			Assets:       testAssets(),
+		},
+	}
+	namedConfig := &atev1alpha1.SandboxConfig{
+		ObjectMeta: metav1.ObjectMeta{Name: "gvisor-custom"},
+		Spec: atev1alpha1.SandboxConfigSpec{
+			SandboxClass: atev1alpha1.SandboxClassGvisor,
+			PauseImage:   namedPause,
+			Assets:       testAssets(),
+		},
+	}
+
+	tests := []struct {
+		name           string
+		configName     string
+		wantPauseImage string
+	}{
+		{name: "class default", wantPauseImage: defaultPause},
+		{name: "named config", configName: "gvisor-custom", wantPauseImage: namedPause},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			pool := &atev1alpha1.WorkerPool{
+				ObjectMeta: metav1.ObjectMeta{Name: "pool1", Namespace: "worker-ns"},
+				Spec:       atev1alpha1.WorkerPoolSpec{SandboxConfigName: tt.configName},
+			}
+			poolLister, configLister := listersFor(t, []*atev1alpha1.WorkerPool{pool},
+				[]*atev1alpha1.SandboxConfig{defaultConfig, namedConfig})
+
+			got, err := resolveSandboxAssets(poolLister, configLister, "worker-ns", "pool1")
+			if err != nil {
+				t.Fatalf("resolveSandboxAssets() error: %v", err)
+			}
+			if got.GetPauseImage() != tt.wantPauseImage {
+				t.Errorf("pause image = %q, want %q", got.GetPauseImage(), tt.wantPauseImage)
+			}
+		})
+	}
+}

cmd/ateapi/internal/controlapi/workload_spec.go

@@ -37,9 +37,7 @@ const envSecretCacheTTL = 30 * time.Second
 // container env vars. Use this when downstream consumers (e.g. checkpoint
 // requests) don't need env entries materialized.
 func workloadSpecFromActorTemplate(actorTemplate *atev1alpha1.ActorTemplate, actor *ateapipb.Actor) (*ateletpb.WorkloadSpec, error) {
-	workloadSpec := &ateletpb.WorkloadSpec{
-		PauseImage: actorTemplate.Spec.PauseImage,
-	}
+	workloadSpec := &ateletpb.WorkloadSpec{}
 
 	// add volumes
 	for _, vol := range actorTemplate.Spec.Volumes {

cmd/ateapi/internal/controlapi/workload_spec_test.go

@@ -43,7 +43,6 @@ func TestWorkloadSpecFromActorTemplate(t *testing.T) {
 			template: &atev1alpha1.ActorTemplate{
 				ObjectMeta: metav1.ObjectMeta{Name: "tmpl1", Namespace: "agent-ns"},
 				Spec: atev1alpha1.ActorTemplateSpec{
-					PauseImage: "pause",
 					Volumes: []atev1alpha1.Volume{
 						{Name: "home", VolumeSource: atev1alpha1.VolumeSource{DurableDir: &atev1alpha1.DurableDirVolumeSource{}}},
 					},
@@ -60,7 +59,6 @@ func TestWorkloadSpecFromActorTemplate(t *testing.T) {
 				},
 			},
 			want: &ateletpb.WorkloadSpec{
-				PauseImage: "pause",
 				Volumes: []*ateletpb.Volume{
 					{
 						Name:   "home",
@@ -227,7 +225,6 @@ func TestWorkloadSpecFromActorTemplateWithEnv(t *testing.T) {
 			template: &atev1alpha1.ActorTemplate{
 				ObjectMeta: metav1.ObjectMeta{Name: "tmpl1", Namespace: "agent-ns"},
 				Spec: atev1alpha1.ActorTemplateSpec{
-					PauseImage: "pause",
 					Containers: []atev1alpha1.Container{
 						{
 							Name:    "main",
@@ -247,7 +244,6 @@ func TestWorkloadSpecFromActorTemplateWithEnv(t *testing.T) {
 				},
 			},
 			want: &ateletpb.WorkloadSpec{
-				PauseImage: "pause",
 				Containers: []*ateletpb.Container{
 					{
 						Name:    "main",

cmd/atelet/main.go

@@ -420,7 +420,7 @@ func (s *AteomHerder) Run(ctx context.Context, req *ateletpb.RunRequest) (resp *
 	}
 
 	if err := s.prepareOCIBundles(ctx, actorUID, actorRef.Name,
-		req.GetSpec(), req.GetTargetAteomUid(),
+		req.GetSpec(), sandboxRec.PauseImage, req.GetTargetAteomUid(),
 	); err != nil {
 		return nil, ateerrors.CrashIfReason(ctx, err, ateerrors.ReasonInvalidContainerConfig)
 	}
@@ -825,12 +825,12 @@ func (s *AteomHerder) Restore(ctx context.Context, req *ateletpb.RestoreRequest)
 	op.kind = restoreSnapshotKind(req, sandboxRec)
 	op.sandboxClass = sandboxRec.SandboxClass
 
-	// The record whose pinned binaries run the restored workload: the golden's
-	// for a DATA_ON_GOLDEN restore, the snapshot's own otherwise. The golden's
-	// set wins because the guest state being resumed is the golden snapshot's
-	// memory image, and a memory image must be resumed by the exact binary
-	// versions that produced it; the actor's snapshot contributes only durable
-	// data (a plain tar), which no binary version reads back.
+	// The record whose pinned sandbox (binaries + pause image) runs the restored
+	// workload: the golden's for a DATA_ON_GOLDEN restore, the snapshot's own
+	// otherwise. The golden's set wins because the guest state being resumed is
+	// the golden snapshot's memory image, and a memory image must be resumed by
+	// the exact sandbox that produced it; the actor's snapshot contributes only
+	// durable data (a plain tar), which no sandbox version reads back.
 	runtimeRec := sandboxRec
 	if goldenRec != nil {
 		runtimeRec = goldenRec
@@ -905,7 +905,7 @@ func (s *AteomHerder) Restore(ctx context.Context, req *ateletpb.RestoreRequest)
 			return ateerrors.CrashIfReason(ctx, err, ateerrors.ReasonFailedGetExternalObject, ateerrors.ReasonInvalidObjectURL, ateerrors.ReasonTerminalFileSystemError, ateerrors.ReasonInvalidSandboxAsset)
 		}
 		t := time.Now()
-		err = s.prepareOCIBundles(gctx, actorUID, actorRef.Name, req.GetSpec(), req.GetTargetAteomUid())
+		err = s.prepareOCIBundles(gctx, actorUID, actorRef.Name, req.GetSpec(), runtimeRec.PauseImage, req.GetTargetAteomUid())
 		dBundles = time.Since(t)
 		if err != nil {
 			prepFailedPhase = ateattr.SnapshotPhaseOCIUnpack
@@ -1201,12 +1201,16 @@ func (s *AteomHerder) downloadExternalCheckpoint(ctx context.Context, snapshotUR
 }
 
 // prepareOCIBundles pulls images and assembles OCI bundles for the pause
-// container and every application container in spec, in parallel.
+// container and every application container in spec, in parallel. pauseImage
+// comes from the sandbox record, not the workload spec: it is sandbox
+// configuration, and on a restore it must be the image the snapshot was taken
+// with.
 func (s *AteomHerder) prepareOCIBundles(
 	ctx context.Context,
 	actorUID string,
 	actorName string,
 	spec *ateletpb.WorkloadSpec,
+	pauseImage string,
 	targetAteomUid string,
 ) error {
 	// Populate the per-actor identity directory that gets bind-mounted into
@@ -1252,7 +1256,7 @@ func (s *AteomHerder) prepareOCIBundles(
 			s.imageCache,
 			actorUID,
 			"pause",
-			spec.GetPauseImage(),
+			pauseImage,
 			[]string{"/pause"},
 			nil,
 			nil,

cmd/atelet/main_test.go

@@ -70,7 +70,7 @@ func TestSnapshotManifestActorMetadata(t *testing.T) {
 // written before the scope field existed must still parse, reporting an empty
 // scope, and a scope-less record must not serialize a scope key at all.
 func TestSnapshotManifestScopeAbsent(t *testing.T) {
-	legacy := []byte(`{"sandboxClass":"gvisor","snapshotFiles":["checkpoint.img"]}`)
+	legacy := []byte(`{"sandboxClass":"gvisor","pauseImage":"pause@sha256:abc","snapshotFiles":["checkpoint.img"]}`)
 	rec, err := unmarshalSandboxRecord(legacy)
 	if err != nil {
 		t.Fatalf("unmarshalSandboxRecord(legacy manifest): %v", err)
@@ -88,6 +88,18 @@ func TestSnapshotManifestScopeAbsent(t *testing.T) {
 	}
 }
 
+// TestSnapshotManifestRequiresPauseImage pins that a manifest without a pause
+// image is rejected outright rather than yielding an empty image that would
+// fail later, deep in the image pull.
+func TestSnapshotManifestRequiresPauseImage(t *testing.T) {
+	noPause := []byte(`{"sandboxClass":"gvisor","snapshotFiles":["checkpoint.img"]}`)
+	if _, err := unmarshalSandboxRecord(noPause); err == nil {
+		t.Fatal("unmarshalSandboxRecord accepted a manifest with no pauseImage")
+	} else if !strings.Contains(err.Error(), "pauseImage") {
+		t.Errorf("error = %v, want it to name pauseImage", err)
+	}
+}
+
 func TestWriteFileAtomic(t *testing.T) {
 	dir := t.TempDir()
 	target := filepath.Join(dir, "actor-id")
@@ -636,7 +648,6 @@ func TestRPCBoundariesReject(t *testing.T) {
 
 func TestBuildAteomWorkloadSpecForwardsReadyz(t *testing.T) {
 	in := &ateletpb.WorkloadSpec{
-		PauseImage: "pause",
 		Containers: []*ateletpb.Container{
 			{
 				Name:  "with-probe",