@specific.dev/spectest 0.26.0 → 0.28.0

package/dist/components/k3s.d.ts

@@ -0,0 +1,172 @@
+import { AppsV1Api, CoreV1Api, KubeConfig, KubernetesObjectApi, type KubernetesObject } from "@kubernetes/client-node";
+import type { ServiceHelpersContext } from "../index.js";
+import type { Wrapped } from "../inspect.js";
+export interface K3sOptions {
+    /** Image tag for the official `rancher/k3s` image. Default `"v1.30.6-k3s1"`. */
+    version?: string;
+    /**
+     * Extra arguments appended to `k3s server`. Useful for `--tls-san=...`,
+     * additional `--disable=<addon>`, custom CIDRs, etc.
+     *
+     * Two values are **rejected** rather than silently ignored, because the
+     * component owns those decisions and passing them here has no effect:
+     * `--disable=traefik` (use `traefik: false`) and `--disable=servicelb`
+     * (use `loadBalancer: false`).
+     */
+    extraArgs?: string[];
+    /**
+     * Install the component's own Traefik ingress controller (hostNetwork,
+     * default IngressClass, wired to the in-VM CA when `ingressDomains` is
+     * set). Default `true`.
+     *
+     * Set `false` to run a cluster with no ingress controller at all — for
+     * a project that installs its own (via Helm, an operator, or a raw
+     * manifest) and wants the port to itself. The bundled k3s Traefik is
+     * disabled either way, so `false` really does mean none.
+     */
+    traefik?: boolean;
+    /**
+     * Run k3s's ServiceLB (klipper-lb) so `type: LoadBalancer` Services are
+     * assigned an address instead of sitting at `<pending>` forever.
+     * Default `true`.
+     *
+     * The assigned address is the **node IP** — the k3s container's own IP
+     * on `spectest-net` — so a LoadBalancer on port 8080 is reachable from
+     * a test or a peer service at `<cluster-key>.internal:8080`. Because
+     * klipper-lb binds the port on the node, a LoadBalancer that asks for
+     * port 80 or 443 collides with the component's hostNetwork Traefik;
+     * either pick another port or pass `traefik: false`.
+     */
+    loadBalancer?: boolean;
+    /**
+     * Readiness probe timeout in seconds. k3s on a warm image is ready in
+     * a few seconds; the first cold start of an env (image pull + cluster
+     * bootstrap) can take 30–60s. Default `120`.
+     */
+    readyTimeoutSecs?: number;
+    /**
+     * Run an in-cluster OCI registry (CNCF `distribution` / `registry:2`)
+     * that the cluster's own containerd trusts. This is the hermetic
+     * stand-in for a cloud registry (ECR/GCR/GHCR): a peer service builds
+     * an image, pushes it here over plain HTTP, references
+     * `<cluster-key>.internal:5000/...` from a Deployment, and the kubelet
+     * pulls it straight back. Lets you test a real
+     * `build → push → deploy → pull` pipeline with no external registry
+     * and no image pre-baking.
+     *
+     * **The registry's push/pull address is `<cluster-key>.internal:5000`**,
+     * where `<cluster-key>` is the key you give this service in the
+     * `services` map (e.g. a cluster at `services.cluster` is reachable at
+     * `cluster.internal:5000`). That's the cluster service's own
+     * unconditional `.internal` alias — peer-reachable and never clobbered
+     * by any `hostnames` you set — so it resolves identically from peer
+     * containers (push) and the cluster's own containerd (pull). Wire it
+     * into your platform, e.g. `env: { REGISTRY_URL: "cluster.internal:5000" }`.
+     * Plain HTTP, so configure your push client for an insecure registry.
+     *
+     * On by default. Set `false` for clusters that only ever run public
+     * images — that skips the extra pod.
+     */
+    registry?: boolean;
+    /**
+     * Domains to route into this cluster's ingress via **wildcard DNS**. For
+     * each `"example.com"`, spectest-resolver answers any `*.example.com`
+     * query with the cluster container's IP, where Traefik dispatches by Host
+     * to the matching Ingress. This lets a test `kubectl apply` an Ingress for
+     * any host under the domain and reach it immediately — no need to
+     * pre-declare each hostname in `hostnames`.
+     *
+     * ```ts
+     * services: { k8s: k3s({ ingressDomains: ["example.com"] }) }
+     * // a test then applies an Ingress for foo.example.com and fetches it.
+     * ```
+     *
+     * For one-off hosts not under a declared domain, a test can also register
+     * dynamically with `ctx.dnsName(host, { service: "k8s" })`.
+     *
+     * **TLS.** Setting `ingressDomains` also makes those domains reachable
+     * over **HTTPS**: Traefik gains a `:443` entrypoint and serves a default
+     * certificate minted from the in-VM root CA with SANs `*.<domain>` for
+     * each declared domain. The CA is already trusted by the test framework
+     * (Node `fetch`, `ctx.browser()`, Python, the system store), so
+     * `ctx.fetch("https://foo.example.com")` gets a clean handshake — no
+     * per-Ingress `spec.tls` and no `--insecure` needed. Only hosts **under**
+     * a declared domain are covered by the cert; static `hostnames` not under
+     * one (and one-off `ctx.dnsName` hosts) remain HTTP-only.
+     */
+    ingressDomains?: string[];
+}
+/**
+ * Rewrites a `@kubernetes/client-node` API class so each method's resolved
+ * value comes back **inspect-wrapped** ({@link Wrapped}) — exactly what
+ * `withTagging` does at runtime. The method *signatures* (argument types) are
+ * untouched; only the `Promise<R>` result becomes `Promise<Wrapped<R>>`, so
+ * `expect(pod.status.phase)` links to the API call with no cast and you
+ * `.unwrap()` before using a value as raw data. Non-method
+ * members pass through unchanged. Mirrors {@link RecordingSqlClient} on the
+ * postgres side.
+ */
+type Tagged<T> = {
+    [K in keyof T]: T[K] extends (...args: infer A) => Promise<infer R> ? (...args: A) => Promise<Wrapped<R>> : T[K];
+};
+/**
+ * Pre-instantiated `@kubernetes/client-node` API clients sharing the
+ * same recording HTTP transport. Every method call lands on the test
+ * event log as an HTTP event alongside `fetch` calls, and its result is
+ * inspect-wrapped (see {@link Tagged}) so assertions on it stay linked.
+ */
+export interface K3sClient {
+    core: Tagged<CoreV1Api>;
+    apps: Tagged<AppsV1Api>;
+    /** Generic object API — `create()`, `read()`, `patch()`, `delete()`
+     *  against any Kubernetes resource (custom resources included). */
+    objects: Tagged<KubernetesObjectApi>;
+}
+/** Helpers a `k3s(...)` service exposes on `ctx.svc.<name>`. */
+export interface K3sHelpers {
+    /**
+     * Fully-loaded `KubeConfig`. The cluster server URL is rewritten to
+     * `https://<service-name>.internal:6443`, the auto-assigned DNS name
+     * for this service on `spectest-net`. TLS verification is off because
+     * Bun's fetch doesn't honor an https.Agent's CA option (the client
+     * cert from the kubeconfig still flows through for auth), so the
+     * server's cert SAN list doesn't need to include the .internal name.
+     */
+    kubeconfig: KubeConfig;
+    /** Pre-built API clients. */
+    client: K3sClient;
+    /**
+     * Apply a (multi-document) YAML manifest. Each parsed document is
+     * created via `KubernetesObjectApi.create`. Returns the API server's
+     * response objects in input order — each element inspect-wrapped (the
+     * array container itself is plain), so `expect(created[0]!.metadata.uid)`
+     * links to its create call.
+     */
+    apply: (manifest: string) => Promise<Wrapped<KubernetesObject>[]>;
+}
+export declare function k3s(opts?: K3sOptions): {
+    readyCheck: {
+        type: "exec";
+        command: string;
+        timeoutSecs: number;
+    };
+    setup: ({ name, helpers }: {
+        name: string;
+        helpers: K3sHelpers;
+    }) => Promise<void>;
+    helpers: ({ name, exec }: ServiceHelpersContext) => Promise<K3sHelpers>;
+    files?: {
+        path: string;
+        content: string;
+    }[] | undefined;
+    image: {
+        type: "registry";
+        reference: string;
+    };
+    command: string;
+    privileged: true;
+    tmpfs: string[];
+    cgroupns: string;
+    ports: number[];
+};
+export {};