@intentius/chant-lexicon-gcp 0.124.38 → 0.124.39

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

@@ -0,0 +1,150 @@
+import { beforeEach, describe, expect, test } from "vitest";
+import { applyResource, MAPPERS, type GcpHttp, type GcpResource } from "./gcp-apply";
+import { changedFields, computeLabels, holds } from "./gcp-compute";
+
+beforeEach(() => {
+  delete process.env.GCP_REGION;
+});
+
+const base = "https://compute.googleapis.com";
+const lb: GcpResource[] = [
+  {
+    kind: "ComputeForwardingRule",
+    metadata: { name: "web-fr" },
+    spec: {
+      location: "global",
+      portRange: "80",
+      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", protocol: "HTTPS", timeoutSec: 30, 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" } },
+];
+const ctx = { base, project: "p1", manifest: lb };
+const byKind = (kind: string) => lb.find((r) => r.kind === kind)!;
+const url = (path: string) => `${base}/compute/v1/projects/p1/${path}`;
+const OP = JSON.stringify({ kind: "compute#operation", selfLink: url("global/operations/op-1"), status: "DONE" });
+
+/** A fake compute API: GETs answer from `live`, every write is recorded and returns a finished operation. */
+function fakeCompute(live: Record<string, unknown>) {
+  const writes: Array<{ method: string; url: string; body: unknown }> = [];
+  const http: GcpHttp = async (method, u, body) => {
+    if (method === "GET") {
+      const hit = live[u];
+      if (hit !== undefined) return { status: 200, text: JSON.stringify(hit) };
+      if (u.includes("/operations/")) return { status: 200, text: OP };
+      return { status: 404, text: "" };
+    }
+    writes.push({ method, url: u, body });
+    return { status: 200, text: OP };
+  };
+  return { http, writes };
+}
+
+describe("compute reconcile against the live resource (#4238)", () => {
+  test("holds: a full compute URL holds its partial form, and live-only fields don't count", () => {
+    expect(holds("projects/p1/global/urlMaps/m", url("global/urlMaps/m"))).toBe(true);
+    expect(holds({ a: 1 }, { a: 1, b: 2 })).toBe(true);
+    expect(holds([{ group: "projects/p1/x" }], [{ group: `${base}/compute/v1/projects/p1/x`, balancingMode: "UTILIZATION" }])).toBe(true);
+    expect(holds([1], [1, 2])).toBe(false);
+    expect(changedFields({ name: "n", a: 1, b: 2 }, { name: "other", a: 1, b: 3 })).toEqual(["b"]);
+  });
+
+  test("a backend service that matches is left alone; a change is a PATCH carrying the live fingerprint", async () => {
+    const liveBody = {
+      name: "web",
+      fingerprint: "fp-1",
+      protocol: "HTTPS",
+      timeoutSec: 30,
+      backends: [{ group: url("regions/europe-west1/networkEndpointGroups/web"), balancingMode: "UTILIZATION" }],
+    };
+    const same = fakeCompute({ [url("global/backendServices/web")]: liveBody });
+    await expect(applyResource(MAPPERS.ComputeBackendService, byKind("ComputeBackendService"), ctx, same.http)).resolves.toMatchObject({ updated: false });
+    expect(same.writes).toEqual([]);
+
+    const drifted = fakeCompute({ [url("global/backendServices/web")]: { ...liveBody, timeoutSec: 10 } });
+    await expect(applyResource(MAPPERS.ComputeBackendService, byKind("ComputeBackendService"), ctx, drifted.http)).resolves.toMatchObject({ updated: true });
+    expect(drifted.writes).toHaveLength(1);
+    expect(drifted.writes[0]).toMatchObject({ method: "PATCH", url: url("global/backendServices/web"), body: { timeoutSec: 30, fingerprint: "fp-1" } });
+  });
+
+  test("a URL map's new default service is a PATCH with the fingerprint", async () => {
+    const f = fakeCompute({ [url("global/urlMaps/web-map")]: { name: "web-map", fingerprint: "fp-m", defaultService: url("global/backendServices/old") } });
+    await applyResource(MAPPERS.ComputeURLMap, byKind("ComputeURLMap"), ctx, f.http);
+    expect(f.writes).toEqual([
+      { method: "PATCH", url: url("global/urlMaps/web-map"), body: expect.objectContaining({ defaultService: "projects/p1/global/backendServices/web", fingerprint: "fp-m" }) },
+    ]);
+  });
+
+  test("a proxy's URL map changes through setUrlMap", async () => {
+    const f = fakeCompute({ [url("global/targetHttpProxies/web-proxy")]: { name: "web-proxy", urlMap: url("global/urlMaps/old") } });
+    await applyResource(MAPPERS.ComputeTargetHTTPProxy, byKind("ComputeTargetHTTPProxy"), ctx, f.http);
+    expect(f.writes).toEqual([{ method: "POST", url: url("global/targetHttpProxies/web-proxy/setUrlMap"), body: { urlMap: "projects/p1/global/urlMaps/web-map" } }]);
+  });
+
+  test("a forwarding rule: the declared address's IP holds, the target changes by setTarget, labels by setLabels", async () => {
+    const f = fakeCompute({
+      [url("global/forwardingRules/web-fr")]: {
+        name: "web-fr",
+        portRange: "80",
+        IPAddress: "34.1.2.3",
+        target: url("global/targetHttpProxies/old"),
+        labels: {},
+        labelFingerprint: "lf-1",
+      },
+      [url("global/addresses/web-ip")]: { name: "web-ip", address: "34.1.2.3" },
+    });
+    await applyResource(MAPPERS.ComputeForwardingRule, byKind("ComputeForwardingRule"), ctx, f.http);
+    expect(f.writes).toEqual([
+      { method: "POST", url: url("global/forwardingRules/web-fr/setTarget"), body: { target: "projects/p1/global/targetHttpProxies/web-proxy" } },
+      { method: "POST", url: url("global/forwardingRules/web-fr/setLabels"), body: { labels: computeLabels(undefined), labelFingerprint: "lf-1" } },
+    ]);
+  });
+
+  test("a forwarding rule on another IP, a changed address and a changed NEG are reported for replacement, not written", async () => {
+    const fr = fakeCompute({
+      [url("global/forwardingRules/web-fr")]: {
+        name: "web-fr",
+        portRange: "80",
+        IPAddress: "10.0.0.9",
+        target: url("global/targetHttpProxies/web-proxy"),
+        labels: computeLabels(undefined),
+      },
+      [url("global/addresses/web-ip")]: { name: "web-ip", address: "34.1.2.3" },
+    });
+    const r = await applyResource(MAPPERS.ComputeForwardingRule, byKind("ComputeForwardingRule"), ctx, fr.http);
+    expect(r).toMatchObject({ updated: false, replaceRequired: expect.stringContaining("IPAddress") });
+    expect(fr.writes).toEqual([]);
+
+    const neg = fakeCompute({
+      [url("regions/europe-west1/networkEndpointGroups/web")]: { name: "web", networkEndpointType: "SERVERLESS", cloudRun: { service: "other" } },
+    });
+    const n = await applyResource(MAPPERS.ComputeRegionNetworkEndpointGroup, byKind("ComputeRegionNetworkEndpointGroup"), ctx, neg.http);
+    expect(n.replaceRequired).toMatch(/cloudRun/);
+    expect(neg.writes).toEqual([]);
+
+    const addr = fakeCompute({ [url("global/addresses/web-ip")]: { name: "web-ip", address: "34.1.2.3", labels: computeLabels(undefined), addressType: "INTERNAL" } });
+    const changed = { ...byKind("ComputeAddress"), spec: { location: "global", addressType: "EXTERNAL" } };
+    const a = await applyResource(MAPPERS.ComputeAddress, changed, ctx, addr.http);
+    expect(a.replaceRequired).toMatch(/addressType/);
+    expect(addr.writes).toEqual([]);
+  });
+
+  test("an address's labels change through setLabels", async () => {
+    const f = fakeCompute({ [url("global/addresses/web-ip")]: { name: "web-ip", address: "34.1.2.3", labels: {}, labelFingerprint: "lf-a" } });
+    await applyResource(MAPPERS.ComputeAddress, byKind("ComputeAddress"), ctx, f.http);
+    expect(f.writes).toEqual([{ method: "POST", url: url("global/addresses/web-ip/setLabels"), body: { labels: computeLabels(undefined), labelFingerprint: "lf-a" } }]);
+  });
+});

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

