@intentius/chant-lexicon-gcp 0.124.37 → 0.124.39

package/src/health.ts

@@ -1,5 +1,7 @@
 /**
- * Runtime health for GCP (#4177): Cloud Run services.
+ * Runtime health for GCP (#4177): Cloud Run services; and (#4239) backend
+ * services, from `getHealth` on each backend group, and IAM policy members,
+ * healthy when the member holds the role in the target's policy.
  *
  * A Cloud Run v2 service carries its `Ready` condition as `terminalCondition`
  * (`CONDITION_SUCCEEDED`, `CONDITION_FAILED`, pending or reconciling). The v1
@@ -10,10 +12,10 @@
  */
 
 import type { HealthEntry, HealthReadOptions, HealthReadResult, UnobservedEntity } from "@intentius/chant/lexicon";
-import { getResource, GcpReadError, isNotFound, type GcpReadHttp } from "./api/read-client";
-import { deriveGVK, manifestProjectAnnotations, readTargets, resolveReadProject } from "./describe-resources";
+import { getResource, GcpReadError, isNotFound, readUrl, type GcpReadHttp } from "./api/read-client";
+import { deriveGVK, manifestProjectAnnotations, readManifest, readTargets, resolveReadProject } from "./describe-resources";
 
-export const GCP_HEALTH_TYPES = ["GCP::Run::Service"] as const;
+export const GCP_HEALTH_TYPES = ["GCP::Run::Service", "GCP::Compute::BackendService", "GCP::Iam::PolicyMember"] as const;
 
 export interface GcpHealthOptions extends HealthReadOptions {
   http?: GcpReadHttp;
@@ -68,6 +70,77 @@ export function cloudRunEntry(body: CloudRunServiceState, observedAt: string): H
   };
 }
 
