feat(infra): sandbox-runner images as schema defaults (drop ${kedge.*} tokens)

The sandbox-runner template was the lone outlier using ${kedge.*}
env-substitution tokens for its container images (Phase 2a) — every
other template declares configurable images as spec.schema fields with
sane defaults and hardcodes fixed sidecar images. That outlier broke in
practice: an unset KEDGE_SANDBOX_RUNNER_IMAGE substituted to "" and kro
authored a Deployment/Job with `image: ""` (Required value).

Make sandbox-runner follow the same convention as simple-webapp / database
/ redis / application:

  - spec.runnerImage is a schema field with a sane default
    (ghcr.io/faroshq/kedge-sandbox-runner:dev); the runner Deployment uses
    ${schema.spec.runnerImage}. Overridable per instance.
  - the control-token Job image is hardcoded bitnami/kubectl, like every
    other template's control job (tokenGeneratorImage field dropped).

Remove all the now-dead image-token machinery:
  - kro backend: drop the sandbox image tokens (only the exposure Gateway
    tokens remain).
  - infra chart: drop KEDGE_SANDBOX_*_IMAGE env, the install guard, and the
    sandboxRunner values block; operator passthrough.
  - App Studio: sandboxRunnerValues supplies only {projectRef}; drop the
    image env helpers, chart guard/env/values, README rows.

Document the convention so this doesn't recur:
  - new providers/infrastructure/docs/template-conventions.md (when to use a
    schema default vs a hardcoded literal vs a ${kedge.*} token, with the
    failure modes that motivated it).
  - AGENTS.md §9 guardrail pointing at it.

Also: dev postgres images default to Google's Docker Hub mirror
(mirror.gcr.io/library/postgres:16-alpine) — Docker Hub has been dropping
pulls with "unexpected EOF".

Preview routing is unchanged (it was already schema-based on main).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: mjudeikis

AGENTS.md

@@ -390,6 +390,14 @@ whole point.
   build/test and `go.work` awareness; they are not in the root `./...`.
 - Before merging: `make verify` is the full gate
   (boilerplate + codegen + vet + lint + build + test).
+- **Infrastructure templates declare configurable inputs (container images,
+  versions, sizes) as `spec.schema` fields with sane defaults** — never via
+  `${kedge.*}` env-substitution tokens. Fixed sidecar images (e.g. the
+  control-token `kubectl` job) are hardcoded literals. `${kedge.*}` tokens are
+  reserved for genuinely platform-global values with no universal default (only
+  the exposure Gateway parent today). A missing env must never be able to
+  produce an empty/invalid field. See
+  [`providers/infrastructure/docs/template-conventions.md`](providers/infrastructure/docs/template-conventions.md).
 
 ---
 

Makefile

@@ -678,7 +678,9 @@ KUERY_RUNTIME_KUBECONFIG ?= $(KCP_DATA_DIR)/kuery-runtime.kubeconfig
 # …) diverges from SQLite and passing on SQLite has shipped real query bugs.
 # kuery-db-up starts a throwaway container matching KUERY_DEV_DATABASE_URL.
 KUERY_POSTGRES_CONTAINER ?= kedge-kuery-postgres
-KUERY_POSTGRES_IMAGE ?= postgres:16-alpine
+# Pulled from Google's Docker Hub mirror (same official image, more reliable
+# pulls — Docker Hub has been dropping them with "unexpected EOF").
+KUERY_POSTGRES_IMAGE ?= mirror.gcr.io/library/postgres:16-alpine
 KUERY_POSTGRES_PORT ?= 55433
 KUERY_POSTGRES_DATA_DIR ?= $(KCP_DATA_DIR)/kuery-postgres
 KUERY_POSTGRES_USER ?= kuery
