@intentius/chant-lexicon-gcp 0.124.37 → 0.124.39

package/src/composites/index.ts

@@ -32,3 +32,7 @@ export { GkeCrdbRegion } from "./gke-crdb-region";
 export type { GkeCrdbRegionConfig, GkeCrdbRegionNodeConfig } from "./gke-crdb-region";
 export { GpuNodePool } from "./gpu-node-pool";
 export type { GpuNodePoolProps, GpuNodePoolTaint } from "./gpu-node-pool";
+export { PrivateEgressNetwork } from "./private-egress-network";
+export type { PrivateEgressNetworkProps } from "./private-egress-network";
+export { PublicCloudRun } from "./public-cloud-run";
+export type { PublicCloudRunProps } from "./public-cloud-run";

package/src/composites/private-egress-network.ts

@@ -0,0 +1,82 @@
+/**
+ * PrivateEgressNetwork composite: a custom-mode VPC with one subnet a service sends its egress into.
+ */
+
+import { Composite, mergeDefaults } from "@intentius/chant";
+import { VPCNetwork, Subnetwork } from "../generated";
+
+export interface PrivateEgressNetworkProps {
+  /** Name prefix: the network is `<name>-vpc`, its subnet `<name>-apps`. */
+  name: string;
+  /** GCP region of the subnet. */
+  region: string;
+  /** IP CIDR range of the subnet. */
+  subnetCidr: string;
+  /** Enable private Google access on the subnet (default: true). */
+  privateIpGoogleAccess?: boolean;
+  /** Additional labels. */
+  labels?: Record<string, string>;
+  /** Namespace for all resources. */
+  namespace?: string;
+  /** Per-member defaults for customizing individual resources. */
+  defaults?: {
+    vpc?: Partial<ConstructorParameters<typeof VPCNetwork>[0]>;
+    subnet?: Partial<ConstructorParameters<typeof Subnetwork>[0]>;
+  };
+}
+
+/**
+ * Create a PrivateEgressNetwork composite.
+ *
+ * @example
+ * ```ts
+ * import { PrivateEgressNetwork } from "@intentius/chant-lexicon-gcp";
+ *
+ * const { vpc, subnet } = PrivateEgressNetwork({
+ *   name: "web",
+ *   region: "us-central1",
+ *   subnetCidr: "10.10.0.0/24",
+ * });
+ * ```
+ */
+export const PrivateEgressNetwork = Composite((props: PrivateEgressNetworkProps) => {
+  const {
+    name,
+    region,
+    subnetCidr,
+    privateIpGoogleAccess = true,
+    labels: extraLabels = {},
+    namespace,
+    defaults: defs,
+  } = props;
+
+  const commonLabels: Record<string, string> = {
+    "app.kubernetes.io/name": name,
+    "app.kubernetes.io/managed-by": "chant",
+    ...extraLabels,
+  };
+
+  const vpc = new VPCNetwork(mergeDefaults({
+    metadata: {
+      name: `${name}-vpc`,
+      ...(namespace && { namespace }),
+      labels: { ...commonLabels, "app.kubernetes.io/component": "network" },
+    },
+    autoCreateSubnetworks: false,
+    routingMode: "REGIONAL",
+  } as Record<string, unknown>, defs?.vpc));
+
+  const subnet = new Subnetwork(mergeDefaults({
+    metadata: {
+      name: `${name}-apps`,
+      ...(namespace && { namespace }),
+      labels: { ...commonLabels, "app.kubernetes.io/component": "subnet" },
+    },
+    region,
+    ipCidrRange: subnetCidr,
+    privateIpGoogleAccess,
+    networkRef: { name: vpc.name },
+  } as Record<string, unknown>, defs?.subnet));
+
+  return { vpc, subnet };
+}, "PrivateEgressNetwork");

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

@@ -61,7 +61,7 @@ import type {
 } from "@intentius/chant/lexicon";
 import { deepObservation, normalizeDeepProperties } from "@intentius/chant/deep-observation";
 import { hasOwnershipMarker, type ChannelKeys } from "@intentius/chant/ownership";
