@microagi/alchemy-gcp 0.5.1 → 0.7.0

package/src/Compute/ForwardingRule.ts

@@ -0,0 +1,301 @@
+import * as compute from "@distilled.cloud/gcp/compute-v1";
+import { Resource } from "alchemy";
+import { Unowned } from "alchemy/AdoptPolicy";
+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 * as Effect from "effect/Effect";
+import { gcpInternalLabels, hasAlchemyLabels } from "../Tags.ts";
+import type * as GCP from "../Providers.ts";
+import { makeAwaitRegionOperation } from "./Operations.ts";
+
+/**
+ * A regional forwarding rule. The intended use here is a **Private
+ * Service Connect consumer endpoint** — binding a reserved internal
+ * {@link Address} to a producer *service attachment* (e.g. the one
+ * Cloud SQL publishes per PSC-enabled instance), so clients in this
+ * VPC reach the producer service at that IP.
+ *
+ * PSC endpoint rules carry no ports / load-balancing scheme — the API
+ * requires `loadBalancingScheme: ""` for them, which is what this
+ * resource sends. The endpoint must be created in the **same region as
+ * the service attachment**; set `allowPscGlobalAccess` so clients in
+ * other regions of the VPC can still use it.
+ *
+ * Other forwarding-rule shapes (L4 ILB, NetLB, proxy LBs) are not
+ * modelled — add props if/when needed.
+ *
+ * All connection-defining props are immutable here and trigger replace;
+ * a PSC endpoint is cheap to recreate. Labels are mutable.
+ *
+ * @section Creating a PSC endpoint
+ * @example Cloud SQL PSC endpoint with global access
+ * ```typescript
+ * const endpoint = yield* GCP.ForwardingRule("DbPscEndpoint", {
+ *   project: hostProject.projectId,
+ *   region: "europe-west1",
+ *   network: vpc.selfLink,
+ *   ipAddress: endpointIp.selfLink,
+ *   target: "projects/<producer>/regions/europe-west1/serviceAttachments/<sa>",
+ *   allowPscGlobalAccess: true,
+ * });
+ * ```
+ */
+export type ForwardingRuleProps = {
+  /** GCP project ID hosting the rule. Immutable — replace if changed. */
+  project: string;
+  /** GCP region. Must match the target service attachment's region. Immutable — replace. */
+  region: string;
+  /**
+   * Rule name. Defaults to `createPhysicalName({ id, lowercase: true,
+   * maxLength: 63 })`. Immutable — replace if changed.
+   */
+  name?: string;
+  /** Description (free-form). Set on create; immutable. */
+  description?: string;
+  /**
+   * URL of the consumer VPC. Pass `vpc.selfLink` from a `GCP.Network`
+   * to make alchemy sequence the rule after the VPC. Immutable — replace.
+   */
+  network: string;
+  /**
+   * The endpoint IP — a URL of a reserved `GCP.Address` (pass
+   * `address.selfLink` for the dep edge) or a literal IP. Immutable —
+   * replace.
+   */
+  ipAddress: string;
+  /**
+   * URI of the producer service attachment to connect to
+   * (`projects/{p}/regions/{r}/serviceAttachments/{name}`). Immutable —
+   * replace.
+   */
+  target: string;
+  /**
+   * Let clients in any region of the VPC use this endpoint (PSC global
+   * access). Defaults to `false`. Immutable — replace.
+   */
+  allowPscGlobalAccess?: boolean;
+  /**
+   * Resource labels. Alchemy internal labels (`alchemy_app`,
+   * `alchemy_stage`, `alchemy_id`) are merged on top automatically and
+   * are reserved. Mutable via `setLabels`.
+   */
+  labels?: Record<string, string>;
+};
+
+export type ForwardingRuleAttributes = {
+  /** Rule name. */
+  name: string;
+  /** GCP project ID, threaded through from props for delete/read. */
+  project: string;
+  /** GCP region, threaded through from props for delete/read. */
+  region: string;
+  /** Server-defined URL. */
+  selfLink: string;
+  /** Server-assigned numeric id. */
+  id: string;
+  /** The endpoint IP (the API always returns the literal IP). */
+  ipAddress: string;
+  /** Producer service attachment URI. */
+  target: string | undefined;
+  /** Consumer VPC URL. */
+  network: string | undefined;
+  /** PSC global access flag. */
+  allowPscGlobalAccess: boolean;
+  /** Server-assigned PSC connection id. */
+  pscConnectionId: string | undefined;
+  /** PSC connection status: `ACCEPTED`, `PENDING`, `REJECTED`, `CLOSED`, … */
+  pscConnectionStatus: string | undefined;
+  /** Labels currently set, including the alchemy internals. */
+  labels: Record<string, string>;
+};
+
+export type ForwardingRule = Resource<
+  "GCP.ForwardingRule",
+  ForwardingRuleProps,
+  ForwardingRuleAttributes,
+  never,
+  GCP.Providers
+>;
+export const ForwardingRule = Resource<ForwardingRule>("GCP.ForwardingRule");
+
+const toForwardingRuleAttributes = (
+  f: compute.ForwardingRule,
+  parent: { project: string; region: string },
+): ForwardingRuleAttributes => ({
+  name: f.name ?? "",
+  project: parent.project,
+  region: parent.region,
+  selfLink: f.selfLink ?? "",
+  id: f.id ?? "",
+  ipAddress: f.IPAddress ?? "",
+  target: f.target,
+  network: f.network,
+  allowPscGlobalAccess: f.allowPscGlobalAccess ?? false,
+  pscConnectionId: f.pscConnectionId,
+  pscConnectionStatus: f.pscConnectionStatus,
+  labels: { ...(f.labels ?? {}) },
+});
+
+export const ForwardingRuleProvider = () =>
+  Provider.effect(
+    ForwardingRule,
+    Effect.gen(function* () {
+      const getForwardingRules = yield* compute.getForwardingRules;
+      const insertForwardingRules = yield* compute.insertForwardingRules;
+      const deleteForwardingRules = yield* compute.deleteForwardingRules;
+      const setLabelsForwardingRules = yield* compute.setLabelsForwardingRules;
+      const getRegionOperations = yield* compute.getRegionOperations;
+      const awaitOp = makeAwaitRegionOperation(getRegionOperations);
+
+      const observe = (project: string, region: string, name: string) =>
+        getForwardingRules({ project, region, forwardingRule: name }).pipe(
+          Effect.catchTag("NotFound", () =>
+            Effect.succeed(undefined as compute.ForwardingRule | undefined),
+          ),
+          Effect.catchTag("Forbidden", () =>
+            Effect.succeed(undefined as compute.ForwardingRule | undefined),
+          ),
+        );
+
+      const syncLabels = Effect.fn(function* (args: {
+        project: string;
+        region: string;
+        observed: compute.ForwardingRule;
+        desired: Record<string, string>;
+        session: ScopedPlanStatusSession;
+      }) {
+        if (deepEqual(args.observed.labels ?? {}, args.desired)) return;
+        const op = yield* setLabelsForwardingRules({
+          project: args.project,
+          region: args.region,
+          resource: args.observed.name ?? "",
+          body: {
+            labels: args.desired,
+            labelFingerprint: args.observed.labelFingerprint,
+          },
+        });
+        if (op.name) {
+          yield* awaitOp(args.project, args.region, op.name, args.session);
+        }
+      });
+
+      return {
+        stables: ["name", "project", "region", "selfLink", "id"],
+        diff: Effect.fn(function* ({ news, olds = {} }) {
+          if (!isResolved(news)) return undefined;
+          if (
+            somePropsAreDifferent(olds as ForwardingRuleProps, news, [
+              "project",
+              "region",
+              "name",
+              "network",
+              "ipAddress",
+              "target",
+              "allowPscGlobalAccess",
+            ])
+          ) {
+            return { action: "replace" } as const;
+          }
+          return undefined;
+        }),
+        reconcile: Effect.fn(function* ({ id, news, session }) {
+          const internalLabels = yield* gcpInternalLabels(id);
+          const desiredName =
+            news.name ??
+            (yield* createPhysicalName({ id, maxLength: 63 })).toLowerCase();
+          const desiredLabels: Record<string, string> = {
+            ...(news.labels ?? {}),
+            ...internalLabels,
+          };
+
+          let observed = yield* observe(news.project, news.region, desiredName);
+
+          if (!observed) {
+            const body: compute.ForwardingRule = {
+              name: desiredName,
+              ...(news.description ? { description: news.description } : {}),
+              network: news.network,
+              IPAddress: news.ipAddress,
+              target: news.target,
+              // PSC consumer endpoints take no scheme — the API rejects
+              // anything other than the empty string for them.
+              loadBalancingScheme: "",
+              ...(news.allowPscGlobalAccess !== undefined
+                ? { allowPscGlobalAccess: news.allowPscGlobalAccess }
+                : {}),
+              labels: desiredLabels,
+            };
+            const op = yield* insertForwardingRules({
+              project: news.project,
+              region: news.region,
+              body,
+            }).pipe(
+              Effect.catchTag("Conflict", () =>
+                Effect.succeed(undefined as compute.Operation | undefined),
+              ),
+            );
+            if (op?.name) {
+              yield* awaitOp(news.project, news.region, op.name, session);
+            }
+            observed = yield* getForwardingRules({
+              project: news.project,
+              region: news.region,
+              forwardingRule: desiredName,
+            });
+          }
+
+          yield* syncLabels({
+            project: news.project,
+            region: news.region,
+            observed,
+            desired: desiredLabels,
+            session,
+          });
+
+          const final = yield* getForwardingRules({
+            project: news.project,
+            region: news.region,
+            forwardingRule: desiredName,
+          });
+          return toForwardingRuleAttributes(final, {
+            project: news.project,
+            region: news.region,
+          });
+        }),
+        delete: Effect.fn(function* ({ output, session }) {
+          yield* deleteForwardingRules({
+            project: output.project,
+            region: output.region,
+            forwardingRule: output.name,
+          }).pipe(
+            Effect.flatMap((op) =>
+              op.name
+                ? awaitOp(output.project, output.region, op.name, session)
+                : Effect.succeed(op),
+            ),
+            Effect.catchTag("NotFound", () => Effect.void),
+          );
+        }),
+        read: Effect.fn(function* ({ id, output, olds }) {
+          const project = output?.project ?? olds?.project;
+          const region = output?.region ?? olds?.region;
+          if (!project || !region) return undefined;
+          const name =
+            output?.name ??
+            olds?.name ??
+            (yield* createPhysicalName({ id, maxLength: 63 })).toLowerCase();
+          const observed = yield* observe(project, region, name);
+          if (!observed) return undefined;
+          const attrs = toForwardingRuleAttributes(observed, {
+            project,
+            region,
+          });
+          return (yield* hasAlchemyLabels(id, observed.labels))
+            ? attrs
+            : Unowned(attrs);
+        }),
+      };
+    }),
+  );