@@ -862,7 +864,7 @@ APP_STUDIO_SANDBOX_RUNNER_IMAGE ?= $(SANDBOX_RUNNER_IMAGE)
 APP_STUDIO_SANDBOX_TOKEN_GENERATOR_IMAGE ?= $(SANDBOX_TOKEN_GENERATOR_IMAGE)
 APP_STUDIO_DEV_DATABASE_URL ?= postgres://appstudio:appstudio@localhost:55432/appstudio?sslmode=disable
 APP_STUDIO_POSTGRES_CONTAINER ?= kedge-app-studio-postgres
-APP_STUDIO_POSTGRES_IMAGE ?= postgres:16-alpine
+APP_STUDIO_POSTGRES_IMAGE ?= mirror.gcr.io/library/postgres:16-alpine
 APP_STUDIO_POSTGRES_PORT ?= 55432
 APP_STUDIO_POSTGRES_DATA_DIR ?= $(KCP_DATA_DIR)/app-studio-postgres
 APP_STUDIO_POSTGRES_USER ?= appstudio

providers/app-studio/README.md

@@ -52,8 +52,6 @@ Environment variables consumed by the binary:
 | `KEDGE_HUB_TOKEN` | Bearer token for the heartbeat |
 | `KEDGE_PROVIDER_NAME` | CatalogEntry name (default `app-studio`) |
 | `KEDGE_PROVIDER_KUBECONFIG` | Provider kubeconfig (kcp front-proxy host + TLS only) |
-| `APP_STUDIO_SANDBOX_RUNNER_IMAGE` | Runner image passed to new `SandboxRunner` resources; use an immutable digest outside local development |
-| `APP_STUDIO_SANDBOX_TOKEN_GENERATOR_IMAGE` | kubectl-capable token-generator image passed to new `SandboxRunner` resources; use an immutable digest outside local development |
 | `APP_STUDIO_PREVIEW_BASE_DOMAIN` | Optional DNS zone for companion Sandbox preview routing. |
 | `APP_STUDIO_PREVIEW_HTTPROUTE_PARENT_GATEWAY_NAME` | Gateway resource name to attach each preview `HTTPRoute` to. |
 | `APP_STUDIO_PREVIEW_HTTPROUTE_PARENT_GATEWAY_NAMESPACE` | Namespace of the parent Gateway (defaults to `kedge-preview`). |

providers/app-studio/api/deployment_defaults.go

@@ -67,17 +67,15 @@ func defaultSandboxRunnerBinding(projectName string) aiv1alpha1.ProjectProviderB
 	}
 }
 
