@shortlink-org/portolan 0.2.4 → 0.4.0

package/scripts/host-plugins/fetch-k8s.mjs

@@ -0,0 +1,263 @@
+// fetch-k8s, run by the host: a live cluster on one side, a catalog fragment
+// on the other. It asks `kubectl` for the workloads, Services, Ingresses,
+// routes and ConfigMaps of the namespaces named, and answers with the names
+// each service answers on and the in-cluster names it dials - the same two
+// lists extract-k8s reads out of the manifests in a repository, from the
+// cluster that actually runs them.
+//
+// It runs in the host (portolan.0008) because it needs a binary, a socket
+// and a credential. The credential is kubectl's own, from the kubeconfig,
+// and never in the manifest.
+//
+// Nothing the cluster says is written down but names. The objects live in
+// this process for the length of one call; a Secret is never asked for; a
+// value from env or a ConfigMap is reduced to a host or to nothing; and a
+// warning names a namespace or a kind, never a value. What kubectl printed
+// on stderr goes to the terminal and not into the build report.
+//
+// Offline, or when the cluster cannot be reached, the fragment committed in
+// the repository is used unchanged - the same rule as fetch-git, for the
+// same reason: a run that lost the cluster must not lose the catalog.
+
+import { execFileSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import optionsSchema from "./fetch-k8s.options.json" with { type: "json" };
+import { topology } from "./k8s-topology.mjs";
+
+export const OFFLINE_ENV = "PORTOLAN_OFFLINE";
+export const DEFAULT_OUT = "k8s-cluster.json";
+export const DEFAULT_LABELS = Object.freeze({
+  context: "app.kubernetes.io/part-of",
+  service: "app.kubernetes.io/name",
+});
+
+// What is asked for, and the whole of it. Secrets are not a kind this list
+// could grow to hold: the reader has no use for one.
+const KINDS = ["deployments", "statefulsets", "daemonsets", "replicasets", "jobs", "cronjobs", "services", "ingresses", "configmaps"];
+const ROUTE_KINDS = ["httproutes.gateway.networking.k8s.io", "grpcroutes.gateway.networking.k8s.io"];
+
+export function describe() {
+  return {
+    name: "fetch-k8s",
+    summary: "Reads the workloads, Services, Ingresses and routes of a live cluster through kubectl into the names each service answers on and dials; values and secrets are never kept.",
+    category: "infrastructure",
+    phases: ["extract"],
+    options: optionsSchema,
+  };
+}
+
+/**
+ * @param {{options?: object}} request
+ * @param {{env?: NodeJS.ProcessEnv, exec?: (args: string[]) => string, stderr?: (text: string) => void}} [io]
+ */
+export function run(request, { env = process.env, exec = kubectl, stderr = (text) => process.stderr.write(text) } = {}) {
+  const options = request.options ?? {};
+  if (!options.cache) {
+    throw new Error("no cache directory: set `cache` to the same path as the step's `out`, so an offline run can replay what the last online one wrote");
+  }
+  const out = String(options.out ?? "").trim() || DEFAULT_OUT;
+  const at = join(options.cache, out);
+  const builder = new Builder();
+
+  if (offline(env)) {
+    emitCached(builder, at, out, "offline");
+    return builder.response();
+  }
+
+  let objects;
+  try {
+    objects = read(exec, options, builder, stderr);
+  } catch (cause) {
+    try {
+      emitCached(builder, at, out, cause.message);
+    } catch (cacheCause) {
+      throw new Error(`the cluster could not be read (${cause.message}) and there is no usable fragment in the tree (${cacheCause.message})`);
+    }
+    return builder.response();
+  }
+
+  builder.file(out, fragment(objects, options, builder));
+  return builder.response();
+}
+
+/** Whether to open a socket. Explicit, and CI verifies what was committed. */
+export function offline(env = process.env) {
+  if (String(env[OFFLINE_ENV] ?? "").trim()) return true;
+  return !["", "0", "false"].includes(String(env.CI ?? "").trim().toLowerCase());
+}
+
+/** The label keys the manifest chose, over the conventional ones. */
+export function labelsOf(options) {
+  const declared = options.labels ?? {};
+  return {
+    context: String(declared.context ?? "").trim() || DEFAULT_LABELS.context,
+    service: String(declared.service ?? "").trim() || DEFAULT_LABELS.service,
+  };
+}
+
+function kubectl(args) {
+  return execFileSync("kubectl", args, { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], maxBuffer: 512 * 1024 * 1024 });
+}
+
+/**
+ * One `kubectl get` per namespace, or one across all of them. The kinds a
+ * Gateway API cluster serves are asked for separately, because a cluster
+ * without the CRDs refuses the whole request otherwise.
+ */
+function read(exec, options, builder, stderr) {
+  const namespaces = Array.isArray(options.namespaces) ? options.namespaces.map((ns) => String(ns).trim()).filter(Boolean).sort() : [];
+  const scopes = namespaces.length ? namespaces.map((ns) => ["-n", ns]) : [["-A"]];
+  const base = String(options.kubeContext ?? "").trim() ? ["--context", String(options.kubeContext).trim()] : [];
+  const objects = [];
+  for (const scope of scopes) {
+    objects.push(...items(call(exec, [...base, "get", KINDS.join(","), ...scope, "-o", "json"], stderr)));
+  }
+  let routesMissing = false;
+  for (const scope of scopes) {
+    for (const kind of ROUTE_KINDS) {
+      try {
+        objects.push(...items(call(exec, [...base, "get", kind, ...scope, "-o", "json"], stderr)));
+      } catch {
+        routesMissing = true;
+      }
+    }
+  }
+  if (routesMissing) builder.warn("", "the cluster serves no Gateway API routes, or refused to list them; hosts of HTTPRoute and GRPCRoute were not read");
+  return objects;
+}
+
+/**
+ * Runs one kubectl. What kubectl says on stderr reaches the terminal, not
+ * the build report: a connection error names the server, and that is a
+ * fact for the person at the keyboard and not for a committed file.
+ */
+function call(exec, args, stderr) {
+  try {
+    return exec(args);
+  } catch (cause) {
+    const said = String(cause.stderr ?? "").trim();
+    if (said) stderr(`kubectl ${args.join(" ")}:\n${said}\n`);
+    const status = Number.isInteger(cause.status) ? `exit ${cause.status}` : cause.code === "ENOENT" ? "kubectl is not on PATH" : "kubectl failed";
+    throw new Error(`kubectl get ${args[args.indexOf("get") + 1] ?? ""}: ${status}`);
+  }
+}
+
+function items(raw) {
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (cause) {
+    throw new Error(`kubectl's answer is not JSON: ${cause.message}`);
+  }
+  const list = Array.isArray(parsed?.items) ? parsed.items : parsed?.kind && parsed?.metadata ? [parsed] : [];
+  return list.filter((item) => item && typeof item === "object" && item.kind !== "Secret");
+}
+
+/**
+ * The fragment: every workload the labels place into a context and a
+ * service, folded by service. A workload the labels do not place and the
+ * namespace map does not claim is counted in a warning, not guessed at.
+ */
+export function fragment(objects, options, builder) {
+  const labels = labelsOf(options);
+  const namespaceContexts = options.namespaceContexts ?? {};
+  const services = new Map();
+  const unmapped = new Map();
+
+  for (const entry of topology(objects)) {
+    const meta = entry.object.metadata ?? {};
+    const ns = meta.namespace ?? "";
+    const all = { ...(podTemplateLabels(entry.object)), ...(meta.labels ?? {}) };
+    const context = String(all[labels.context] ?? "").trim() || String(namespaceContexts[ns] ?? "").trim();
+    if (!context) {
+      unmapped.set(ns, (unmapped.get(ns) ?? 0) + 1);
+      continue;
+    }
+    const slug = String(all[labels.service] ?? "").trim() || String(meta.name ?? "");
+    const id = `${context}.${slug}`;
+    const service = services.get(id) ?? { id, context, slug, kinds: new Set(), hosts: new Set(), dials: new Set() };
+    service.kinds.add(entry.kind);
+    for (const host of entry.hosts) service.hosts.add(host);
+    for (const dial of entry.dials) service.dials.add(dial);
+    services.set(id, service);
+  }
+
+  for (const ns of [...unmapped.keys()].sort()) {
+    builder.warn(ns || "cluster", `${unmapped.get(ns)} workload(s) carry no "${labels.context}" label and the namespace is not in namespaceContexts; they were left out`);
+  }
+
+  const contexts = new Map();
+  for (const id of [...services.keys()].sort()) {
+    const service = services.get(id);
+    const context = contexts.get(service.context) ?? { id: service.context, slug: service.context, name: "", summary: "", services: [] };
+    const record = {
+      id: service.id,
+      slug: service.slug,
+      name: "",
+      repo: "",
+      path: "",
+      readme: "",
+      provides: [],
+      consumes: [],
+      aggregates: [],
+    };
+    // A service that is only jobs is a job; one with a Deployment beside
+    // its CronJob is whatever its code says it is.
+    if (service.kinds.size === 1 && service.kinds.has("job")) record.kind = "job";
+    const dials = [...service.dials].filter((dial) => !service.hosts.has(dial)).sort();
+    if (service.hosts.size) record.hosts = [...service.hosts].sort();
+    if (dials.length) record.dials = dials;
+    context.services.push(record);
+    contexts.set(service.context, context);
+  }
+
+  const catalog = {
+    contexts: [...contexts.keys()].sort().map((id) => contexts.get(id)),
+    defs: {},
+    flows: [],
+    adrs: [],
+  };
+  return `${JSON.stringify(catalog, null, 2)}\n`;
+}
+
+function podTemplateLabels(object) {
+  const spec = object.spec ?? {};
+  const template = object.kind === "CronJob" ? spec.jobTemplate?.spec?.template : spec.template;
+  return template?.metadata?.labels ?? {};
+}
+
+function emitCached(builder, at, out, why) {
+  let raw;
+  try {
+    raw = readFileSync(at, "utf8");
+  } catch (cause) {
+    if (cause.code === "ENOENT") throw new Error(`no ${out} in ${at.split("\\").join("/").slice(0, -out.length - 1) || "."}`);
+    throw cause;
+  }
+  try {
+    JSON.parse(raw);
+  } catch (cause) {
+    throw new Error(`${out} is not JSON: ${cause.message}`);
+  }
+  builder.file(out, raw);
+  builder.warn("", `the cluster was not read (${why}); the fragment committed in this repository is used unchanged`);
+}
+
+class Builder {
+  files = [];
+  warnings = [];
+
+  file(name, contents) {
+    this.files.push({ name, contents });
+  }
+
+  warn(ref, message) {
+    this.warnings.push({ severity: "warning", message, ref });
+  }
+
+  response() {
+    return { files: this.files, warnings: this.warnings };
+  }
+}