package/src/Compute/index.ts

@@ -1,3 +1,6 @@
+export * from "./Address.ts";
+export * from "./Firewall.ts";
+export * from "./ForwardingRule.ts";
 export * from "./GlobalAddress.ts";
 export * from "./Network.ts";
 export * from "./SharedVpcHost.ts";

package/src/Container/Cluster.ts

@@ -74,6 +74,26 @@ export type ClusterProps = {
     clusterSecondaryRangeName?: string;
     servicesSecondaryRangeName?: string;
   };
+  /**
+   * Cluster-level network settings. `datapathProvider:
+   * "ADVANCED_DATAPATH"` enables GKE Dataplane V2 (eBPF/Cilium
+   * dataplane with built-in NetworkPolicy enforcement). GKE only
+   * honors this at cluster creation — existing clusters cannot be
+   * migrated in place.
+   *
+   * **Consumed only on the create path** (like `initialNodePool`):
+   * changing it on an existing cluster is a silent no-op, NOT a
+   * replace trigger. A diff-driven same-name replace would be
+   * destructive here — the engine creates the new generation first,
+   * which observe-adopts the still-existing same-name cluster, and
+   * end-of-deploy GC would then delete that physical cluster out from
+   * under the "new" generation. To rebuild with a different datapath,
+   * delete the cluster out-of-band and redeploy; reconcile observes
+   * it missing and creates with the new setting.
+   */
+  networkConfig?: {
+    datapathProvider?: "LEGACY_DATAPATH" | "ADVANCED_DATAPATH";
+  };
   /** GKE release channel. Mutable via `update` (`desiredReleaseChannel`). */
   releaseChannel?: { channel: "RAPID" | "REGULAR" | "STABLE" | "UNSPECIFIED" };
   /**
@@ -470,8 +490,10 @@ export const ClusterProvider = () =>
           if (!deepEqual(olds.ipAllocationPolicy, news.ipAllocationPolicy)) {
             return { action: "replace" } as const;
           }
-          // `initialNodePool` is intentionally NOT part of diff — it is
-          // consumed only on create. See ClusterProps JSDoc.
+          // `initialNodePool` and `networkConfig` are intentionally NOT
+          // part of diff — both are consumed only on create. See the
+          // ClusterProps JSDoc (networkConfig explains why a same-name
+          // replace would be destructive).
           return undefined;
         }),
         reconcile: Effect.fn(function* ({ id, news, session }) {
@@ -521,6 +543,7 @@ export const ClusterProvider = () =>
                   ...(news.ipAllocationPolicy
                     ? { ipAllocationPolicy: news.ipAllocationPolicy }
                     : {}),
+                  ...(news.networkConfig ? { networkConfig: news.networkConfig } : {}),
                   ...(news.releaseChannel ? { releaseChannel: news.releaseChannel } : {}),
                   ...(news.workloadIdentityConfig
                     ? { workloadIdentityConfig: news.workloadIdentityConfig }

package/src/Container/NodePool.ts

@@ -113,8 +113,31 @@ export type NodePoolProps = {
       enableSecureBoot?: boolean;
       enableIntegrityMonitoring?: boolean;
     };
-    /** Local SSDs. **Replace-only**. */
+    /**
+     * Local SSDs via the legacy SCSI-era count field. Prefer
+     * `localNvmeSsdBlockConfig` / `ephemeralStorageLocalSsdConfig` for
+     * NVMe-only machine families (Gen3+, Titanium SSD). Mutually
+     * exclusive with both. **Replace-only**.
+     */
     localSsdCount?: number;
