@intentius/chant-lexicon-gcp 0.124.38 → 0.124.39

package/src/composites/public-cloud-run.ts

@@ -0,0 +1,245 @@
+/**
+ * PublicCloudRun composite: a Cloud Run service behind a global external
+ * Application Load Balancer, running as its own service account with Direct
+ * VPC egress into a subnet.
+ */
+
+import { Composite, mergeDefaults } from "@intentius/chant";
+import {
+  BackendService,
+  ComputeAddress,
+  ForwardingRule,
+  GCPServiceAccount,
+  ManagedSSLCertificate,
+  RegionNetworkEndpointGroup,
+  TargetHTTPProxy,
+  TargetHTTPSProxy,
+  URLMap,
+} from "../generated";
+import { GCP } from "../pseudo";
+import { CloudRunServiceComposite } from "./cloud-run-service";
+
+export interface PublicCloudRunProps {
+  /** Name prefix every resource is named with. */
+  name: string;
+  /** Container image. */
+  image: string;
+  /** GCP region of the service and its network endpoint group. */
+  region: string;
+  /** GCP project, as `projectRef.external` (default: GCP.ProjectId, resolved from GCP_PROJECT_ID at build). */
+  projectId?: string;
+  /** VPC the service's egress goes into, such as a PrivateEgressNetwork's `vpc`. */
+  vpc: { name: string };
+  /** Subnet the service's egress goes into, such as a PrivateEgressNetwork's `subnet`. */
+  subnet: { name: string };
+  /** Egress sent through the VPC: "PRIVATE_RANGES_ONLY" or "ALL_TRAFFIC" (default: "PRIVATE_RANGES_ONLY"). */
+  vpcEgress?: string;
+  /** Port the container listens on (default: 8080). */
+  port?: number;
+  /** Port the HTTP forwarding rule listens on (default: 80). */
+  frontendPort?: number;
+  /** Minimum instances (default: 0). */
+  minInstanceCount?: number;
+  /** Maximum instances (default: 100). */
+  maxInstanceCount?: number;
+  /** Environment variables. */
+  env?: Array<{ name: string; value: string }>;
+  /** An existing service account to run as: an email, or the account id of an IAMServiceAccount in the project. When unset, the composite creates `<name>-run`. */
+  serviceAccount?: string;
+  /** Domains for a Google-managed certificate. When set, the composite adds an HTTPS proxy and a rule on 443, and the HTTP rule redirects to HTTPS. */
+  domains?: string[];
+  /** Name of a ComputeSecurityPolicy (Cloud Armor) attached to the backend service. */
+  securityPolicy?: string;
+  /** Additional labels. */
+  labels?: Record<string, string>;
+  /** Namespace for all resources. */
+  namespace?: string;
+  /** Per-member defaults for customizing individual resources. */
+  defaults?: {
+    runtime?: Partial<ConstructorParameters<typeof GCPServiceAccount>[0]>;
+    service?: Record<string, unknown>;
+    publicAccess?: Record<string, unknown>;
+    neg?: Partial<ConstructorParameters<typeof RegionNetworkEndpointGroup>[0]>;
+    backend?: Partial<ConstructorParameters<typeof BackendService>[0]>;
+    urlMap?: Partial<ConstructorParameters<typeof URLMap>[0]>;
+    proxy?: Partial<ConstructorParameters<typeof TargetHTTPProxy>[0]>;
+    address?: Partial<ConstructorParameters<typeof ComputeAddress>[0]>;
+    rule?: Partial<ConstructorParameters<typeof ForwardingRule>[0]>;
+    certificate?: Partial<ConstructorParameters<typeof ManagedSSLCertificate>[0]>;
+    httpsProxy?: Partial<ConstructorParameters<typeof TargetHTTPSProxy>[0]>;
+    httpsRule?: Partial<ConstructorParameters<typeof ForwardingRule>[0]>;
+    redirectMap?: Partial<ConstructorParameters<typeof URLMap>[0]>;
+  };
+}
+
+/**
+ * Create a PublicCloudRun composite.
+ *
+ * @example
+ * ```ts
+ * import { PrivateEgressNetwork, PublicCloudRun } from "@intentius/chant-lexicon-gcp";
+ *
+ * const network = PrivateEgressNetwork({ name: "web", region: "us-central1", subnetCidr: "10.10.0.0/24" });
+ * const web = PublicCloudRun({
+ *   name: "web",
+ *   projectId: "my-project",
+ *   region: "us-central1",
+ *   vpc: network.vpc,
+ *   subnet: network.subnet,
+ *   image: "us-docker.pkg.dev/my-project/web/site:1",
+ * });
+ * ```
+ */
+export const PublicCloudRun = Composite((props: PublicCloudRunProps) => {
+  const {
+    name,
+    image,
+    region,
+    projectId,
+    vpc,
+    subnet,
+    vpcEgress = "PRIVATE_RANGES_ONLY",
+    port = 8080,
+    frontendPort = 80,
+    minInstanceCount = 0,
+    maxInstanceCount = 100,
+    env,
+    serviceAccount,
+    domains,
+    securityPolicy,
+    labels: extraLabels = {},
+    namespace,
+    defaults: defs,
+  } = props;
+
+  const commonLabels: Record<string, string> = {
+    "app.kubernetes.io/name": name,
+    "app.kubernetes.io/managed-by": "chant",
+    ...extraLabels,
+  };
+  const meta = (suffix: string, component: string) => ({
+    name: `${name}-${suffix}`,
+    ...(namespace && { namespace }),
+    labels: { ...commonLabels, "app.kubernetes.io/component": component },
+  });
+
+  const result: Record<string, any> = {};
+
+  if (!serviceAccount) {
+    result.runtime = new GCPServiceAccount(mergeDefaults({
+      metadata: meta("run", "service-account"),
+      displayName: `${name} Cloud Run runtime`,
+    } as Record<string, unknown>, defs?.runtime));
+  }
+
+  const run = CloudRunServiceComposite({
+    name: `${name}-site`,
+    image,
+    projectId,
+    location: region,
+    port,
+    minInstanceCount,
+    maxInstanceCount,
+    env,
+    publicAccess: true,
+    serviceAccount: serviceAccount ?? `${name}-run`,
+    labels: extraLabels,
+    namespace,
+    defaults: {
+      service: mergeDefaults({
+        template: {
+          vpcAccess: {
+            egress: vpcEgress,
+            networkInterfaces: [{ networkRef: { name: vpc.name }, subnetworkRef: { name: subnet.name } }],
+          },
+        },
+      } as Record<string, unknown>, defs?.service) as any,
+      publicIam: defs?.publicAccess as any,
+    },
+  });
+  result.service = run.service;
+  result.publicAccess = run.publicIam;
+
+  const neg = new RegionNetworkEndpointGroup(mergeDefaults({
+    metadata: meta("neg", "neg"),
+    region,
+    networkEndpointType: "SERVERLESS",
+    cloudRun: { serviceRef: { name: run.service.name } },
+  } as Record<string, unknown>, defs?.neg));
+
+  // A backend service over a serverless NEG takes no health check: Cloud Run
+  // reports its own readiness.
+  const backend = new BackendService(mergeDefaults({
+    metadata: meta("backend", "backend"),
+    location: "global",
+    loadBalancingScheme: "EXTERNAL_MANAGED",
+    protocol: "HTTP",
+    backend: [{ group: { networkEndpointGroupRef: { name: neg.name } } }],
+    ...(securityPolicy && { securityPolicyRef: { name: securityPolicy } }),
+  } as Record<string, unknown>, defs?.backend));
+
+  const urlMap = new URLMap(mergeDefaults({
+    metadata: meta("map", "url-map"),
+    location: "global",
+    defaultService: { backendServiceRef: { name: backend.name } },
+  } as Record<string, unknown>, defs?.urlMap));
+
+  const address = new ComputeAddress(mergeDefaults({
+    metadata: meta("ip", "address"),
+    location: "global",
+  } as Record<string, unknown>, defs?.address));
+
+  Object.assign(result, { neg, backend, urlMap, address });
+
+  // With domains, HTTPS serves the URL map and HTTP serves a redirect to it.
+  let httpMapName: string = urlMap.name;
+  if (domains && domains.length > 0) {
+    const certificate = new ManagedSSLCertificate(mergeDefaults({
+      metadata: meta("cert", "certificate"),
+      projectRef: { external: projectId ?? GCP.ProjectId },
+      managed: { domains },
+    } as Record<string, unknown>, defs?.certificate));
+
+    const httpsProxy = new TargetHTTPSProxy(mergeDefaults({
+      metadata: meta("https-proxy", "proxy"),
+      location: "global",
+      urlMapRef: { name: urlMap.name },
+      sslCertificates: [{ name: certificate.name }],
+    } as Record<string, unknown>, defs?.httpsProxy));
+
+    const httpsRule = new ForwardingRule(mergeDefaults({
+      metadata: meta("https-rule", "forwarding-rule"),
+      location: "global",
+      loadBalancingScheme: "EXTERNAL_MANAGED",
+      portRange: "443",
+      ipAddress: { addressRef: { name: address.name } },
+      target: { targetHTTPSProxyRef: { name: httpsProxy.name } },
+    } as Record<string, unknown>, defs?.httpsRule));
+
+    const redirectMap = new URLMap(mergeDefaults({
+      metadata: meta("redirect", "url-map"),
+      location: "global",
+      defaultUrlRedirect: { httpsRedirect: true, stripQuery: false },
+    } as Record<string, unknown>, defs?.redirectMap));
+    httpMapName = redirectMap.name;
+
+    Object.assign(result, { certificate, httpsProxy, httpsRule, redirectMap });
+  }
+
+  result.proxy = new TargetHTTPProxy(mergeDefaults({
+    metadata: meta("proxy", "proxy"),
+    location: "global",
+    urlMapRef: { name: httpMapName },
+  } as Record<string, unknown>, defs?.proxy));
+
+  result.rule = new ForwardingRule(mergeDefaults({
+    metadata: meta("rule", "forwarding-rule"),
+    location: "global",
+    loadBalancingScheme: "EXTERNAL_MANAGED",
+    portRange: String(frontendPort),
+    ipAddress: { addressRef: { name: address.name } },
+    target: { targetHTTPProxyRef: { name: result.proxy.name } },
+  } as Record<string, unknown>, defs?.rule));
+
+  return result;
+}, "PublicCloudRun");