package/scripts/host-plugins/fetch-k8s.options.json

@@ -0,0 +1,50 @@
+{
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["cache"],
+  "properties": {
+    "kubeContext": {
+      "type": "string",
+      "description": "The kubeconfig context to read, passed to kubectl as --context. Left out, kubectl's current context.",
+      "examples": ["prod-eu"]
+    },
+    "namespaces": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "The namespaces to read. Left out, every namespace the credential can list.",
+      "examples": [["shop", "auth", "payments"]]
+    },
+    "labels": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Which labels place a workload into the catalog. The defaults are the Kubernetes recommended labels; an estate that labels differently names its own keys here.",
+      "properties": {
+        "context": {
+          "type": "string",
+          "description": "The label whose value is the bounded context's slug.",
+          "default": "app.kubernetes.io/part-of"
+        },
+        "service": {
+          "type": "string",
+          "description": "The label whose value is the service's slug. A workload without it is named after itself.",
+          "default": "app.kubernetes.io/name"
+        }
+      }
+    },
+    "namespaceContexts": {
+      "type": "object",
+      "additionalProperties": { "type": "string" },
+      "description": "Namespace to bounded context, for workloads that carry no context label. A workload with the label keeps it; one with neither is counted in a warning and left out.",
+      "examples": [{ "shop": "shop", "shop-jobs": "shop" }]
+    },
+    "cache": {
+      "type": "string",
+      "description": "Where the last run's fragment was written, repo-relative: the same path as the step's out. An offline run, or one that cannot reach the cluster, replays it unchanged."
+    },
+    "out": {
+      "type": "string",
+      "description": "Name of the fragment file, inside the step's output directory.",
+      "default": "k8s-cluster.json"
+    }
+  }
+}

