@specific.dev/spectest 0.90.3 → 0.91.1

package/dist/android-step.js

@@ -15,7 +15,7 @@ export function androidTargetLabel(target) {
         case "id":
             return `id ${quoted}`;
         case "accessibility":
-            return `accessibility label ${quoted}`;
+            return `label ${quoted}`;
         case "xpath":
             return `XPath ${quoted}`;
         case "custom":
@@ -74,5 +74,5 @@ export function androidStepTitle(step) {
             label = `run command ${JSON.stringify(step.command)}`;
             break;
     }
-    return `${step.device}: ${label}`;
+    return label;
 }

package/dist/components/expo.d.ts

@@ -103,6 +103,7 @@ export declare function nodeMajorFromRange(range: string): number | null;
 export declare function expo(opts?: ExpoOptions): {
     image: {
         type: "dockerfile";
+        reference?: string;
         path: string;
         content?: never;
         context?: string;
@@ -111,6 +112,7 @@ export declare function expo(opts?: ExpoOptions): {
         buildArgs?: Readonly<Record<string, string>>;
     } | {
         type: "dockerfile";
+        reference?: string;
         content: string;
         path?: never;
         context?: string;

package/dist/components/index.d.ts

@@ -2,7 +2,7 @@ export { temporal, temporalClient, type TemporalOptions, type TemporalClient, ty
 export { postgres, type PostgresOptions, type PostgresHelpers, } from "./postgres.js";
 export { s3, type S3Options, type S3Helpers, } from "./s3.js";
 export { SQL, type SqlClient, type SqlOptions } from "../sql.js";
-export { k3s, type K3sOptions, type K3sHelpers, type K3sClient, type TaggedObjectApi, type KubernetesObjectRef, type ApplyOptions, type RolloutTarget, type WaitOptions, type LogsOptions, type KubernetesObject, type KubernetesListObject, } from "./k3s.js";
+export { k3s, type K3sOptions, type KubernetesImage, type K3sHelpers, type K3sClient, type TaggedObjectApi, type KubernetesObjectRef, type ApplyOptions, type RolloutTarget, type WaitOptions, type LogsOptions, type KubernetesObject, type KubernetesListObject, } from "./k3s.js";
 export { expo, type ExpoOptions, type ExpoHelpers, type ExpoPackageManager, } from "./expo.js";
 export { supabase, type SupabaseOptions, type SupabaseHelpers, type SupabaseStack, } from "./supabase.js";
 export { email, type EmailOptions, type EmailHelpers, type EmailMessage, type EmailSummary, type EmailMatch, type EmailAttachment, } from "./email.js";

package/dist/components/k3s-trust.d.ts

@@ -0,0 +1,57 @@
+export declare const POD_CA_PATH = "/spectest/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 declare const TRUST_OPT_OUT = "spectest.dev/inject-ca";
+export declare function podTrustPatch(pod: Pod, configMap: string, ephemeral?: boolean): Patch[];
+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>;
+}
+export declare function installPodTrust(options: {
+    name: string;
+    gateway: string;
+    bundle: string;
+    cert: string;
+    key: string;
+    ca: string;
+}, deps: TrustDependencies): Promise<void>;
+/** Release a component listener on replacement or in standalone tests. */
+export declare function stopPodTrust(name: string): void;
+export {};

package/dist/components/k3s-trust.js

@@ -0,0 +1,125 @@
+/** 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 } from "node:https";
+export const POD_CA_PATH = "/spectest/ca-bundle.crt";
+const TRUST_ENV = {
+    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"];
+export const TRUST_OPT_OUT = "spectest.dev/inject-ca";
+export function podTrustPatch(pod, configMap, ephemeral = false) {
+    if (!pod.spec || pod.spec.os?.name === "windows" || pod.metadata?.annotations?.[TRUST_OPT_OUT] === "false")
+        return [];
+    const patches = [];
+    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"] : ["containers", "initContainers"];
+    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;
+}
+const servers = new Map();
+export async function installPodTrust(options, deps) {
+    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 = [];
+        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;
+            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((resolve, reject) => { server.once("error", reject); server.listen(0, options.gateway, resolve); });
+        const port = server.address().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) {
+    const server = servers.get(name);
+    servers.delete(name);
+    server?.closeAllConnections();
+    server?.close();
+}

package/dist/components/k3s.d.ts

@@ -1,8 +1,22 @@
 import { AppsV1Api, BatchV1Api, CoreV1Api, KubeConfig, PatchStrategy, type KubernetesListObject, type KubernetesObject, type V1DeleteOptions, type V1Job, type V1Status } from "@kubernetes/client-node";
-import type { ServiceHelpersContext } from "../index.js";
+import type { ServiceHelpersContext, ServiceSetupContext } from "../index.js";
+import { type KubernetesImage } from "../harness/component-images.js";
+export type { KubernetesImage } from "../harness/component-images.js";
 import type { Wrapped } from "../inspect.js";
 export type { KubernetesObject, 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
@@ -319,6 +333,7 @@ export declare function k3s(opts?: K3sOptions): {
         type: "registry";
         reference: string;
     };
+    imageBuilds: import("../index.js").ComponentImageBuild[];
     command: string;
     privileged: true;
     tmpfs: string[];
@@ -344,9 +359,6 @@ export declare function k3s(opts?: K3sOptions): {
         command: string;
         timeoutSecs: number;
     };
-    setup: ({ name, helpers }: {
-        name: string;
-        helpers: K3sHelpers;
-    }) => Promise<void>;
+    setup: (ctx: ServiceSetupContext<K3sHelpers>) => Promise<void>;
     helpers: ({ name, exec, poll }: ServiceHelpersContext) => Promise<K3sHelpers>;
 };

package/dist/components/k3s.js

@@ -1,3 +1,7 @@
+import { isIP } from "node:net";
+import { installPodTrust } from "./k3s-trust.js";
+import { waitForAll } from "../harness/concurrency.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";
@@ -7,6 +11,10 @@ import { AppsV1Api, BatchV1Api, CoreV1Api, KubeConfig, KubernetesObjectApi, Patc
 import { Observable } from "@kubernetes/client-node/dist/gen/rxjsStub.js";
 import { dnsName, provides, SELF_SERVICE_TOKEN } from "../index.js";
 import { MKFS_EROFS_PATH, STORE_ADOPT_PATH, imageCachePathsSync, nestedStoreDir, } 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 } from "../harness/component-images.js";
 import { deepUnwrap, readTag, wrap } from "../inspect.js";
 import { recorderAnnotate, recorderRemove } from "../recorder.js";
 /** Port the in-cluster registry listens on (plain HTTP). */
@@ -32,8 +40,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
@@ -195,8 +208,8 @@ function storePrepareSh(cache) {
         `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; ` +
@@ -287,7 +300,7 @@ async function issueIngressCert(hostnames) {
     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", [
         "req",
         "-newkey",
@@ -1231,48 +1244,51 @@ async function waitForJob(deps, name, opts) {
  * reachable over HTTPS with a cert the test framework already trusts.
  */
 async function setupK3sCluster(name, helpers, opts) {
-    const tlsEnabled = opts.traefik && opts.ingressDomains.length > 0 && caPresent();
-    if (tlsEnabled) {
-        const { cert, key } = await issueIngressCert(opts.ingressDomains.map((d) => `*.${d}`));
-        // Apply the cert Secret + dynamic-config ConfigMap before the
-        // Deployment that mounts them. `stringData` lets us hand over plain
-        // PEM; the API server base64-encodes it.
-        await helpers.client.core.createNamespacedSecret({
-            namespace: "kube-system",
-            body: {
-                metadata: { name: TRAEFIK_TLS_SECRET, namespace: "kube-system" },
-                type: "kubernetes.io/tls",
-                stringData: { "tls.crt": cert, "tls.key": key },
-            },
-        });
-        await helpers.client.core.createNamespacedConfigMap({
-            namespace: "kube-system",
-            body: {
-                metadata: {
-                    name: TRAEFIK_DYNAMIC_CONFIGMAP,
-                    namespace: "kube-system",
-                },
-                data: { "tls.yaml": TRAEFIK_DYNAMIC_TLS },
-            },
-        });
-    }
-    if (opts.traefik)
-        await helpers.apply(buildTraefikManifest(tlsEnabled));
-    if (opts.registry)
-        await helpers.apply(REGISTRY_MANIFEST);
-    // Both rollouts proceed independently inside the cluster — wait on them
-    // concurrently (they used to serialize, wasting up to a rollout's tail).
-    // 250ms polling: these two sit on the cold start's critical path, where
-    // the default 500ms interval wastes real time.
+    // The registry can start while Traefik's certificates are being prepared.
     const wait = (deployment) => helpers.waitForRollout(deployment, {
         namespace: "kube-system",
         timeoutMs: 120_000,
         intervalMs: 250,
     });
-    const waits = opts.traefik ? [wait("traefik")] : [];
-    if (opts.registry)
-        waits.push(wait("spectest-registry"));
-    await Promise.all(waits);
+    await waitForAll([
+        (async () => {
+            if (!opts.traefik)
+                return;
+            const tlsEnabled = opts.ingressDomains.length > 0 && caPresent();
+            if (tlsEnabled) {
+                const { cert, key } = await issueIngressCert(opts.ingressDomains.map((d) => `*.${d}`));
+                // Apply the cert Secret + dynamic-config ConfigMap before the
+                // Deployment that mounts them. `stringData` lets us hand over plain
+                // PEM; the API server base64-encodes it.
+                await helpers.client.core.createNamespacedSecret({
+                    namespace: "kube-system",
+                    body: {
+                        metadata: { name: TRAEFIK_TLS_SECRET, namespace: "kube-system" },
+                        type: "kubernetes.io/tls",
+                        stringData: { "tls.crt": cert, "tls.key": key },
+                    },
+                });
+                await helpers.client.core.createNamespacedConfigMap({
+                    namespace: "kube-system",
+                    body: {
+                        metadata: {
+                            name: TRAEFIK_DYNAMIC_CONFIGMAP,
+                            namespace: "kube-system",
+                        },
+                        data: { "tls.yaml": TRAEFIK_DYNAMIC_TLS },
+                    },
+                });
+            }
+            await helpers.apply(buildTraefikManifest(tlsEnabled));
+            await wait("traefik");
+        })(),
+        (async () => {
+            if (!opts.registry)
+                return;
+            await helpers.apply(REGISTRY_MANIFEST);
+            await wait("spectest-registry");
+        })(),
+    ]);
 }
 /**
  * Snapshot of a namespace's state, dumped whenever a wait times out: pod
@@ -1393,6 +1409,7 @@ async function collectDiagnostics(client, namespace) {
 const DEFAULT_K3S_VERSION = "v1.33.5-k3s1";
 export function k3s(opts = {}) {
     const version = opts.version ?? DEFAULT_K3S_VERSION;
+    const images = kubernetesImages(opts.images ?? []);
     const extra = opts.extraArgs ?? [];
     assertUsableExtraArgs(extra);
     const registryEnabled = opts.registry !== false;
@@ -1409,7 +1426,8 @@ export function k3s(opts = {}) {
     // 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",
@@ -1507,6 +1525,7 @@ export function k3s(opts = {}) {
     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"],
@@ -1520,21 +1539,23 @@ export function k3s(opts = {}) {
         // 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 },
                 { source: STORE_ADOPT_PATH, target: STORE_ADOPT_PATH, readOnly: true },
             ]
-            : [{ target: CLUSTER_STORE_TARGET }],
+                : [{ target: CLUSTER_STORE_TARGET }],
         files: [
             ...(registriesYaml ? [{ path: "/etc/rancher/k3s/registries.yaml", content: registriesYaml }] : []),
             ...(cache
@@ -1549,12 +1570,64 @@ export function k3s(opts = {}) {
             command: readyCmd,
             timeoutSecs: opts.readyTimeoutSecs ?? 120,
         },
-        setup: async ({ name, helpers }) => {
-            await setupK3sCluster(name, helpers, {
-                registry: registryEnabled,
-                ingressDomains,
-                traefik: traefikEnabled,
-            });
+        setup: async (ctx) => {
+            const { name, helpers, exec } = ctx;
+            const runtime = componentRuntime(ctx);
+            if (images.builds.length && !runtime)
+                throw new Error(`k3s(${name}): prepared image inputs are missing`);
+            await waitForAll([
+                runtime ? loadK3sBuildImages(name, runtime.images, runtime.gateway, exec) : Promise.resolve(),
+                prePullK3sImages(name, images.pulls, exec),
+                (async () => {
+                    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));
+                        }
+                    }
+                    await setupK3sCluster(name, helpers, {
+                        registry: registryEnabled,
+                        ingressDomains,
+                        traefik: traefikEnabled,
+                    });
+                })(),
+            ]);
+            if (sticky)
+                await registerStickyKubernetesStore(name, version);
         },
         helpers: async ({ name, exec, poll }) => {
             // Read the cluster's kubeconfig and address the API server by its