package/src/deep-observe.test.ts

@@ -352,3 +352,49 @@ describe("observeResourcesDeepGcp — over REST (#1209)", () => {
     expect(fetchMock).not.toHaveBeenCalled();
   });
 });
+
+describe("a forwarding rule's IP read back as its declared addressRef (#4238)", () => {
+  beforeEach(() => {
+    fetchMock.mockReset();
+    vi.stubGlobal("fetch", fetchMock);
+    process.env.GOOGLE_CLOUD_PROJECT = "my-project";
+    process.env.GCP_ENDPOINT_URL = "http://localhost:4588";
+  });
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    delete process.env.GCP_ENDPOINT_URL;
+    delete process.env.GOOGLE_CLOUD_PROJECT;
+  });
+
+  test("toCnrmTree: the declared address's IP becomes the addressRef; any other IP stays an ip", () => {
+    const ref = { name: "web-ip" };
+    expect(toCnrmTree("ComputeForwardingRule", { name: "fr", IPAddress: "34.1.2.3" }, { project: "p", address: { ip: "34.1.2.3", ref } })).toMatchObject({
+      ipAddress: { addressRef: ref },
+    });
+    const other = toCnrmTree("ComputeForwardingRule", { name: "fr", IPAddress: "10.0.0.9" }, { project: "p", address: { ip: "34.1.2.3", ref } });
+    expect(other).toMatchObject({ ipAddress: { ip: "10.0.0.9" } });
+    expect(other).not.toHaveProperty("IPAddress");
+  });
+
+  test("observe reads the declared address and reports the rule's ipAddress as declared", async () => {
+    fetchMock.mockImplementation(async (url: string) => {
+      if (url.endsWith("/global/forwardingRules/web-fr")) {
+        return reply(200, { name: "web-fr", IPAddress: "34.1.2.3", portRange: "80", target: "projects/my-project/global/targetHttpProxies/web-proxy" });
+      }
+      if (url.endsWith("/global/addresses/web-ip")) return reply(200, { name: "web-ip", address: "34.1.2.3" });
+      return reply(404, {});
+    });
+    const result = await observe(
+      entities([
+        [
+          "rule",
+          "GCP::Compute::ForwardingRule",
+          { metadata: { name: "web-fr" }, location: "global", portRange: "80", ipAddress: { addressRef: { name: "web-ip" } }, target: { targetHTTPProxyRef: { name: "web-proxy" } } },
+        ],
+        ["ip", "GCP::Compute::Address", { metadata: { name: "web-ip" }, location: "global" }],
+      ]),
+    );
+    expect(result.resources.rule?.properties).toMatchObject({ ipAddress: { addressRef: { name: "web-ip" } } });
+    expect(result.resources.rule?.properties).not.toHaveProperty("IPAddress");
+  });
+});

