@intentius/chant-lexicon-gcp 0.124.34 → 0.124.35

package/dist/op/activities/gcp-iam.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gcp-iam.d.ts","sourceRoot":"","sources":["../../../src/op/activities/gcp-iam.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,KAAK,EAAW,WAAW,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAExE,iDAAiD;AACjD,MAAM,WAAW,mBAAmB;IAClC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACvF,SAAS,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC1E,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,UAAU,OAAO;IACf,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,SAAS,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAC3E;AAED,UAAU,MAAM;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,OAAO,EAAE,CAAC;CACtB;AAED,mDAAmD;AACnD,MAAM,WAAW,SAAS;IACxB,8CAA8C;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb,yEAAyE;IACzE,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK;QAAE,MAAM,EAAE,KAAK,GAAG,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;IAC/E,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK;QAAE,MAAM,EAAE,MAAM,GAAG,KAAK,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,OAAO,CAAA;KAAE,CAAC;CAC/F;AAED,gHAAgH;AAChH,eAAO,MAAM,gBAAgB,+BAA+B,CAAC;AAqB7D;;;;GAIG;AACH,wBAAgB,SAAS,CACvB,IAAI,EAAE,mBAAmB,EACzB,OAAO,EAAE,MAAM,EACf,QAAQ,GAAE,SAAS,WAAW,EAAO,EACrC,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,SAAS,GAAG,SAAS,CAgDvB;AAYD,uFAAuF;AACvF,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAElF;AAED,8FAA8F;AAC9F,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,mBAAmB,GAAG,MAAM,CAY5E;AAED,kGAAkG;AAClG,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,mBAAmB,GAAG,MAAM,CAS/E;AAkED,eAAO,MAAM,qBAAqB,EAAE,cA8CnC,CAAC"}

package/dist/op/activities/gcp-iam.js