+    /**
+     * Raw-block local NVMe SSDs — exposed to workloads as unformatted
+     * block devices (local PVs / your own RAID). For machine types with
+     * a fixed disk count (e.g. g4-standard-48 → 4), `localSsdCount`
+     * must equal that count or be 0/unset for the machine default.
+     * **Replace-only**.
+     */
+    localNvmeSsdBlockConfig?: { localSsdCount?: number };
+    /**
+     * Local NVMe SSDs backing node ephemeral storage (emptyDir, image
+     * layers, logs) — GKE RAID0s the disks. Same fixed-count rule as
+     * `localNvmeSsdBlockConfig`. `dataCacheCount` carves disks out for
+     * GKE Data Cache. **Replace-only**.
+     */
+    ephemeralStorageLocalSsdConfig?: {
+      localSsdCount?: number;
+      dataCacheCount?: number;
+    };
     /** Workload Identity metadata. Mutable via `update`. */
     workloadMetadataConfig?: { mode: "GKE_METADATA" | "GCE_METADATA" };
     /** GVNIC. Mutable via `update`. */
@@ -261,6 +284,12 @@ export const toNodeConfigCreateBody = (
     ...(config.localSsdCount !== undefined
       ? { localSsdCount: config.localSsdCount }
       : {}),
+    ...(config.localNvmeSsdBlockConfig
+      ? { localNvmeSsdBlockConfig: config.localNvmeSsdBlockConfig }
+      : {}),
+    ...(config.ephemeralStorageLocalSsdConfig
+      ? { ephemeralStorageLocalSsdConfig: config.ephemeralStorageLocalSsdConfig }
+      : {}),
     ...(config.workloadMetadataConfig
       ? { workloadMetadataConfig: config.workloadMetadataConfig }
       : {}),
@@ -320,8 +349,23 @@ const toNodePoolUpdateBody = (
   if (nc.taints && !deepEqual(oc.taints ?? [], nc.taints)) {
     body.taints = { taints: nc.taints };
   }
-  if (!deepEqual(oc.resourceLabels ?? {}, desiredResourceLabels)) {
-    body.resourceLabels = { labels: desiredResourceLabels };
+  // GKE injects its own `goog-*` resource labels (accelerator type,
+  // provisioning model, …) after create. Treat them as server-managed:
+  // fold the observed ones into the desired set before diffing, or
+  // every reconcile issues a labels update — which on a large pool is
+  // a long rolling cluster operation that wedges all other mutations
+  // on the cluster ("incompatible operation").
+  const observedResourceLabels = oc.resourceLabels ?? {};
+  const desiredWithServerManaged = {
+    ...Object.fromEntries(
+      Object.entries(observedResourceLabels).filter(([k]) =>
+        k.startsWith("goog-"),
+      ),
+    ),
+    ...desiredResourceLabels,
+  };
+  if (!deepEqual(observedResourceLabels, desiredWithServerManaged)) {
+    body.resourceLabels = { labels: desiredWithServerManaged };
   }
 
   if (nc.gvnic && !deepEqual(oc.gvnic, nc.gvnic)) {
@@ -365,6 +409,7 @@ export const NodePoolProvider = () =>
     NodePool,
     Effect.gen(function* () {
       const getNodePools = yield* cont.getProjectsLocationsClustersNodePools;
+      const listNodePools = yield* cont.listProjectsLocationsClustersNodePools;
       const createNodePools = yield* cont.createProjectsLocationsClustersNodePools;
       const updateNodePools = yield* cont.updateProjectsLocationsClustersNodePools;
       const setSize = yield* cont.setSizeProjectsLocationsClustersNodePools;
@@ -500,7 +545,12 @@ export const NodePoolProvider = () =>
             !deepEqual(oc.metadata, nc.metadata) ||
             !deepEqual(oc.sandboxConfig, nc.sandboxConfig) ||
             !deepEqual(oc.reservationAffinity, nc.reservationAffinity) ||
-            !deepEqual(oc.shieldedInstanceConfig, nc.shieldedInstanceConfig)
+            !deepEqual(oc.shieldedInstanceConfig, nc.shieldedInstanceConfig) ||
+            !deepEqual(oc.localNvmeSsdBlockConfig, nc.localNvmeSsdBlockConfig) ||
+            !deepEqual(
+              oc.ephemeralStorageLocalSsdConfig,
+              nc.ephemeralStorageLocalSsdConfig,
+            )
           ) {
             return { action: "replace" } as const;
           }
@@ -596,15 +646,39 @@ export const NodePoolProvider = () =>
           const location = output?.location ?? olds?.location;
           const clusterName = output?.clusterName ?? olds?.clusterName;
           if (!project || !location || !clusterName) return undefined;
-          const name =
-            output?.name ??
-            olds?.name ??
-            (yield* createPhysicalName({ id, maxLength: 40 })).toLowerCase();
-          const fqName = `projects/${project}/locations/${location}/clusters/${clusterName}/nodePools/${name}`;
-          const observed = yield* getNodePools({ name: fqName }).pipe(
-            Effect.catchTag("NotFound", () => Effect.succeed(undefined as cont.NodePool | undefined)),
-            Effect.catchTag("Forbidden", () => Effect.succeed(undefined as cont.NodePool | undefined)),
-          );
+          const name = output?.name ?? olds?.name;
+          let observed: cont.NodePool | undefined;
+          if (name) {
+            const fqName = `projects/${project}/locations/${location}/clusters/${clusterName}/nodePools/${name}`;
+            observed = yield* getNodePools({ name: fqName }).pipe(
+              Effect.catchTag("NotFound", () => Effect.succeed(undefined as cont.NodePool | undefined)),
+              Effect.catchTag("Forbidden", () => Effect.succeed(undefined as cont.NodePool | undefined)),
+            );
+          } else {
+            // Cold recovery (lost state): the pool name truncates the
+            // logical id and appends a random per-instance suffix that
+            // lived only in state, so a probe against a freshly-generated
+            // name can never hit. Scan the cluster's pools for our
+            // alchemy labels (stamped into config.resourceLabels).
+            const page = yield* listNodePools({
+              parent: `projects/${project}/locations/${location}/clusters/${clusterName}`,
+            }).pipe(
+              Effect.catchTag("NotFound", () =>
+                Effect.succeed(undefined as cont.ListNodePoolsResponse | undefined),
+              ),
+              Effect.catchTag("Forbidden", () =>
+                Effect.succeed(undefined as cont.ListNodePoolsResponse | undefined),
+              ),
+            );
+            for (const candidate of page?.nodePools ?? []) {
+              if (
+                yield* hasAlchemyLabels(id, candidate.config?.resourceLabels)
+              ) {
+                observed = candidate;
+                break;
+              }
+            }
+          }
           if (!observed) return undefined;
           const attrs = toNodePoolAttributes(observed, {
             project,