@specific.dev/spectest 0.90.3 → 0.91.0

package/dist/index.js

@@ -220,6 +220,19 @@ function expandServiceGroups(input) {
     }
     return out;
 }
+/** @internal Keep the wire format compatible with existing control planes. */
+export function normalizeServiceImage(image) {
+    if (typeof image === "string")
+        return { type: "registry", reference: image };
+    if (!image || typeof image !== "object" || Array.isArray(image))
+        throw new Error("image must be a registry reference or Dockerfile build");
+    if ("type" in image) {
+        if (image.type !== "registry" && image.type !== "dockerfile")
+            throw new Error("unsupported image type");
+        return image;
+    }
+    return { ...image, type: "dockerfile" };
+}
 /** A Dockerfile `ARG` name: what `docker build --build-arg` accepts as a key. */
 const BUILD_ARG_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
 function validateBuildArgs(serviceName, buildArgs) {
@@ -255,9 +268,17 @@ const BUILD_TARGET_RE = /^[^\s]+$/;
  * checks go through the project-file resolver, so the same rules as
  * `ctx.readProjectFile` apply.
  */
-export function validateServiceImage(serviceName, image) {
+export function validateServiceImage(serviceName, input) {
+    const image = normalizeServiceImage(input);
+    const reference = typeof input === "string" ? input : "reference" in input ? input.reference : undefined;
+    if (reference !== undefined && (typeof reference !== "string" || !reference || reference.startsWith("-") || /[\s\x00]/.test(reference)))
+        throw new Error(`service "${serviceName}" image reference must be a non-empty image name without whitespace`);
     if (image.type !== "dockerfile")
         return image;
+    if (reference?.includes("@"))
+        throw new Error(`service "${serviceName}" build reference must be an image name/tag, not a digest`);
+    if (image.exclude !== undefined && (!Array.isArray(image.exclude) || image.exclude.some(e => typeof e !== "string")))
+        throw new Error(`service "${serviceName}" image exclude must be an array of glob patterns`);
     validateBuildArgs(serviceName, image.buildArgs);
     const hasPath = typeof image.path === "string";
     const hasContent = typeof image.content === "string";
@@ -265,7 +286,7 @@ export function validateServiceImage(serviceName, image) {
         throw new Error(`service "${serviceName}" image sets both \`path\` and \`content\` — point at the Dockerfile in your repo with \`path\`, or inline it with \`content\`, not both`);
     }
     if (!hasPath && !hasContent) {
-        throw new Error(`service "${serviceName}" image { type: "dockerfile" } needs \`path\` (a Dockerfile in your repo, relative to the project root) or \`content\``);
+        throw new Error(`service "${serviceName}" image build needs \`path\` (a Dockerfile in your repo, relative to the project root) or \`content\``);
     }
     if (hasPath) {
         const file = resolveExistingProjectPath(image.path, `service "${serviceName}" Dockerfile`);
@@ -403,6 +424,8 @@ export function defineEnvironment(input) {
     const { fakes, services: rawServices, ...rest } = input;
     const expanded = expandServiceGroups(rawServices);
     for (const [key, svc] of Object.entries(expanded)) {
+        for (const build of svc.imageBuilds ?? [])
+            validateServiceImage(`${key} image ${build.reference}`, build.image);
         expanded[key] = applyCoverageAdapters(key, {
             ...svc,
             image: validateServiceImage(key, svc.image),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specific.dev/spectest",
-  "version": "0.90.3",
+  "version": "0.91.0",
   "description": "Spectest SDK for defining test environments in TypeScript.",
   "type": "module",
   "main": "./dist/index.js",

package/src/components/index.ts

@@ -26,6 +26,7 @@ export { SQL, type SqlClient, type SqlOptions } from "../sql.js";
 export {
   k3s,
   type K3sOptions,
+  type KubernetesImage,
   type K3sHelpers,
   type K3sClient,
   type TaggedObjectApi,

package/src/components/k3s-trust.test.ts

@@ -0,0 +1,81 @@
+import { afterEach, expect, test } from "bun:test";
+import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { execFileSync } from "node:child_process";
+import { request } from "node:https";
+import { installPodTrust, podTrustPatch, stopPodTrust, TRUST_OPT_OUT } from "./k3s-trust";
+
+function patched<T>(value: T, patch: ReturnType<typeof podTrustPatch>): T {
+  const out = structuredClone(value);
+  for (const operation of patch) {
+    const keys = operation.path.slice(1).split("/");
+    const key = keys.pop()!;
+    const parent = keys.reduce((o, k) => o[k], out as any);
+    if (key === "-") parent.push(operation.value); else parent[key] = operation.value;
+  }
+  return out;
+}
+
+test("mounts trust into regular and init containers without changing images or security settings", () => {
+  const pod = { spec: { containers: [{ name: "app", image: "app@sha256:original", securityContext: { runAsUser: 1000, readOnlyRootFilesystem: true } }], initContainers: [{ name: "init", image: "init:1" }] } };
+  const patch = podTrustPatch(pod, "bundle");
+  const result: any = patched(pod, patch);
+  expect(result.spec.containers[0].image).toBe("app@sha256:original");
+  expect(result.spec.containers[0].securityContext).toEqual(pod.spec.containers[0].securityContext);
+  expect(result.spec.initContainers[0].env).toContainEqual({ name: "SSL_CERT_FILE", value: "/spectest/ca-bundle.crt" });
+  expect(result.spec.volumes[0].configMap.name).toBe("bundle");
+  expect(result.spec.containers[0].volumeMounts.every((m: any) => m.readOnly)).toBe(true);
+  expect(podTrustPatch(result, "bundle")).toEqual([]);
+  expect(pod).not.toHaveProperty("spec.volumes");
+});
+
+test("preserves explicit trust settings and mounts, including volume name collisions", () => {
+  const pod = { spec: {
+    volumes: [{ name: "spectest-ca", emptyDir: {} }],
+    containers: [{ env: [{ name: "SSL_CERT_FILE", value: "/custom.pem" }], volumeMounts: [{ name: "custom", mountPath: "/etc/ssl" }] }],
+  } };
+  const result: any = patched(pod, podTrustPatch(pod, "bundle"));
+  expect(result.spec.volumes[1].name).toBe("spectest-ca-1");
+  expect(result.spec.containers[0].env.filter((e: any) => e.name === "SSL_CERT_FILE")).toEqual([{ name: "SSL_CERT_FILE", value: "/custom.pem" }]);
+  expect(result.spec.containers[0].volumeMounts.some((m: any) => m.mountPath === "/etc/ssl/certs/ca-certificates.crt")).toBe(false);
+});
+
+test("opt-out, Windows and ephemeral container updates are handled without changing immutable Pod volumes", () => {
+  expect(podTrustPatch({ metadata: { annotations: { [TRUST_OPT_OUT]: "false" } }, spec: { containers: [{}] } }, "bundle")).toEqual([]);
+  expect(podTrustPatch({ spec: { os: { name: "windows" }, containers: [{}] } }, "bundle")).toEqual([]);
+  expect(podTrustPatch({ spec: { ephemeralContainers: [{}] } }, "bundle", true)).toEqual([]);
+  const result: any = patched({ spec: { containers: [{}], ephemeralContainers: [{}], volumes: [{ name: "existing", configMap: { name: "bundle" } }] } }, podTrustPatch({ spec: { ephemeralContainers: [{}], volumes: [{ name: "existing", configMap: { name: "bundle" } }] } }, "bundle", true));
+  expect(result.spec.volumes).toHaveLength(1);
+  expect(result.spec.containers[0]).toEqual({});
+  expect(result.spec.ephemeralContainers[0].volumeMounts[0].name).toBe("existing");
+});
+
+afterEach(() => stopPodTrust("fixture"));
+test("admission uses verified TLS, provisions bundles on real requests, and fails closed", async () => {
+  const dir = mkdtempSync(join(tmpdir(), "k3s-trust-"));
+  try {
+    execFileSync("openssl", ["req", "-x509", "-newkey", "rsa:2048", "-nodes", "-keyout", join(dir, "key"), "-out", join(dir, "cert"), "-subj", "/CN=fixture", "-addext", "subjectAltName=IP:127.0.0.1", "-days", "1"], { stdio: "ignore" });
+    const cert = readFileSync(join(dir, "cert"), "utf8");
+    let config: any, calls = 0, fail = false;
+    await installPodTrust({ name: "fixture", gateway: "127.0.0.1", bundle: "bundle", cert, key: readFileSync(join(dir, "key"), "utf8"), ca: cert }, {
+      apply: async c => { config = c; },
+      ensureBundle: async namespace => { expect(namespace).toBe("app"); calls++; if (fail) throw new Error("API unavailable"); },
+    });
+    expect(config.webhooks[0].failurePolicy).toBe("Fail");
+    const send = (dryRun = false) => new Promise<{ status: number; body: any }>((resolve, reject) => {
+      const req = request(config.webhooks[0].clientConfig.url + "?timeout=10s", { method: "POST", ca: cert }, res => {
+        let body = ""; res.on("data", c => body += c); res.on("end", () => resolve({ status: res.statusCode!, body: res.statusCode === 200 ? JSON.parse(body) : body }));
+      });
+      req.on("error", reject);
+      req.end(JSON.stringify({ request: { uid: "request-1", resource: { resource: "pods" }, namespace: "app", dryRun, object: { spec: { containers: [{}] } } } }));
+    });
+    const dry = await send(true);
+    expect(dry.body.response.uid).toBe("request-1");
+    expect(calls).toBe(0);
+    expect((await send()).status).toBe(200);
+    expect(calls).toBe(1);
+    fail = true;
+    expect((await send()).status).toBe(500);
+  } finally { rmSync(dir, { recursive: true, force: true }); }
+});

package/src/components/k3s-trust.ts

@@ -0,0 +1,135 @@
+/** Pod trust belongs to the cluster. Admission adds read-only ConfigMap
+ * mounts and environment defaults, without changing any image bytes. */
+import { createHash, randomUUID } from "node:crypto";
+import { createServer, type Server } from "node:https";
+
+export const POD_CA_PATH = "/spectest/ca-bundle.crt";
+const TRUST_ENV: Readonly<Record<string, string>> = {
+  NODE_EXTRA_CA_CERTS: POD_CA_PATH, SSL_CERT_FILE: POD_CA_PATH,
+  REQUESTS_CA_BUNDLE: POD_CA_PATH, AWS_CA_BUNDLE: POD_CA_PATH,
+  PGSSLROOTCERT: POD_CA_PATH, DENO_TLS_CA_STORE: "mozilla,system",
+};
+const MOUNT_PATHS = [POD_CA_PATH, "/etc/ssl/certs/ca-certificates.crt", "/etc/pki/tls/certs/ca-bundle.crt"];
+interface Container {
+  env?: { name: string; value?: string; valueFrom?: unknown }[];
+  volumeMounts?: { name: string; mountPath: string; subPath?: string; readOnly?: boolean }[];
+}
+interface Pod {
+  metadata?: { annotations?: Record<string, string> };
+  spec?: {
+    os?: { name: string };
+    volumes?: { name: string; configMap?: { name: string }; [key: string]: unknown }[];
+    containers?: Container[]; initContainers?: Container[]; ephemeralContainers?: Container[];
+  };
+}
+interface Patch { op: "add"; path: string; value: unknown }
+export const TRUST_OPT_OUT = "spectest.dev/inject-ca";
+
+export function podTrustPatch(pod: Pod, configMap: string, ephemeral = false): Patch[] {
+  if (!pod.spec || pod.spec.os?.name === "windows" || pod.metadata?.annotations?.[TRUST_OPT_OUT] === "false") return [];
+  const patches: Patch[] = [];
+  const volumes = pod.spec.volumes ?? [];
+  // Reuse our immutable ConfigMap, but never overwrite a user's volume.
+  let volume = volumes.find(v => v.configMap?.name === configMap)?.name;
+  if (!volume && ephemeral) return []; // Pod volumes cannot change on this subresource.
+  if (!volume) {
+    const names = new Set(volumes.map(v => v.name));
+    volume = "spectest-ca";
+    for (let n = 1; names.has(volume); n++) volume = `spectest-ca-${n}`;
+    const value = { name: volume, configMap: { name: configMap, defaultMode: 0o444, items: [{ key: "ca-bundle.crt", path: "ca-bundle.crt" }] } };
+    patches.push(pod.spec.volumes
+      ? { op: "add", path: "/spec/volumes/-", value }
+      : { op: "add", path: "/spec/volumes", value: [value] });
+  }
+  const groups = ephemeral ? ["ephemeralContainers"] as const : ["containers", "initContainers"] as const;
+  for (const group of groups) {
+    for (const [index, container] of (pod.spec[group] ?? []).entries()) {
+      const prefix = `/spec/${group}/${index}`;
+      const env = container.env ?? [];
+      const names = new Set(env.map(e => e.name));
+      const extraEnv = Object.entries(TRUST_ENV).filter(([name]) => !names.has(name)).map(([name, value]) => ({ name, value }));
+      const mounts = container.volumeMounts ?? [];
+      // A user mount at a path (or a parent directory) owns that path.
+      const extraMounts = MOUNT_PATHS.filter(path => !mounts.some(m => path === m.mountPath || path.startsWith(m.mountPath.replace(/\/$/, "") + "/")))
+        .map(mountPath => ({ name: volume!, mountPath, subPath: "ca-bundle.crt", readOnly: true }));
+      if (extraEnv.length) patches.push({ op: "add", path: `${prefix}/env`, value: [...env, ...extraEnv] });
+      if (extraMounts.length) patches.push({ op: "add", path: `${prefix}/volumeMounts`, value: [...mounts, ...extraMounts] });
+    }
+  }
+  return patches;
+}
+
+interface AdmissionRequest {
+  uid: string; namespace?: string; dryRun?: boolean; subResource?: string;
+  resource?: { resource: string }; object?: Pod;
+}
+export interface TrustDependencies {
+  /** Ensure this immutable ConfigMap exists in the requesting namespace. */
+  ensureBundle(namespace: string, name: string, bundle: string): Promise<void>;
+  apply(configuration: unknown): Promise<void>;
+}
+const servers = new Map<string, Server>();
+
+export async function installPodTrust(options: {
+  name: string; gateway: string; bundle: string; cert: string; key: string; ca: string;
+}, deps: TrustDependencies): Promise<void> {
+  const configMap = `spectest-ca-${createHash("sha256").update(options.bundle).digest("hex").slice(0, 20)}`;
+  const endpoint = `/admit/${randomUUID()}`;
+  const server = createServer({ cert: options.cert, key: options.key }, async (req, res) => {
+    if (req.method !== "POST" || new URL(req.url ?? "/", "https://local").pathname !== endpoint) { res.writeHead(404).end(); return; }
+    const chunks: Buffer[] = [];
+    let size = 0;
+    try {
+      for await (const chunk of req) {
+        size += chunk.length;
+        if (size > 2 * 1024 * 1024) { res.writeHead(413).end(); return; }
+        chunks.push(Buffer.from(chunk));
+      }
+      const review = JSON.parse(Buffer.concat(chunks).toString());
+      const request = review.request as AdmissionRequest | undefined;
+      if (!request?.uid || request.resource?.resource !== "pods" || !request.object || !request.namespace) {
+        res.writeHead(400).end("invalid Pod admission request"); return;
+      }
+      const patch = podTrustPatch(request.object, configMap, request.subResource === "ephemeralcontainers");
+      // Dry runs return the same patch but perform no API writes.
+      if (patch.length && !request.dryRun) await deps.ensureBundle(request.namespace, configMap, options.bundle);
+      res.setHeader("Content-Type", "application/json");
+      res.end(JSON.stringify({ apiVersion: "admission.k8s.io/v1", kind: "AdmissionReview", response: {
+        uid: request.uid, allowed: true,
+        ...(patch.length ? { patchType: "JSONPatch", patch: Buffer.from(JSON.stringify(patch)).toString("base64") } : {}),
+      } }));
+    } catch (err) {
+      console.error(`[k3s-trust] ${options.name}: ${err instanceof Error ? err.message : err}`);
+      res.writeHead(500).end("could not mount the environment CA");
+    }
+  });
+  server.requestTimeout = 15_000;
+  try {
+    await new Promise<void>((resolve, reject) => { server.once("error", reject); server.listen(0, options.gateway, resolve); });
+    const port = (server.address() as { port: number }).port;
+    await deps.apply({
+      apiVersion: "admissionregistration.k8s.io/v1", kind: "MutatingWebhookConfiguration",
+      metadata: { name: "spectest-pod-trust" },
+      webhooks: [{
+        name: "pod-trust.spectest.dev", admissionReviewVersions: ["v1"],
+        sideEffects: "NoneOnDryRun", failurePolicy: "Fail", timeoutSeconds: 10,
+        reinvocationPolicy: "IfNeeded", matchPolicy: "Equivalent",
+        clientConfig: { url: `https://${options.gateway}:${port}${endpoint}`, caBundle: Buffer.from(options.ca).toString("base64") },
+        rules: [{ operations: ["CREATE"], apiGroups: [""], apiVersions: ["v1"], resources: ["pods"], scope: "Namespaced" },
+          { operations: ["UPDATE"], apiGroups: [""], apiVersions: ["v1"], resources: ["pods/ephemeralcontainers"], scope: "Namespaced" }],
+      }],
+    });
+  } catch (err) {
+    server.closeAllConnections(); server.close(); throw err;
+  }
+  const previous = servers.get(options.name);
+  servers.set(options.name, server);
+  previous?.closeAllConnections(); previous?.close();
+}
+
+/** Release a component listener on replacement or in standalone tests. */
+export function stopPodTrust(name: string): void {
+  const server = servers.get(name);
+  servers.delete(name);
+  server?.closeAllConnections(); server?.close();
+}

package/src/components/k3s.ts

@@ -1,3 +1,6 @@
+import { isIP } from "node:net";
+import { installPodTrust } from "./k3s-trust.js";
+import { loadK3sBuildImages } from "../harness/k3s-image-loader.js";
 import { AsyncLocalStorage } from "node:async_hooks";
 import { spawn as nodeSpawn } from "node:child_process";
 import { randomUUID } from "node:crypto";
@@ -31,6 +34,7 @@ import { Observable } from "@kubernetes/client-node/dist/gen/rxjsStub.js";
 import type {
   ServiceDefinition,
   ServiceHelpersContext,
+  ServiceSetupContext,
   SpectestContext,
 } from "../index.js";
 import { dnsName, provides, SELF_SERVICE_TOKEN } from "../index.js";
@@ -41,6 +45,11 @@ import {
   nestedStoreDir,
   type ImageCachePaths,
 } from "../harness/image-cache.js";
+import { stickyDiskPathSync } from "../harness/sticky-paths.js";
+import { registerStickyKubernetesStore, stickyKubernetesDirectory } from "../harness/sticky-kubernetes.js";
+import { prePullK3sImages } from "../harness/k3s-prepull.js";
+import { componentRuntime, kubernetesImages, type KubernetesImage } from "../harness/component-images.js";
+export type { KubernetesImage } from "../harness/component-images.js";
 import { deepUnwrap, readTag, wrap } from "../inspect.js";
 import type { Wrapped } from "../inspect.js";
 import { recorderAnnotate, recorderRemove } from "../recorder.js";
@@ -50,7 +59,19 @@ export type {
   KubernetesListObject,
 } from "@kubernetes/client-node";
 
+/** Kubernetes pods receive read-only environment CA mounts during admission.
+ * Image bytes and digests stay unchanged; explicit pod trust settings win. */
 export interface K3sOptions {
+  /** Images available to kubelet before project setup. Use registry strings,
+   * or Dockerfile builds with a full `reference` matching your manifests. Builds
+   * support path/content, context, exclude, target and buildArgs, and run in
+   * parallel with service builds through the standard BuildKit pipeline.
+   * Setup waits for every pull and fails if a requested image cannot be pulled.
+   * Sticky-enabled projects retain image content and unpacked layers between
+   * fresh builds automatically. Digest references can reuse the cache offline;
+   * tags are resolved again on each fresh setup. Pod imagePullPolicy still applies.
+   */
+  images?: readonly KubernetesImage[];
   /**
    * Image tag for the official `rancher/k3s` image. Default
    * `"v1.33.5-k3s1"`. Any tag works; a k3s older than 1.33 embeds a
@@ -178,8 +199,13 @@ const CRI_MANAGED_LABEL = "io.cri-containerd.image=managed";
 const BOOT_MARKER = ".spectest-boot-incomplete";
 
 /**
- * The cluster's image store, and how it shares the environment's image
- * cache (`CONTAINER_STORE.md` §12).
+ * Sticky-enabled projects bind a per-service/version directory on the
+ * sticky disk at CLUSTER_STORE_TARGET and use overlayfs. Publication's
+ * sticky-kubernetes adapter removes runtime state and retains images and
+ * unpacked layers under the shared filesystem budget. Test forks do not
+ * write back. The preparation wrapper below also handles delta rebuilds.
+ *
+ * Legacy image-cache integration (`CONTAINER_STORE.md` §12):
  *
  * The cluster's embedded containerd keeps its root on the **root disk**
  * of the environment's image cache, in a directory of its own
@@ -346,8 +372,8 @@ function storePrepareSh(cache: ImageCachePaths | null): string {
     `timeout 60 ctr -a "$A" -n k8s.io containers rm $ids >/dev/null 2>&1 || true; fi; ` +
     // containerd 2.x keeps sandboxes in a store of their own; on the 1.7
     // k3s ships they are ordinary containers and this is a no-op.
-    `sb=$(timeout 30 ctr -a "$A" -n k8s.io sandboxes ls -q 2>/dev/null); ` +
-    `[ -n "$sb" ] && timeout 60 ctr -a "$A" -n k8s.io sandboxes rm $sb >/dev/null 2>&1; return 0; }; ` +
+    `sb=$(timeout 30 ctr -a "$A" -n k8s.io sandboxes ls 2>/dev/null | awk 'NR > 1 {print $1}'); ` +
+    `[ -n "$sb" ] && timeout 60 ctr -a "$A" -n k8s.io sandboxes rm --force $sb >/dev/null 2>&1; return 0; }; ` +
     adopt +
     `if [ -e "$M" ]; then ` +
     `echo 'spectest: the previous cluster on this image store never became ready; starting from an empty one' >&2; ` +
@@ -724,7 +750,7 @@ async function issueIngressCert(
   const id = `spectest-k3s-ingress-${randomUUID().slice(0, 8)}`;
   const keyPath = `/tmp/${id}.key`;
   const crtPath = `/tmp/${id}.crt`;
-  const sans = hostnames.map((h) => `DNS:${h}`).join(",");
+  const sans = hostnames.map((h) => `${isIP(h) ? "IP" : "DNS"}:${h}`).join(",");
   const r = await runProcess(
     "openssl",
     [
@@ -2007,6 +2033,7 @@ const DEFAULT_K3S_VERSION = "v1.33.5-k3s1";
 
 export function k3s(opts: K3sOptions = {}) {
   const version = opts.version ?? DEFAULT_K3S_VERSION;
+  const images = kubernetesImages(opts.images ?? []);
   const extra = opts.extraArgs ?? [];
   assertUsableExtraArgs(extra);
   const registryEnabled = opts.registry !== false;
@@ -2023,7 +2050,8 @@ export function k3s(opts: K3sOptions = {}) {
   // The environment's image cache, when this VM carries one: the
   // cluster's store goes on its root disk and its layers come off the
   // shared layers disk (see the store section above).
-  const cache = imageCachePathsSync();
+  const sticky = stickyDiskPathSync();
+  const cache = sticky ? null : imageCachePathsSync();
   const serverArgs = [
     "k3s",
     "server",
@@ -2122,6 +2150,7 @@ export function k3s(opts: K3sOptions = {}) {
   const readyCmd = `kubectl get --raw=/readyz >/dev/null 2>&1 && rm -f ${CLUSTER_STORE_TARGET}/${BOOT_MARKER}`;
   const def = {
     image: { type: "registry", reference: `rancher/k3s:${version}` },
+    imageBuilds: images.builds,
     command: cmd,
     privileged: true,
     tmpfs: ["/run", "/var/run"],
@@ -2135,15 +2164,17 @@ export function k3s(opts: K3sOptions = {}) {
     // the same netns and are reachable the same way, without appearing
     // in this list (it's documentation, not a firewall).
     ports: registryEnabled ? [80, 443, 6443, K3S_REGISTRY_PORT] : [80, 443, 6443],
-    // The cluster's image store (see the store section above): its
+    // Sticky disks retain an independent overlayfs store per service/version.
+    // The legacy image cache (see the store section above) keeps its
     // containerd root on the image cache's root disk, the shared layers
     // disk read-only at its guest path, golden's mkfs.erofs and the adopt
     // helper — or, with no cache, a per-environment volume. Two clusters
     // in one environment get separate roots either way (the service
     // token names the directory), because two containerd daemons cannot
     // share a store: bolt takes an exclusive lock.
-    volumes: cache
-      ? [
+    volumes: sticky
+      ? [{ source: `${stickyKubernetesDirectory(SELF_SERVICE_TOKEN, version)}/containerd`, target: CLUSTER_STORE_TARGET }]
+      : cache ? [
           { source: nestedStoreDir(cache, SELF_SERVICE_TOKEN), target: CLUSTER_STORE_TARGET },
           { source: cache.layers, target: cache.layers, readOnly: true },
           { source: MKFS_EROFS_PATH, target: MKFS_EROFS_PATH, readOnly: true },
@@ -2164,12 +2195,52 @@ export function k3s(opts: K3sOptions = {}) {
       command: readyCmd,
       timeoutSecs: opts.readyTimeoutSecs ?? 120,
     },
-    setup: async ({ name, helpers }: { name: string; helpers: K3sHelpers }) => {
+    setup: async (ctx: ServiceSetupContext<K3sHelpers>) => {
+      const { name, helpers, exec } = ctx;
+      const runtime = componentRuntime(ctx);
+      if (images.builds.length && !runtime) throw new Error(`k3s(${name}): prepared image inputs are missing`);
+      if (runtime?.caBundle && caPresent()) {
+        const { cert, key } = await issueIngressCert([runtime.gateway]);
+        await installPodTrust({ name, gateway: runtime.gateway, cert, key,
+          ca: await readFile(CA_PATH, "utf8"), bundle: await readFile(runtime.caBundle, "utf8"),
+        }, {
+          apply: async configuration => { await helpers.apply(JSON.stringify(configuration)); },
+          ensureBundle: async (namespace, configMap, bundle) => {
+            try {
+              await helpers.client.core.createNamespacedConfigMap({ namespace, body: {
+                metadata: { name: configMap, namespace }, immutable: true, data: { "ca-bundle.crt": bundle },
+              } });
+            } catch (err) {
+              // A simultaneous Pod may have created the same namespace's bundle.
+              const existing = (await helpers.client.core.readNamespacedConfigMap({ namespace, name: configMap })).unwrap();
+              if (existing.data?.["ca-bundle.crt"] !== bundle || existing.immutable !== true) throw err;
+            }
+          },
+        });
+        // The API server observes webhook registration asynchronously. A dry-run
+        // Pod proves TLS reachability and admission before any project workload.
+        const deadline = Date.now() + 30_000;
+        for (;;) {
+          try {
+            const pod = (await helpers.client.core.createNamespacedPod({ namespace: "default", dryRun: "All", body: {
+              metadata: { generateName: "spectest-trust-probe-" }, spec: { containers: [{ name: "probe", image: "registry.k8s.io/pause:3.10" }] },
+            } })).unwrap();
+            if (pod.spec?.containers[0].env?.some(e => e.name === "SSL_CERT_FILE" && e.value === "/spectest/ca-bundle.crt")) break;
+            if (Date.now() >= deadline) throw new Error(`k3s(${name}): Pod CA mounts did not become ready`);
+          } catch (err) {
+            if (Date.now() >= deadline) throw err;
+          }
+          await new Promise(resolve => setTimeout(resolve, 100));
+        }
+      }
+      if (runtime) await loadK3sBuildImages(name, runtime.images, runtime.gateway, exec);
       await setupK3sCluster(name, helpers, {
         registry: registryEnabled,
         ingressDomains,
         traefik: traefikEnabled,
       });
+      await prePullK3sImages(name, images.pulls, exec);
+      if (sticky) await registerStickyKubernetesStore(name, version);
     },
     helpers: async ({ name, exec, poll }: ServiceHelpersContext): Promise<K3sHelpers> => {
       // Read the cluster's kubeconfig and address the API server by its