package/scripts/host-plugins/fetch-k8s.test.mjs

@@ -0,0 +1,259 @@
+// The cluster reader, against a recorded kubectl. NEVER against a live one.
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+
+import { DEFAULT_OUT, OFFLINE_ENV, fragment, labelsOf, run } from "./fetch-k8s.mjs";
+import { hostOnly, topology } from "./k8s-topology.mjs";
+
+const cleanups = [];
+afterEach(() => {
+  for (const cleanup of cleanups.splice(0)) cleanup();
+});
+
+function cache() {
+  const dir = mkdtempSync(join(tmpdir(), "portolan-fetch-k8s-"));
+  cleanups.push(() => rmSync(dir, { recursive: true, force: true }));
+  return dir;
+}
+
+const workload = (kind, name, namespace, labels, containers, extra = {}) => ({
+  kind,
+  apiVersion: kind === "CronJob" || kind === "Job" ? "batch/v1" : "apps/v1",
+  metadata: { name, namespace, labels },
+  spec: kind === "CronJob"
+    ? { schedule: "0 3 * * *", jobTemplate: { spec: { template: { metadata: { labels }, spec: { containers } } } } }
+    : { selector: { matchLabels: labels }, template: { metadata: { labels }, spec: { containers } }, ...extra },
+});
+
+const service = (name, namespace, selector) => ({ kind: "Service", apiVersion: "v1", metadata: { name, namespace }, spec: { selector, ports: [{ port: 8080 }] } });
+
+// The recorded cluster. Every value that must never reach the fragment is
+// planted here and grepped for below.
+const OBJECTS = [
+  workload("Deployment", "pricing", "shop", { "app.kubernetes.io/name": "pricing", "app.kubernetes.io/part-of": "shop" }, [{
+    name: "pricing",
+    image: "ghcr.io/acme/pricing:1.4.2",
+    env: [
+      { name: "CART_URL", value: "http://cart.shop.svc:8080/api" },
+      { name: "LEDGER_DSN", value: "postgres://pricing:hunter2@ledger-db.payments.svc:5432/ledger?sslmode=disable" },
+      { name: "LOG_LEVEL", value: "info" },
+      { name: "DB_PASSWORD", value: "s3cr3t-password" },
+      { name: "AUTH_URL", value: "http://auth:9000" },
+      { name: "OMS_URL", valueFrom: { configMapKeyRef: { name: "pricing-config", key: "OMS_URL" } } },
+      { name: "API_TOKEN", valueFrom: { secretKeyRef: { name: "pricing-secrets", key: "token" } } },
+    ],
+    envFrom: [{ configMapRef: { name: "pricing-shared" } }, { secretRef: { name: "pricing-secrets" } }],
+  }]),
+  workload("CronJob", "nightly-reprice", "shop", { "app.kubernetes.io/name": "pricing", "app.kubernetes.io/part-of": "shop" }, [{
+    name: "reprice",
+    env: [{ name: "PRICING_URL", value: "http://pricing.shop.svc" }, { name: "OMS_URL", value: "grpc://oms.shop.svc:9090" }],
+  }]),
+  workload("Deployment", "cart", "shop", { app: "cart", team: "checkout" }, [{ name: "cart", env: [{ name: "PRICING_ADDR", value: "pricing.shop.svc:9090" }] }]),
+  workload("Deployment", "orphan", "sandbox", { app: "orphan" }, [{ name: "orphan" }]),
+  workload("Job", "migrate", "payments", { "app.kubernetes.io/name": "ledger", "app.kubernetes.io/part-of": "payments" }, [{ name: "migrate", env: [{ name: "DATABASE_URL", value: "postgres://u:p@ledger-db.payments.svc/x" }] }]),
+  service("pricing", "shop", { "app.kubernetes.io/name": "pricing" }),
+  service("auth", "shop", { app: "auth" }),
+  service("cart", "shop", { app: "cart" }),
+  service("ledger-db", "payments", { app: "ledger-db" }),
+  {
+    kind: "Ingress", apiVersion: "networking.k8s.io/v1", metadata: { name: "shop", namespace: "shop" },
+    spec: { rules: [
+      { host: "shop.example.com", http: { paths: [{ path: "/pricing", backend: { service: { name: "pricing" } } }, { path: "/cart", backend: { service: { name: "cart" } } }] } },
+      { host: "admin.example.com", http: { paths: [{ path: "/", backend: { service: { name: "auth" } } }] } },
+    ] },
+  },
+  { kind: "ConfigMap", apiVersion: "v1", metadata: { name: "pricing-config", namespace: "shop" }, data: { OMS_URL: "grpc://oms.shop.svc:9090", GREETING: "hello" } },
+  { kind: "ConfigMap", apiVersion: "v1", metadata: { name: "pricing-shared", namespace: "shop" }, data: { CATALOG_URL: "https://catalog.shop.svc.cluster.local/v1", REGION: "eu-west-1" } },
+];
+
+const ROUTES = [{
+  kind: "HTTPRoute", apiVersion: "gateway.networking.k8s.io/v1", metadata: { name: "pricing", namespace: "shop" },
+  spec: { hostnames: ["api.example.com"], rules: [{ backendRefs: [{ name: "pricing" }] }] },
+}];
+
+const PLANTED = [
+  "hunter2", "s3cr3t", "pricing-secrets", "8080", "9090", "/api", "sslmode", "u:p@",
+  "CART_URL", "LEDGER_DSN", "OMS_URL", "DB_PASSWORD", "LOG_LEVEL", "info", "hello", "eu-west-1", "ghcr.io",
+];
+
+/** A kubectl that answers from the recording, by namespace, and knows no Gateway API. */
+function recorded({ routes = true, fail = false, calls = [] } = {}) {
+  return (args) => {
+    calls.push(args);
+    if (fail) {
+      const cause = new Error("kubectl failed");
+      cause.status = 1;
+      cause.stderr = "Unable to connect to the server: dial tcp 10.0.0.1:6443: i/o timeout";
+      throw cause;
+    }
+    const kinds = args[args.indexOf("get") + 1];
+    const scoped = args.includes("-n") ? args[args.indexOf("-n") + 1] : "";
+    const pool = kinds.startsWith("httproutes") || kinds.startsWith("grpcroutes")
+      ? (routes ? (kinds.startsWith("httproutes") ? ROUTES : []) : null)
+      : OBJECTS;
+    if (pool === null) {
+      const cause = new Error("kubectl failed");
+      cause.status = 1;
+      cause.stderr = `error: the server doesn't have a resource type "${kinds.split(".")[0]}"`;
+      throw cause;
+    }
+    return JSON.stringify({ kind: "List", items: pool.filter((item) => !scoped || item.metadata.namespace === scoped) });
+  };
+}
+
+const isolated = { [OFFLINE_ENV]: "", CI: "" };
+const read = (options, io = {}) => {
+  const said = [];
+  const response = run({ options }, { env: { ...isolated, ...(io.env ?? {}) }, exec: io.exec ?? recorded(), stderr: (text) => said.push(text) });
+  const file = response.files.find((f) => f.name === (options.out ?? DEFAULT_OUT));
+  return { response, file, catalog: file ? JSON.parse(file.contents) : undefined, said, warnings: response.warnings.map((w) => `${w.ref ? `${w.ref}: ` : ""}${w.message}`) };
+};
+const serviceOf = (catalog, id) => catalog.contexts.flatMap((c) => c.services).find((s) => s.id === id);
+
+describe("fetch-k8s", () => {
+  it("reads hosts and dials per service, by the recommended labels, and nothing else", () => {
+    const { catalog, response, warnings, said } = read({ cache: cache(), namespaceContexts: { shop: "shop" } });
+
+    expect(catalog.contexts.map((c) => c.id)).toEqual(["payments", "shop"]);
+    const pricing = serviceOf(catalog, "shop.pricing");
+    expect(pricing.hosts).toEqual(["api.example.com", "pricing", "pricing.shop", "pricing.shop.svc", "pricing.shop.svc.cluster.local", "shop.example.com"]);
+    expect(pricing.dials).toEqual(["auth", "cart.shop.svc", "catalog.shop.svc.cluster.local", "ledger-db.payments.svc", "oms.shop.svc"]);
+    // A Deployment beside the CronJob: the service is not a job.
+    expect(pricing.kind).toBeUndefined();
+
+    const cart = serviceOf(catalog, "shop.cart");
+    expect(cart.slug).toBe("cart");
+    expect(cart.dials).toEqual(["pricing.shop.svc"]);
+    expect(cart.hosts).toContain("shop.example.com");
+
+    const ledger = serviceOf(catalog, "payments.ledger");
+    expect(ledger.kind).toBe("job");
+    expect(ledger.dials).toEqual(["ledger-db.payments.svc"]);
+
+    expect(warnings).toEqual(['sandbox: 1 workload(s) carry no "app.kubernetes.io/part-of" label and the namespace is not in namespaceContexts; they were left out']);
+    expect(said).toEqual([]);
+
+    const everything = response.files.map((f) => f.contents).join("\n") + warnings.join("\n");
+    for (const planted of PLANTED) expect(everything, planted).not.toContain(planted);
+    expect(everything).not.toContain("Secret");
+  });
+
+  it("asks for no secrets, and asks once per namespace when namespaces are named", () => {
+    const calls = [];
+    read({ cache: cache(), namespaces: ["shop", "auth"], kubeContext: "prod" }, { exec: recorded({ calls }) });
+    for (const args of calls) {
+      expect(args.slice(0, 2)).toEqual(["--context", "prod"]);
+      expect(args.join(" ")).not.toMatch(/secret/i);
+    }
+    const scopes = calls.map((args) => args[args.indexOf("-n") + 1]);
+    expect(scopes.filter((ns) => ns === "auth").length).toBe(3);
+    expect(scopes.filter((ns) => ns === "shop").length).toBe(3);
+    expect(calls.some((args) => args.includes("-A"))).toBe(false);
+  });
+
+  it("lets the manifest name its own labels", () => {
+    const { catalog, warnings } = read({ cache: cache(), labels: { context: "team", service: "app" } });
+    expect(warnings).toEqual([
+      'payments: 1 workload(s) carry no "team" label and the namespace is not in namespaceContexts; they were left out',
+      'sandbox: 1 workload(s) carry no "team" label and the namespace is not in namespaceContexts; they were left out',
+      'shop: 2 workload(s) carry no "team" label and the namespace is not in namespaceContexts; they were left out',
+    ]);
+    expect(catalog.contexts.map((c) => c.id)).toEqual(["checkout"]);
+    expect(serviceOf(catalog, "checkout.cart").dials).toEqual(["pricing.shop.svc"]);
+    expect(labelsOf({ labels: { context: " " } })).toEqual({ context: "app.kubernetes.io/part-of", service: "app.kubernetes.io/name" });
+  });
+
+  it("goes on without Gateway API routes, with one warning", () => {
+    const { catalog, warnings } = read({ cache: cache() }, { exec: recorded({ routes: false }) });
+    expect(serviceOf(catalog, "shop.pricing").hosts).not.toContain("api.example.com");
+    expect(warnings).toContain("the cluster serves no Gateway API routes, or refused to list them; hosts of HTTPRoute and GRPCRoute were not read");
+  });
+
+  it("replays the committed fragment offline, unchanged", () => {
+    const dir = cache();
+    const first = read({ cache: dir });
+    writeFileSync(join(dir, DEFAULT_OUT), first.file.contents);
+
+    const replayed = read({ cache: dir }, { env: { [OFFLINE_ENV]: "1" }, exec: () => { throw new Error("must not be called"); } });
+    expect(replayed.file.contents).toBe(first.file.contents);
+    expect(replayed.warnings).toEqual(["the cluster was not read (offline); the fragment committed in this repository is used unchanged"]);
+
+    const inCI = read({ cache: dir }, { env: { CI: "true" }, exec: () => { throw new Error("must not be called"); } });
+    expect(inCI.file.contents).toBe(first.file.contents);
+  });
+
+  it("falls back to the committed fragment when the cluster cannot be reached, and keeps the server out of the report", () => {
+    const dir = cache();
+    const first = read({ cache: dir });
+    writeFileSync(join(dir, DEFAULT_OUT), first.file.contents);
+
+    const { file, warnings, said } = read({ cache: dir }, { exec: recorded({ fail: true }) });
+    expect(file.contents).toBe(first.file.contents);
+    expect(warnings).toEqual(["the cluster was not read (kubectl get deployments,statefulsets,daemonsets,replicasets,jobs,cronjobs,services,ingresses,configmaps: exit 1); the fragment committed in this repository is used unchanged"]);
+    expect(warnings.join("\n")).not.toContain("10.0.0.1");
+    expect(said.join("\n")).toContain("10.0.0.1:6443");
+  });
+
+  it("is an error, never a short answer, with no cluster and no committed copy", () => {
+    expect(() => read({ cache: cache() }, { exec: recorded({ fail: true }) })).toThrow(/could not be read .* no usable fragment/);
+    expect(() => read({ cache: cache() }, { env: { [OFFLINE_ENV]: "1" } })).toThrow(/no usable fragment|no k8s-cluster.json/);
+    expect(() => run({ options: {} }, { env: isolated })).toThrow(/no cache directory/);
+  });
+
+  it("writes the fragment the same way whatever order the cluster listed things in", () => {
+    const shuffled = [...OBJECTS].reverse();
+    const exec = (args) => {
+      const kinds = args[args.indexOf("get") + 1];
+      if (kinds.startsWith("httproutes")) return JSON.stringify({ items: ROUTES });
+      if (kinds.startsWith("grpcroutes")) return JSON.stringify({ items: [] });
+      return JSON.stringify({ items: shuffled });
+    };
+    expect(read({ cache: cache() }, { exec }).file.contents).toBe(read({ cache: cache() }).file.contents);
+  });
+});
+
+describe("k8s-topology", () => {
+  // The same table as extract-k8s's TestHostOnly, so the two readers stay
+  // one rule.
+  it("hostOnly keeps a host and nothing else", () => {
+    const known = new Set(["auth", "auth.shop"]);
+    const cases = {
+      "http://cart.shop.svc:8080/api": "cart.shop.svc",
+      "postgres://u:p@db.payments.svc:5432/x?sslmode=off": "db.payments.svc",
+      "HTTPS://Cart.Shop.SVC.cluster.local": "cart.shop.svc.cluster.local",
+      "auth:9000": "auth",
+      "auth.shop": "auth.shop",
+      "oms.shop.svc.cluster.local": "oms.shop.svc.cluster.local",
+      cart: undefined,
+      "example.com": undefined,
+      "https://api.stripe.com/v1": undefined,
+      hunter2: undefined,
+      true: undefined,
+      info: undefined,
+      "host=db.shop.svc user=x password=y": undefined,
+      "": undefined,
+      "-bad.shop.svc": undefined,
+      "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxIn0.abc": undefined,
+    };
+    for (const [value, want] of Object.entries(cases)) expect(hostOnly(value, known), value).toBe(want);
+  });
+
+  it("an empty selector selects nothing, and a Service in another namespace never does", () => {
+    const objects = [
+      workload("Deployment", "a", "one", { app: "a" }, [{ name: "a" }]),
+      service("headless", "one", {}),
+      service("a", "two", { app: "a" }),
+    ];
+    expect(topology(objects)[0].hosts).toEqual([]);
+  });
+
+  it("fragment leaves a service its kind when only jobs deploy it", () => {
+    const only = [workload("CronJob", "sweep", "ops", { "app.kubernetes.io/name": "sweeper", "app.kubernetes.io/part-of": "ops" }, [{ name: "s" }])];
+    const warnings = [];
+    const out = JSON.parse(fragment(only, {}, { warn: (ref, message) => warnings.push(message) }));
+    expect(out.contexts[0].services[0]).toEqual({ id: "ops.sweeper", slug: "sweeper", name: "", repo: "", path: "", readme: "", provides: [], consumes: [], aggregates: [], kind: "job" });
+    expect(warnings).toEqual([]);
+  });
+});