@@ -0,0 +1,215 @@
+/** 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 = process.env) {
+    return env.GCP_REGION || "us-central1";
+}
+/** A `:getIamPolicy` / `:setIamPolicy` pair on a REST resource path (the Google API convention). */
+function verbTarget(host, version, path, getMethod) {
+    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, project, manifest = [], env = process.env) {
+    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?.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) => `${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, b) {
+    if (!a && !b)
+        return true;
+    if (!a || !b)
+        return false;
+    return (a.expression ?? "") === (b.expression ?? "") && (a.title ?? "") === (b.title ?? "");
+}
+function findBinding(policy, spec) {
+    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, spec) {
+    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, spec) {
+    const member = spec.member;
+    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, 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, spec) {
+    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) {
+    const spec = (resource.spec ?? {});
+    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, ctx, env) {
+    const target = iamTarget(specOf(resource), ctx.project, ctx.manifest, env);
+    if (!target) {
+        const ref = resource.spec?.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 };
+}
+async function readPolicy(target, base, http, signal) {
+    const req = target.get(base);
+    const res = await http(req.method, req.url, req.body, signal);
+    if (res.status >= 300)
+        return res;
+    let policy;
+    try {
+        policy = JSON.parse(res.text);
+    }
+    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, ctx, http, signal, change) {
+    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 = {
+    kind: "IAMPolicyMember",
+    defaultHost: IAM_DEFAULT_HOST,
+    accepts(resource, ctx) {
+        return iamTarget((resource.spec ?? {}), 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-gcp",
-  "version": "0.124.34",
+  "version": "0.124.35",
   "description": "Google Cloud lexicon for chant — declarative IaC in TypeScript",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",
@@ -76,6 +76,6 @@
     "typescript": "^5.9.3"
   },
   "peerDependencies": {
-    "@intentius/chant": "^0.124.34"
+    "@intentius/chant": "^0.124.35"
   }
 }

package/src/api/read-client.ts

@@ -22,7 +22,11 @@
  *
  * Coverage is exactly the applier's dispatch table (`MAPPERS`) — StorageBucket,
  * PubSubTopic, PubSubSubscription, SecretManagerSecret, IAMServiceAccount,
- * RunService. The kubectl path could fetch any CNRM kind the cluster knew
+ * RunService, IAMPolicyMember and the Cloud Run load balancer kinds
+ * (ComputeAddress, ComputeRegionNetworkEndpointGroup, ComputeBackendService,
+ * ComputeURLMap, ComputeTargetHTTPProxy, ComputeForwardingRule; #4233). An
+ * IAMPolicyMember is read through its target's policy and is present when the
+ * policy grants its member the role. The kubectl path could fetch any CNRM kind the cluster knew
  * about, so this is narrower on paper. It is not narrower in practice for
  * anything chant can act on: a kind with no mapper cannot be applied either, so
  * observing it produced a live tree nothing could ever reconcile against.
@@ -44,11 +48,14 @@ export interface GcpReadClientOptions {
   http?: GcpReadHttp;
 }
 
-/** Injectable HTTP client — mirrors the applier's `GcpHttp`. */
-export type GcpReadHttp = (method: string, url: string) => Promise<{ status: number; text: string }>;
+/** Injectable HTTP client — mirrors the applier's `GcpHttp`. A body is sent only for a POST read (`:getIamPolicy`). */
+export type GcpReadHttp = (method: string, url: string, body?: unknown) => Promise<{ status: number; text: string }>;
 
-const defaultHttp: GcpReadHttp = async (method, url) => {
-  const res = await fetch(url, { method });
+const defaultHttp: 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() };
 };
 
@@ -100,21 +107,33 @@ export async function getResource(
     spec: (declared?.spec as Record<string, unknown> | undefined) ?? declared ?? {},
   };
 
-  let getUrl: string;
-  try {
-    getUrl = mapper.plan(resource, { base, project: client.project }).getUrl;
-  } catch (err) {
-    // A mapper that cannot plan from the declared spec cannot produce a URL, so
-    // there is nothing to read — a hole, never an absence.
-    throw new GcpReadError(`could not build a read URL for ${kind}/${name}: ${err instanceof Error ? err.message : String(err)}`);
+  const ctx = { base, project: client.project };
+  if (mapper.accepts && !mapper.accepts(resource, ctx)) {
+    throw new GcpReadError(`no REST read for ${kind}/${name}: its target has no endpoint chant can read`);
   }
 
   const http = client.http ?? defaultHttp;
   let res: { status: number; text: string };
-  try {
-    res = await http("GET", getUrl);
-  } catch (err) {
-    throw new GcpReadError(err instanceof Error ? err.message : String(err));
+  if (mapper.custom) {
+    try {
+      res = await mapper.custom.read(resource, ctx, (method, url, body) => http(method, url, body));
+    } catch (err) {
+      throw new GcpReadError(`could not read ${kind}/${name}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  } else {
+    let getUrl: string;
+    try {
+      getUrl = mapper.plan(resource, ctx).getUrl;
+    } catch (err) {
+      // A mapper that cannot plan from the declared spec cannot produce a URL, so
+      // there is nothing to read — a hole, never an absence.
+      throw new GcpReadError(`could not build a read URL for ${kind}/${name}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    try {
+      res = await http("GET", getUrl);
+    } catch (err) {
+      throw new GcpReadError(err instanceof Error ? err.message : String(err));
+    }
   }
 
   if (res.status === 404) throw new GcpReadError(`${kind}/${name} not found`, 404);

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

@@ -34,6 +34,8 @@ export interface CloudRunServiceProps {
   publicAccess?: boolean;
   /** Environment variables. */
   env?: Array<{ name: string; value: string }>;
+  /** Service account the service runs as: an email, or the account id of an IAMServiceAccount in the project. */
+  serviceAccount?: string;
   /** Additional labels. */
   labels?: Record<string, string>;
   /** Namespace for all resources. */
@@ -75,6 +77,7 @@ export const CloudRunServiceComposite = Composite((props: CloudRunServiceProps)
     maxInstanceCount = 100,
     publicAccess = false,
     env,
+    serviceAccount,
     labels: extraLabels = {},
     namespace,
     defaults: defs,
@@ -112,6 +115,9 @@ export const CloudRunServiceComposite = Composite((props: CloudRunServiceProps)
         maxInstanceCount,
       },
       containers,
+      ...(serviceAccount && {
+        serviceAccountRef: serviceAccount.includes("@") ? { external: serviceAccount } : { name: serviceAccount },
+      }),
     },
   }, defs?.service));
 

package/src/composites/composites.test.ts

@@ -83,6 +83,13 @@ describe("CloudRunServiceComposite", () => {
     expect(result.service).toBeDefined();
   });
 
+  test("serviceAccount sets serviceAccountRef: an account id by name, an email as external (#4240)", () => {
+    const byName = CloudRunServiceComposite({ name: "api", image: "i", serviceAccount: "run-sa" });
+    expect((p(byName.service).template as Record<string, unknown>).serviceAccountRef).toEqual({ name: "run-sa" });
+    const byEmail = CloudRunServiceComposite({ name: "api", image: "i", serviceAccount: "x@o.iam.gserviceaccount.com" });
+    expect((p(byEmail.service).template as Record<string, unknown>).serviceAccountRef).toEqual({ external: "x@o.iam.gserviceaccount.com" });
+  });
+
   test("sets projectRef and location, which the RunService CRD requires", () => {
     const result = CloudRunServiceComposite({
       name: "api",

package/src/deep-observe.test.ts

@@ -124,6 +124,21 @@ describe("toCnrmTree — each REST shape in the declared vocabulary (#1210)", ()
     expect(tree).toEqual({ metadata: { name: "t" }, messageRetentionDuration: "86400s" });
   });
 
+  test("run service: the v2 serviceAccount email maps back to the declared serviceAccountRef (#4240)", () => {
+    const same = toCnrmTree(
+      "RunService",
+      { name: "projects/my-project/locations/us-central1/services/web", template: { serviceAccount: "run-sa@my-project.iam.gserviceaccount.com" } },
+      ctx,
+    ) as { template: Record<string, unknown> };
+    expect(same.template).toEqual({ serviceAccountRef: { name: "run-sa" } });
+    const other = toCnrmTree(
+      "RunService",
+      { name: "projects/my-project/locations/us-central1/services/web", template: { serviceAccount: "x@other.iam.gserviceaccount.com" } },
+      ctx,
+    ) as { template: Record<string, unknown> };
+    expect(other.template).toEqual({ serviceAccountRef: { external: "x@other.iam.gserviceaccount.com" } });
+  });
+
   test("bucket: GCS's iamConfiguration and lifecycle map onto the CNRM field names", () => {
     const tree = toCnrmTree(
       "StorageBucket",
@@ -235,7 +250,7 @@ describe("observeResourcesDeepGcp — over REST (#1209)", () => {
   });
 
   test("a kind the applier cannot write is unsupported-kind, and is never queried", async () => {
-    const out = await observe(entities([["e", "GCP::Compute::Address", { metadata: { name: "a" } }]]));
+    const out = await observe(entities([["e", "GCP::Compute::Network", { metadata: { name: "n" } }]]));
     expect(out.unobserved?.e?.reason).toBe("unsupported-kind");
     expect(fetchMock).not.toHaveBeenCalled();
   });

package/src/deep-observe.ts

@@ -182,9 +182,133 @@ const CNRM_REFINERS: Record<string, (tree: CnrmTree, ctx: RefineContext) => void
     // name. The declared side writes it as `location`.
     const m = ctx.restName ? /\/locations\/([^/]+)\//.exec(ctx.restName) : null;
     if (m) tree.location = m[1];
+    // #4240: v2 returns the account as an email; the declared side writes a
+    // `serviceAccountRef`, `name` for an account in the project.
+    const template = tree.template as Record<string, unknown> | undefined;
+    if (template && typeof template.serviceAccount === "string") {
+      const email = template.serviceAccount;
+      const suffix = `@${ctx.project}.iam.gserviceaccount.com`;
+      template.serviceAccountRef = email.endsWith(suffix) ? { name: email.slice(0, -suffix.length) } : { external: email };
+      delete template.serviceAccount;
+    }
+  },
+  // #4233: the inverse of gcp-compute.ts's body builders. Compute returns refs
+  // as full URLs and a region as a URL; CNRM writes `*Ref: { name }` and a
+  // bare `location` (`"global"` when the resource has no region).
+  IAMPolicyMember(tree) {
+    delete tree.etag;
+    delete tree.resource;
+  },
+  ComputeAddress(tree) {
+    computeLocation(tree);
+  },
+  ComputeRegionNetworkEndpointGroup(tree) {
+    if (typeof tree.region === "string") tree.region = lastSegment(tree.region);
+    const cloudRun = tree.cloudRun as Record<string, unknown> | undefined;
+    if (cloudRun && typeof cloudRun.service === "string") {
+      cloudRun.serviceRef = { name: cloudRun.service };
+      delete cloudRun.service;
+    }
+  },
+  ComputeBackendService(tree) {
+    computeLocation(tree);
+    if (tree.enableCDN !== undefined) {
+      tree.enableCdn = tree.enableCDN;
+      delete tree.enableCDN;
+    }
+    const draining = tree.connectionDraining as { drainingTimeoutSec?: unknown } | undefined;
+    if (draining) {
+      if (draining.drainingTimeoutSec !== undefined) tree.connectionDrainingTimeoutSec = draining.drainingTimeoutSec;
+      delete tree.connectionDraining;
+    }
+    if (Array.isArray(tree.backends)) {
+      tree.backend = (tree.backends as Array<Record<string, unknown>>).map((b) => {
+        const { group, ...rest } = b;
+        return { ...rest, ...(typeof group === "string" ? { group: refOf(group) } : {}) };
+      });
+      delete tree.backends;
+    }
+    if (Array.isArray(tree.healthChecks)) {
+      tree.healthChecks = (tree.healthChecks as unknown[]).map((h) => (typeof h === "string" ? { healthCheckRef: { name: lastSegment(h) } } : h));
+    }
+    if (typeof tree.securityPolicy === "string") {
+      tree.securityPolicyRef = { name: lastSegment(tree.securityPolicy) };
+      delete tree.securityPolicy;
+    }
+  },
+  ComputeURLMap(tree) {
+    computeLocation(tree);
+    if (typeof tree.defaultService === "string") tree.defaultService = refOf(tree.defaultService);
+    if (Array.isArray(tree.hostRules)) {
+      tree.hostRule = tree.hostRules;
+      delete tree.hostRules;
+    }
+    if (Array.isArray(tree.pathMatchers)) {
+      tree.pathMatcher = (tree.pathMatchers as Array<Record<string, unknown>>).map((m) => {
+        const { defaultService, pathRules, ...rest } = m;
+        return {
+          ...rest,
+          ...(typeof defaultService === "string" ? { defaultService: refOf(defaultService) } : {}),
+          ...(Array.isArray(pathRules)
+            ? {
+                pathRule: (pathRules as Array<Record<string, unknown>>).map(({ service, ...r }) => ({
+                  ...r,
+                  ...(typeof service === "string" ? { service: refOf(service) } : {}),
+                })),
+              }
+            : {}),
+        };
+      });
+      delete tree.pathMatchers;
+    }
+  },
+  ComputeTargetHTTPProxy(tree) {
+    computeLocation(tree);
+    if (typeof tree.urlMap === "string") {
+      tree.urlMapRef = { name: lastSegment(tree.urlMap) };
+      delete tree.urlMap;
+    }
   },
+  ComputeForwardingRule(tree) {
+    computeLocation(tree);
+    if (tree.IPProtocol !== undefined) {
+      tree.ipProtocol = tree.IPProtocol;
+      delete tree.IPProtocol;
+    }
+    if (typeof tree.target === "string") tree.target = refOf(tree.target);
+    if (typeof tree.backendService === "string") {
+      tree.backendServiceRef = { name: lastSegment(tree.backendService) };
+      delete tree.backendService;
+    }
+  },
+};
+
+function lastSegment(url: string): string {
+  return url.slice(url.lastIndexOf("/") + 1);
+}
+
+/** Compute's `region` URL as CNRM's `location`; no region means a global resource. */
+function computeLocation(tree: CnrmTree): void {
+  tree.location = typeof tree.region === "string" ? lastSegment(tree.region) : "global";
+  delete tree.region;
+}
+
+/** The `*Ref` a compute URL names, by its collection (`.../backendServices/web` -> `{ backendServiceRef: { name: "web" } }`). */
+const REF_KEY_BY_COLLECTION: Record<string, string> = {
+  networkEndpointGroups: "networkEndpointGroupRef",
+  backendServices: "backendServiceRef",
+  backendBuckets: "backendBucketRef",
+  targetHttpProxies: "targetHTTPProxyRef",
+  targetHttpsProxies: "targetHTTPSProxyRef",
+  instanceGroups: "instanceGroupRef",
 };
 
+function refOf(url: string): unknown {
+  const parts = url.split("/");
+  const key = REF_KEY_BY_COLLECTION[parts[parts.length - 2] ?? ""];
+  return key ? { [key]: { name: parts[parts.length - 1] } } : url;
+}
+
 /**
  * A REST payload as a CNRM-shaped property tree, in the declared side's
  * vocabulary. The generic reshape runs first, then the full resource path is

package/src/describe-resources.test.ts

@@ -80,7 +80,7 @@ describe("gcp describeResources — direct REST (#1209)", () => {
 
   test("a kind the applier has no mapper for is unsupported-kind, not absent", async () => {
     const out = await read(
-      makeEntities([{ name: "e", entityType: "GCP::Compute::Address", props: { metadata: { name: "addr" } } }]),
+      makeEntities([{ name: "e", entityType: "GCP::Compute::Network", props: { metadata: { name: "net" } } }]),
     );
     expect(out.unobserved?.e?.reason).toBe("unsupported-kind");
     expect(fetchMock).not.toHaveBeenCalled();

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

@@ -5,6 +5,7 @@ import {
   bucketInsertBody,
   pubSubTopicBody,
   cloudRunServiceBody,
+  serviceAccountEmail,
   resolveGcpProject,
   resolveGcpEndpoint,
   applyResource,
@@ -118,6 +119,13 @@ describe("mappers build correct plans (#706)", () => {
 
   test("registry keys match each mapper's kind", () => {
     expect(Object.keys(MAPPERS).sort()).toEqual([
+      "ComputeAddress",
+      "ComputeBackendService",
+      "ComputeForwardingRule",
+      "ComputeRegionNetworkEndpointGroup",
+      "ComputeTargetHTTPProxy",
+      "ComputeURLMap",
+      "IAMPolicyMember",
       "IAMServiceAccount",
       "PubSubSubscription",
       "PubSubTopic",
@@ -136,6 +144,35 @@ describe("Cloud Run mapper + LRO (#706)", () => {
     });
   });
 
+  test("cloudRunServiceBody sends serviceAccountRef as template.serviceAccount (#4240)", () => {
+    const withRef = (ref: Record<string, string>) => ({
+      ...RUN_SERVICE,
+      spec: { ...(RUN_SERVICE.spec as object), template: { containers: [{ image: "gcr.io/x/hello" }], serviceAccountRef: ref } },
+    });
+    expect(cloudRunServiceBody(withRef({ name: "run-sa" }), "p")).toEqual({
+      template: { containers: [{ image: "gcr.io/x/hello" }], serviceAccount: "run-sa@p.iam.gserviceaccount.com" },
+    });
+    expect(cloudRunServiceBody(withRef({ external: "x@other.iam.gserviceaccount.com" }), "p")).toEqual({
+      template: { containers: [{ image: "gcr.io/x/hello" }], serviceAccount: "x@other.iam.gserviceaccount.com" },
+    });
+  });
+
+  test("serviceAccountEmail: external as given or from a path, name in the project", () => {
+    expect(serviceAccountEmail({ external: "projects/o/serviceAccounts/x@o.iam.gserviceaccount.com" })).toBe("x@o.iam.gserviceaccount.com");
+    expect(serviceAccountEmail({ name: "run-sa" }, "p")).toBe("run-sa@p.iam.gserviceaccount.com");
+    expect(serviceAccountEmail(undefined, "p")).toBeUndefined();
+    expect(() => serviceAccountEmail({ name: "run-sa" })).toThrow(/needs a project/);
+  });
+
+  test("RunService plan sends the service account email on create and update", () => {
+    const resource = {
+      ...RUN_SERVICE,
+      spec: { ...(RUN_SERVICE.spec as object), template: { containers: [{ image: "i" }], serviceAccountRef: { name: "run-sa" } } },
+    };
+    const plan = cloudRunServiceMapper.plan(resource, { base: "http://x", project: "p" });
+    expect((plan.create.body as { template: { serviceAccount: string } }).template.serviceAccount).toBe("run-sa@p.iam.gserviceaccount.com");
+  });
+
   test("RunService plan → POST v2 services?serviceId, async operation present", () => {
     const plan = cloudRunServiceMapper.plan(RUN_SERVICE, { base: "http://x", project: "p" });
     expect(plan.getUrl).toBe("http://x/v2/projects/p/locations/us-central1/services/hello-svc");