@intentius/chant-lexicon-gcp 0.124.34 → 0.124.36

package/src/op/activities/gcp-compute.test.ts

@@ -0,0 +1,306 @@
+import { beforeEach, describe, expect, test } from "vitest";
+import { applyResource, deleteResource, MAPPERS, orderByReferences, type GcpHttp, type GcpResource } from "./gcp-apply";
+import { computeLabels, computeOperation } from "./gcp-compute";
+import { getResource } from "../../api/read-client";
+
+beforeEach(() => {
+  delete process.env.GCP_REGION;
+});
+
+/** The serverless load balancer behold's three-cloud demo declares, in the shape the serializer writes. */
+const lb: GcpResource[] = [
+  {
+    kind: "ComputeForwardingRule",
+    metadata: { name: "web-fr", labels: { "app.kubernetes.io/component": "lb", tier: "edge" } },
+    spec: {
+      location: "global",
+      loadBalancingScheme: "EXTERNAL_MANAGED",
+      portRange: "80",
+      ipProtocol: "TCP",
+      ipAddress: { addressRef: { name: "web-ip" } },
+      target: { targetHTTPProxyRef: { name: "web-proxy" } },
+    },
+  },
+  { kind: "ComputeTargetHTTPProxy", metadata: { name: "web-proxy" }, spec: { location: "global", urlMapRef: { name: "web-map" } } },
+  { kind: "ComputeURLMap", metadata: { name: "web-map" }, spec: { location: "global", defaultService: { backendServiceRef: { name: "web" } } } },
+  {
+    kind: "ComputeBackendService",
+    metadata: { name: "web" },
+    spec: {
+      location: "global",
+      loadBalancingScheme: "EXTERNAL_MANAGED",
+      protocol: "HTTPS",
+      enableCdn: false,
+      backend: [{ group: { networkEndpointGroupRef: { name: "web" } } }],
+    },
+  },
+  {
+    kind: "ComputeRegionNetworkEndpointGroup",
+    metadata: { name: "web" },
+    spec: { region: "europe-west1", networkEndpointType: "SERVERLESS", cloudRun: { serviceRef: { name: "web" } } },
+  },
+  { kind: "ComputeAddress", metadata: { name: "web-ip" }, spec: { location: "global" } },
+  { kind: "RunService", metadata: { name: "web" }, spec: { location: "europe-west1" } },
+];
+
+const ctx = { base: "https://compute.googleapis.com", project: "p1", manifest: lb };
+const byKind = (kind: string) => lb.find((r) => r.kind === kind)!;
+const plan = (kind: string) => MAPPERS[kind].plan(byKind(kind), ctx);
+
+describe("compute load balancer mappers (#4233)", () => {
+  test("apply order: service, NEG and address before the backend, map, proxy and forwarding rule", () => {
+    const order = orderByReferences(lb).map((r) => r.kind);
+    const at = (k: string) => order.indexOf(k);
+    expect(at("RunService")).toBeLessThan(at("ComputeRegionNetworkEndpointGroup"));
+    expect(at("ComputeRegionNetworkEndpointGroup")).toBeLessThan(at("ComputeBackendService"));
+    expect(at("ComputeBackendService")).toBeLessThan(at("ComputeURLMap"));
+    expect(at("ComputeURLMap")).toBeLessThan(at("ComputeTargetHTTPProxy"));
+    expect(at("ComputeTargetHTTPProxy")).toBeLessThan(at("ComputeForwardingRule"));
+    expect(at("ComputeAddress")).toBeLessThan(at("ComputeForwardingRule"));
+  });
+
+  test("a serverless NEG is regional and names its Cloud Run service", () => {
+    expect(plan("ComputeRegionNetworkEndpointGroup")).toEqual({
+      getUrl: "https://compute.googleapis.com/compute/v1/projects/p1/regions/europe-west1/networkEndpointGroups/web",
+      create: {
+        method: "POST",
+        url: "https://compute.googleapis.com/compute/v1/projects/p1/regions/europe-west1/networkEndpointGroups",
+        body: { name: "web", networkEndpointType: "SERVERLESS", cloudRun: { service: "web" } },
+      },
+    });
+  });
+
+  test("a global backend service points at the regional NEG by the NEG's own region", () => {
+    expect(plan("ComputeBackendService").create).toEqual({
+      method: "POST",
+      url: "https://compute.googleapis.com/compute/v1/projects/p1/global/backendServices",
+      body: {
+        name: "web",
+        loadBalancingScheme: "EXTERNAL_MANAGED",
+        protocol: "HTTPS",
+        enableCDN: false,
+        backends: [{ group: "projects/p1/regions/europe-west1/networkEndpointGroups/web" }],
+      },
+    });
+  });
+
+  test("URL map, proxy and forwarding rule resolve their refs to partial URLs", () => {
+    expect(plan("ComputeURLMap").create.body).toEqual({ name: "web-map", defaultService: "projects/p1/global/backendServices/web" });
+    expect(plan("ComputeTargetHTTPProxy").create.body).toEqual({ name: "web-proxy", urlMap: "projects/p1/global/urlMaps/web-map" });
+    expect(plan("ComputeForwardingRule").create.body).toEqual({
+      name: "web-fr",
+      loadBalancingScheme: "EXTERNAL_MANAGED",
+      portRange: "80",
+      IPProtocol: "TCP",
+      IPAddress: "projects/p1/global/addresses/web-ip",
+      target: "projects/p1/global/targetHttpProxies/web-proxy",
+      labels: { tier: "edge", "managed-by": "chant" },
+    });
+  });
+
+  test("a global address goes to the global collection, with the ownership label", () => {
+    expect(plan("ComputeAddress")).toMatchObject({
+      getUrl: "https://compute.googleapis.com/compute/v1/projects/p1/global/addresses/web-ip",
+      create: { body: { name: "web-ip", labels: { "managed-by": "chant" } } },
+    });
+  });
+
+  test("labels GCP refuses are left out", () => {
+    expect(computeLabels({ "app.kubernetes.io/name": "x", Bad: "y", ok: "Value", good: "v-1" })).toEqual({ good: "v-1", "managed-by": "chant" });
+  });
+
+  test("an external ref is used as given", () => {
+    const proxy: GcpResource = {
+      kind: "ComputeTargetHTTPProxy",
+      metadata: { name: "p" },
+      spec: { location: "global", urlMapRef: { external: "projects/shared/global/urlMaps/m" } },
+    };
+    expect(MAPPERS.ComputeTargetHTTPProxy.plan(proxy, { base: "b", project: "p1" }).create.body).toEqual({
+      name: "p",
+      urlMap: "projects/shared/global/urlMaps/m",
+    });
+  });
+});
+
+describe("compute operations (#4233)", () => {
+  test("the selfLink is rebased onto an endpoint override, and DONE ends the poll", () => {
+    const op = { kind: "compute#operation", selfLink: "https://compute.googleapis.com/compute/v1/projects/p1/global/operations/op-1", status: "RUNNING" };
+    expect(computeOperation.pollUrl(op, { base: "http://localhost:4588", project: "p1" })).toBe(
+      "http://localhost:4588/compute/v1/projects/p1/global/operations/op-1",
+    );
+    expect(computeOperation.isDone({ status: "DONE" })).toBe(true);
+    expect(computeOperation.error({ status: "DONE", error: { errors: [{ message: "quota" }] } })).toBe("quota");
+    expect(computeOperation.pollUrl({ name: "web" }, { base: "b", project: "p1" })).toBeUndefined();
+  });
+
+  test("apply inserts, polls the operation, and leaves an existing resource alone", async () => {
+    const calls: string[] = [];
+    let exists = false;
+    const http: GcpHttp = async (method, url) => {
+      calls.push(`${method} ${url}`);
+      if (method === "GET" && url.endsWith("/addresses/web-ip")) return exists ? { status: 200, text: "{}" } : { status: 404, text: "" };
+      if (method === "POST") {
+        exists = true;
+        return { status: 200, text: JSON.stringify({ kind: "compute#operation", selfLink: "https://compute.googleapis.com/compute/v1/projects/p1/global/operations/op-1", status: "PENDING" }) };
+      }
+      if (url.includes("/operations/")) return { status: 200, text: JSON.stringify({ status: "DONE" }) };
+      return { status: 500, text: "" };
+    };
+    const created = await applyResource(MAPPERS.ComputeAddress, byKind("ComputeAddress"), ctx, http);
+    expect(created.created).toBe(true);
+    expect(calls).toContain("GET https://compute.googleapis.com/compute/v1/projects/p1/global/operations/op-1");
+    const again = await applyResource(MAPPERS.ComputeAddress, byKind("ComputeAddress"), ctx, http);
+    expect(again).toMatchObject({ created: false, updated: false });
+  });
+
+  test("delete removes the resource at its scoped URL", async () => {
+    const calls: string[] = [];
+    const http: GcpHttp = async (method, url) => {
+      calls.push(`${method} ${url}`);
+      return { status: 200, text: JSON.stringify({ status: "DONE" }) };
+    };
+    await deleteResource(MAPPERS.ComputeRegionNetworkEndpointGroup, byKind("ComputeRegionNetworkEndpointGroup"), ctx, http);
+    expect(calls[0]).toBe("DELETE https://compute.googleapis.com/compute/v1/projects/p1/regions/europe-west1/networkEndpointGroups/web");
+  });
+
+  test("the reader reads a load balancer kind through the same URL", async () => {
+    const http = async (_m: string, url: string) =>
+      url.endsWith("/global/urlMaps/web-map") ? { status: 200, text: JSON.stringify({ name: "web-map" }) } : { status: 404, text: "" };
+    const body = await getResource({ project: "p1", http }, "ComputeURLMap", "web-map", byKind("ComputeURLMap").spec);
+    expect(body).toEqual({ name: "web-map" });
+  });
+});
+
+describe("deep observe reads a load balancer back in the declared vocabulary (#4233)", () => {
+  test("refs, renamed fields and the scope invert the body builders", async () => {
+    const { toCnrmTree } = await import("../../deep-observe");
+    const c = { project: "p1" };
+    expect(
+      toCnrmTree(
+        "ComputeBackendService",
+        {
+          name: "web",
+          selfLink: "https://compute.googleapis.com/compute/v1/projects/p1/global/backendServices/web",
+          enableCDN: false,
+          protocol: "HTTPS",
+          backends: [{ group: "https://compute.googleapis.com/compute/v1/projects/p1/regions/europe-west1/networkEndpointGroups/web" }],
+        },
+        c,
+      ),
+    ).toEqual({
+      metadata: { name: "web" },
+      selfLink: "https://compute.googleapis.com/compute/v1/projects/p1/global/backendServices/web",
+      enableCdn: false,
+      protocol: "HTTPS",
+      location: "global",
+      backend: [{ group: { networkEndpointGroupRef: { name: "web" } } }],
+    });
+    expect(
+      toCnrmTree(
+        "ComputeRegionNetworkEndpointGroup",
+        { name: "web", region: "https://compute.googleapis.com/compute/v1/projects/p1/regions/europe-west1", cloudRun: { service: "web" } },
+        c,
+      ),
+    ).toMatchObject({ region: "europe-west1", cloudRun: { serviceRef: { name: "web" } } });
+    expect(
+      toCnrmTree("ComputeForwardingRule", { name: "fr", IPProtocol: "TCP", target: "projects/p1/global/targetHttpProxies/web-proxy" }, c),
+    ).toMatchObject({ ipProtocol: "TCP", location: "global", target: { targetHTTPProxyRef: { name: "web-proxy" } } });
+    expect(toCnrmTree("ComputeURLMap", { name: "m", defaultService: "projects/p1/global/backendServices/web" }, c)).toMatchObject({
+      defaultService: { backendServiceRef: { name: "web" } },
+    });
+  });
+});
+
+describe("network and subnetwork mappers (#4248)", () => {
+  const net: GcpResource[] = [
+    {
+      kind: "ComputeSubnetwork",
+      metadata: { name: "apps" },
+      spec: {
+        region: "europe-west1",
+        ipCidrRange: "10.0.0.0/24",
+        networkRef: { name: "vpc" },
+        privateIpGoogleAccess: true,
+        secondaryIpRange: [{ rangeName: "pods", ipCidrRange: "10.4.0.0/14" }],
+      },
+    },
+    { kind: "ComputeNetwork", metadata: { name: "vpc" }, spec: { routingMode: "REGIONAL" } },
+    {
+      kind: "RunService",
+      metadata: { name: "web" },
+      spec: { location: "europe-west1", template: { vpcAccess: { networkInterfaces: [{ networkRef: { name: "vpc" }, subnetworkRef: { name: "apps" } }] } } },
+    },
+  ];
+  const nctx = { base: "https://compute.googleapis.com", project: "p1", manifest: net };
+  const find = (kind: string) => net.find((r) => r.kind === kind)!;
+
+  test("a network is global, with autoCreateSubnetworks false unless declared and the routing mode nested", () => {
+    process.env.GCP_REGION = "us-east1";
+    const plan = MAPPERS.ComputeNetwork.plan(find("ComputeNetwork"), nctx);
+    expect(plan.create.url).toBe("https://compute.googleapis.com/compute/v1/projects/p1/global/networks");
+    expect(plan.getUrl).toBe("https://compute.googleapis.com/compute/v1/projects/p1/global/networks/vpc");
+    expect(plan.create.body).toEqual({ name: "vpc", autoCreateSubnetworks: false, routingConfig: { routingMode: "REGIONAL" } });
+  });
+
+  test("a subnetwork is regional and names its network by partial URL", () => {
+    const plan = MAPPERS.ComputeSubnetwork.plan(find("ComputeSubnetwork"), nctx);
+    expect(plan.create.url).toBe("https://compute.googleapis.com/compute/v1/projects/p1/regions/europe-west1/subnetworks");
+    expect(plan.create.body).toEqual({
+      name: "apps",
+      ipCidrRange: "10.0.0.0/24",
+      privateIpGoogleAccess: true,
+      network: "projects/p1/global/networks/vpc",
+      secondaryIpRanges: [{ rangeName: "pods", ipCidrRange: "10.4.0.0/14" }],
+    });
+  });
+
+  test("apply order: network, then subnetwork, then the Cloud Run service that egresses into them", () => {
+    const order = orderByReferences(net).map((r) => r.kind);
+    expect(order.indexOf("ComputeNetwork")).toBeLessThan(order.indexOf("ComputeSubnetwork"));
+    expect(order.indexOf("ComputeSubnetwork")).toBeLessThan(order.indexOf("RunService"));
+  });
+
+  test("the reader reads a network at its global URL", async () => {
+    const http = async (_m: string, url: string) =>
+      url.endsWith("/global/networks/vpc") ? { status: 200, text: JSON.stringify({ name: "vpc" }) } : { status: 404, text: "" };
+    expect(await getResource({ project: "p1", http }, "ComputeNetwork", "vpc", {})).toEqual({ name: "vpc" });
+  });
+
+  test("deep observe inverts both body builders", async () => {
+    const { toCnrmTree } = await import("../../deep-observe");
+    const c = { project: "p1" };
+    expect(
+      toCnrmTree(
+        "ComputeNetwork",
+        {
+          name: "vpc",
+          autoCreateSubnetworks: false,
+          routingConfig: { routingMode: "REGIONAL" },
+          subnetworks: ["https://compute.googleapis.com/compute/v1/projects/p1/regions/europe-west1/subnetworks/apps"],
+        },
+        c,
+      ),
+    ).toEqual({ metadata: { name: "vpc" }, autoCreateSubnetworks: false, routingMode: "REGIONAL" });
+    expect(
+      toCnrmTree(
+        "ComputeSubnetwork",
+        {
+          name: "apps",
+          region: "https://compute.googleapis.com/compute/v1/projects/p1/regions/europe-west1",
+          network: "https://compute.googleapis.com/compute/v1/projects/p1/global/networks/vpc",
+          ipCidrRange: "10.0.0.0/24",
+          gatewayAddress: "10.0.0.1",
+          fingerprint: "abc",
+          secondaryIpRanges: [{ rangeName: "pods", ipCidrRange: "10.4.0.0/14" }],
+        },
+        c,
+      ),
+    ).toEqual({
+      metadata: { name: "apps" },
+      region: "europe-west1",
+      networkRef: { name: "vpc" },
+      ipCidrRange: "10.0.0.0/24",
+      secondaryIpRange: [{ rangeName: "pods", ipCidrRange: "10.4.0.0/14" }],
+    });
+  });
+});

