@intentius/chant-lexicon-gcp 0.124.34 → 0.124.36

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

@@ -0,0 +1,82 @@
+/**
+ * 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 { GcpResource, ResourceMapper } from "./gcp-apply.js";
+/** 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 declare const IAM_DEFAULT_HOST = "https://iam.googleapis.com";
+/**
+ * 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 declare function iamTarget(spec: IamPolicyMemberSpec, project: string, manifest?: readonly GcpResource[], env?: NodeJS.ProcessEnv): IamTarget | undefined;
+/** True when the policy grants the spec's member in its role (and condition). Pure. */
+export declare function policyHasMember(policy: Policy, spec: IamPolicyMemberSpec): boolean;
+/** The policy with the spec's member added to its binding, every other binding kept. Pure. */
+export declare function withMember(policy: Policy, spec: IamPolicyMemberSpec): Policy;
+/** The policy with the spec's member removed; a binding left with no members is dropped. Pure. */
+export declare function withoutMember(policy: Policy, spec: IamPolicyMemberSpec): Policy;
+export declare const iamPolicyMemberMapper: ResourceMapper;
+export {};
+//# sourceMappingURL=gcp-iam.d.ts.map

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/dist/serializer.d.ts

@@ -4,6 +4,7 @@
  * Converts Chant declarables to multi-document K8s YAML output
  * for Config Connector resources with apiVersion, kind, metadata, and spec.
  */
+import type { Declarable } from "@intentius/chant/declarable";
 import type { Serializer } from "@intentius/chant/serializer";
 /**
  * Resolve entityType to apiVersion and kind.
@@ -17,6 +18,11 @@ export declare function resolveGVK(entityType: string): {
     apiVersion: string;
     kind: string;
 } | null;
+/**
+ * The metadata.name a resource is written with: a string `metadata.name` in its
+ * props, else its logical id in kebab case.
+ */
+export declare function cnrmName(logical: string, entity: Declarable): string;
 /**
  * GCP Config Connector YAML serializer implementation.
  */

package/dist/serializer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"serializer.d.ts","sourceRoot":"","sources":["../src/serializer.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,OAAO,KAAK,EAAE,UAAU,EAAsC,MAAM,6BAA6B,CAAC;AAiClG;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAW1F;AAsED;;GAEG;AACH,eAAO,MAAM,aAAa,EAAE,UAiG3B,CAAC"}
+{"version":3,"file":"serializer.d.ts","sourceRoot":"","sources":["../src/serializer.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAE9D,OAAO,KAAK,EAAE,UAAU,EAAsC,MAAM,6BAA6B,CAAC;AAiClG;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAW1F;AA+CD;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,GAAG,MAAM,CAIpE;AA4BD;;GAEG;AACH,eAAO,MAAM,aAAa,EAAE,UAiG3B,CAAC"}

package/dist/serializer.js

@@ -62,15 +62,15 @@ function deriveGVKFromType(entityType) {
  * GCP visitor for the generic serializer walker.
  */
 function gcpVisitor(entityNames) {
+    // Config Connector resolves a `*Ref: { name }` by the target's metadata.name,
+    // which is its declared name or else the kebab-cased logical id (#4242).
+    const cnrmNames = new Map();
+    for (const [entity, logical] of entityNames)
+        cnrmNames.set(logical, cnrmName(logical, entity));
+    const resolve = (logical) => cnrmNames.get(logical) ?? logical;
     return {
-        attrRef: (name, _attr) => {
-            // For Config Connector, references resolve to metadata.name
-            return name;
-        },
-        resourceRef: (name) => {
-            // Config Connector uses resourceRef pattern: { name: "resource-name" }
-            return { name };
-        },
+        attrRef: (name, _attr) => resolve(name),
+        resourceRef: (name) => ({ name: resolve(name) }),
         propertyDeclarable: (entity, walk) => {
             if (!isResourceDeclarable(entity) || typeof entity.props !== "object" || entity.props === null) {
                 return undefined;
@@ -86,6 +86,18 @@ function gcpVisitor(entityNames) {
         },
     };
 }
+/**
+ * The metadata.name a resource is written with: a string `metadata.name` in its
+ * props, else its logical id in kebab case.
+ */
+export function cnrmName(logical, entity) {
+    const props = isResourceDeclarable(entity) ? entity.props : undefined;
+    const declared = props?.metadata?.name;
+    return typeof declared === "string" && declared.length > 0 ? declared : kebabName(logical);
+}
+function kebabName(logical) {
+    return logical.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
+}
 /**
  * Convert a value to YAML-compatible form using the walker.
  */
@@ -152,7 +164,7 @@ export const gcpSerializer = {
             // Build metadata
             const metadata = props.metadata ?? {};
             if (!metadata.name) {
-                metadata.name = name.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
+                metadata.name = kebabName(name);
             }
             // Merge default labels
             if (Object.keys(defaultLabelEntries).length > 0) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-gcp",
-  "version": "0.124.34",
+  "version": "0.124.36",
   "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.36"
   }
 }

package/src/api/read-client.ts

@@ -22,7 +22,12 @@
  *
  * 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), and
+ * ComputeNetwork and ComputeSubnetwork (#4248). 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 +49,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 +108,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,47 @@ 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("run service: vpcAccess network and subnetwork paths map back to refs (#4249)", () => {
+    const tree = toCnrmTree(
+      "RunService",
+      {
+        name: "projects/my-project/locations/europe-west1/services/web",
+        template: {
+          vpcAccess: {
+            egress: "PRIVATE_RANGES_ONLY",
+            networkInterfaces: [
+              { network: "projects/my-project/global/networks/vpc", subnetwork: "projects/my-project/regions/europe-west1/subnetworks/apps" },
+              { network: "projects/other/global/networks/shared", subnetwork: "apps" },
+            ],
+          },
+        },
+      },
+      ctx,
+    ) as { template: { vpcAccess: unknown } };
+    expect(tree.template.vpcAccess).toEqual({
+      egress: "PRIVATE_RANGES_ONLY",
+      networkInterfaces: [
+        { networkRef: { name: "vpc" }, subnetworkRef: { name: "apps" } },
+        { networkRef: { external: "projects/other/global/networks/shared" }, subnetworkRef: { name: "apps" } },
+      ],
+    });
+  });
+
   test("bucket: GCS's iamConfiguration and lifecycle map onto the CNRM field names", () => {
     const tree = toCnrmTree(
       "StorageBucket",
@@ -235,7 +276,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::Firewall", { metadata: { name: "n" } }]]));
     expect(out.unobserved?.e?.reason).toBe("unsupported-kind");
     expect(fetchMock).not.toHaveBeenCalled();
   });