@microagi/alchemy-gcp 0.1.4 → 0.2.0

package/src/CloudResourceManager/Project.ts

@@ -21,6 +21,23 @@ export type ProjectParent =
   | { type: "folder"; id: string }
   | { type: "organization"; id: string };
 
+/**
+ * Single (role, members) entry on a Project's IAM policy. Targets
+ * declare this contract so capabilities can `.bind` IAM grants onto
+ * the project — the provider's `reconcile` merges all bound entries
+ * by role into a single `setIamPolicy` call.
+ */
+export type ProjectIamBinding = {
+  /** IAM role, e.g. `"roles/container.hostServiceAgentUser"`. */
+  role: string;
+  /** Principals, e.g. `["serviceAccount:foo@bar.iam.gserviceaccount.com"]`. */
+  members: ReadonlyArray<string>;
+};
+
+export type ProjectBindingContract = {
+  iamBindings: ReadonlyArray<ProjectIamBinding>;
+};
+
 export type ProjectProps = {
   /**
    * Globally-unique project ID. 6-30 lowercase letters/digits/hyphens,
@@ -153,7 +170,7 @@ export type Project = Resource<
      */
     billingEnabled: boolean;
   },
-  never,
+  ProjectBindingContract,
   GCP.Providers
 >;
 
@@ -208,6 +225,8 @@ export const ProjectProvider = () =>
       const patchProjects = yield* crm.patchProjects;
       const deleteProjects = yield* crm.deleteProjects;
       const getOperations = yield* crm.getOperations;
+      const getIamPolicy = yield* crm.getIamPolicyProjects;
+      const setIamPolicy = yield* crm.setIamPolicyProjects;
       const getBillingInfo = yield* billing.getBillingInfoProjects;
       const updateBillingInfo = yield* billing.updateBillingInfoProjects;
 
@@ -393,6 +412,67 @@ export const ProjectProvider = () =>
         );
       });
 
+      // Apply merged IAM bindings as a single setIamPolicy. Bindings
+      // are unioned per role (multiple `.bind` callers sharing a role
+      // get their members combined). Foreign bindings on the policy
+      // (non-alchemy roles, or members we don't manage on the same
+      // role) are preserved verbatim. Etag round-trip handles
+      // concurrent edits; Conflict triggers a re-read + retry.
+      const syncIam = (args: {
+        projectId: string;
+        bindings: ReadonlyArray<
+          import("alchemy/Resource").ResourceBinding<ProjectBindingContract>
+        >;
+      }) =>
+        Effect.gen(function* () {
+          const desiredByRole = new Map<string, Set<string>>();
+          for (const b of args.bindings) {
+            for (const ib of b.data.iamBindings) {
+              const set = desiredByRole.get(ib.role) ?? new Set<string>();
+              for (const m of ib.members) set.add(m);
+              desiredByRole.set(ib.role, set);
+            }
+          }
+          if (desiredByRole.size === 0) return;
+
+          const current = yield* getIamPolicy({
+            resource: `projects/${args.projectId}`,
+            body: { options: { requestedPolicyVersion: 3 } },
+          });
+
+          const existingBindings = (current.bindings ?? []).map((b) => ({
+            ...b,
+            members: [...(b.members ?? [])],
+          }));
+          let mutated = false;
+          for (const [role, members] of desiredByRole) {
+            let existing = existingBindings.find(
+              (b) => b.role === role && !b.condition,
+            );
+            if (!existing) {
+              existing = { role, members: [] };
+              existingBindings.push(existing);
+            }
+            const merged = new Set([...(existing.members ?? []), ...members]);
+            if (merged.size !== (existing.members?.length ?? 0)) mutated = true;
+            existing.members = [...merged];
+          }
+          if (!mutated) return;
+
+          yield* setIamPolicy({
+            resource: `projects/${args.projectId}`,
+            body: {
+              policy: { ...current, bindings: existingBindings, version: 3 },
+            },
+          });
+        }).pipe(
+          Effect.retry({
+            schedule: Schedule.exponential(Duration.seconds(2)).pipe(
+              Schedule.both(Schedule.recurs(8)),
+            ),
+          }),
+        );
+
       return {
         stables: ["projectId", "projectNumber", "name"],
         diff: Effect.fn(function* ({ id, news, olds = {}, output }) {
@@ -410,7 +490,7 @@ export const ProjectProvider = () =>
             return { action: "replace" } as const;
           }
         }),