+/** One backend group's `getHealth` answer: `healthStatus[].healthState` per endpoint. */
+export interface BackendGroupHealth {
+  group: string;
+  healthStatus?: Array<{ healthState?: string }>;
+  /** Set when the call failed; the group then counts as unknown. */
+  error?: string;
+}
+
+/**
+ * A backend service's verdict from its groups: any endpoint `UNHEALTHY` is
+ * unhealthy; every endpoint `HEALTHY`, with at least one, is healthy; anything
+ * else (no backends, a group that reports no status, as a serverless NEG
+ * does, a failed call) is unknown.
+ */
+export function backendServiceEntry(groups: readonly BackendGroupHealth[], observedAt: string): HealthEntry {
+  const type = "GCP::Compute::BackendService";
+  if (groups.length === 0) return { type, state: "unknown", detail: "no backends", observedAt };
+  let healthy = 0;
+  let unhealthy = 0;
+  let unknown = 0;
+  for (const g of groups) {
+    const states = g.error ? [] : (g.healthStatus ?? []).map((h) => (h.healthState ?? "").toUpperCase());
+    if (states.length === 0) unknown++;
+    else if (states.some((st) => st === "UNHEALTHY")) unhealthy++;
+    else if (states.every((st) => st === "HEALTHY")) healthy++;
+    else unknown++;
+  }
+  const state = unhealthy > 0 ? "unhealthy" : healthy === groups.length ? "healthy" : "unknown";
+  const parts = [`${healthy} of ${groups.length} backend${groups.length === 1 ? "" : "s"} healthy`];
+  if (unhealthy) parts.push(`${unhealthy} unhealthy`);
+  if (unknown) parts.push(`${unknown} with no health status`);
+  return { type, state, detail: parts.join(", "), observedAt };
+}
+
+/** A binding the read found in its target's policy. A missing one is `absent`, never here. */
+export function policyMemberEntry(binding: { role?: string; member?: string; resource?: string }, observedAt: string): HealthEntry {
+  return {
+    type: "GCP::Iam::PolicyMember",
+    state: "healthy",
+    detail: `${binding.member ?? "member"} holds ${binding.role ?? "the role"}${binding.resource ? ` on ${binding.resource}` : ""}`,
+    observedAt,
+  };
+}
+
+const defaultReadHttp: GcpReadHttp = async (method, url, body) => {
+  const res = await fetch(url, {
+    method,
+    ...(body === undefined ? {} : { headers: { "content-type": "application/json" }, body: JSON.stringify(body) }),
+  });
+  return { status: res.status, text: await res.text() };
+};
+
+/** `getHealth` for each of a backend service's groups, at the service's own read URL. */
+async function backendGroupsHealth(url: string, body: Record<string, unknown>, http: GcpReadHttp): Promise<BackendGroupHealth[]> {
+  const backends = Array.isArray(body.backends) ? (body.backends as Array<{ group?: unknown }>) : [];
+  return Promise.all(
+    backends
+      .map((b) => b.group)
+      .filter((g): g is string => typeof g === "string")
+      .map(async (group) => {
+        try {
+          const res = await http("POST", `${url}/getHealth`, { group });
+          if (res.status < 200 || res.status >= 300) return { group, error: `getHealth ${res.status}` };
+          return { group, ...(JSON.parse(res.text) as { healthStatus?: Array<{ healthState?: string }> }) };
+        } catch (err) {
+          return { group, error: err instanceof Error ? err.message : String(err) };
+        }
+      }),
+  );
+}
+
 export async function observeHealthGcp(options: GcpHealthOptions): Promise<HealthReadResult> {
   const observedAt = (options.now?.() ?? new Date()).toISOString();
   const endpoint = process.env.GCP_ENDPOINT_URL;
@@ -76,6 +149,7 @@ export async function observeHealthGcp(options: GcpHealthOptions): Promise<Healt
   const unobserved: Record<string, UnobservedEntity> = {};
   const absent: string[] = [];
   const targets = readTargets(options.entities);
+  const manifest = readManifest(options.entities, targets);
 
   await Promise.all(
     [...options.entities].map(async ([entityName, { entityType }]) => {
@@ -94,13 +168,16 @@ export async function observeHealthGcp(options: GcpHealthOptions): Promise<Healt
         return;
       }
       try {
-        const body = await getResource(
-          { project, ...(endpoint ? { endpoint } : {}), ...(options.http ? { http: options.http } : {}) },
-          gvk.kind,
-          name,
-          props,
-        );
-        entities[entityName] = cloudRunEntry(body as CloudRunServiceState, observedAt);
+        const client = { project, ...(endpoint ? { endpoint } : {}), ...(options.http ? { http: options.http } : {}), manifest };
+        const body = await getResource(client, gvk.kind, name, props);
+        if (gvk.kind === "ComputeBackendService") {
+          const groups = await backendGroupsHealth(readUrl(client, gvk.kind, name, props), body, options.http ?? defaultReadHttp);
+          entities[entityName] = backendServiceEntry(groups, observedAt);
+        } else if (gvk.kind === "IAMPolicyMember") {
+          entities[entityName] = policyMemberEntry(body as { role?: string; member?: string; resource?: string }, observedAt);
+        } else {
+          entities[entityName] = cloudRunEntry(body as CloudRunServiceState, observedAt);
+        }
       } catch (err) {
         if (isNotFound(err)) {
           absent.push(entityName);

package/src/index.ts

@@ -32,7 +32,7 @@ export * from "./generated/index";
 export {
   GkeCluster, CloudRunServiceComposite, CloudSqlInstance, GcsBucket, VpcNetwork,
   PubSubPipeline, CloudFunctionWithTrigger, PrivateService, ManagedCertificate, SecureProject,
-  MemorystoreRedis, MultiRegionVpc, GkeCrdbRegion, GpuNodePool,
+  MemorystoreRedis, MultiRegionVpc, GkeCrdbRegion, GpuNodePool, PrivateEgressNetwork, PublicCloudRun,
   GovernanceFoundation, LocationRestriction, OrganizationAuditConfig,
 } from "./composites/index";
 export type {
@@ -50,6 +50,7 @@ export type {
   MultiRegionVpcConfig, MultiRegionVpcRegion,
   GkeCrdbRegionConfig, GkeCrdbRegionNodeConfig,
   GpuNodePoolProps, GpuNodePoolTaint,
+  PrivateEgressNetworkProps, PublicCloudRunProps,
   GovernanceFoundationProps, LocationRestrictionProps, OrganizationAuditConfigProps,
 } from "./composites/index";
 

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

@@ -104,8 +104,21 @@ export interface ApplyPlan {
   getUrl: string;
   create: { method: "POST" | "PUT"; url: string; body: unknown };
   update?: { method: "PATCH" | "PUT"; url: string; body: unknown };
+  /**
+   * In place of `update`, for a resource whose update depends on the live body
+   * (#4238): compute updates carry the live `fingerprint`, and some fields only
+   * change through a setter (`setTarget`, `setLabels`). Returns the requests to
+   * send, none when the live resource already matches, or `replace` naming what
+   * differs on a field that can't change in place.
+   */
+  reconcile?(live: unknown, http: GcpHttp, signal?: AbortSignal): Promise<ReconcileStep>;
 }
 
+/** What {@link ApplyPlan.reconcile} decided for an existing resource. */
+export type ReconcileStep =
+  | { requests: Array<{ method: "POST" | "PATCH" | "PUT"; url: string; body: unknown }> }
+  | { replace: string };
+
 /**
  * Handles an async create whose response is a long-running operation. Present
  * only on mappers for resources that provision asynchronously (Cloud Run, GKE,
@@ -637,7 +650,7 @@ export async function applyResource(
   ctx: MapperCtx,
   http: GcpHttp = defaultHttp,
   signal?: AbortSignal,
-): Promise<{ kind: string; name: string; created: boolean; updated: boolean }> {
+): Promise<{ kind: string; name: string; created: boolean; updated: boolean; replaceRequired?: string }> {
   const name = resource.metadata?.name ?? "?";
   if (mapper.custom) {
     const result = await mapper.custom.apply(resource, ctx, http, signal);
@@ -646,6 +659,23 @@ export async function applyResource(
   const plan = mapper.plan(resource, ctx);
   const get = await http("GET", plan.getUrl, undefined, signal);
 
+  if (get.status === 200 && plan.reconcile) {
+    const step = await plan.reconcile(parseJson(get.text), http, signal);
+    if ("replace" in step) {
+      // Reported, not attempted: replacing deletes the resource, which apply never does on its own.
+      console.log(`replace required: ${mapper.kind}/${name}: ${step.replace}`);
+      return { kind: mapper.kind, name, created: false, updated: false, replaceRequired: step.replace };
+    }
+    for (const req of step.requests) {
+      const res = await http(req.method, req.url, req.body, signal);
+      if (res.status >= 300) {
+        throw new Error(`${mapper.kind} ${name} update failed (${res.status}): ${res.text}`);
+      }
+      await pollIfAsync(mapper, res.text, ctx, http, signal);
+    }
+    return { kind: mapper.kind, name, created: false, updated: step.requests.length > 0 };
+  }
+
   if (get.status === 200) {
     // Exists. Reconcile to desired if the mapper supports it; otherwise leave it.
     if (!plan.update) {

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/project-config.test.ts

@@ -1,4 +1,4 @@
-import { describe, test, expect, beforeEach, afterEach } from "vitest";
+import { describe, test, expect, beforeEach, afterEach, vi } from "vitest";
 import { mkdir, writeFile, rm, realpath } from "node:fs/promises";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
@@ -6,9 +6,9 @@ import type { Declarable } from "@intentius/chant/declarable";
 import { loadChantConfig } from "@intentius/chant/config";
 import { armSandboxConfigEvaluation, resetSandboxConfigEvaluationForTests } from "@intentius/chant/config-sandbox";
 import { gcpSerializer } from "./serializer";
-import { manifestProjectAnnotations, resolveReadProject } from "./describe-resources";
+import { describeResources, manifestProjectAnnotations, resolveReadProject } from "./describe-resources";
 import { parseManifest, resolveGcpProject } from "./op/activities/gcp-apply";
-import { CloudRunService, StorageBucket } from "./generated";
+import { CloudRunService, PubSubTopic, StorageBucket } from "./generated";
 import { defaultAnnotations } from "./default-labels";
 import { GCP } from "./pseudo";
 
@@ -117,3 +117,50 @@ describe("gcp.project under --sandbox (#4252)", () => {
     }
   });
 });
+
+describe("the live read takes gcp.project with no project env var (#4252)", () => {
+  let saved: NodeJS.ProcessEnv;
+  const fetchMock = vi.fn();
+  beforeEach(() => {
+    saved = { ...process.env };
+    delete process.env.GCP_PROJECT_ID;
+    delete process.env.GOOGLE_CLOUD_PROJECT;
+    delete process.env.GCP_ENDPOINT_URL;
+    fetchMock.mockReset();
+    fetchMock.mockImplementation(async (url: string) => new Response(JSON.stringify({ name: "projects/p/topics/assets" }), { status: 200 }));
+    vi.stubGlobal("fetch", fetchMock);
+  });
+  afterEach(() => {
+    process.env = saved;
+    vi.unstubAllGlobals();
+  });
+
+  async function read(config: Record<string, unknown> | undefined, props: Record<string, unknown>) {
+    const yaml = build({ assets: new PubSubTopic(props as never) }, config);
+    return describeResources({
+      environment: "local",
+      buildOutput: yaml,
+      entityNames: ["assets"],
+      entities: new Map([["assets", { entityType: "GCP::Pubsub::Topic", props }]]),
+    });
+  }
+
+  test("only gcp.project in config: the read targets that project", async () => {
+    const result = await read({ gcp: { project: "three-cloud" } }, { metadata: { name: "assets" } });
+    expect(result.unobserved?.assets).toBeUndefined();
+    expect(result.resources.assets).toBeDefined();
+    expect(String(fetchMock.mock.calls[0]?.[0])).toContain("three-cloud");
+  });
+
+  test("only a project-id annotation on the resource: the read targets that project", async () => {
+    const result = await read(undefined, { metadata: { name: "assets", annotations: { [ANNOTATION]: "annotated" } } });
+    expect(result.unobserved?.assets).toBeUndefined();
+    expect(String(fetchMock.mock.calls[0]?.[0])).toContain("annotated");
+  });
+
+  test("neither: no-binding, naming every place a project can come from", async () => {
+    const result = await read(undefined, { metadata: { name: "assets" } });
+    expect(result.unobserved?.assets?.reason).toBe("no-binding");
+    expect(result.unobserved?.assets?.detail).toMatch(/gcp\.project in chant\.config/);
+  });
+});