@intentius/chant-lexicon-gcp 0.124.33 → 0.124.35

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

@@ -0,0 +1,152 @@
+import { beforeEach, describe, expect, test } from "vitest";
+import { applyResource, deleteResource, MAPPERS, type GcpHttp, type GcpResource } from "./gcp-apply";
+import { iamPolicyMemberMapper, iamTarget, policyHasMember, withMember, withoutMember } from "./gcp-iam";
+import { getResource } from "../../api/read-client";
+
+const binding = (overrides: Record<string, unknown> = {}): GcpResource => ({
+  kind: "IAMPolicyMember",
+  metadata: { name: "web-public" },
+  spec: {
+    member: "allUsers",
+    role: "roles/run.invoker",
+    resourceRef: { apiVersion: "run.cnrm.cloud.google.com/v1beta1", kind: "RunService", name: "web" },
+    ...overrides,
+  },
+});
+
+/** A fake policy store: one policy per `:getIamPolicy` path, recording each call. */
+function policyServer(initial: Record<string, unknown> = { etag: "e1", bindings: [{ role: "roles/viewer", members: ["user:a@x.io"] }] }) {
+  let policy = initial as { etag?: string; bindings?: Array<{ role: string; members: string[] }> };
+  const calls: Array<{ method: string; url: string; body?: unknown }> = [];
+  let conflicts = 0;
+  const http: GcpHttp = async (method, url, body) => {
+    calls.push({ method, url, ...(body !== undefined ? { body } : {}) });
+    if (url.includes(":getIamPolicy")) return { status: 200, text: JSON.stringify(policy) };
+    if (url.includes(":setIamPolicy")) {
+      if (conflicts > 0) {
+        conflicts--;
+        return { status: 409, text: "etag mismatch" };
+      }
+      policy = { ...(body as { policy: typeof policy }).policy, etag: "e2" };
+      return { status: 200, text: JSON.stringify(policy) };
+    }
+    return { status: 404, text: "" };
+  };
+  return { http, calls, policy: () => policy, conflict: (n: number) => (conflicts = n) };
+}
+
+const ctx = { base: "https://iam.googleapis.com", project: "p1" };
+
+// The region default reads GCP_REGION; pin it so the URLs below hold.
+beforeEach(() => {
+  delete process.env.GCP_REGION;
+});
+
+describe("IAMPolicyMember targets (#4233)", () => {
+  test("a RunService takes its region from the manifest, and its host when there is no override", () => {
+    const manifest: GcpResource[] = [{ kind: "RunService", metadata: { name: "web" }, spec: { location: "europe-west1" } }];
+    const t = iamTarget(binding().spec as never, "p1", manifest)!;
+    expect(t.get(t.host)).toEqual({
+      method: "GET",
+      url: "https://run.googleapis.com/v2/projects/p1/locations/europe-west1/services/web:getIamPolicy?options.requestedPolicyVersion=3",
+    });
+  });
+
+  test("Project, IAMServiceAccount, StorageBucket, PubSub and secrets resolve; other kinds do not", () => {
+    const of = (resourceRef: Record<string, unknown>) => iamTarget({ member: "m", role: "r", resourceRef } as never, "p1");
+    expect(of({ kind: "Project", external: "projects/other" })!.path).toBe("projects/other");
+    expect(of({ kind: "IAMServiceAccount", name: "sa" })!.path).toBe("projects/p1/serviceAccounts/sa@p1.iam.gserviceaccount.com");
+    expect(of({ kind: "StorageBucket", name: "b" })!.set("https://storage.googleapis.com", { bindings: [] })).toEqual({
+      method: "PUT",
+      url: "https://storage.googleapis.com/storage/v1/b/b/iam",
+      body: { bindings: [] },
+    });
+    expect(of({ kind: "PubSubSubscription", name: "s" })!.path).toBe("projects/p1/subscriptions/s");
+    expect(of({ kind: "SecretManagerSecret", name: "k" })!.path).toBe("projects/p1/secrets/k");
+    expect(of({ kind: "CloudFunctionsFunction", name: "f" })).toBeUndefined();
+  });
+});
+
+describe("policy merge (#4233)", () => {
+  const spec = { member: "allUsers", role: "roles/run.invoker" };
+
+  test("adds the member to its role and keeps every other binding", () => {
+    const next = withMember({ etag: "e1", bindings: [{ role: "roles/viewer", members: ["user:a"] }] }, spec);
+    expect(next).toEqual({
+      etag: "e1",
+      bindings: [
+        { role: "roles/viewer", members: ["user:a"] },
+        { role: "roles/run.invoker", members: ["allUsers"] },
+      ],
+    });
+    expect(policyHasMember(next, spec)).toBe(true);
+  });
+
+  test("a conditional binding is its own binding, at policy version 3", () => {
+    const cond = { ...spec, condition: { title: "t", expression: "request.time < timestamp('2030-01-01T00:00:00Z')" } };
+    const next = withMember({ bindings: [{ role: "roles/run.invoker", members: ["user:b"] }] }, cond);
+    expect(next.version).toBe(3);
+    expect(next.bindings).toHaveLength(2);
+    expect(policyHasMember(next, spec)).toBe(false);
+  });
+
+  test("removing the last member drops the binding", () => {
+    expect(withoutMember({ bindings: [{ role: "roles/run.invoker", members: ["allUsers"] }] }, spec).bindings).toEqual([]);
+  });
+});
+
+describe("IAMPolicyMember apply, delete and read (#4233)", () => {
+  test("apply reads, merges and writes the policy with its etag, then leaves it alone", async () => {
+    const server = policyServer();
+    const first = await applyResource(iamPolicyMemberMapper, binding(), ctx, server.http);
+    expect(first).toEqual({ kind: "IAMPolicyMember", name: "web-public", created: true, updated: false });
+    const set = server.calls.find((c) => c.url.endsWith(":setIamPolicy"))!;
+    expect(set.url).toBe("https://run.googleapis.com/v2/projects/p1/locations/us-central1/services/web:setIamPolicy");
+    expect((set.body as { policy: { etag: string; bindings: unknown[] } }).policy).toEqual({
+      etag: "e1",
+      bindings: [
+        { role: "roles/viewer", members: ["user:a@x.io"] },
+        { role: "roles/run.invoker", members: ["allUsers"] },
+      ],
+    });
+    const again = await applyResource(iamPolicyMemberMapper, binding(), ctx, server.http);
+    expect(again.created).toBe(false);
+    expect(server.calls.filter((c) => c.url.endsWith(":setIamPolicy"))).toHaveLength(1);
+  });
+
+  test("an etag conflict is read again and retried", async () => {
+    const server = policyServer();
+    server.conflict(1);
+    await applyResource(iamPolicyMemberMapper, binding(), ctx, server.http);
+    expect(server.calls.filter((c) => c.url.endsWith(":setIamPolicy"))).toHaveLength(2);
+    expect(policyHasMember(server.policy(), { member: "allUsers", role: "roles/run.invoker" })).toBe(true);
+  });
+
+  test("an endpoint override serves every target", async () => {
+    const server = policyServer();
+    await applyResource(iamPolicyMemberMapper, binding(), { base: "http://localhost:4588", project: "p1" }, server.http);
+    expect(server.calls.every((c) => c.url.startsWith("http://localhost:4588/v2/"))).toBe(true);
+  });
+
+  test("delete removes only this member", async () => {
+    const server = policyServer({ etag: "e1", bindings: [{ role: "roles/run.invoker", members: ["allUsers", "user:b"] }] });
+    expect((await deleteResource(iamPolicyMemberMapper, binding(), ctx, server.http)).deleted).toBe(true);
+    expect(server.policy().bindings).toEqual([{ role: "roles/run.invoker", members: ["user:b"] }]);
+    expect((await deleteResource(iamPolicyMemberMapper, binding(), ctx, server.http)).deleted).toBe(false);
+  });
+
+  test("the reader answers present when the policy grants the member, absent when not", async () => {
+    const server = policyServer({ bindings: [{ role: "roles/run.invoker", members: ["allUsers"] }] });
+    const props = binding().spec as Record<string, unknown>;
+    const body = await getResource({ project: "p1", http: server.http }, "IAMPolicyMember", "web-public", props);
+    expect(body).toMatchObject({ member: "allUsers", role: "roles/run.invoker", resource: "projects/p1/locations/us-central1/services/web" });
+
+    const empty = policyServer({ bindings: [] });
+    await expect(getResource({ project: "p1", http: empty.http }, "IAMPolicyMember", "web-public", props)).rejects.toMatchObject({ status: 404 });
+  });
+
+  test("a binding on a target chant cannot reach is not accepted", () => {
+    const fn = binding({ resourceRef: { kind: "CloudFunctionsFunction", name: "f" } });
+    expect(MAPPERS.IAMPolicyMember.accepts!(fn, ctx)).toBe(false);
+  });
+});

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