package/src/deep-observe.ts

@@ -122,6 +122,8 @@ function propertiesTreeOf(obj: Record<string, unknown>): Record<string, unknown>
 interface RefineContext {
   project: string;
   restName?: string;
+  /** A forwarding rule's declared `ipAddress.addressRef` and that address's live IP (#4238). */
+  address?: { ip: string; ref: unknown };
 }
 
 type CnrmTree = Record<string, unknown> & { metadata?: Record<string, unknown> };
@@ -316,8 +318,14 @@ const CNRM_REFINERS: Record<string, (tree: CnrmTree, ctx: RefineContext) => void
     delete tree.gatewayAddress;
     delete tree.fingerprint;
   },
-  ComputeForwardingRule(tree) {
+  ComputeForwardingRule(tree, ctx) {
     computeLocation(tree);
+    // Compute returns the IP; CNRM writes `ipAddress: { addressRef }` or `{ ip }`.
+    // The IP is the declared address's own when the read found it so (#4238).
+    if (typeof tree.IPAddress === "string") {
+      tree.ipAddress = ctx.address && ctx.address.ip === tree.IPAddress ? { addressRef: ctx.address.ref } : { ip: tree.IPAddress };
+      delete tree.IPAddress;
+    }
     if (tree.IPProtocol !== undefined) {
       tree.ipProtocol = tree.IPProtocol;
       delete tree.IPProtocol;
@@ -374,6 +382,33 @@ export function toCnrmTree(kind: string, body: Record<string, unknown>, ctx: Ref
   return tree as Record<string, unknown>;
 }
 
+/**
+ * The live IP of the address a forwarding rule declares in
+ * `ipAddress.addressRef`, read with the address's own declaration when the
+ * manifest holds it, so the rule's `IPAddress` can be matched to the ref
+ * rather than read as drift (#4238). Undefined when there is no ref or the
+ * read fails; the rule then shows the IP as it is.
+ */
+async function declaredAddressIp(
+  client: GcpReadClientOptions,
+  props: Record<string, unknown>,
+  manifest: readonly { kind?: string; metadata?: { name?: string }; spec?: Record<string, unknown> }[],
+): Promise<{ ip: string; ref: unknown } | undefined> {
+  const spec = (props.spec as Record<string, unknown> | undefined) ?? props;
+  const ref = (spec.ipAddress as { addressRef?: { name?: unknown; external?: unknown } } | undefined)?.addressRef;
+  if (!ref) return undefined;
+  const raw = typeof ref.name === "string" ? ref.name : typeof ref.external === "string" ? ref.external : undefined;
+  if (!raw) return undefined;
+  const name = raw.slice(raw.lastIndexOf("/") + 1);
+  const declared = manifest.find((r) => r.kind === "ComputeAddress" && r.metadata?.name === name);
+  try {
+    const body = await getResource(client, "ComputeAddress", name, declared?.spec ?? { location: spec.location });
+    return typeof body.address === "string" ? { ip: body.address, ref } : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 /**
  * Read the live property tree for each declared entity over the applier's
  * REST transport, normalized into the declared CNRM shape (see the module
@@ -425,6 +460,7 @@ export async function observeResourcesDeepGcp(options: GcpDeepObserveOptions): P
     try {
       const obj = await getResource(client, gvk.kind, name, props);
       const labels = obj.labels as Record<string, string> | null | undefined;
+      const address = gvk.kind === "ComputeForwardingRule" ? await declaredAddressIp(client, props, manifest) : undefined;
 
       // owned filter: withhold what does not carry chant's marker. Withheld is
       // not absent (#1089). Where the payload has no labels at all there is
@@ -443,7 +479,7 @@ export async function observeResourcesDeepGcp(options: GcpDeepObserveOptions): P
         type: entityType,
         physicalId:
           (obj.id as string | undefined) ?? (obj.selfLink as string | undefined) ?? (obj.name as string | undefined),
-        properties: normalizeDeepProperties(toCnrmTree(gvk.kind, obj, { project: client.project }), {
+        properties: normalizeDeepProperties(toCnrmTree(gvk.kind, obj, { project: client.project, ...(address ? { address } : {}) }), {
           entityType,
           side: "live",
           // The static table is the whole prune here — there is no per-resource

package/src/health.test.ts

@@ -1,5 +1,6 @@
 import { afterEach, beforeEach, describe, expect, test } from "vitest";
-import { cloudRunEntry, observeHealthGcp } from "./health";
+import { backendServiceEntry, cloudRunEntry, GCP_HEALTH_TYPES, observeHealthGcp } from "./health";
+import { gcpPlugin } from "./plugin";
 import type { GcpReadHttp } from "./api/read-client";
 
 const AT = "2026-10-20T21:00:00.000Z";
@@ -56,4 +57,67 @@ describe("gcp health (#4177)", () => {
     const r = await observeHealthGcp({ environment: "dev", buildOutput: "", entities, http: denied });
     expect(r.unobserved.api?.reason).toBe("no-credentials");
   });
+
+  test("backend service: any unhealthy endpoint is unhealthy, all healthy is healthy, no status is unknown (#4239)", () => {
+    const g = (healthState: string) => ({ group: "g", healthStatus: [{ healthState }] });
+    expect(backendServiceEntry([g("HEALTHY"), g("HEALTHY")], AT)).toMatchObject({ state: "healthy", detail: "2 of 2 backends healthy" });
+    expect(backendServiceEntry([g("HEALTHY"), g("UNHEALTHY")], AT)).toMatchObject({ state: "unhealthy", detail: "1 of 2 backends healthy, 1 unhealthy" });
+    // A serverless NEG reports no health status; a failed call counts the same.
+    expect(backendServiceEntry([{ group: "neg", healthStatus: [] }], AT)).toMatchObject({ state: "unknown", detail: "0 of 1 backend healthy, 1 with no health status" });
+    expect(backendServiceEntry([{ group: "g", error: "getHealth 400" }], AT).state).toBe("unknown");
+    expect(backendServiceEntry([], AT)).toMatchObject({ state: "unknown", detail: "no backends" });
+  });
+
+  test("a backend service is read, then getHealth is called for each backend group at its URL (#4239)", async () => {
+    const calls: Array<{ method: string; url: string; body?: unknown }> = [];
+    const group = "https://compute.googleapis.com/compute/v1/projects/demo/zones/us-central1-a/instanceGroups/ig";
+    const http: GcpReadHttp = async (method, url, body) => {
+      calls.push({ method, url, ...(body === undefined ? {} : { body }) });
+      if (method === "GET") return { status: 200, text: JSON.stringify({ name: "web", backends: [{ group }] }) };
+      return { status: 200, text: JSON.stringify({ healthStatus: [{ healthState: "HEALTHY" }, { healthState: "HEALTHY" }] }) };
+    };
+    const lb = new Map([
+      [
+        "backend",
+        {
+          entityType: "GCP::Compute::BackendService",
+          props: { metadata: { name: "web", annotations: { "cnrm.cloud.google.com/project-id": "demo" } }, location: "global" },
+        },
+      ],
+    ]);
+    const r = await observeHealthGcp({ environment: "dev", buildOutput: "", entities: lb, http, now });
+    expect(r.entities.backend).toMatchObject({ type: "GCP::Compute::BackendService", state: "healthy" });
+    expect(calls[1]).toEqual({ method: "POST", url: "http://localhost:4588/compute/v1/projects/demo/global/backendServices/web/getHealth", body: { group } });
+  });
+
+  test("an IAM policy member in the target's policy is healthy; one missing from it is absent (#4239)", async () => {
+    const iam = new Map<string, { entityType: string; props: Record<string, unknown> }>([
+      [
+        "publicIam",
+        {
+          entityType: "GCP::Iam::PolicyMember",
+          props: {
+            metadata: { name: "api-public", annotations: { "cnrm.cloud.google.com/project-id": "demo" } },
+            member: "allUsers",
+            role: "roles/run.invoker",
+            resourceRef: { kind: "RunService", name: "api" },
+          },
+        },
+      ],
+      ...entities,
+    ]);
+    const policy = (members: string[]): GcpReadHttp => async (_m, url) =>
+      url.includes(":getIamPolicy")
+        ? { status: 200, text: JSON.stringify({ bindings: [{ role: "roles/run.invoker", members }] }) }
+        : { status: 200, text: JSON.stringify({ terminalCondition: { type: "Ready", state: "CONDITION_SUCCEEDED" } }) };
+    const present = await observeHealthGcp({ environment: "dev", buildOutput: "", entities: iam, http: policy(["allUsers"]), now });
+    expect(present.entities.publicIam).toMatchObject({ type: "GCP::Iam::PolicyMember", state: "healthy" });
+    expect(present.entities.publicIam?.detail).toMatch(/^allUsers holds roles\/run\.invoker on /);
+    const missing = await observeHealthGcp({ environment: "dev", buildOutput: "", entities: iam, http: policy(["user:x@y.z"]), now });
+    expect(missing.absent).toContain("publicIam");
+  });
+
+  test("the plugin's healthTypes match the reader's", () => {
+    expect([...(gcpPlugin.healthTypes ?? [])]).toEqual([...GCP_HEALTH_TYPES]);
+  });
 });

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) {