@@ -60,7 +60,7 @@ describe("compute load balancer mappers (#4233)", () => {
   });
 
   test("a serverless NEG is regional and names its Cloud Run service", () => {
-    expect(plan("ComputeRegionNetworkEndpointGroup")).toEqual({
+    expect(plan("ComputeRegionNetworkEndpointGroup")).toMatchObject({
       getUrl: "https://compute.googleapis.com/compute/v1/projects/p1/regions/europe-west1/networkEndpointGroups/web",
       create: {
         method: "POST",
@@ -138,7 +138,9 @@ describe("compute operations (#4233)", () => {
     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 === "GET" && url.endsWith("/addresses/web-ip")) {
+        return exists ? { status: 200, text: JSON.stringify({ name: "web-ip", labels: computeLabels(undefined) }) } : { 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" }) };

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

@@ -14,13 +14,20 @@
  * 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.
+ * the endpoint override, so floci-gcp answers).
+ *
+ * An existing load balancer resource is compared with its desired body and
+ * updated in place where compute allows it (#4238): a backend service or URL
+ * map by PATCH with the live `fingerprint`, a proxy's URL map by `setUrlMap`,
+ * a forwarding rule's target by `setTarget`, labels by `setLabels` with the
+ * live `labelFingerprint`. A difference on a field compute can't change in
+ * place (anything on a serverless NEG, an address's IP) is reported as
+ * "replace required" and left alone. A network and a subnetwork still
+ * reconcile by existence only.
  */
 import { GCP_RESOURCE_OWNERSHIP_KEYS } from "../../ownership";
 import { OWNERSHIP_MANAGED_BY_VALUE } from "@intentius/chant/ownership";
-import type { GcpResource, OperationSpec, ResourceMapper } from "./gcp-apply";
+import type { GcpHttp, GcpResource, OperationSpec, ReconcileStep, ResourceMapper } from "./gcp-apply";
 
 export const COMPUTE_HOST = "https://compute.googleapis.com";
 
@@ -324,12 +331,103 @@ export const computeOperation: OperationSpec = {
   },
 };
 
+/** A compute reference with everything before `projects/` dropped, so a full URL and a partial one compare equal. */
+function refTail(v: string): string {
+  const at = v.indexOf("projects/");
+  return at >= 0 ? v.slice(at) : v;
+}
+
+/**
+ * True when the live value holds the desired one: every desired key is set
+ * live to an equal value, arrays element by element, and a compute URL
+ * equals its partial form. Fields only the live side has (defaults, server
+ * ids) don't count. Pure.
+ */
+export function holds(desired: unknown, live: unknown): boolean {
+  if (typeof desired === "string" && typeof live === "string") {
+    return desired === live || (desired.includes("projects/") && refTail(desired) === refTail(live));
+  }
+  if (Array.isArray(desired)) {
+    return Array.isArray(live) && desired.length === live.length && desired.every((d, i) => holds(d, live[i]));
+  }
+  if (isObj(desired)) {
+    return isObj(live) && Object.entries(desired).every(([k, v]) => holds(v, live[k]));
+  }
+  return desired === live;
+}
+
+/** The desired body's top-level fields the live resource doesn't hold, `name` aside. Pure. */
+export function changedFields(desired: Obj, live: Obj): string[] {
+  return Object.keys(desired).filter((k) => k !== "name" && !holds(desired[k], live[k]));
+}
+
+type Reconcile = (args: {
+  url: string;
+  desired: Obj;
+  live: Obj;
+  changed: string[];
+  ctx: ComputeCtx;
+  http: GcpHttp;
+  signal?: AbortSignal;
+}) => Promise<ReconcileStep>;
+
+const replace = (kind: string, fields: readonly string[]): ReconcileStep => ({
+  replace: `${fields.join(", ")} differ${fields.length === 1 ? "s" : ""}, and compute can't change ${fields.length === 1 ? "it" : "them"} on a ${kind} in place`,
+});
+
+/** `labels` by `setLabels` with the live `labelFingerprint`; anything else changed is a replace. */
+function labelsOnly(kind: string): Reconcile {
+  return async ({ url, desired, live, changed }) => {
+    const other = changed.filter((f) => f !== "labels");
+    if (other.length) return replace(kind, other);
+    if (!changed.length) return { requests: [] };
+    return { requests: [{ method: "POST", url: `${url}/setLabels`, body: { labels: desired.labels, labelFingerprint: live.labelFingerprint } }] };
+  };
+}
+
+/** Every changed field by one PATCH carrying the live `fingerprint` (backend services, URL maps). */
+const patchWithFingerprint: Reconcile = async ({ url, desired, live, changed }) =>
+  changed.length ? { requests: [{ method: "PATCH", url, body: { ...desired, fingerprint: live.fingerprint } }] } : { requests: [] };
+
+const reconcileProxy: Reconcile = async ({ url, desired, changed }) => {
+  const other = changed.filter((f) => f !== "urlMap");
+  if (other.length) return replace("ComputeTargetHTTPProxy", other);
+  return changed.length ? { requests: [{ method: "POST", url: `${url}/setUrlMap`, body: { urlMap: desired.urlMap } }] } : { requests: [] };
+};
+
+/**
+ * A forwarding rule's `IPAddress` is a declared address's partial URL, where
+ * the live rule holds the IP itself, so the address is read and its IP
+ * compared. The target changes by `setTarget`, labels by `setLabels`; any
+ * other field is a replace.
+ */
+const reconcileForwardingRule: Reconcile = async ({ url, desired, live, changed, ctx, http, signal }) => {
+  let fields = changed;
+  const ip = desired.IPAddress;
+  if (fields.includes("IPAddress") && typeof ip === "string" && ip.includes("/addresses/")) {
+    const res = await http("GET", `${ctx.base}/compute/v1/${refTail(ip)}`, undefined, signal);
+    const address = res.status === 200 ? (JSON.parse(res.text) as Obj).address : undefined;
+    if (address !== undefined && address === live.IPAddress) fields = fields.filter((f) => f !== "IPAddress");
+  }
+  const other = fields.filter((f) => f !== "target" && f !== "labels");
+  if (other.length) return replace("ComputeForwardingRule", other);
+  const requests: Array<{ method: "POST"; url: string; body: unknown }> = [];
+  if (fields.includes("target")) requests.push({ method: "POST", url: `${url}/setTarget`, body: { target: desired.target } });
+  if (fields.includes("labels")) {
+    requests.push({ method: "POST", url: `${url}/setLabels`, body: { labels: desired.labels, labelFingerprint: live.labelFingerprint } });
+  }
+  return { requests };
+};
+
+const replaceOnAnyChange = (kind: string): Reconcile => async ({ changed }) => (changed.length ? replace(kind, changed) : { requests: [] });
+
 function computeMapper(
   kind: string,
   collection: string,
   build: (resource: GcpResource, ctx: ComputeCtx) => Obj,
   regionalCollection = collection,
   scopeFor: (spec: Obj | undefined) => string = (spec) => scopeOf(spec),
+  reconcile?: Reconcile,
 ): ResourceMapper {
   return {
     kind,
@@ -339,16 +437,36 @@ function computeMapper(
       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) } };
+      const url = `${coll}/${enc(name)}`;
+      const desired = build(resource, ctx);
+      return {
+        getUrl: url,
+        create: { method: "POST", url: coll, body: desired },
+        ...(reconcile
+          ? {
+              reconcile: (live: unknown, http: GcpHttp, signal?: AbortSignal) => {
+                const l = isObj(live) ? live : {};
+                return reconcile({ url, desired, live: l, changed: changedFields(desired, l), ctx, http, signal });
+              },
+            }
+          : {}),
+      };
     },
   };
 }
 
-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 computeAddressMapper = computeMapper("ComputeAddress", "addresses", addressBody, undefined, undefined, labelsOnly("ComputeAddress"));
+export const regionNetworkEndpointGroupMapper = computeMapper(
+  "ComputeRegionNetworkEndpointGroup",
+  "networkEndpointGroups",
+  negBody,
+  undefined,
+  undefined,
+  replaceOnAnyChange("ComputeRegionNetworkEndpointGroup"),
+);
+export const backendServiceMapper = computeMapper("ComputeBackendService", "backendServices", backendServiceBody, undefined, undefined, patchWithFingerprint);
+export const urlMapMapper = computeMapper("ComputeURLMap", "urlMaps", urlMapBody, undefined, undefined, patchWithFingerprint);
+export const targetHttpProxyMapper = computeMapper("ComputeTargetHTTPProxy", "targetHttpProxies", targetHttpProxyBody, undefined, undefined, reconcileProxy);
+export const forwardingRuleMapper = computeMapper("ComputeForwardingRule", "forwardingRules", forwardingRuleBody, undefined, undefined, reconcileForwardingRule);
 export const networkMapper = computeMapper("ComputeNetwork", "networks", networkBody, "networks", () => "global");
 export const subnetworkMapper = computeMapper("ComputeSubnetwork", "subnetworks", subnetworkBody);

package/src/plugin.ts

@@ -411,8 +411,12 @@ export const bucket = new StorageBucket({
 
   deepNormalizationHooks: gcpDeepNormalizationHooks,
 
-  /** Runtime health (#4177): Cloud Run services. Implementation in ./health.ts. */
-  healthTypes: ["GCP::Run::Service"],
+  /**
+   * Runtime health (#4177, #4239): Cloud Run services, backend services and IAM
+   * policy members. Implementation in ./health.ts, whose GCP_HEALTH_TYPES this
+   * list matches; written out so the build never imports the reader.
+   */
+  healthTypes: ["GCP::Run::Service", "GCP::Compute::BackendService", "GCP::Iam::PolicyMember"],
 
   async observeHealth(options) {
     const { observeHealthGcp } = await import("./health");

package/src/skills/chant-gcp.md

@@ -202,6 +202,8 @@ Composites group related Config Connector resources with secure defaults. Each r
 | `ManagedCertificate` | ComputeManagedSslCertificate | Auto-renewal via Google-managed cert |
 | `SecureProject` | Project + IAMAuditConfig + essential Service resources | Audit logging, required APIs enabled, org policy constraints |
 | `GpuNodePool` | ContainerNodePool with GPU accelerators | Scale-to-zero, nvidia.com/gpu taint, GKE metadata workload identity |
+| `PrivateEgressNetwork` | ComputeNetwork + ComputeSubnetwork | Custom mode, regional routing, Private Google Access |
+| `PublicCloudRun` | IAMServiceAccount + RunService + serverless NEG + global external Application Load Balancer | Own service account, Direct VPC egress for private ranges, optional managed certificate with HTTP to HTTPS redirect, optional Cloud Armor policy |
 
 ### Example: GKE cluster with secure defaults