@@ -0,0 +1,284 @@
+/**
+ * IAMPolicyMember (#4233): one member in one role on one resource's IAM policy.
+ *
+ * GCP has no REST resource for a single binding member. The member lives inside
+ * the target's policy, read with `getIamPolicy` and written whole with
+ * `setIamPolicy`. So this mapper does not fit the GET-then-create plan the other
+ * kinds use: apply reads the policy, adds the member to the role's binding when
+ * it is missing and writes the policy back with its `etag`; delete removes it
+ * the same way. Other members and bindings are kept as read (a merge, never an
+ * overwrite), and a write that loses an `etag` race is retried.
+ *
+ * Targets are the kinds `resourceRef` can name that have an IAM policy chant can
+ * reach: Project, RunService, IAMServiceAccount, StorageBucket, PubSubTopic,
+ * PubSubSubscription and SecretManagerSecret. Any other target is reported as
+ * not attempted, the way a kind with no mapper is.
+ */
+import type { GcpHttp, GcpResource, ResourceMapper } from "./gcp-apply";
+
+/** The CNRM IAMPolicyMember spec chant reads. */
+export interface IamPolicyMemberSpec {
+  member?: string;
+  role?: string;
+  resourceRef?: { kind?: string; name?: string; external?: string; apiVersion?: string };
+  condition?: { title?: string; description?: string; expression?: string };
+  location?: string;
+}
+
+interface Binding {
+  role: string;
+  members?: string[];
+  condition?: { title?: string; description?: string; expression?: string };
+}
+
+interface Policy {
+  version?: number;
+  etag?: string;
+  bindings?: Binding[];
+}
+
+/** Where a target's policy is read and written. */
+export interface IamTarget {
+  /** Real-GCP host for the target's service. */
+  host: string;
+  /** The target's resource path, used in messages and in the read body. */
+  path: string;
+  get: (base: string) => { method: "GET" | "POST"; url: string; body?: unknown };
+  set: (base: string, policy: Policy) => { method: "POST" | "PUT"; url: string; body: unknown };
+}
+
+/** The default host this mapper reports; a target's own host replaces it when there is no endpoint override. */
+export const IAM_DEFAULT_HOST = "https://iam.googleapis.com";
+
+const enc = encodeURIComponent;
+
+function region(env: NodeJS.ProcessEnv = process.env): string {
+  return env.GCP_REGION || "us-central1";
+}
+
+/** A `:getIamPolicy` / `:setIamPolicy` pair on a REST resource path (the Google API convention). */
+function verbTarget(host: string, version: string, path: string, getMethod: "GET" | "POST"): IamTarget {
+  return {
+    host,
+    path,
+    get: (base) =>
+      getMethod === "GET"
+        ? { method: "GET", url: `${base}/${version}/${path}:getIamPolicy?options.requestedPolicyVersion=3` }
+        : { method: "POST", url: `${base}/${version}/${path}:getIamPolicy`, body: { options: { requestedPolicyVersion: 3 } } },
+    set: (base, policy) => ({ method: "POST", url: `${base}/${version}/${path}:setIamPolicy`, body: { policy } }),
+  };
+}
+
+/**
+ * Resolve `resourceRef` to the target's policy endpoints, or undefined for a
+ * target chant cannot reach. `manifest` is the rest of the applied manifest, so
+ * a RunService named by `name` takes its region from its own spec. Pure.
+ */
+export function iamTarget(
+  spec: IamPolicyMemberSpec,
+  project: string,
+  manifest: readonly GcpResource[] = [],
+  env: NodeJS.ProcessEnv = process.env,
+): IamTarget | undefined {
+  const ref = spec.resourceRef ?? {};
+  const external = typeof ref.external === "string" && ref.external !== "" ? ref.external : undefined;
+  const name = typeof ref.name === "string" && ref.name !== "" ? ref.name : undefined;
+  switch (ref.kind) {
+    case "Project": {
+      const id = external ? external.replace(/^projects\//, "") : (name ?? project);
+      return verbTarget("https://cloudresourcemanager.googleapis.com", "v1", `projects/${enc(id)}`, "POST");
+    }
+    case "RunService": {
+      if (external) return verbTarget("https://run.googleapis.com", "v2", external, "GET");
+      if (!name) return undefined;
+      const declared = manifest.find((r) => r.kind === "RunService" && r.metadata?.name === name);
+      const location = (declared?.spec as { location?: unknown } | undefined)?.location;
+      const loc = typeof location === "string" ? location : (spec.location ?? region(env));
+      return verbTarget("https://run.googleapis.com", "v2", `projects/${enc(project)}/locations/${enc(loc)}/services/${enc(name)}`, "GET");
+    }
+    case "IAMServiceAccount": {
+      if (external?.startsWith("projects/")) return verbTarget(IAM_DEFAULT_HOST, "v1", external, "POST");
+      const email = external ?? (name ? `${name}@${project}.iam.gserviceaccount.com` : undefined);
+      if (!email) return undefined;
+      return verbTarget(IAM_DEFAULT_HOST, "v1", `projects/${enc(project)}/serviceAccounts/${email}`, "POST");
+    }
+    case "PubSubTopic":
+    case "PubSubSubscription": {
+      const collection = ref.kind === "PubSubTopic" ? "topics" : "subscriptions";
+      const path = external ?? (name ? `projects/${enc(project)}/${collection}/${enc(name)}` : undefined);
+      return path ? verbTarget("https://pubsub.googleapis.com", "v1", path, "GET") : undefined;
+    }
+    case "SecretManagerSecret": {
+      const path = external ?? (name ? `projects/${enc(project)}/secrets/${enc(name)}` : undefined);
+      return path ? verbTarget("https://secretmanager.googleapis.com", "v1", path, "GET") : undefined;
+    }
+    case "StorageBucket": {
+      const bucket = external ? external.replace(/^(gs:\/\/|projects\/_\/buckets\/)/, "") : name;
+      if (!bucket) return undefined;
+      // GCS has its own IAM shape: GET and PUT on `b/<bucket>/iam`, with the policy as the body.
+      const url = (base: string) => `${base}/storage/v1/b/${enc(bucket)}/iam`;
+      return {
+        host: "https://storage.googleapis.com",
+        path: `b/${bucket}`,
+        get: (base) => ({ method: "GET", url: `${url(base)}?optionsRequestedPolicyVersion=3` }),
+        set: (base, policy) => ({ method: "PUT", url: url(base), body: policy }),
+      };
+    }
+    default:
+      return undefined;
+  }
+}
+
+function sameCondition(a: Binding["condition"], b: IamPolicyMemberSpec["condition"]): boolean {
+  if (!a && !b) return true;
+  if (!a || !b) return false;
+  return (a.expression ?? "") === (b.expression ?? "") && (a.title ?? "") === (b.title ?? "");
+}
+
+function findBinding(policy: Policy, spec: IamPolicyMemberSpec): Binding | undefined {
+  return policy.bindings?.find((b) => b.role === spec.role && sameCondition(b.condition, spec.condition));
+}
+
+/** True when the policy grants the spec's member in its role (and condition). Pure. */
+export function policyHasMember(policy: Policy, spec: IamPolicyMemberSpec): boolean {
+  return findBinding(policy, spec)?.members?.includes(spec.member ?? "") ?? false;
+}
+
+/** The policy with the spec's member added to its binding, every other binding kept. Pure. */
+export function withMember(policy: Policy, spec: IamPolicyMemberSpec): Policy {
+  const member = spec.member as string;
+  const bindings = (policy.bindings ?? []).map((b) => ({ ...b, members: [...(b.members ?? [])] }));
+  const existing = bindings.find((b) => b.role === spec.role && sameCondition(b.condition, spec.condition));
+  if (existing) {
+    if (!existing.members.includes(member)) existing.members.push(member);
+  } else {
+    bindings.push({ role: spec.role as string, members: [member], ...(spec.condition ? { condition: spec.condition } : {}) });
+  }
+  // A conditional binding needs policy version 3; otherwise keep what was read.
+  const version = spec.condition || bindings.some((b) => b.condition) ? 3 : policy.version;
+  return { ...policy, bindings, ...(version !== undefined ? { version } : {}) };
+}
+
+/** The policy with the spec's member removed; a binding left with no members is dropped. Pure. */
+export function withoutMember(policy: Policy, spec: IamPolicyMemberSpec): Policy {
+  const bindings = (policy.bindings ?? [])
+    .map((b) =>
+      b.role === spec.role && sameCondition(b.condition, spec.condition)
+        ? { ...b, members: (b.members ?? []).filter((m) => m !== spec.member) }
+        : b,
+    )
+    .filter((b) => (b.members ?? []).length > 0);
+  return { ...policy, bindings };
+}
+
+function specOf(resource: GcpResource): IamPolicyMemberSpec {
+  const spec = (resource.spec ?? {}) as IamPolicyMemberSpec;
+  const name = resource.metadata?.name ?? "?";
+  if (!spec.member) throw new Error(`IAMPolicyMember ${name} has no spec.member`);
+  if (!spec.role) throw new Error(`IAMPolicyMember ${name} has no spec.role`);
+  return spec;
+}
+
+function targetOf(resource: GcpResource, ctx: IamCtx, env?: NodeJS.ProcessEnv): { target: IamTarget; base: string } {
+  const target = iamTarget(specOf(resource), ctx.project, ctx.manifest, env);
+  if (!target) {
+    const ref = (resource.spec as IamPolicyMemberSpec | undefined)?.resourceRef;
+    throw new Error(`IAMPolicyMember ${resource.metadata?.name ?? "?"}: no IAM policy endpoint for resourceRef kind ${ref?.kind ?? "(none)"}`);
+  }
+  // No endpoint override: each target's own service host. An override (floci-gcp) serves every service.
+  const base = ctx.base === IAM_DEFAULT_HOST ? target.host : ctx.base;
+  return { target, base };
+}
+
+interface IamCtx {
+  base: string;
+  project: string;
+  manifest?: readonly GcpResource[];
+}
+
+async function readPolicy(target: IamTarget, base: string, http: GcpHttp, signal?: AbortSignal): Promise<{ status: number; text: string; policy?: Policy }> {
+  const req = target.get(base);
+  const res = await http(req.method, req.url, req.body, signal);
+  if (res.status >= 300) return res;
+  let policy: Policy;
+  try {
+    policy = JSON.parse(res.text) as Policy;
+  } catch {
+    policy = {};
+  }
+  return { ...res, policy };
+}
+
+/** How many times a write that loses an `etag` race (409, or 412 on GCS) is retried. */
+const ETAG_ATTEMPTS = 3;
+
+async function writeWith(
+  resource: GcpResource,
+  ctx: IamCtx,
+  http: GcpHttp,
+  signal: AbortSignal | undefined,
+  change: (policy: Policy, spec: IamPolicyMemberSpec) => Policy | undefined,
+): Promise<boolean> {
+  const spec = specOf(resource);
+  const { target, base } = targetOf(resource, ctx);
+  const name = resource.metadata?.name ?? "?";
+  for (let attempt = 1; ; attempt++) {
+    const read = await readPolicy(target, base, http, signal);
+    if (!read.policy) throw new Error(`IAMPolicyMember ${name}: reading the policy of ${target.path} failed (${read.status}): ${read.text}`);
+    const next = change(read.policy, spec);
+    if (!next) return false;
+    const req = target.set(base, next);
+    const res = await http(req.method, req.url, req.body, signal);
+    if (res.status < 300) return true;
+    if ((res.status === 409 || res.status === 412) && attempt < ETAG_ATTEMPTS) continue;
+    throw new Error(`IAMPolicyMember ${name}: writing the policy of ${target.path} failed (${res.status}): ${res.text}`);
+  }
+}
+
+export const iamPolicyMemberMapper: ResourceMapper = {
+  kind: "IAMPolicyMember",
+  defaultHost: IAM_DEFAULT_HOST,
+  accepts(resource, ctx) {
+    return iamTarget((resource.spec ?? {}) as IamPolicyMemberSpec, ctx.project, ctx.manifest) !== undefined;
+  },
+  plan(resource, ctx) {
+    // Only the read is a single URL here; apply and delete go through `custom`.
+    const { target, base } = targetOf(resource, ctx);
+    const get = target.get(base);
+    return { getUrl: get.url, create: { method: "POST", url: get.url, body: get.body ?? {} } };
+  },
+  custom: {
+    async apply(resource, ctx, http, signal) {
+      const created = await writeWith(resource, ctx, http, signal, (policy, spec) =>
+        policyHasMember(policy, spec) ? undefined : withMember(policy, spec),
+      );
+      return { created, updated: false };
+    },
+    async delete(resource, ctx, http, signal) {
+      return writeWith(resource, ctx, http, signal, (policy, spec) =>
+        policyHasMember(policy, spec) ? withoutMember(policy, spec) : undefined,
+      );
+    },
+    async read(resource, ctx, http, signal) {
+      const spec = specOf(resource);
+      const { target, base } = targetOf(resource, ctx);
+      const read = await readPolicy(target, base, http, signal);
+      if (!read.policy) return read;
+      // The binding member is the resource: absent from the policy reads as absent.
+      if (!policyHasMember(read.policy, spec)) return { status: 404, text: `${spec.member} has no ${spec.role} on ${target.path}` };
+      const binding = findBinding(read.policy, spec);
+      return {
+        status: 200,
+        // `resourceRef` is the declared one: the policy read is that target's, so the binding is on it.
+        text: JSON.stringify({
+          member: spec.member,
+          role: spec.role,
+          resource: target.path,
+          ...(spec.resourceRef ? { resourceRef: spec.resourceRef } : {}),
+          ...(binding?.condition ? { condition: binding.condition } : {}),
+          ...(read.policy.etag ? { etag: read.policy.etag } : {}),
+        }),
+      };
+    },
+  },
+};

package/src/op/activities/index.ts

@@ -34,6 +34,7 @@ export {
   isChantOwned,
   resolveGcpEndpoint,
   resolveGcpProject,
+  projectRefProject,
   parseManifest,
 } from "./gcp-apply";
 export type {

package/src/project-resolution.test.ts

@@ -0,0 +1,41 @@
+/**
+ * The live readers take a resource's project from `projectRef.external`
+ * (#4201), the way `CloudRunServiceComposite` declares it, before
+ * GOOGLE_CLOUD_PROJECT and the annotations.
+ */
+
+import { afterEach, describe, expect, test } from "vitest";
+import { manifestProjectAnnotations, resolveReadProject } from "./describe-resources";
+
+const saved = process.env.GOOGLE_CLOUD_PROJECT;
+afterEach(() => {
+  if (saved === undefined) delete process.env.GOOGLE_CLOUD_PROJECT;
+  else process.env.GOOGLE_CLOUD_PROJECT = saved;
+});
+
+describe("resolveReadProject", () => {
+  test("reads the entity's projectRef.external with no env or annotation", () => {
+    delete process.env.GOOGLE_CLOUD_PROJECT;
+    const props = { projectRef: { external: "three-cloud" }, location: "asia-northeast1" };
+    expect(resolveReadProject("RunService", "web", { annotations: {} }, new Map(), props)).toBe("three-cloud");
+  });
+
+  test("still names every knob when nothing resolves", () => {
+    delete process.env.GOOGLE_CLOUD_PROJECT;
+    expect(() => resolveReadProject("RunService", "web", undefined, new Map(), {})).toThrow(/projectRef\.external/);
+  });
+});
+
+describe("manifestProjectAnnotations", () => {
+  test("takes a document's spec.projectRef.external", () => {
+    const yaml = `apiVersion: run.cnrm.cloud.google.com/v1beta1
+kind: RunService
+metadata:
+  name: web
+spec:
+  projectRef:
+    external: projects/three-cloud
+`;
+    expect(manifestProjectAnnotations(yaml).get("RunService/web")).toBe("three-cloud");
+  });
+});

package/src/serializer-pseudo.test.ts

@@ -0,0 +1,38 @@
+/**
+ * GCP pseudo-parameters in spec values are resolved at build, and a build
+ * that can't resolve one refuses with the variable named (#4200).
+ */
+
+import { afterEach, describe, expect, test } from "vitest";
+import { CloudRunServiceComposite } from "./composites/cloud-run-service";
+import { gcpSerializer } from "./serializer";
+
+const saved = { project: process.env.GCP_PROJECT_ID, region: process.env.GCP_REGION };
+afterEach(() => {
+  for (const [k, v] of [["GCP_PROJECT_ID", saved.project], ["GCP_REGION", saved.region]] as const) {
+    if (v === undefined) delete process.env[k];
+    else process.env[k] = v;
+  }
+});
+
+function build(): string {
+  const { service } = CloudRunServiceComposite({ name: "web", image: "traefik/whoami:v1.10", port: 80 });
+  return gcpSerializer.serialize(new Map([["web", service]])) as string;
+}
+
+describe("gcp pseudo-parameters in spec values", () => {
+  test("resolve from GCP_PROJECT_ID and GCP_REGION", () => {
+    process.env.GCP_PROJECT_ID = "three-cloud";
+    process.env.GCP_REGION = "asia-northeast1";
+    const yaml = build();
+    expect(yaml).toContain("location: asia-northeast1");
+    expect(yaml).toContain("external: three-cloud");
+    expect(yaml).not.toMatch(/Ref: GCP::/);
+  });
+
+  test("refuse the build, naming each unset variable", () => {
+    delete process.env.GCP_PROJECT_ID;
+    delete process.env.GCP_REGION;
+    expect(build).toThrow(/GCP_REGION, GCP_PROJECT_ID are not set[\s\S]*web: GCP::Region needs GCP_REGION[\s\S]*web: GCP::ProjectId needs GCP_PROJECT_ID/);
+  });
+});

package/src/serializer.ts

@@ -162,6 +162,7 @@ export const gcpSerializer: Serializer = {
     }
 
     const documents: string[] = [];
+    const unresolved: UnresolvedPseudo[] = [];
 
     for (const [name, entity] of entities) {
       if (isPropertyDeclarable(entity)) continue;
@@ -171,9 +172,10 @@ export const gcpSerializer: Serializer = {
       const gvk = resolveGVK(entityType);
       if (!gvk) continue;
 
-      const props = toYAMLValue(
-        isResourceDeclarable(entity) ? entity.props : undefined,
-        entityNames,
+      const props = resolvePseudoParameters(
+        toYAMLValue(isResourceDeclarable(entity) ? entity.props : undefined, entityNames),
+        name,
+        unresolved,
       ) as Record<string, unknown> | undefined;
 
       if (!props) continue;
@@ -223,6 +225,8 @@ export const gcpSerializer: Serializer = {
       documents.push(yamlDoc);
     }
 
+    if (unresolved.length > 0) throw new Error(unresolvedMessage(unresolved));
+
     const primary = documents.join("\n---\n");
     const warnings = unwritableOutputWarnings(outputs);
     return warnings.length > 0 ? { primary, warnings } : primary;
@@ -240,6 +244,42 @@ const PSEUDO_ENV_MAP: Record<string, { envVar: string; fallback: string }> = {
   "GCP::Zone": { envVar: "GCP_ZONE", fallback: "us-central1-a" },
 };
 
+interface UnresolvedPseudo {
+  entity: string;
+  ref: string;
+  envVar: string;
+}
+
+/**
+ * Replace each GCP pseudo-parameter (`{ Ref: "GCP::Region" }`) in a
+ * serialized resource with its environment variable's value (#4200).
+ * Config Connector has no parameters, so a `Ref` left in the YAML reaches
+ * the API as an object. A variable that isn't set is recorded, and the
+ * build refuses with every one named.
+ */
+function resolvePseudoParameters(value: unknown, entity: string, unresolved: UnresolvedPseudo[]): unknown {
+  if (Array.isArray(value)) return value.map((v) => resolvePseudoParameters(v, entity, unresolved));
+  if (value === null || typeof value !== "object") return value;
+  const obj = value as Record<string, unknown>;
+  const keys = Object.keys(obj);
+  if (keys.length === 1 && keys[0] === "Ref" && typeof obj.Ref === "string" && obj.Ref in PSEUDO_ENV_MAP) {
+    const { envVar } = PSEUDO_ENV_MAP[obj.Ref];
+    const resolved = process.env[envVar];
+    if (resolved) return resolved;
+    unresolved.push({ entity, ref: obj.Ref, envVar });
+    return value;
+  }
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(obj)) out[k] = resolvePseudoParameters(v, entity, unresolved);
+  return out;
+}
+
+function unresolvedMessage(unresolved: UnresolvedPseudo[]): string {
+  const vars = [...new Set(unresolved.map((u) => u.envVar))];
+  const lines = unresolved.map((u) => `  ${u.entity}: ${u.ref} needs ${u.envVar}`);
+  return `gcp: ${vars.join(", ")} ${vars.length === 1 ? "is" : "are"} not set, and Config Connector YAML can't carry a pseudo-parameter. Set ${vars.length === 1 ? "it" : "them"} at build, or pass the value explicitly:\n${lines.join("\n")}`;
+}
+
 /**
  * Resolve an annotation value to a plain string.
  * PseudoParameter intrinsics are resolved from environment variables;