-        reconcile: Effect.fn(function* ({ id, news, session }) {
+        reconcile: Effect.fn(function* ({ id, news, session, bindings }) {
           const projectId = yield* createProjectId(id, news.projectId);
           const parent = parentToString(news.parent);
           const internalLabels = yield* gcpInternalLabels(id);
@@ -471,6 +551,14 @@ export const ProjectProvider = () =>
             news.billingAccount,
           );
 
+          // 5. Sync IAM bindings (host-side IAM grants etc). Single
+          //    setIamPolicy with merged bindings; foreign roles
+          //    preserved. Etag-retried internally.
+          yield* syncIam({
+            projectId: synced.projectId!,
+            bindings,
+          });
+
           return toAttributes(synced, finalBilling);
         }),
         delete: Effect.fn(function* ({ output, session }) {

package/src/CloudResourceManager/ProjectIamMember.ts

@@ -0,0 +1,29 @@
+import * as Effect from "effect/Effect";
+import type { Project } from "./Project.ts";
+
+/**
+ * Bind a single `(role, member)` IAM grant onto a {@link Project}.
+ *
+ * Target-side binding — see
+ * {@link import("../Compute/SubnetworkIamMember.ts").subnetworkIamMember}
+ * for the pattern, the SID-collision pitfall, and why `key` exists.
+ * Project's `reconcile` merges all bindings into a single
+ * `setIamPolicy` against the project, preserving foreign roles +
+ * members.
+ *
+ * @example Granting GKE service agent host-service-agent-user on a Shared VPC host
+ * ```typescript
+ * yield* GCP.projectIamMember(hostProject, "ClusterA-HostSvcAgent", {
+ *   role: "roles/container.hostServiceAgentUser",
+ *   member: gkeAgentMember,
+ * });
+ * ```
+ */
+export const projectIamMember = (
+  project: Project,
+  key: string,
+  args: { role: string; member: string },
+): Effect.Effect<void> =>
+  project.bind`IamMember(${project}, ${key})`({
+    iamBindings: [{ role: args.role, members: [args.member] }],
+  }) as unknown as Effect.Effect<void>;

package/src/CloudResourceManager/index.ts

@@ -1,2 +1,3 @@
 export { Project, ProjectProvider } from "./Project.ts";
 export type { ProjectParent, ProjectProps } from "./Project.ts";
+export * from "./ProjectIamMember.ts";

package/src/Compute/Network.ts

@@ -15,6 +15,15 @@ import {
 import type * as GCP from "../Providers.ts";
 import { makeAwaitGlobalOperation } from "./Operations.ts";
 
+// Distinct nominal brands keep `NetworkRef` and `NetworkRefById`
+// mutually unassignable even though their underlying template-literal
+// shapes overlap. The brand symbols are `declare`-only — never present
+// at runtime — and only the constructor functions below mint values
+// carrying them, so a caller cannot bypass the type by hand-crafting a
+// raw string and asserting it.
+declare const _networkRefByNumberBrand: unique symbol;
+declare const _networkRefByIdBrand: unique symbol;
+
 /**
  * Fully-qualified VPC reference in **project-number** form:
  * `projects/{projectNumber}/global/networks/{name}`.
@@ -33,9 +42,32 @@ import { makeAwaitGlobalOperation } from "./Operations.ts";
  *
  * `Project.projectNumber` is typed as `` `${number}` `` precisely so
  * this template literal type composes without a runtime coercion at
- * the call site.
+ * the call site. The nominal brand prevents a `NetworkRefById` from
+ * being passed where this is expected and vice versa — see
+ * {@link NetworkRefById}.
  */
-export type NetworkRef = `projects/${number}/global/networks/${string}`;
+export type NetworkRef = `projects/${number}/global/networks/${string}` & {
+  readonly [_networkRefByNumberBrand]: true;
+};
+
+/**
+ * Fully-qualified VPC reference in **project-ID** form:
+ * `projects/{projectId}/global/networks/{name}`.
+ *
+ * Required by Managed Lustre's `instances.create` (and any future GCP
+ * API that explicitly rejects the project-number form). Build with
+ * {@link networkRefById}.
+ *
+ * Note: project-ID form is in some places interchangeable with
+ * project-number form (the SDK accepts either for compute / GKE), but
+ * Managed Lustre's API validates the path segment shape and refuses
+ * numeric ids — without this distinct branded type, a stack would
+ * compile fine and only fail at deploy time with `BadRequest: Valid
+ * format: projects/{project_id}/global/networks/{network_id}`.
+ */
+export type NetworkRefById = `projects/${string}/global/networks/${string}` & {
+  readonly [_networkRefByIdBrand]: true;
+};
 
 /**
  * Build a project-number-form `NetworkRef`. Lifted through `Output`
@@ -58,10 +90,31 @@ export const networkRef = (
     Output.asOutput(networkName),
   ).pipe(
     Output.map(
-      ([num, name]) =>
-        `projects/${num}/global/networks/${name}` as NetworkRef,
+      ([num, name]) => `projects/${num}/global/networks/${name}`,
     ),
-  );
+  ) as unknown as Output.Output<NetworkRef>;
+
+/**
+ * Build a project-ID-form `NetworkRefById`. Use for APIs that require
+ * the project-ID path segment — Managed Lustre is the current example.
+ *
+ * Pass `Project.projectId` (an `Output<string>`) plus `Network.name`.
+ * Plain literal arguments work too: `networkRefById("research-shared",
+ * "main")`. The branded return type prevents the value from being
+ * confused with a project-number-form {@link NetworkRef} at any call
+ * site downstream — even though their string shapes happen to coincide
+ * for numeric ids.
+ */
+export const networkRefById = (
+  projectId: string | Output.Output<string>,
+  networkName: string | Output.Output<string>,
+): Output.Output<NetworkRefById> =>
+  Output.all(
+    Output.asOutput(projectId),
+    Output.asOutput(networkName),
+  ).pipe(
+    Output.map(([id, name]) => `projects/${id}/global/networks/${name}`),
+  ) as unknown as Output.Output<NetworkRefById>;
 
 /**
  * A VPC Network in custom-mode (`autoCreateSubnetworks=false`). Auto-mode

package/src/Compute/SharedVpcServiceProject.ts

@@ -76,7 +76,12 @@ export const SharedVpcServiceProjectProvider = () =>
       // empty fields instead, so we coalesce both.
       const observeHost = (serviceProject: string) =>
         getXpnHostProjects({ project: serviceProject }).pipe(
-          Effect.map((p) => p.name ?? p.id ?? undefined),
+          // Three "not attached" shapes observed:
+          //   - 404 NotFound (catchTag below)
+          //   - 200 with a `Project` whose name/id are empty
+          //   - 200 with an undefined body (no Project payload at all)
+          // Coalesce all three to `undefined`.
+          Effect.map((p) => p?.name ?? p?.id ?? undefined),
           Effect.catchTag("NotFound", () =>
             Effect.succeed(undefined as string | undefined),
           ),

package/src/Compute/Subnetwork.ts

@@ -5,7 +5,10 @@ import type { ScopedPlanStatusSession } from "alchemy/Cli/Cli";
 import { deepEqual, isResolved, somePropsAreDifferent } from "alchemy/Diff";
 import { createPhysicalName } from "alchemy/PhysicalName";
 import * as Provider from "alchemy/Provider";
+import type { ResourceBinding } from "alchemy/Resource";
+import * as Duration from "effect/Duration";
 import * as Effect from "effect/Effect";
+import * as Schedule from "effect/Schedule";
 import {
   descriptionHasAlchemyMarker,
   gcpAlchemyDescription,
@@ -118,11 +121,28 @@ export type SubnetworkAttributes = {
   gatewayAddress: string | undefined;
 };
 
+/**
+ * Single (role, members) entry on a Subnetwork's IAM policy. Targets
+ * declare this contract so capabilities can `.bind` IAM grants onto
+ * the subnet — the provider's `reconcile` merges all bound entries
+ * by role into a single `setIamPolicy` call.
+ */
+export type SubnetworkIamBinding = {
+  /** IAM role, e.g. `"roles/compute.networkUser"`. */
+  role: string;
+  /** Principals, e.g. `["serviceAccount:foo@bar.iam.gserviceaccount.com"]`. */
+  members: ReadonlyArray<string>;
+};
+
+export type SubnetworkBindingContract = {
+  iamBindings: ReadonlyArray<SubnetworkIamBinding>;
+};
+
 export type Subnetwork = Resource<
   "GCP.Subnetwork",
   SubnetworkProps,
   SubnetworkAttributes,
-  never,
+  SubnetworkBindingContract,
   GCP.Providers
 >;
 export const Subnetwork = Resource<Subnetwork>("GCP.Subnetwork");
@@ -164,8 +184,82 @@ export const SubnetworkProvider = () =>
       const deleteSubnetworks = yield* compute.deleteSubnetworks;
       const expandIpCidrRange = yield* compute.expandIpCidrRangeSubnetworks;
       const getRegionOperations = yield* compute.getRegionOperations;
+      const getIamPolicy = yield* compute.getIamPolicySubnetworks;
+      const setIamPolicy = yield* compute.setIamPolicySubnetworks;
       const awaitOp = makeAwaitRegionOperation(getRegionOperations);
 
+      // Apply merged IAM bindings as a single setIamPolicy. Bindings
+      // are unioned per role (multiple `.bind` callers sharing a role
+      // get their members combined). Foreign bindings on the policy
+      // (non-alchemy roles, or members we don't manage in this role)
+      // are preserved verbatim. Etag round-trip handles concurrent
+      // edits; Conflict triggers a re-read + retry.
+      const syncIam = (args: {
+        project: string;
+        region: string;
+        name: string;
+        bindings: ReadonlyArray<ResourceBinding<SubnetworkBindingContract>>;
+      }) =>
+        Effect.gen(function* () {
+          // Union all incoming binds by role.
+          const desiredByRole = new Map<string, Set<string>>();
+          for (const b of args.bindings) {
+            for (const ib of b.data.iamBindings) {
+              const set = desiredByRole.get(ib.role) ?? new Set<string>();
+              for (const m of ib.members) set.add(m);
+              desiredByRole.set(ib.role, set);
+            }
+          }
+          if (desiredByRole.size === 0) return;
+
+          const current = yield* getIamPolicy({
+            project: args.project,
+            region: args.region,
+            resource: args.name,
+            optionsRequestedPolicyVersion: 3,
+          });
+
+          // Take the current policy verbatim, then for each role we
+          // manage, union desired members into the existing binding (or
+          // create one). This preserves foreign roles and any extra
+          // members on the same role that we don't know about.
+          const bindings = (current.bindings ?? []).map((b) => ({
+            ...b,
+            members: [...(b.members ?? [])],
+          }));
+          let mutated = false;
+          for (const [role, members] of desiredByRole) {
+            let existing = bindings.find(
+              (b) => b.role === role && !b.condition,
+            );
+            if (!existing) {
+              existing = { role, members: [] };
+              bindings.push(existing);
+            }
+            const merged = new Set([...(existing.members ?? []), ...members]);
+            if (merged.size !== (existing.members?.length ?? 0)) mutated = true;
+            existing.members = [...merged];
+          }
+          if (!mutated) return;
+
+          yield* setIamPolicy({
+            project: args.project,
+            region: args.region,
+            resource: args.name,
+            body: { policy: { ...current, bindings, version: 3 } },
+          });
+        }).pipe(
+          // setIamPolicy returns Conflict on etag race. Re-read + retry.
+          // With multiple subnets/projects in a stack each receiving
+          // multiple bindings in parallel, races are common. Cap at
+          // ~1.5 min total to surface real failures.
+          Effect.retry({
+            schedule: Schedule.exponential(Duration.seconds(2)).pipe(
+              Schedule.both(Schedule.recurs(8)),
+            ),
+          }),
+        );
+
       const observe = (project: string, region: string, name: string) =>
         getSubnetworks({ project, region, subnetwork: name }).pipe(
           Effect.catchTag("NotFound", () =>
@@ -265,7 +359,7 @@ export const SubnetworkProvider = () =>
           }
           return undefined;
         }),
-        reconcile: Effect.fn(function* ({ id, news, session }) {
+        reconcile: Effect.fn(function* ({ id, news, session, bindings }) {
           const desiredName =
             news.name ??
             (yield* createPhysicalName({ id, maxLength: 63 })).toLowerCase();
@@ -331,6 +425,15 @@ export const SubnetworkProvider = () =>
             session,
           });
 
+          // Apply IAM bindings AFTER the subnet exists. Single
+          // setIamPolicy call covers all bindings for this subnet.
+          yield* syncIam({
+            project: news.project,
+            region: news.region,
+            name: desiredName,
+            bindings,
+          });
+
           const final = yield* getSubnetworks({
             project: news.project,
             region: news.region,

package/src/Compute/SubnetworkIamMember.ts

@@ -0,0 +1,52 @@
+import * as Effect from "effect/Effect";
+import type { Subnetwork } from "./Subnetwork.ts";
+
+/**
+ * Bind a single `(role, member)` IAM grant onto a {@link Subnetwork}.
+ *
+ * This is a **target-side binding** — it records the grant onto the
+ * subnet's binding bag (`stack.bindings[subnet]`); the Subnetwork
+ * provider's `reconcile` later merges all such bindings (across all
+ * callers, including parallel ones from different cluster projects)
+ * into a single `setIamPolicy` call on the subnet.
+ *
+ * Identity for dedup: the rendered SID is `IamMember(<subnet>, <key>)`.
+ * The engine collapses binds by SID, so callers MUST supply a
+ * stack-unique `key` per (subnet, role, member) triple — otherwise a
+ * later bind silently overwrites an earlier one with the same key.
+ *
+ * The reason `key` exists: `member` is usually an `Output<string>`
+ * (e.g. `Output.interpolate\`...${proj.projectNumber}...\``), and
+ * `Output` expressions stringify by their AST shape, not by the
+ * eventual value. Two interpolations of the same shape but different
+ * literal templates render the same SID. `key` sidesteps that by
+ * forcing a static, caller-supplied label into the SID.
+ *
+ * Use this for the "Pulumi `gcp.compute.SubnetworkIAMMember`" pattern:
+ * authoritative-for-(role, member)-tuple, additive (does not displace
+ * other members on the same role).
+ *
+ * @example Granting GKE Standard cluster networkUser on a Shared VPC subnet
+ * ```typescript
+ * yield* GCP.subnetworkIamMember(subnet, "ClusterA-GkeAgent", {
+ *   role: "roles/compute.networkUser",
+ *   member: gkeAgentMember,
+ * });
+ * yield* GCP.subnetworkIamMember(subnet, "ClusterA-CloudSvc", {
+ *   role: "roles/compute.networkUser",
+ *   member: cloudServicesMember,
+ * });
+ * // → one setIamPolicy on `subnet` with both members under networkUser.
+ * ```
+ */
+export const subnetworkIamMember = (
+  subnet: Subnetwork,
+  key: string,
+  args: { role: string; member: string },
+): Effect.Effect<void> =>
+  // Tagged-template `.bind` records into the target's binding bag.
+  // Subnetwork's reconcile sees `bindings: ResourceBinding<…>[]` and
+  // merges all entries by role into one setIamPolicy call.
+  subnet.bind`IamMember(${subnet}, ${key})`({
+    iamBindings: [{ role: args.role, members: [args.member] }],
+  }) as unknown as Effect.Effect<void>;

package/src/Compute/index.ts

@@ -3,3 +3,4 @@ export * from "./Network.ts";
 export * from "./SharedVpcHost.ts";
 export * from "./SharedVpcServiceProject.ts";
 export * from "./Subnetwork.ts";
+export * from "./SubnetworkIamMember.ts";