@intentius/chant-lexicon-gcp 0.124.35 → 0.124.37

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

@@ -5,6 +5,7 @@ import {
   bucketInsertBody,
   pubSubTopicBody,
   cloudRunServiceBody,
+  networkInterface,
   serviceAccountEmail,
   resolveGcpProject,
   resolveGcpEndpoint,
@@ -122,7 +123,9 @@ describe("mappers build correct plans (#706)", () => {
       "ComputeAddress",
       "ComputeBackendService",
       "ComputeForwardingRule",
+      "ComputeNetwork",
       "ComputeRegionNetworkEndpointGroup",
+      "ComputeSubnetwork",
       "ComputeTargetHTTPProxy",
       "ComputeURLMap",
       "IAMPolicyMember",
@@ -164,6 +167,41 @@ describe("Cloud Run mapper + LRO (#706)", () => {
     expect(() => serviceAccountEmail({ name: "run-sa" })).toThrow(/needs a project/);
   });
 
+  test("cloudRunServiceBody sends vpcAccess refs as network and subnetwork paths (#4249)", () => {
+    const resource = {
+      ...RUN_SERVICE,
+      spec: {
+        ...(RUN_SERVICE.spec as object),
+        location: "europe-west1",
+        template: {
+          containers: [{ image: "i" }],
+          vpcAccess: {
+            egress: "PRIVATE_RANGES_ONLY",
+            networkInterfaces: [{ networkRef: { name: "vpc" }, subnetworkRef: { name: "apps" }, tags: ["run"] }],
+          },
+        },
+      },
+    };
+    expect(cloudRunServiceBody(resource, "p")).toEqual({
+      template: {
+        containers: [{ image: "i" }],
+        vpcAccess: {
+          egress: "PRIVATE_RANGES_ONLY",
+          networkInterfaces: [
+            { tags: ["run"], network: "projects/p/global/networks/vpc", subnetwork: "projects/p/regions/europe-west1/subnetworks/apps" },
+          ],
+        },
+      },
+    });
+  });
+
+  test("networkInterface: external as given, name needs a project", () => {
+    expect(networkInterface({ networkRef: { external: "projects/o/global/networks/shared" } }, "p", "r")).toEqual({
+      network: "projects/o/global/networks/shared",
+    });
+    expect(() => networkInterface({ subnetworkRef: { name: "apps" } }, undefined, "r")).toThrow(/needs a project/);
+  });
+
   test("RunService plan sends the service account email on create and update", () => {
     const resource = {
       ...RUN_SERVICE,
@@ -258,9 +296,16 @@ describe("Cloud Run mapper + LRO (#706)", () => {
 });
 
 describe("resolveGcpProject (#711)", () => {
-  test("env wins over the annotation", () => {
-    expect(resolveGcpProject(BUCKET, { GOOGLE_CLOUD_PROJECT: "env-project" } as NodeJS.ProcessEnv))
-      .toBe("env-project");
+  test("the annotation (where chant.config's gcp.project lands) wins over the env vars (#4252)", () => {
+    expect(resolveGcpProject(BUCKET, { GOOGLE_CLOUD_PROJECT: "env-project", GCP_PROJECT_ID: "id-project" } as NodeJS.ProcessEnv))
+      .toBe("annotated-project");
+  });
+
+  test("without an annotation, GCP_PROJECT_ID wins over GOOGLE_CLOUD_PROJECT, and projectRef over both (#4252)", () => {
+    const bare = { metadata: { name: "b" } };
+    expect(resolveGcpProject(bare, { GOOGLE_CLOUD_PROJECT: "g", GCP_PROJECT_ID: "p" } as NodeJS.ProcessEnv)).toBe("p");
+    expect(resolveGcpProject(bare, { GOOGLE_CLOUD_PROJECT: "g" } as NodeJS.ProcessEnv)).toBe("g");
+    expect(resolveGcpProject({ ...bare, spec: { projectRef: { external: "own" } } }, { GCP_PROJECT_ID: "p" } as NodeJS.ProcessEnv)).toBe("own");
   });
 
   test("falls back to the CNRM annotation", () => {

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

@@ -8,6 +8,8 @@ import {
   backendServiceMapper,
   computeAddressMapper,
   forwardingRuleMapper,
+  networkMapper,
+  subnetworkMapper,
   regionNetworkEndpointGroupMapper,
   targetHttpProxyMapper,
   urlMapMapper,
@@ -292,10 +294,39 @@ export function cloudRunServiceBody(resource: GcpResource, project?: string): {
   if (!spec.template) return body;
   const { serviceAccountRef, ...template } = spec.template as { serviceAccountRef?: { name?: string; external?: string } };
   const email = serviceAccountEmail(serviceAccountRef, project);
-  body.template = email ? { ...template, serviceAccount: email } : template;
+  const out: Record<string, unknown> = email ? { ...template, serviceAccount: email } : { ...template };
+  const vpcAccess = out.vpcAccess as { networkInterfaces?: unknown } | undefined;
+  if (vpcAccess && Array.isArray(vpcAccess.networkInterfaces)) {
+    const region = ((resource.spec ?? {}) as { location?: string }).location ?? "us-central1";
+    out.vpcAccess = { ...vpcAccess, networkInterfaces: vpcAccess.networkInterfaces.map((i) => networkInterface(i, project, region)) };
+  }
+  body.template = out;
   return body;
 }
 
+type NameRef = { name?: string; external?: string };
+
+/**
+ * A CNRM Direct VPC egress interface as Cloud Run v2 takes it (#4249):
+ * `networkRef` and `subnetworkRef` become `network` and `subnetwork` paths,
+ * `name` in the project (the subnetwork in the service's region) and
+ * `external` as given. `tags` and anything else pass through. Pure.
+ */
+export function networkInterface(iface: unknown, project: string | undefined, region: string): unknown {
+  if (!iface || typeof iface !== "object") return iface;
+  const { networkRef, subnetworkRef, ...rest } = iface as { networkRef?: NameRef; subnetworkRef?: NameRef };
+  const path = (ref: NameRef | undefined, scoped: (p: string, n: string) => string, key: string): string | undefined => {
+    if (!ref) return undefined;
+    if (ref.external) return ref.external;
+    if (!ref.name) return undefined;
+    if (!project) throw new Error(`${key} { name: "${ref.name}" } needs a project to form its path`);
+    return scoped(project, ref.name);
+  };
+  const network = path(networkRef, (p, n) => `projects/${p}/global/networks/${n}`, "networkRef");
+  const subnetwork = path(subnetworkRef, (p, n) => `projects/${p}/regions/${region}/subnetworks/${n}`, "subnetworkRef");
+  return { ...rest, ...(network ? { network } : {}), ...(subnetwork ? { subnetwork } : {}) };
+}
+
 /**
  * The email a CNRM `serviceAccountRef` names: `external` as given (an email,
  * or a `projects/<p>/serviceAccounts/<email>` path), `name` as an account id
@@ -435,6 +466,8 @@ export const MAPPERS: Record<string, ResourceMapper> = {
   ComputeURLMap: urlMapMapper,
   ComputeTargetHTTPProxy: targetHttpProxyMapper,
   ComputeForwardingRule: forwardingRuleMapper,
+  ComputeNetwork: networkMapper,
+  ComputeSubnetwork: subnetworkMapper,
 };
 
 /**
@@ -461,6 +494,8 @@ const REF_KINDS: Record<string, string> = {
   backendServiceRef: "ComputeBackendService",
   urlMapRef: "ComputeURLMap",
   targetHTTPProxyRef: "ComputeTargetHTTPProxy",
+  networkRef: "ComputeNetwork",
+  subnetworkRef: "ComputeSubnetwork",
 };
 
 /** The local resources this resource references via `*Ref` fields, each with its kind when known. Pure. */
@@ -533,7 +568,6 @@ export function resolveGcpEndpoint(
   return args.endpoint || env.GCP_ENDPOINT_URL || undefined;
 }
 
-/** Resolve the project: `GOOGLE_CLOUD_PROJECT` env, else the CNRM project-id annotation. Pure. */
 /**
  * The project a resource names in `spec.projectRef.external` (#4201): a
  * project id or `projects/<id>`. A `GCP.ProjectId` pseudo-parameter there
@@ -554,19 +588,25 @@ export function projectRefProject(spec: Record<string, unknown> | undefined, env
   return external.startsWith("projects/") ? external.slice("projects/".length).split("/")[0] : external;
 }
 
+/**
+ * The project a resource is applied in (#4252): its own `spec.projectRef.external`,
+ * else its project-id annotation (where chant.config's `gcp.project` is
+ * written at build), else `GCP_PROJECT_ID`, else `GOOGLE_CLOUD_PROJECT`. Pure.
+ */
 export function resolveGcpProject(resource: GcpResource, env: NodeJS.ProcessEnv = process.env): string {
   const project =
     projectRefProject(resource.spec, env) ||
-    env.GOOGLE_CLOUD_PROJECT ||
-    resource.metadata?.annotations?.[PROJECT_ID_ANNOTATION];
-  if (!project) {
-    throw new Error(
-      `no GCP project — set spec.projectRef.external, GOOGLE_CLOUD_PROJECT or the ${PROJECT_ID_ANNOTATION} annotation`,
-    );
-  }
+    resource.metadata?.annotations?.[PROJECT_ID_ANNOTATION] ||
+    env.GCP_PROJECT_ID ||
+    env.GOOGLE_CLOUD_PROJECT;
+  if (!project) throw new Error(NO_PROJECT);
   return project;
 }
 
+/** The error every stage gives when no project resolves. */
+export const NO_PROJECT =
+  `no GCP project — set gcp.project in chant.config, GCP_PROJECT_ID or GOOGLE_CLOUD_PROJECT, or the resource's spec.projectRef.external`;
+
 /** Injectable HTTP client — mirrors argo's injectable fetcher so tests avoid the network. */
 export type GcpHttp = (
   method: string,

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

@@ -210,3 +210,97 @@ describe("deep observe reads a load balancer back in the declared vocabulary (#4
     });
   });
 });
+
+describe("network and subnetwork mappers (#4248)", () => {
+  const net: GcpResource[] = [
+    {
+      kind: "ComputeSubnetwork",
+      metadata: { name: "apps" },
+      spec: {
+        region: "europe-west1",
+        ipCidrRange: "10.0.0.0/24",
+        networkRef: { name: "vpc" },
+        privateIpGoogleAccess: true,
+        secondaryIpRange: [{ rangeName: "pods", ipCidrRange: "10.4.0.0/14" }],
+      },
+    },
+    { kind: "ComputeNetwork", metadata: { name: "vpc" }, spec: { routingMode: "REGIONAL" } },
+    {
+      kind: "RunService",
+      metadata: { name: "web" },
+      spec: { location: "europe-west1", template: { vpcAccess: { networkInterfaces: [{ networkRef: { name: "vpc" }, subnetworkRef: { name: "apps" } }] } } },
+    },
+  ];
+  const nctx = { base: "https://compute.googleapis.com", project: "p1", manifest: net };
+  const find = (kind: string) => net.find((r) => r.kind === kind)!;
+
+  test("a network is global, with autoCreateSubnetworks false unless declared and the routing mode nested", () => {
+    process.env.GCP_REGION = "us-east1";
+    const plan = MAPPERS.ComputeNetwork.plan(find("ComputeNetwork"), nctx);
+    expect(plan.create.url).toBe("https://compute.googleapis.com/compute/v1/projects/p1/global/networks");
+    expect(plan.getUrl).toBe("https://compute.googleapis.com/compute/v1/projects/p1/global/networks/vpc");
+    expect(plan.create.body).toEqual({ name: "vpc", autoCreateSubnetworks: false, routingConfig: { routingMode: "REGIONAL" } });
+  });
+
+  test("a subnetwork is regional and names its network by partial URL", () => {
+    const plan = MAPPERS.ComputeSubnetwork.plan(find("ComputeSubnetwork"), nctx);
+    expect(plan.create.url).toBe("https://compute.googleapis.com/compute/v1/projects/p1/regions/europe-west1/subnetworks");
+    expect(plan.create.body).toEqual({
+      name: "apps",
+      ipCidrRange: "10.0.0.0/24",
+      privateIpGoogleAccess: true,
+      network: "projects/p1/global/networks/vpc",
+      secondaryIpRanges: [{ rangeName: "pods", ipCidrRange: "10.4.0.0/14" }],
+    });
+  });
+
+  test("apply order: network, then subnetwork, then the Cloud Run service that egresses into them", () => {
+    const order = orderByReferences(net).map((r) => r.kind);
+    expect(order.indexOf("ComputeNetwork")).toBeLessThan(order.indexOf("ComputeSubnetwork"));
+    expect(order.indexOf("ComputeSubnetwork")).toBeLessThan(order.indexOf("RunService"));
+  });
+
+  test("the reader reads a network at its global URL", async () => {
+    const http = async (_m: string, url: string) =>
+      url.endsWith("/global/networks/vpc") ? { status: 200, text: JSON.stringify({ name: "vpc" }) } : { status: 404, text: "" };
+    expect(await getResource({ project: "p1", http }, "ComputeNetwork", "vpc", {})).toEqual({ name: "vpc" });
+  });
+
+  test("deep observe inverts both body builders", async () => {
+    const { toCnrmTree } = await import("../../deep-observe");
+    const c = { project: "p1" };
+    expect(
+      toCnrmTree(
+        "ComputeNetwork",
+        {
+          name: "vpc",
+          autoCreateSubnetworks: false,
+          routingConfig: { routingMode: "REGIONAL" },
+          subnetworks: ["https://compute.googleapis.com/compute/v1/projects/p1/regions/europe-west1/subnetworks/apps"],
+        },
+        c,
+      ),
+    ).toEqual({ metadata: { name: "vpc" }, autoCreateSubnetworks: false, routingMode: "REGIONAL" });
+    expect(
+      toCnrmTree(
+        "ComputeSubnetwork",
+        {
+          name: "apps",
+          region: "https://compute.googleapis.com/compute/v1/projects/p1/regions/europe-west1",
+          network: "https://compute.googleapis.com/compute/v1/projects/p1/global/networks/vpc",
+          ipCidrRange: "10.0.0.0/24",
+          gatewayAddress: "10.0.0.1",
+          fingerprint: "abc",
+          secondaryIpRanges: [{ rangeName: "pods", ipCidrRange: "10.4.0.0/14" }],
+        },
+        c,
+      ),
+    ).toEqual({
+      metadata: { name: "apps" },
+      region: "europe-west1",
+      networkRef: { name: "vpc" },
+      ipCidrRange: "10.0.0.0/24",
+      secondaryIpRange: [{ rangeName: "pods", ipCidrRange: "10.4.0.0/14" }],
+    });
+  });
+});

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

@@ -1,7 +1,9 @@
 /**
  * Compute Engine mappers for the Cloud Run load balancer (#4233): ComputeAddress,
  * ComputeRegionNetworkEndpointGroup (serverless NEGs), ComputeBackendService,
- * ComputeURLMap, ComputeTargetHTTPProxy and ComputeForwardingRule.
+ * ComputeURLMap, ComputeTargetHTTPProxy and ComputeForwardingRule; and for a
+ * declared network (#4248): ComputeNetwork (always global) and
+ * ComputeSubnetwork (regional, by its CNRM `region`).
  *
  * Each maps a CNRM spec onto the compute v1 insert body. A resource is global
  * or regional by its CNRM `location` (`"global"` or a region; a NEG has
@@ -168,6 +170,36 @@ export function negBody(resource: GcpResource, ctx: ComputeCtx): Obj {
   return body;
 }
 
+/**
+ * ComputeNetwork → networks.insert body. A network is global. CNRM's
+ * `autoCreateSubnetworks` defaults to false, where compute's default is true,
+ * so it is always sent. Pure.
+ */
+export function networkBody(resource: GcpResource): Obj {
+  const spec = (resource.spec ?? {}) as Obj;
+  const body: Obj = {
+    name: computeName(resource),
+    autoCreateSubnetworks: spec.autoCreateSubnetworks === true,
+    ...pick(spec, ["description", "mtu", "networkFirewallPolicyEnforcementOrder"]),
+  };
+  if (typeof spec.routingMode === "string") body.routingConfig = { routingMode: spec.routingMode };
+  return body;
+}
+
+/** ComputeSubnetwork → subnetworks.insert body. CNRM's `secondaryIpRange` and `logConfig` become compute's `secondaryIpRanges` and an enabled `logConfig`. Pure. */
+export function subnetworkBody(resource: GcpResource, ctx: ComputeCtx): Obj {
+  const spec = (resource.spec ?? {}) as Obj;
+  const scope = scopeOf(spec);
+  const body: Obj = {
+    name: computeName(resource),
+    ...pick(spec, ["ipCidrRange", "description", "privateIpGoogleAccess", "purpose", "role", "stackType"]),
+  };
+  if (isObj(spec.networkRef)) body.network = refUrl("networkRef", spec.networkRef as Ref, ctx, scope);
+  if (Array.isArray(spec.secondaryIpRange)) body.secondaryIpRanges = spec.secondaryIpRange;
+  if (isObj(spec.logConfig)) body.logConfig = { enable: true, ...spec.logConfig };
+  return body;
+}
+
 /** ComputeBackendService → backendServices.insert body. Pure. */
 export function backendServiceBody(resource: GcpResource, ctx: ComputeCtx): Obj {
   const spec = (resource.spec ?? {}) as Obj;
@@ -297,13 +329,14 @@ function computeMapper(
   collection: string,
   build: (resource: GcpResource, ctx: ComputeCtx) => Obj,
   regionalCollection = collection,
+  scopeFor: (spec: Obj | undefined) => string = (spec) => scopeOf(spec),
 ): ResourceMapper {
   return {
     kind,
     defaultHost: COMPUTE_HOST,
     operation: computeOperation,
     plan(resource, ctx) {
-      const scope = scopeOf(resource.spec as Obj | undefined);
+      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) } };
@@ -317,3 +350,5 @@ export const backendServiceMapper = computeMapper("ComputeBackendService", "back
 export const urlMapMapper = computeMapper("ComputeURLMap", "urlMaps", urlMapBody);
 export const targetHttpProxyMapper = computeMapper("ComputeTargetHTTPProxy", "targetHttpProxies", targetHttpProxyBody);
 export const forwardingRuleMapper = computeMapper("ComputeForwardingRule", "forwardingRules", forwardingRuleBody);
+export const networkMapper = computeMapper("ComputeNetwork", "networks", networkBody, "networks", () => "global");
+export const subnetworkMapper = computeMapper("ComputeSubnetwork", "subnetworks", subnetworkBody);

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

@@ -271,6 +271,8 @@ export const iamPolicyMemberMapper: ResourceMapper = {
         status: 200,
         // `resourceRef` is the declared one: the policy read is that target's, so the binding is on it.
         text: JSON.stringify({
+          // The binding has no id of its own; this one names it, so a read reports a physical id (#4251).
+          selfLink: `${target.path}#${spec.role}#${spec.member}`,
           member: spec.member,
           role: spec.role,
           resource: target.path,

package/src/project-config.test.ts

@@ -0,0 +1,119 @@
+import { describe, test, expect, beforeEach, afterEach } from "vitest";
+import { mkdir, writeFile, rm, realpath } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+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 { parseManifest, resolveGcpProject } from "./op/activities/gcp-apply";
+import { CloudRunService, StorageBucket } from "./generated";
+import { defaultAnnotations } from "./default-labels";
+import { GCP } from "./pseudo";
+
+/** #4252: one GCP project for build, apply and read, set once in chant.config. */
+
+const ANNOTATION = "cnrm.cloud.google.com/project-id";
+
+function build(entities: Record<string, unknown>, config?: Record<string, unknown>): string {
+  const out = gcpSerializer.serialize(new Map(Object.entries(entities)) as Map<string, Declarable>, undefined, config ? { config } : undefined);
+  return typeof out === "string" ? out : out.primary;
+}
+
+describe("gcp.project in chant.config (#4252)", () => {
+  let saved: NodeJS.ProcessEnv;
+  beforeEach(() => {
+    saved = { ...process.env };
+    process.env.GCP_PROJECT_ID = "env-id";
+    process.env.GOOGLE_CLOUD_PROJECT = "env-google";
+  });
+  afterEach(() => {
+    process.env = saved;
+  });
+
+  test("the build writes it as each resource's project-id annotation and resolves GCP.ProjectId from it", () => {
+    const yaml = build(
+      {
+        assets: new StorageBucket({ metadata: { name: "assets" }, location: "US" } as never),
+        web: new CloudRunService({ metadata: { name: "web" }, location: "us-central1", projectRef: { external: GCP.ProjectId } } as never),
+      },
+      { gcp: { project: "cfg-project" } },
+    );
+    const docs = parseManifest(yaml, "test");
+    expect(docs.find((d) => d.metadata?.name === "assets")?.metadata?.annotations?.[ANNOTATION]).toBe("cfg-project");
+    expect((docs.find((d) => d.metadata?.name === "web")?.spec as { projectRef: unknown }).projectRef).toEqual({ external: "cfg-project" });
+  });
+
+  test("without it the build writes no annotation, as before", () => {
+    const yaml = build({ assets: new StorageBucket({ metadata: { name: "assets" }, location: "US" } as never) });
+    expect(parseManifest(yaml, "test")[0].metadata?.annotations?.[ANNOTATION]).toBeUndefined();
+  });
+
+  test("a defaultAnnotations project wins over the config's", () => {
+    const yaml = build(
+      {
+        assets: new StorageBucket({ metadata: { name: "assets" }, location: "US" } as never),
+        annotations: defaultAnnotations({ [ANNOTATION]: "declared-project" }),
+      },
+      { gcp: { project: "cfg-project" } },
+    );
+    expect(parseManifest(yaml, "test")[0].metadata?.annotations?.[ANNOTATION]).toBe("declared-project");
+  });
+
+  test("apply and read both take it ahead of GCP_PROJECT_ID and GOOGLE_CLOUD_PROJECT, and a projectRef ahead of it", () => {
+    const yaml = build(
+      {
+        assets: new StorageBucket({ metadata: { name: "assets" }, location: "US" } as never),
+        other: new StorageBucket({ metadata: { name: "other" }, location: "US", projectRef: { external: "own-project" } } as never),
+      },
+      { gcp: { project: "cfg-project" } },
+    );
+    const docs = parseManifest(yaml, "test");
+    expect(resolveGcpProject(docs.find((d) => d.metadata?.name === "assets")!)).toBe("cfg-project");
+    expect(resolveGcpProject(docs.find((d) => d.metadata?.name === "other")!)).toBe("own-project");
+
+    const manifest = manifestProjectAnnotations(yaml);
+    expect(resolveReadProject("StorageBucket", "assets", undefined, manifest, { metadata: { name: "assets" } })).toBe("cfg-project");
+    expect(resolveReadProject("StorageBucket", "other", undefined, manifest, { projectRef: { external: "own-project" } })).toBe("own-project");
+  });
+
+  test("with nothing declared, read falls back to GCP_PROJECT_ID, then GOOGLE_CLOUD_PROJECT", () => {
+    const none = new Map<string, string>();
+    expect(resolveReadProject("StorageBucket", "b", undefined, none, {})).toBe("env-id");
+    delete process.env.GCP_PROJECT_ID;
+    expect(resolveReadProject("StorageBucket", "b", undefined, none, {})).toBe("env-google");
+    delete process.env.GOOGLE_CLOUD_PROJECT;
+    expect(() => resolveReadProject("StorageBucket", "b", undefined, none, {})).toThrow(/gcp\.project in chant\.config/);
+  });
+});
+
+describe("gcp.project under --sandbox (#4252)", () => {
+  let dir: string;
+  beforeEach(async () => {
+    const d = join(tmpdir(), `chant-4252-${Date.now()}-${Math.random()}`);
+    await mkdir(d, { recursive: true });
+    dir = await realpath(d);
+    resetSandboxConfigEvaluationForTests();
+  });
+  afterEach(async () => {
+    resetSandboxConfigEvaluationForTests();
+    await rm(dir, { recursive: true, force: true });
+  });
+
+  test("the config crosses from the sandboxed child as data, and the build reads it from there, not from process.env", async () => {
+    await writeFile(join(dir, "chant.config.ts"), `export default { lexicons: ["gcp"], gcp: { project: "sandboxed-project" } };\n`);
+    armSandboxConfigEvaluation();
+    const { config } = await loadChantConfig(dir);
+    expect((config as { gcp?: { project?: string } }).gcp?.project).toBe("sandboxed-project");
+
+    const saved = process.env.GCP_PROJECT_ID;
+    delete process.env.GCP_PROJECT_ID;
+    try {
+      const yaml = build({ assets: new StorageBucket({ metadata: { name: "assets" }, location: "US" } as never) }, config as Record<string, unknown>);
+      expect(parseManifest(yaml, "test")[0].metadata?.annotations?.[ANNOTATION]).toBe("sandboxed-project");
+    } finally {
+      if (saved !== undefined) process.env.GCP_PROJECT_ID = saved;
+    }
+  });
+});

package/src/read-refs.test.ts

@@ -0,0 +1,135 @@
+import { describe, test, expect, vi, beforeEach, afterEach } from "vitest";
+import { describeResources } from "./describe-resources";
+import {
+  BackendService,
+  CloudRunService,
+  ComputeAddress,
+  ForwardingRule,
+  IAMPolicyMember,
+  RegionNetworkEndpointGroup,
+  Subnetwork,
+  TargetHTTPProxy,
+  URLMap,
+  VPCNetwork,
+} from "./generated";
+
+/**
+ * #4251: behold's three-cloud gcp member, read back. Every resource here names
+ * another by `.name`, an attribute reference the serializer resolves to the
+ * target's metadata.name (#4245). The read path has to resolve it the same way
+ * before a mapper builds a URL from the declared props.
+ */
+const fetchMock = vi.fn();
+
+function reply(status: number, body: unknown) {
+  return { status, text: async () => JSON.stringify(body) };
+}
+
+function estate() {
+  const web = new CloudRunService({ metadata: { name: "three-cloud-site" }, location: "us-central1", template: {} } as never);
+  const vpc = new VPCNetwork({ metadata: { name: "three-cloud-vpc" }, autoCreateSubnetworks: false } as never);
+  const subnet = new Subnetwork({
+    metadata: { name: "three-cloud-subnet" },
+    region: "us-central1",
+    ipCidrRange: "10.8.0.0/24",
+    networkRef: { name: vpc.name },
+  } as never);
+  (web as unknown as { props: Record<string, unknown> }).props.template = {
+    containers: [{ image: "gcr.io/p/site:1" }],
+    vpcAccess: { egress: "ALL_TRAFFIC", networkInterfaces: [{ networkRef: { name: vpc.name }, subnetworkRef: { name: subnet.name } }] },
+  };
+  const neg = new RegionNetworkEndpointGroup({
+    metadata: { name: "three-cloud-neg" },
+    region: "us-central1",
+    networkEndpointType: "SERVERLESS",
+    cloudRun: { serviceRef: { name: web.name } },
+  } as never);
+  const backend = new BackendService({
+    metadata: { name: "three-cloud-backend" },
+    location: "global",
+    loadBalancingScheme: "EXTERNAL_MANAGED",
+    backend: [{ group: { networkEndpointGroupRef: { name: neg.name } } }],
+  } as never);
+  const urlMap = new URLMap({
+    metadata: { name: "three-cloud-urlmap" },
+    location: "global",
+    defaultService: { backendServiceRef: { name: backend.name } },
+  } as never);
+  const proxy = new TargetHTTPProxy({ metadata: { name: "three-cloud-proxy" }, location: "global", urlMapRef: { name: urlMap.name } } as never);
+  const address = new ComputeAddress({ metadata: { name: "three-cloud-ip" }, location: "global" } as never);
+  const rule = new ForwardingRule({
+    metadata: { name: "three-cloud-rule" },
+    location: "global",
+    loadBalancingScheme: "EXTERNAL_MANAGED",
+    portRange: "80",
+    target: { targetHTTPProxyRef: { name: proxy.name } },
+    ipAddress: { addressRef: { name: address.name } },
+  } as never);
+  const publicIam = new IAMPolicyMember({
+    metadata: { name: "three-cloud-site-public" },
+    member: "allUsers",
+    role: "roles/run.invoker",
+    resourceRef: { apiVersion: "run.cnrm.cloud.google.com/v1beta1", kind: "RunService", name: "three-cloud-site" },
+  } as never);
+  const all = { web, vpc, subnet, neg, backend, urlMap, proxy, address, rule, publicIam };
+  return new Map(
+    Object.entries(all).map(([logical, e]) => {
+      const entity = e as unknown as { entityType: string; props: Record<string, unknown> };
+      return [logical, { entityType: entity.entityType, props: entity.props }];
+    }),
+  );
+}
+
+describe("gcp live read resolves .name references as the build does (#4251)", () => {
+  beforeEach(() => {
+    fetchMock.mockReset();
+    vi.stubGlobal("fetch", fetchMock);
+    process.env.GCP_ENDPOINT_URL = "http://localhost:4588";
+    process.env.GOOGLE_CLOUD_PROJECT = "three-cloud";
+    fetchMock.mockImplementation(async (url: string) => {
+      if (url.includes(":getIamPolicy")) {
+        return reply(200, { etag: "e1", bindings: [{ role: "roles/run.invoker", members: ["allUsers"] }] });
+      }
+      return reply(200, { id: url, name: url.split("/").pop() });
+    });
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    delete process.env.GCP_ENDPOINT_URL;
+    delete process.env.GOOGLE_CLOUD_PROJECT;
+  });
+
+  test("every resource reads, by the names the build writes, and none fails on a reference", async () => {
+    const entities = estate();
+    const out = await describeResources({ environment: "local", buildOutput: "", entityNames: [...entities.keys()], entities });
+
+    expect(out.unobserved ?? {}).toEqual({});
+    for (const logical of entities.keys()) {
+      expect(out.resources[logical]?.physicalId, logical).toBeTruthy();
+    }
+    const urls = fetchMock.mock.calls.map((c) => String(c[0]));
+    for (const name of ["three-cloud-neg", "three-cloud-backend", "three-cloud-urlmap", "three-cloud-proxy", "three-cloud-rule", "three-cloud-subnet", "three-cloud-site"]) {
+      expect(urls.some((u) => u.includes(name)), name).toBe(true);
+    }
+    expect(urls.every((u) => !u.includes("[object"))).toBe(true);
+  });
+
+  test("the public IAMPolicyMember reads as the binding in the service's policy, with a physical id", async () => {
+    const entities = estate();
+    const out = await describeResources({ environment: "local", buildOutput: "", entityNames: [...entities.keys()], entities });
+    expect(out.resources.publicIam?.physicalId).toBe(
+      "projects/three-cloud/locations/us-central1/services/three-cloud-site#roles/run.invoker#allUsers",
+    );
+  });
+
+  test("a binding missing from the policy reads as absent, not observed", async () => {
+    fetchMock.mockImplementation(async (url: string) =>
+      url.includes(":getIamPolicy") ? reply(200, { etag: "e1", bindings: [] }) : reply(200, { id: url }),
+    );
+    const entities = estate();
+    const out = await describeResources({ environment: "local", buildOutput: "", entityNames: [...entities.keys()], entities });
+    expect(out.resources.publicIam).toBeUndefined();
+    expect(out.unobserved?.publicIam).toBeUndefined();
+  });
+});

package/src/serializer.test.ts

@@ -293,3 +293,29 @@ describe("gcpSerializer", () => {
     expect(result).toContain("ComputeInstance");
   });
 });
+
+describe("a .name reference serializes as the target's metadata.name (#4242)", () => {
+  test("a declared metadata.name wins; without one, the kebab-cased logical id", async () => {
+    const { RegionNetworkEndpointGroup, BackendService, CloudRunService } = await import("./generated");
+    const web = new CloudRunService({ location: "us-central1", template: { containers: [{ image: "i" }] } } as any);
+    (web as any).name._setLogicalName("webService");
+    const neg = new RegionNetworkEndpointGroup({
+      metadata: { name: "three-cloud-neg" },
+      region: "us-central1",
+      networkEndpointType: "SERVERLESS",
+      cloudRun: { serviceRef: { name: (web as any).name } },
+    } as any);
+    (neg as any).name._setLogicalName("neg");
+    const backend = new BackendService({
+      metadata: { name: "three-cloud-backend" },
+      location: "global",
+      backend: [{ group: { networkEndpointGroupRef: { name: (neg as any).name } } }],
+    } as any);
+    const entities = new Map<string, any>([["webService", web], ["neg", neg], ["backend", backend]]);
+    const yaml = String(gcpSerializer.serialize(entities));
+    expect(yaml).toContain("name: three-cloud-neg");
+    expect(yaml).not.toMatch(/networkEndpointGroupRef:\s*\n\s*name: neg\b/);
+    expect(yaml).toMatch(/serviceRef:\s*\n\s*name: web-service/);
+    expect(yaml).toMatch(/networkEndpointGroupRef:\s*\n\s*name: three-cloud-neg/);
+  });
+});