foundation/bootstrap/components/network.ts

// components/network.ts
//
// The foundation-net user-defined bridge (CONTRACT_003 §3.1). Created once, on the
// shared provider; every service container attaches to it and reaches peers by
// container name via Docker's embedded DNS. This is the first thing the bootstrap
// creates — all data-plane and forge components depend on it.
import * as docker from "@pulumi/docker";
import { BaseCtx } from "../lib/context";

export function deployNetwork(ctx: BaseCtx): docker.Network {
  return new docker.Network(
    "foundation-net",
    {
      name: ctx.cfg.network.name, // "foundation-net" (CONTRACT_003)
      driver: "bridge",
      attachable: true,
      ipamConfigs: [{ subnet: ctx.cfg.network.subnet }], // "172.30.0.0/24"
    },
    {
      provider: ctx.provider,
      deleteBeforeReplace: true,
      // Docker auto-assigns the subnet's first host (.1) as the bridge gateway —
      // a field we never declared, so a `pulumi up --refresh` surfaced it as a
      // spurious ipamConfigs drift. `gateway` is ForceNew, so reconciling it
      // (either by declaring it OR by applying the refreshed diff) would REPLACE
      // the network and disconnect every container. The IPAM is immutable by
      // design (subnet fixed by CONTRACT_003), so we ignore drift on it: plain
      // `up` stays clean AND `up --refresh` no longer wants to recreate the net.
      ignoreChanges: ["ipamConfigs"],
    },
  );
}