-import { deriveGVK, manifestProjectAnnotations, readTargets, resolveReadProject } from "./describe-resources";
+import { deriveGVK, manifestProjectAnnotations, readManifest, readTargets, resolveReadProject } from "./describe-resources";
 import { getResource, mapperForKind, GcpReadError, isNotFound, type GcpReadClientOptions } from "./api/read-client";
 import { gcpDeepNormalizationHooks } from "./deep-observe-hooks";
 
@@ -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
@@ -388,6 +423,7 @@ export async function observeResourcesDeepGcp(options: GcpDeepObserveOptions): P
   const endpoint = process.env.GCP_ENDPOINT_URL;
   const manifestProjects = manifestProjectAnnotations(options.buildOutput);
   const targets = readTargets(options.entities);
+  const manifest = readManifest(options.entities, targets);
 
   const reads = [...options.entities].map(async ([entityName, { entityType }]) => {
     const gvk = deriveGVK(entityType);
@@ -410,6 +446,7 @@ export async function observeResourcesDeepGcp(options: GcpDeepObserveOptions): P
       client = {
         project: resolveReadProject(gvk.kind, name, metadata, manifestProjects, props),
         ...(endpoint ? { endpoint } : {}),
+        manifest,
       };
     } catch (err) {
       unobserved[entityName] = {
@@ -423,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
@@ -441,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/describe-resources.ts

@@ -40,7 +40,7 @@ import type { ObservationResult, ResourceMetadata, UnobservedEntity } from "@int
 import { observation } from "@intentius/chant/observation";
 import { hasOwnershipMarker, classifyOwnership, readOwnership, type ChannelKeys } from "@intentius/chant/ownership";
 import { getResource, mapperForKind, GcpReadError, isNotFound, type GcpReadClientOptions } from "./api/read-client";
-import { NO_PROJECT, parseManifest, projectRefProject } from "./op/activities/gcp-apply";
+import { NO_PROJECT, parseManifest, projectRefProject, type GcpResource } from "./op/activities/gcp-apply";
 import { cnrmNameOf, resolveCnrmRefs, resolveGVK } from "./serializer";
 
 /**
@@ -167,6 +167,26 @@ export function readTargets(
   return out;
 }
 
+/**
+ * The declared resources as the applier's manifest holds them (kind, CNRM
+ * name, spec), for a read that needs another declared resource: an
+ * IAMPolicyMember on a RunService takes the service's region from it (#4251).
+ */
+export function readManifest(
+  entities: Map<string, { entityType: string; props: Record<string, unknown> }>,
+  targets: Map<string, { name: string; props: Record<string, unknown> }>,
+): GcpResource[] {
+  const out: GcpResource[] = [];
+  for (const [logical, { entityType }] of entities) {
+    const gvk = deriveGVK(entityType);
+    const target = targets.get(logical);
+    if (!gvk || !target) continue;
+    const spec = (target.props.spec as Record<string, unknown> | undefined) ?? target.props;
+    out.push({ kind: gvk.kind, metadata: { name: target.name }, spec });
+  }
+  return out;
+}
+
 function pruneUndefined<T extends Record<string, unknown>>(obj: T): Record<string, unknown> {
   const out: Record<string, unknown> = {};
   for (const [k, v] of Object.entries(obj)) {
@@ -223,6 +243,7 @@ export async function describeResources(options: {
 
   const manifestProjects = manifestProjectAnnotations(options.buildOutput);
   const targets = readTargets(options.entities);
+  const manifest = readManifest(options.entities, targets);
 
   const reads = [...options.entities].map(async ([entityName, { entityType }]) => {
     const gvk = deriveGVK(entityType);
@@ -253,6 +274,7 @@ export async function describeResources(options: {
       client = {
         project: resolveReadProject(gvk.kind, name, metadata, manifestProjects, props),
         ...(endpoint ? { endpoint } : {}),
+        manifest,
       };
     } catch (err) {
       // No project resolvable — nothing was queried, so nothing is known.

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]);
+  });
 });