+// sandboxRunnerValues are the project-scoped fields App Studio supplies on a
+// SandboxRunner binding. The runner image is NOT one of them: the sandbox-runner
+// template declares spec.runnerImage as a schema field with a sane default (the
+// web-app convention), so App Studio doesn't pass it. See
+// providers/infrastructure/docs/template-conventions.md.
 func sandboxRunnerValues(projectName string) map[string]any {
-	values := map[string]any{
+	return map[string]any{
 		"projectRef": projectName,
 	}
-	if image := sandboxRunnerImage(); image != "" {
-		values["runnerImage"] = image
-	}
-	if image := sandboxTokenGeneratorImage(); image != "" {
-		values["tokenGeneratorImage"] = image
-	}
-	return values
 }
 
 func previewHTTPRouteEnabled() bool {
@@ -132,14 +130,6 @@ func previewBackendServicePort() int64 {
 	return port
 }
 
-func sandboxRunnerImage() string {
-	return envValue("APP_STUDIO_SANDBOX_RUNNER_IMAGE")
-}
-
-func sandboxTokenGeneratorImage() string {
-	return envValue("APP_STUDIO_SANDBOX_TOKEN_GENERATOR_IMAGE")
-}
-
 func envValue(key string) string {
 	return strings.TrimSpace(os.Getenv(key))
 }

providers/app-studio/api/deployment_defaults_test.go

@@ -12,31 +12,19 @@ package api
 
 import "testing"
 
-func TestSandboxRunnerValuesOmitImagesWithoutConfiguration(t *testing.T) {
-	t.Setenv("APP_STUDIO_SANDBOX_RUNNER_IMAGE", "")
-	t.Setenv("APP_STUDIO_SANDBOX_TOKEN_GENERATOR_IMAGE", "")
+// App Studio supplies only projectRef on a SandboxRunner binding. The runner
+// image is a schema field with a sane default on the sandbox-runner template
+// (the web-app convention), so App Studio never sets it — not even from the
+// legacy env.
+func TestSandboxRunnerValuesSuppliesOnlyProjectRef(t *testing.T) {
+	t.Setenv("APP_STUDIO_SANDBOX_RUNNER_IMAGE", "ghcr.io/faroshq/kedge-sandbox-runner@sha256:runner")
+	t.Setenv("APP_STUDIO_SANDBOX_TOKEN_GENERATOR_IMAGE", "registry.example.com/kubectl@sha256:token")
 
 	values := sandboxRunnerValues("demo")
 	if got := values["projectRef"]; got != "demo" {
 		t.Fatalf("projectRef = %q, want demo", got)
 	}
-	if _, ok := values["runnerImage"]; ok {
-		t.Fatal("runnerImage must not default to a mutable development image")
-	}
-	if _, ok := values["tokenGeneratorImage"]; ok {
-		t.Fatal("tokenGeneratorImage must not default to a mutable development image")
-	}
-}
-
-func TestSandboxRunnerValuesUseConfiguredImages(t *testing.T) {
-	t.Setenv("APP_STUDIO_SANDBOX_RUNNER_IMAGE", " ghcr.io/faroshq/kedge-sandbox-runner@sha256:runner ")
-	t.Setenv("APP_STUDIO_SANDBOX_TOKEN_GENERATOR_IMAGE", " registry.example.com/kubectl@sha256:token ")
-
-	values := sandboxRunnerValues("demo")
-	if got := values["runnerImage"]; got != "ghcr.io/faroshq/kedge-sandbox-runner@sha256:runner" {
-		t.Fatalf("runnerImage = %q, want configured digest", got)
-	}
-	if got := values["tokenGeneratorImage"]; got != "registry.example.com/kubectl@sha256:token" {
-		t.Fatalf("tokenGeneratorImage = %q, want configured digest", got)
+	if len(values) != 1 {
+		t.Fatalf("sandboxRunnerValues = %#v, want only projectRef (image is a template schema default)", values)
 	}
 }

providers/app-studio/deploy/chart/templates/deployment.yaml

@@ -1,26 +1,11 @@
 {{- $catalogEntryConfigMap := and .Values.catalogEntry.enabled .Values.catalogEntry.renderAsConfigMap -}}
-{{- $sandboxRunnerImage := .Values.sandboxRunner.runnerImage | default "" -}}
-{{- $sandboxTokenGeneratorImage := .Values.sandboxRunner.tokenGeneratorImage | default "" -}}
 {{- $previewGatewayEnabled := .Values.previewGateway.enabled | default false -}}
 {{- $previewGatewayBaseDomain := .Values.previewGateway.baseDomain | default "" -}}
 {{- $previewGatewayFeatureEnabled := and $previewGatewayEnabled (ne (trim $previewGatewayBaseDomain) "") -}}
 {{- $previewGatewayServiceName := printf "%s-preview-gateway" (include "appstudio.fullname" .) | trunc 63 | trimSuffix "-" -}}
 {{- if and $previewGatewayFeatureEnabled (not .Values.previewTokenSecretRef.name) -}}
 {{- fail "previewGateway is enabled with baseDomain, but previewTokenSecretRef.name is required for shared preview tokens" -}}
 {{- end -}}
-{{- /*
-App Studio creates a SandboxRunner for every project's development environment,
-and the SandboxRunner spec requires both images. Require them unconditionally so
-a misconfigured install fails here instead of producing invalid SandboxRunner
-resources at runtime. (Image ownership moves to the infrastructure provider in a
-later phase; until then App Studio still passes them through.)
-*/ -}}
-{{- if not $sandboxRunnerImage -}}
-{{- fail "sandboxRunner.runnerImage is required; use an immutable digest reference" -}}
-{{- end -}}
-{{- if not $sandboxTokenGeneratorImage -}}
-{{- fail "sandboxRunner.tokenGeneratorImage is required; use an immutable digest reference" -}}
-{{- end -}}
 apiVersion: apps/v1
 kind: Deployment
 metadata:
@@ -106,12 +91,6 @@ spec:
             # calling user via the forwarded bearer token.
             - name: KEDGE_PROVIDER_KUBECONFIG
               value: /var/run/secrets/kedge/kedge-provider-kubeconfig
-            # Always set: the SandboxRunner spec requires both images, and the
-            # template above fails the install when either is unset.
-            - name: APP_STUDIO_SANDBOX_RUNNER_IMAGE
-              value: {{ $sandboxRunnerImage | quote }}
-            - name: APP_STUDIO_SANDBOX_TOKEN_GENERATOR_IMAGE
-              value: {{ $sandboxTokenGeneratorImage | quote }}
             {{- if $previewGatewayFeatureEnabled }}
             - name: APP_STUDIO_PREVIEW_BASE_DOMAIN
               value: {{ $previewGatewayBaseDomain | quote }}

providers/app-studio/deploy/chart/values.yaml

@@ -39,14 +39,10 @@ providerKubeconfig:
 # infrastructure provider as subresources on the SandboxRunner instance, reached
 # through the hub as the calling user. See docs/app-studio-runtime-decoupling.md.
 
-# Images passed into infrastructure-backed SandboxRunner resources. App Studio
-# creates a SandboxRunner for every project, and its spec requires both images,
-# so the chart fails the install when either is unset (independent of the
-# runtime kubeconfig). They are empty by default so installs do not silently
-# trust mutable development tags — set both to immutable digest references.
-sandboxRunner:
-  runnerImage: ""
-  tokenGeneratorImage: ""
+# The SandboxRunner runner image is NOT configured here — the sandbox-runner
+# template declares it as a schema field with a sane default (the web-app
+# convention). App Studio passes only the project reference. See
+# providers/infrastructure/docs/template-conventions.md.
 
 # Optional preview route deployment settings and companion infrastructure binding.
 # If baseDomain is empty, App Studio does not add the SandboxPreviewHTTPRoute

providers/infrastructure/backend/kro/backend.go

@@ -56,9 +56,10 @@ type Backend struct {
 	// tokens are the platform-config values substituted for reserved ${kedge.*}
 	// placeholders in a Template's backendConfig before the RGD is authored —
 	// platform-wide settings that belong on the backend, not in per-tenant data.
-	// See substituteTokens in rgd.go. Today: the exposure-layer Gateway parent
-	// (${kedge.gatewayName}/${kedge.gatewayNamespace}) and the sandbox runner
-	// images (${kedge.sandboxRunnerImage}/${kedge.sandboxTokenGeneratorImage}).
+	// See substituteTokens in rgd.go. The ONLY tokens are the exposure-layer
+	// Gateway parent (${kedge.gatewayName}/${kedge.gatewayNamespace}); per-instance
+	// inputs like container images are schema fields with defaults, not tokens
+	// (see providers/infrastructure/docs/template-conventions.md).
 	tokens map[string]string
 }
 
@@ -82,10 +83,11 @@ const (
 //
 //   - KEDGE_GATEWAY_NAME / KEDGE_GATEWAY_NAMESPACE — the exposure-layer Gateway
 //     parent (defaults "cloudflare-tunnel" / "cfgate-system").
-//   - KEDGE_SANDBOX_RUNNER_IMAGE / KEDGE_SANDBOX_TOKEN_GENERATOR_IMAGE — the
-//     images materialized into SandboxRunner workloads. The platform owns these
-//     (App Studio no longer injects them); deployments should pin immutable
-//     digests. Empty when unset — the chart guards against that at install.
+//
+// Per-instance inputs (container images, etc.) are NOT env tokens — templates
+// declare them as schema fields with sane defaults (e.g. SandboxRunner's
+// spec.runnerImage), the same convention every other template follows. See
+// providers/infrastructure/docs/template-conventions.md.
 func New(runtime dynamic.Interface) *Backend {
 	gatewayName := os.Getenv("KEDGE_GATEWAY_NAME")
 	if gatewayName == "" {
@@ -96,10 +98,8 @@ func New(runtime dynamic.Interface) *Backend {
 		gatewayNamespace = DefaultGatewayNamespace
 	}
 	tokens := map[string]string{
-		gatewayNameToken:           gatewayName,
-		gatewayNamespaceToken:      gatewayNamespace,
-		sandboxRunnerImageToken:    os.Getenv("KEDGE_SANDBOX_RUNNER_IMAGE"),
-		sandboxTokenGeneratorToken: os.Getenv("KEDGE_SANDBOX_TOKEN_GENERATOR_IMAGE"),
+		gatewayNameToken:      gatewayName,
+		gatewayNamespaceToken: gatewayNamespace,
 	}
 	return &Backend{runtime: runtime, tokens: tokens}
 }

providers/infrastructure/backend/kro/backend_test.go

@@ -162,27 +162,12 @@ func TestSubstituteTokensLeavesKroRefs(t *testing.T) {
 	}
 }
 
-func TestSubstituteTokensSandboxImages(t *testing.T) {
-	in := []byte(`{"runner":"${kedge.sandboxRunnerImage}","token":"${kedge.sandboxTokenGeneratorImage}"}`)
-	tokens := map[string]string{
-		sandboxRunnerImageToken:    "ghcr.io/faroshq/kedge-sandbox-runner@sha256:abc",
-		sandboxTokenGeneratorToken: "docker.io/bitnami/kubectl@sha256:def",
-	}
-	out := string(substituteTokens(in, tokens))
-	want := `{"runner":"ghcr.io/faroshq/kedge-sandbox-runner@sha256:abc","token":"docker.io/bitnami/kubectl@sha256:def"}`
-	if out != want {
-		t.Errorf("substituteTokens = %s, want %s", out, want)
-	}
-}
-
-// testTokens is the platform-config token map the backend builds from env,
-// with the gateway defaults and placeholder sandbox images, for buildRGD tests.
+// testTokens is the platform-config token map the backend builds from env (the
+// exposure-layer Gateway parent), for buildRGD tests.
 func testTokens() map[string]string {
 	return map[string]string{
-		gatewayNameToken:           DefaultGatewayName,
-		gatewayNamespaceToken:      DefaultGatewayNamespace,
-		sandboxRunnerImageToken:    "ghcr.io/faroshq/kedge-sandbox-runner:test",
-		sandboxTokenGeneratorToken: "docker.io/bitnami/kubectl:test",
+		gatewayNameToken:      DefaultGatewayName,
+		gatewayNamespaceToken: DefaultGatewayNamespace,
 	}
 }
 

providers/infrastructure/backend/kro/rgd.go

@@ -30,11 +30,6 @@ import (
 const (
 	gatewayNameToken      = "${kedge.gatewayName}"
 	gatewayNamespaceToken = "${kedge.gatewayNamespace}"
-	// sandboxRunnerImageToken / sandboxTokenGeneratorToken carry the images the
-	// SandboxRunner workload + its control-token Job run. The platform owns them
-	// (App Studio no longer injects them into the instance spec).
-	sandboxRunnerImageToken    = "${kedge.sandboxRunnerImage}"
-	sandboxTokenGeneratorToken = "${kedge.sandboxTokenGeneratorImage}"
 )
 
 const (