package/src/op/activities/gcp-compute.ts

@@ -0,0 +1,354 @@
+/**
+ * Compute Engine mappers for the Cloud Run load balancer (#4233): ComputeAddress,
+ * ComputeRegionNetworkEndpointGroup (serverless NEGs), ComputeBackendService,
+ * ComputeURLMap, ComputeTargetHTTPProxy and ComputeForwardingRule; and for a
+ * declared network (#4248): ComputeNetwork (always global) and
+ * ComputeSubnetwork (regional, by its CNRM `region`).
+ *
+ * Each maps a CNRM spec onto the compute v1 insert body. A resource is global
+ * or regional by its CNRM `location` (`"global"` or a region; a NEG has
+ * `region`), and that picks `projects/<p>/global/<collection>` or
+ * `projects/<p>/regions/<r>/<collection>`. `*Ref` fields become the referenced
+ * resource's partial URL, which compute accepts; a ref to a resource in the
+ * same manifest takes its scope from that resource's own spec, so a global
+ * backend service can point at a regional NEG.
+ *
+ * Inserts return a compute `Operation`, polled at its `selfLink` (rebased onto
+ * the endpoint override, so floci-gcp answers). These kinds reconcile by
+ * existence only: an existing resource is left as it is, since compute updates
+ * need the live `fingerprint` and most of these fields are immutable.
+ */
+import { GCP_RESOURCE_OWNERSHIP_KEYS } from "../../ownership";
+import { OWNERSHIP_MANAGED_BY_VALUE } from "@intentius/chant/ownership";
+import type { GcpResource, OperationSpec, ResourceMapper } from "./gcp-apply";
+
+export const COMPUTE_HOST = "https://compute.googleapis.com";
+
+const enc = encodeURIComponent;
+
+type Ref = { name?: string; external?: string; kind?: string };
+type Obj = Record<string, unknown>;
+
+function isObj(v: unknown): v is Obj {
+  return v !== null && typeof v === "object" && !Array.isArray(v);
+}
+
+/** What a `*Ref` key points at: the CNRM kind (for a manifest lookup), the collection, and whether it is global only. */
+const REF_TARGETS: Record<string, { kind: string; collection: string; scope: "global" | "regional" | "either" }> = {
+  addressRef: { kind: "ComputeAddress", collection: "addresses", scope: "either" },
+  networkEndpointGroupRef: { kind: "ComputeRegionNetworkEndpointGroup", collection: "networkEndpointGroups", scope: "regional" },
+  backendServiceRef: { kind: "ComputeBackendService", collection: "backendServices", scope: "either" },
+  backendBucketRef: { kind: "ComputeBackendBucket", collection: "backendBuckets", scope: "global" },
+  urlMapRef: { kind: "ComputeURLMap", collection: "urlMaps", scope: "either" },
+  targetHTTPProxyRef: { kind: "ComputeTargetHTTPProxy", collection: "targetHttpProxies", scope: "either" },
+  targetHTTPSProxyRef: { kind: "ComputeTargetHTTPSProxy", collection: "targetHttpsProxies", scope: "either" },
+  healthCheckRef: { kind: "ComputeHealthCheck", collection: "healthChecks", scope: "either" },
+  securityPolicyRef: { kind: "ComputeSecurityPolicy", collection: "securityPolicies", scope: "global" },
+  networkRef: { kind: "ComputeNetwork", collection: "networks", scope: "global" },
+  subnetworkRef: { kind: "ComputeSubnetwork", collection: "subnetworks", scope: "regional" },
+};
+
+export interface ComputeCtx {
+  base: string;
+  project: string;
+  manifest?: readonly GcpResource[];
+}
+
+/** The region or `"global"` a CNRM compute spec declares. A NEG names `region`; the rest `location`. */
+export function scopeOf(spec: Obj | undefined, env: NodeJS.ProcessEnv = process.env): string {
+  const loc = spec?.location ?? spec?.region;
+  return typeof loc === "string" && loc !== "" ? loc : (env.GCP_REGION || "us-central1");
+}
+
+function scopePath(project: string, scope: string): string {
+  return scope === "global" ? `projects/${enc(project)}/global` : `projects/${enc(project)}/regions/${enc(scope)}`;
+}
+
+/** The compute name: CNRM's `resourceID` when set, else `metadata.name`. */
+export function computeName(resource: GcpResource): string {
+  const id = (resource.spec as Obj | undefined)?.resourceID;
+  const name = typeof id === "string" && id !== "" ? id : resource.metadata?.name;
+  if (!name) throw new Error(`${resource.kind ?? "compute resource"} has no metadata.name`);
+  return name;
+}
+
+/**
+ * The partial URL a `*Ref` resolves to. `external` is used as given when it is
+ * a path or URL; a bare name (or `name`) is scoped by the referenced resource's
+ * own spec when the manifest holds it, else by `fallbackScope`. Pure.
+ */
+export function refUrl(key: string, ref: Ref, ctx: ComputeCtx, fallbackScope: string): string {
+  const target = REF_TARGETS[key];
+  if (!target) throw new Error(`no compute collection for ${key}`);
+  if (typeof ref.external === "string" && ref.external !== "") {
+    if (ref.external.startsWith("projects/") || ref.external.startsWith("https://")) return ref.external;
+  }
+  const name = ref.name ?? ref.external;
+  if (!name) throw new Error(`${key} has no name or external`);
+  const declared = ctx.manifest?.find((r) => r.kind === target.kind && (r.metadata?.name === name || (r.spec as Obj | undefined)?.resourceID === name));
+  const scope =
+    target.scope === "global"
+      ? "global"
+      : declared
+        ? scopeOf(declared.spec as Obj)
+        : target.scope === "regional" && fallbackScope === "global"
+          ? scopeOf(undefined)
+          : fallbackScope;
+  const resolvedName = declared ? computeName(declared) : name;
+  return `${scopePath(ctx.project, scope)}/${target.collection}/${resolvedName}`;
+}
+
+/** Resolve the one `*Ref` key an object holds (`{ backendServiceRef: {...} }` → URL), or undefined. */
+function oneRef(value: unknown, ctx: ComputeCtx, scope: string): string | undefined {
+  if (!isObj(value)) return undefined;
+  for (const [k, v] of Object.entries(value)) {
+    if (REF_TARGETS[k] && isObj(v)) return refUrl(k, v as Ref, ctx, scope);
+  }
+  return undefined;
+}
+
+/** Copy the listed fields that are set. */
+function pick(spec: Obj, keys: readonly string[]): Obj {
+  const out: Obj = {};
+  for (const k of keys) if (spec[k] !== undefined) out[k] = spec[k];
+  return out;
+}
+
+/**
+ * The resource's labels GCP accepts, plus the ownership marker. Composites put
+ * Kubernetes-style keys (`app.kubernetes.io/component`) in `metadata.labels`,
+ * which a compute label key can't hold, so those are left out.
+ */
+export function computeLabels(labels: Record<string, string> | undefined): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const [k, v] of Object.entries(labels ?? {})) {
+    if (/^[a-z][a-z0-9_-]{0,62}$/.test(k) && typeof v === "string" && /^[a-z0-9_-]{0,63}$/.test(v)) out[k] = v;
+  }
+  return { ...out, [GCP_RESOURCE_OWNERSHIP_KEYS.managedBy]: OWNERSHIP_MANAGED_BY_VALUE };
+}
+
+/** ComputeAddress → addresses.insert body. Pure. */
+export function addressBody(resource: GcpResource, ctx: ComputeCtx): Obj {
+  const spec = (resource.spec ?? {}) as Obj;
+  const scope = scopeOf(spec);
+  const body: Obj = {
+    name: computeName(resource),
+    ...pick(spec, ["address", "addressType", "description", "ipVersion", "ipv6EndpointType", "networkTier", "prefixLength", "purpose"]),
+    labels: computeLabels(resource.metadata?.labels),
+  };
+  if (isObj(spec.networkRef)) body.network = refUrl("networkRef", spec.networkRef as Ref, ctx, scope);
+  if (isObj(spec.subnetworkRef)) body.subnetwork = refUrl("subnetworkRef", spec.subnetworkRef as Ref, ctx, scope);
+  return body;
+}
+
+/** ComputeRegionNetworkEndpointGroup → regionNetworkEndpointGroups.insert body (serverless NEGs). Pure. */
+export function negBody(resource: GcpResource, ctx: ComputeCtx): Obj {
+  const spec = (resource.spec ?? {}) as Obj;
+  const scope = scopeOf(spec);
+  const body: Obj = {
+    name: computeName(resource),
+    networkEndpointType: (spec.networkEndpointType as string | undefined) ?? "SERVERLESS",
+    ...pick(spec, ["description", "pscTargetService"]),
+  };
+  const serviceName = (ref: unknown): string | undefined => {
+    if (!isObj(ref)) return undefined;
+    const r = ref as Ref;
+    // A serverless NEG names the service, not its path.
+    return (r.external ?? r.name)?.split("/").pop();
+  };
+  if (isObj(spec.cloudRun)) {
+    const c = spec.cloudRun as Obj;
+    body.cloudRun = { ...pick(c, ["tag", "urlMask"]), ...(serviceName(c.serviceRef) ? { service: serviceName(c.serviceRef) } : {}) };
+  }
+  if (isObj(spec.cloudFunction)) {
+    const c = spec.cloudFunction as Obj;
+    body.cloudFunction = { ...pick(c, ["urlMask"]), ...(serviceName(c.functionRef) ? { function: serviceName(c.functionRef) } : {}) };
+  }
+  if (isObj(spec.appEngine)) body.appEngine = spec.appEngine;
+  if (isObj(spec.networkRef)) body.network = refUrl("networkRef", spec.networkRef as Ref, ctx, scope);
+  if (isObj(spec.subnetworkRef)) body.subnetwork = refUrl("subnetworkRef", spec.subnetworkRef as Ref, ctx, scope);
+  return body;
+}
+
+/**
+ * ComputeNetwork → networks.insert body. A network is global. CNRM's
+ * `autoCreateSubnetworks` defaults to false, where compute's default is true,
+ * so it is always sent. Pure.
+ */
+export function networkBody(resource: GcpResource): Obj {
+  const spec = (resource.spec ?? {}) as Obj;
+  const body: Obj = {
+    name: computeName(resource),
+    autoCreateSubnetworks: spec.autoCreateSubnetworks === true,
+    ...pick(spec, ["description", "mtu", "networkFirewallPolicyEnforcementOrder"]),
+  };
+  if (typeof spec.routingMode === "string") body.routingConfig = { routingMode: spec.routingMode };
+  return body;
+}
+
+/** ComputeSubnetwork → subnetworks.insert body. CNRM's `secondaryIpRange` and `logConfig` become compute's `secondaryIpRanges` and an enabled `logConfig`. Pure. */
+export function subnetworkBody(resource: GcpResource, ctx: ComputeCtx): Obj {
+  const spec = (resource.spec ?? {}) as Obj;
+  const scope = scopeOf(spec);
+  const body: Obj = {
+    name: computeName(resource),
+    ...pick(spec, ["ipCidrRange", "description", "privateIpGoogleAccess", "purpose", "role", "stackType"]),
+  };
+  if (isObj(spec.networkRef)) body.network = refUrl("networkRef", spec.networkRef as Ref, ctx, scope);
+  if (Array.isArray(spec.secondaryIpRange)) body.secondaryIpRanges = spec.secondaryIpRange;
+  if (isObj(spec.logConfig)) body.logConfig = { enable: true, ...spec.logConfig };
+  return body;
+}
+
+/** ComputeBackendService → backendServices.insert body. Pure. */
+export function backendServiceBody(resource: GcpResource, ctx: ComputeCtx): Obj {
+  const spec = (resource.spec ?? {}) as Obj;
+  const scope = scopeOf(spec);
+  const body: Obj = {
+    name: computeName(resource),
+    ...pick(spec, [
+      "affinityCookieTtlSec",
+      "cdnPolicy",
+      "compressionMode",
+      "customRequestHeaders",
+      "customResponseHeaders",
+      "description",
+      "loadBalancingScheme",
+      "localityLbPolicy",
+      "logConfig",
+      "portName",
+      "protocol",
+      "sessionAffinity",
+      "timeoutSec",
+    ]),
+  };
+  if (spec.enableCdn !== undefined) body.enableCDN = spec.enableCdn;
+  if (spec.connectionDrainingTimeoutSec !== undefined) body.connectionDraining = { drainingTimeoutSec: spec.connectionDrainingTimeoutSec };
+  if (Array.isArray(spec.backend)) {
+    body.backends = (spec.backend as Obj[]).map((b) => {
+      const { group, ...rest } = b;
+      const groupUrl = isObj(group) ? oneRef(group, ctx, scope) ?? ((group as Obj).instanceGroupRef as Ref | undefined)?.external : undefined;
+      return { ...rest, ...(groupUrl ? { group: groupUrl } : {}) };
+    });
+  }
+  if (Array.isArray(spec.healthChecks)) {
+    body.healthChecks = (spec.healthChecks as Obj[]).map((h) => oneRef(h, ctx, scope)).filter((u): u is string => !!u);
+  }
+  if (isObj(spec.securityPolicyRef)) body.securityPolicy = refUrl("securityPolicyRef", spec.securityPolicyRef as Ref, ctx, scope);
+  else if (typeof spec.securityPolicy === "string") body.securityPolicy = spec.securityPolicy;
+  return body;
+}
+
+/** ComputeURLMap → urlMaps.insert body. Pure. */
+export function urlMapBody(resource: GcpResource, ctx: ComputeCtx): Obj {
+  const spec = (resource.spec ?? {}) as Obj;
+  const scope = scopeOf(spec);
+  const service = (v: unknown) => oneRef(v, ctx, scope);
+  const body: Obj = {
+    name: computeName(resource),
+    ...pick(spec, ["description", "defaultUrlRedirect", "headerAction"]),
+  };
+  const def = service(spec.defaultService);
+  if (def) body.defaultService = def;
+  if (Array.isArray(spec.hostRule)) body.hostRules = spec.hostRule;
+  if (Array.isArray(spec.pathMatcher)) {
+    body.pathMatchers = (spec.pathMatcher as Obj[]).map((m) => {
+      const { defaultService, pathRule, ...rest } = m;
+      const out: Obj = { ...rest };
+      const d = service(defaultService);
+      if (d) out.defaultService = d;
+      if (Array.isArray(pathRule)) {
+        out.pathRules = (pathRule as Obj[]).map((r) => {
+          const { service: s, ...rr } = r;
+          const u = service(s);
+          return { ...rr, ...(u ? { service: u } : {}) };
+        });
+      }
+      return out;
+    });
+  }
+  return body;
+}
+
+/** ComputeTargetHTTPProxy → targetHttpProxies.insert body. Pure. */
+export function targetHttpProxyBody(resource: GcpResource, ctx: ComputeCtx): Obj {
+  const spec = (resource.spec ?? {}) as Obj;
+  const body: Obj = { name: computeName(resource), ...pick(spec, ["description", "proxyBind", "httpKeepAliveTimeoutSec"]) };
+  if (isObj(spec.urlMapRef)) body.urlMap = refUrl("urlMapRef", spec.urlMapRef as Ref, ctx, scopeOf(spec));
+  return body;
+}
+
+/** ComputeForwardingRule → forwardingRules.insert body. Pure. */
+export function forwardingRuleBody(resource: GcpResource, ctx: ComputeCtx): Obj {
+  const spec = (resource.spec ?? {}) as Obj;
+  const scope = scopeOf(spec);
+  const body: Obj = {
+    name: computeName(resource),
+    ...pick(spec, ["allowGlobalAccess", "description", "ipVersion", "isMirroringCollector", "loadBalancingScheme", "networkTier", "portRange", "ports", "allPorts"]),
+    labels: computeLabels(resource.metadata?.labels),
+  };
+  if (spec.ipProtocol !== undefined) body.IPProtocol = spec.ipProtocol;
+  if (isObj(spec.ipAddress)) {
+    const ip = spec.ipAddress as Obj;
+    const addr = isObj(ip.addressRef) ? refUrl("addressRef", ip.addressRef as Ref, ctx, scope) : (ip.ip as string | undefined);
+    if (addr) body.IPAddress = addr;
+  }
+  const target = oneRef(spec.target, ctx, scope);
+  if (target) body.target = target;
+  if (isObj(spec.backendServiceRef)) body.backendService = refUrl("backendServiceRef", spec.backendServiceRef as Ref, ctx, scope);
+  if (isObj(spec.networkRef)) body.network = refUrl("networkRef", spec.networkRef as Ref, ctx, scope);
+  if (isObj(spec.subnetworkRef)) body.subnetwork = refUrl("subnetworkRef", spec.subnetworkRef as Ref, ctx, scope);
+  return body;
+}
+
+/**
+ * A compute `Operation`: the insert or delete returns one with a `selfLink`,
+ * polled until `status: "DONE"`. The link is rebased onto `base`, so an
+ * endpoint override (floci-gcp) is polled too. A create that returned the
+ * resource itself has nothing to poll.
+ */
+export const computeOperation: OperationSpec = {
+  pollUrl(body, { base }) {
+    const op = body as { kind?: string; selfLink?: string } | undefined;
+    const link = op?.selfLink;
+    if (!link || !link.includes("/operations/")) return undefined;
+    const at = link.indexOf("/compute/v1/");
+    return at >= 0 ? `${base}${link.slice(at)}` : link;
+  },
+  isDone(body) {
+    return (body as { status?: string })?.status === "DONE";
+  },
+  error(body) {
+    const errors = (body as { error?: { errors?: Array<{ message?: string; code?: string }> } })?.error?.errors;
+    return errors?.length ? errors.map((e) => e.message ?? e.code ?? "error").join("; ") : undefined;
+  },
+};
+
+function computeMapper(
+  kind: string,
+  collection: string,
+  build: (resource: GcpResource, ctx: ComputeCtx) => Obj,
+  regionalCollection = collection,
+  scopeFor: (spec: Obj | undefined) => string = (spec) => scopeOf(spec),
+): ResourceMapper {
+  return {
+    kind,
+    defaultHost: COMPUTE_HOST,
+    operation: computeOperation,
+    plan(resource, ctx) {
+      const scope = scopeFor(resource.spec as Obj | undefined);
+      const coll = `${ctx.base}/compute/v1/${scopePath(ctx.project, scope)}/${scope === "global" ? collection : regionalCollection}`;
+      const name = computeName(resource);
+      return { getUrl: `${coll}/${enc(name)}`, create: { method: "POST", url: coll, body: build(resource, ctx) } };
+    },
+  };
+}
+
+export const computeAddressMapper = computeMapper("ComputeAddress", "addresses", addressBody);
+export const regionNetworkEndpointGroupMapper = computeMapper("ComputeRegionNetworkEndpointGroup", "networkEndpointGroups", negBody);
+export const backendServiceMapper = computeMapper("ComputeBackendService", "backendServices", backendServiceBody);
+export const urlMapMapper = computeMapper("ComputeURLMap", "urlMaps", urlMapBody);
+export const targetHttpProxyMapper = computeMapper("ComputeTargetHTTPProxy", "targetHttpProxies", targetHttpProxyBody);
+export const forwardingRuleMapper = computeMapper("ComputeForwardingRule", "forwardingRules", forwardingRuleBody);
+export const networkMapper = computeMapper("ComputeNetwork", "networks", networkBody, "networks", () => "global");
+export const subnetworkMapper = computeMapper("ComputeSubnetwork", "subnetworks", subnetworkBody);