@microagi/alchemy-gcp 0.5.1 → 0.6.0

package/src/Compute/Firewall.ts

@@ -0,0 +1,330 @@
+import * as compute from "@distilled.cloud/gcp/compute-v1";
+import { Resource } from "alchemy";
+import { Unowned } from "alchemy/AdoptPolicy";
+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 {
+  descriptionHasAlchemyMarker,
+  gcpAlchemyDescription,
+  stripAlchemyMarker,
+} from "../Tags.ts";
+import type * as GCP from "../Providers.ts";
+import { makeAwaitGlobalOperation } from "./Operations.ts";
+
+/** One allow entry: a protocol plus optional port list. */
+export type FirewallAllowed = {
+  /** `tcp` | `udp` | `icmp` | `esp` | `ah` | `sctp` | protocol number. */
+  IPProtocol: string;
+  /** Ports / ranges (`"8000"`, `"8000-8100"`). Omit = all ports. */
+  ports?: ReadonlyArray<string>;
+};
+
+/**
+ * A VPC firewall rule (allow rules only — `denied` is not modelled;
+ * add it when a consumer needs it).
+ *
+ * Firewalls have no `labels` field, so adoption gating uses the
+ * alchemy marker embedded in `description` (same as `GCP.Network`).
+ * Unlike Network, firewall `description` IS mutable, and the sync step
+ * keeps the marker prefix in place on every reconcile.
+ *
+ * GCP rejects rules carrying BOTH `targetTags` and
+ * `targetServiceAccounts` — prefer service accounts for GKE node
+ * targeting: node tags embed a per-cluster random suffix and go stale
+ * on every cluster rebuild, while the compute default SA is stable.
+ *
+ * @section Creating a firewall rule
+ * @example GCLB health checks → GKE pods on 8000
+ * ```typescript
+ * yield* GCP.Firewall("LbHealthChecks", {
+ *   project: host.projectId,
+ *   network: vpc.selfLink,
+ *   name: "k8s-app-hc",
+ *   sourceRanges: ["130.211.0.0/22", "35.191.0.0/16"],
+ *   allowed: [{ IPProtocol: "tcp", ports: ["8000"] }],
+ *   targetServiceAccounts: [nodeSa],
+ * });
+ * ```
+ */
+export type FirewallProps = {
+  /** GCP project ID hosting the rule. Immutable — replace if changed. */
+  project: string;
+  /**
+   * Rule name. Defaults to `createPhysicalName({ id, lowercase: true,
+   * maxLength: 63 })`. Immutable — replace if changed.
+   */
+  name?: string;
+  /**
+   * VPC the rule attaches to — short name or selfLink. Immutable —
+   * replace if changed.
+   */
+  network: string;
+  /** User-visible description (stored after the alchemy marker). Mutable. */
+  description?: string;
+  /** INGRESS (default) or EGRESS. Immutable — replace if changed. */
+  direction?: "INGRESS" | "EGRESS";
+  /** 0–65535, lower wins. GCP default 1000. Mutable. */
+  priority?: number;
+  /** Source CIDRs (INGRESS). Mutable. */
+  sourceRanges?: ReadonlyArray<string>;
+  /** Destination CIDRs (EGRESS). Mutable. */
+  destinationRanges?: ReadonlyArray<string>;
+  /** Allow entries. Required — this resource models allow rules only. Mutable. */
+  allowed: ReadonlyArray<FirewallAllowed>;
+  /**
+   * Instance network tags the rule applies to. Mutually exclusive with
+   * `targetServiceAccounts`. Mutable.
+   */
+  targetTags?: ReadonlyArray<string>;
+  /**
+   * Service accounts whose instances the rule applies to. Preferred
+   * over tags for GKE nodes (stable across cluster rebuilds). Mutually
+   * exclusive with `targetTags`. Mutable.
+   */
+  targetServiceAccounts?: ReadonlyArray<string>;
+  /** Rule disabled (kept but not enforced). Mutable. */
+  disabled?: boolean;
+};
+
+export type FirewallAttributes = {
+  /** Rule name. */
+  name: string;
+  /** GCP project ID, threaded through from props for delete/read. */
+  project: string;
+  /** Server-defined URL. */
+  selfLink: string;
+  /** Server-assigned numeric id. */
+  id: string;
+  /** VPC selfLink the rule is attached to. */
+  network: string;
+  /** INGRESS / EGRESS. */
+  direction: string | undefined;
+  /** Effective priority. */
+  priority: number | undefined;
+  /** Source CIDRs. */
+  sourceRanges: ReadonlyArray<string> | undefined;
+  /** Allow entries. */
+  allowed: ReadonlyArray<FirewallAllowed> | undefined;
+  /** Target network tags. */
+  targetTags: ReadonlyArray<string> | undefined;
+  /** Target service accounts. */
+  targetServiceAccounts: ReadonlyArray<string> | undefined;
+  /** User description (alchemy marker stripped). */
+  description: string | undefined;
+  /** Disabled flag. */
+  disabled: boolean | undefined;
+};
+
+export type Firewall = Resource<
+  "GCP.Firewall",
+  FirewallProps,
+  FirewallAttributes,
+  never,
+  GCP.Providers
+>;
+export const Firewall = Resource<Firewall>("GCP.Firewall");
+
+const toFirewallAttributes = (
+  f: compute.Firewall,
+  parent: { project: string },
+): FirewallAttributes => ({
+  name: f.name ?? "",
+  project: parent.project,
+  selfLink: f.selfLink ?? "",
+  id: f.id ?? "",
+  network: f.network ?? "",
+  direction: f.direction,
+  priority: f.priority,
+  sourceRanges: f.sourceRanges,
+  allowed: f.allowed as ReadonlyArray<FirewallAllowed> | undefined,
+  targetTags: f.targetTags,
+  targetServiceAccounts: f.targetServiceAccounts,
+  description: stripAlchemyMarker(f.description),
+  disabled: f.disabled,
+});
+
+/**
+ * Normalize for drift comparison: GCP reorders list fields and the
+ * `allowed` entries' ports — compare order-insensitively so a
+ * cosmetic reordering doesn't trigger a PATCH every reconcile.
+ */
+const normalized = (f: {
+  priority?: number | undefined;
+  sourceRanges?: ReadonlyArray<string> | undefined;
+  destinationRanges?: ReadonlyArray<string> | undefined;
+  // `IPProtocol` is optional here because the SDK's observed Firewall
+  // type marks every field optional — desired props always set it.
+  allowed?: ReadonlyArray<{ IPProtocol?: string; ports?: ReadonlyArray<string> }> | undefined;
+  targetTags?: ReadonlyArray<string> | undefined;
+  targetServiceAccounts?: ReadonlyArray<string> | undefined;
+  disabled?: boolean | undefined;
+  description?: string | undefined;
+}) => ({
+  priority: f.priority ?? 1000,
+  sourceRanges: [...(f.sourceRanges ?? [])].sort(),
+  destinationRanges: [...(f.destinationRanges ?? [])].sort(),
+  allowed: [...(f.allowed ?? [])]
+    .map((a) => ({
+      IPProtocol: (a.IPProtocol ?? "").toLowerCase(),
+      ports: [...(a.ports ?? [])].sort(),
+    }))
+    .sort((x, y) => x.IPProtocol.localeCompare(y.IPProtocol)),
+  targetTags: [...(f.targetTags ?? [])].sort(),
+  targetServiceAccounts: [...(f.targetServiceAccounts ?? [])].sort(),
+  disabled: f.disabled ?? false,
+  description: f.description,
+});
+
+export const FirewallProvider = () =>
+  Provider.effect(
+    Firewall,
+    Effect.gen(function* () {
+      const getFirewalls = yield* compute.getFirewalls;
+      const insertFirewalls = yield* compute.insertFirewalls;
+      const patchFirewalls = yield* compute.patchFirewalls;
+      const deleteFirewalls = yield* compute.deleteFirewalls;
+      const getGlobalOperations = yield* compute.getGlobalOperations;
+      const awaitOp = makeAwaitGlobalOperation(getGlobalOperations);
+
+      const observe = (project: string, name: string) =>
+        getFirewalls({ project, firewall: name }).pipe(
+          Effect.catchTag("NotFound", () =>
+            Effect.succeed(undefined as compute.Firewall | undefined),
+          ),
+          Effect.catchTag("Forbidden", () =>
+            Effect.succeed(undefined as compute.Firewall | undefined),
+          ),
+        );
+
+      return {
+        stables: ["name", "project", "selfLink", "id", "network"],
+        diff: Effect.fn(function* ({ news, olds = {} }) {
+          if (!isResolved(news)) return undefined;
+          if (
+            somePropsAreDifferent(olds as FirewallProps, news, [
+              "project",
+              "name",
+              "network",
+              "direction",
+            ])
+          ) {
+            return { action: "replace" } as const;
+          }
+          return undefined;
+        }),
+        reconcile: Effect.fn(function* ({ id, news, session }) {
+          if (news.targetTags?.length && news.targetServiceAccounts?.length) {
+            return yield* Effect.fail(
+              new Error(
+                "Firewall: targetTags and targetServiceAccounts are mutually exclusive (GCP rejects rules with both)",
+              ),
+            );
+          }
+          const desiredName =
+            news.name ??
+            (yield* createPhysicalName({ id, maxLength: 63 })).toLowerCase();
+          const desiredDescription = yield* gcpAlchemyDescription(
+            id,
+            news.description,
+          );
+
+          const mutableBody = (): compute.Firewall => ({
+            description: desiredDescription,
+            ...(news.priority !== undefined ? { priority: news.priority } : {}),
+            ...(news.sourceRanges
+              ? { sourceRanges: [...news.sourceRanges] }
+              : {}),
+            ...(news.destinationRanges
+              ? { destinationRanges: [...news.destinationRanges] }
+              : {}),
+            allowed: news.allowed.map((a) => ({
+              IPProtocol: a.IPProtocol,
+              ...(a.ports ? { ports: [...a.ports] } : {}),
+            })),
+            // Always send both target fields: switching tags → service
+            // accounts must CLEAR the other side, and PATCH leaves
+            // omitted fields untouched.
+            targetTags: [...(news.targetTags ?? [])],
+            targetServiceAccounts: [...(news.targetServiceAccounts ?? [])],
+            disabled: news.disabled ?? false,
+          });
+
+          // 1. Observe — collapse 403 to "missing" alongside 404.
+          let observed = yield* observe(news.project, desiredName);
+
+          // 2. Ensure — create if missing. `Conflict` covers concurrent
+          //    creates and state-persistence races.
+          if (!observed) {
+            const op = yield* insertFirewalls({
+              project: news.project,
+              body: {
+                name: desiredName,
+                network: news.network,
+                ...(news.direction ? { direction: news.direction } : {}),
+                ...mutableBody(),
+              },
+            }).pipe(
+              Effect.catchTag("Conflict", () =>
+                Effect.succeed(undefined as compute.Operation | undefined),
+              ),
+            );
+            if (op?.name) yield* awaitOp(news.project, op.name, session);
+            observed = yield* getFirewalls({
+              project: news.project,
+              firewall: desiredName,
+            });
+          }
+
+          // 3. Sync — everything except name/network/direction is
+          //    PATCHable. Diff against OBSERVED state (cloud is
+          //    authoritative), order-insensitively.
+          const desired = mutableBody();
+          if (!deepEqual(normalized(observed), normalized(desired))) {
+            const op = yield* patchFirewalls({
+              project: news.project,
+              firewall: desiredName,
+              body: desired,
+            });
+            if (op.name) yield* awaitOp(news.project, op.name, session);
+          }
+
+          const final = yield* getFirewalls({
+            project: news.project,
+            firewall: desiredName,
+          });
+          return toFirewallAttributes(final, { project: news.project });
+        }),
+        delete: Effect.fn(function* ({ output, session }) {
+          yield* deleteFirewalls({
+            project: output.project,
+            firewall: output.name,
+          }).pipe(
+            Effect.flatMap((op) =>
+              op.name
+                ? awaitOp(output.project, op.name, session)
+                : Effect.succeed(op),
+            ),
+            Effect.catchTag("NotFound", () => Effect.void),
+          );
+        }),
+        read: Effect.fn(function* ({ id, output, olds }) {
+          const project = output?.project ?? olds?.project;
+          if (!project) return undefined;
+          const name =
+            output?.name ??
+            olds?.name ??
+            (yield* createPhysicalName({ id, maxLength: 63 })).toLowerCase();
+          const observed = yield* observe(project, name);
+          if (!observed) return undefined;
+          const attrs = toFirewallAttributes(observed, { project });
+          // Adoption gate via the description marker — firewalls have
+          // no labels field (same situation as GCP.Network).
+          return (yield* descriptionHasAlchemyMarker(id, observed.description))
+            ? attrs
+            : Unowned(attrs);
+        }),
+      };
+    }),
+  );

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 }