@deployfoundation/foundation-deploy 0.1.0

package/src/stacks/network-stack.ts

@@ -0,0 +1,282 @@
+import * as cdk from "aws-cdk-lib";
+import * as ec2 from "aws-cdk-lib/aws-ec2";
+import * as iam from "aws-cdk-lib/aws-iam";
+import type { Construct } from "constructs";
+import { type Instance, capabilityEnabled } from "../names.ts";
+
+/**
+ * Network — VPC + endpoints.
+ *
+ * - "ingress": public subnets, present only to host the NAT gateways.
+ * - "egress": PRIVATE_WITH_EGRESS, NAT-routed. AgentCore session ENIs
+ *   (networkMode VPC) live here so github.com / slack.com / the Codex API are
+ *   reachable, while AWS API traffic still resolves to the interface endpoints
+ *   through private DNS and S3/DynamoDB ride the gateway endpoints.
+ * - "app": PRIVATE_ISOLATED, hosts the interface VPC endpoints.
+ *
+ * AgentCore AZ constraint: in us-east-1 the AgentCore Runtime only schedules
+ * session ENIs into the AZ-IDs `use1-az1`, `use1-az2` and `use1-az4`. CDK
+ * picks AZs by *name* (us-east-1a…), and the name→AZ-ID mapping differs per
+ * account, so this stack does not try to pin them. If the two AZs CDK picks
+ * turn out not to be AgentCore-supported, the escape hatch is FoundationAgent's
+ * `-c agentSubnetIds=subnet-a,subnet-b` context override, which selects the
+ * egress subnets by id instead of by tier.
+ *
+ * Existing-VPC import: `-c vpcId=vpc-...` (needs CDK_DEFAULT_ACCOUNT for the
+ * context lookup); the imported VPC must already have private-with-NAT
+ * subnets. Endpoints are still created by default; `-c createVpcEndpoints=false`
+ * skips them all and `-c skipEndpoints=s3,secretsmanager` skips named ones
+ * that the imported VPC already provides.
+ */
+/** MongoDB's wire-protocol port. Atlas serves every cluster on it. */
+const MONGODB_PORT = 27017;
+
+export interface FoundationNetworkProps extends cdk.StackProps {
+  /** The deployment this stack belongs to. Only its naming prefix is used here. */
+  instance: Instance;
+  /** The instance's runtime config, read at synth for the Mongo egress switch. */
+  configPath: string;
+}
+
+export class FoundationNetwork extends cdk.Stack {
+  public readonly vpc: ec2.IVpc;
+  /** Only set when this stack creates the endpoints (createVpcEndpoints). */
+  public endpointSecurityGroup?: ec2.SecurityGroup;
+  /** Private-with-NAT subnets for the AgentCore session ENIs. */
+  public readonly egressSubnets: ec2.SubnetSelection;
+  /** SG for AgentCore session ENIs: 443 + DNS egress only. */
+  public readonly agentSecurityGroup: ec2.SecurityGroup;
+  /** SG for VPC-attached Lambda ENIs, should we ever attach them: 443 + DNS. */
+  public readonly gatewaySecurityGroup: ec2.SecurityGroup;
+  /** SG for the S3 Files mount targets: NFS (2049) from the agent ENIs only. */
+  public readonly mountTargetSecurityGroup: ec2.SecurityGroup;
+
+  constructor(scope: Construct, id: string, props: FoundationNetworkProps) {
+    super(scope, id, props);
+    // Security-group descriptions are immutable in CloudFormation: a changed
+    // description forces SG replacement, which fails while the group id is an
+    // in-use cross-stack export. So they key off the stable naming PREFIX, not
+    // the cosmetic displayName — renaming a teammate wedged a live pipeline
+    // for exactly this reason (2026-09, sky-tags#94).
+    const { prefix } = props.instance.naming;
+
+    const importedVpcId: string | undefined = this.node.tryGetContext("vpcId");
+    const createVpcEndpoints: boolean =
+      String(this.node.tryGetContext("createVpcEndpoints") ?? "true") !== "false";
+
+    if (importedVpcId) {
+      this.vpc = ec2.Vpc.fromLookup(this, "ImportedVpc", { vpcId: importedVpcId });
+      this.egressSubnets = { subnetType: ec2.SubnetType.PRIVATE_WITH_EGRESS };
+    } else {
+      this.vpc = new ec2.Vpc(this, "FoundationVpc", {
+        maxAzs: 2,
+        // One NAT per AZ: the Slack ack / chat.update path must survive a
+        // single-AZ failure.
+        natGateways: 2,
+        subnetConfiguration: [
+          { name: "ingress", subnetType: ec2.SubnetType.PUBLIC, cidrMask: 24 },
+          { name: "egress", subnetType: ec2.SubnetType.PRIVATE_WITH_EGRESS, cidrMask: 24 },
+          { name: "app", subnetType: ec2.SubnetType.PRIVATE_ISOLATED, cidrMask: 24 },
+        ],
+      });
+      this.egressSubnets = { subnetGroupName: "egress" };
+      // The addresses everything in the VPC leaves through, so a third party
+      // (an Atlas IP allowlist, say) can name this instance and no other.
+      // One per AZ, matching `natGateways: 2` above.
+      new cdk.CfnOutput(this, "NatEgressIp", {
+        value: cdk.Fn.join(
+          ",",
+          this.vpc.publicSubnets
+            .map(
+              (subnet) =>
+                (subnet.node.tryFindChild("EIP") as ec2.CfnEIP | undefined)?.attrPublicIp ?? "",
+            )
+            .filter((value) => value !== ""),
+        ),
+        description: "Public egress addresses (NAT gateway EIPs) for allowlisting this instance",
+      });
+    }
+
+    // HTTPS anywhere (NAT for github.com/slack.com; private DNS steers AWS
+    // APIs onto the interface endpoints) plus DNS to the VPC resolver.
+    // Nothing else leaves. Per-channel host allowlisting narrows further
+    // inside the agent.
+    const egressOnly = (constructId: string, description: string): ec2.SecurityGroup => {
+      const sg = new ec2.SecurityGroup(this, constructId, {
+        vpc: this.vpc,
+        description,
+        allowAllOutbound: false,
+      });
+      sg.addEgressRule(ec2.Peer.anyIpv4(), ec2.Port.tcp(443), "HTTPS egress");
+      sg.addEgressRule(
+        ec2.Peer.ipv4(this.vpc.vpcCidrBlock),
+        ec2.Port.udp(53),
+        "DNS to VPC resolver",
+      );
+      sg.addEgressRule(
+        ec2.Peer.ipv4(this.vpc.vpcCidrBlock),
+        ec2.Port.tcp(53),
+        "DNS over TCP to VPC resolver",
+      );
+      return sg;
+    };
+    this.agentSecurityGroup = egressOnly(
+      "AgentSg",
+      `${prefix} AgentCore session ENIs: 443 + DNS egress only`,
+    );
+    this.gatewaySecurityGroup = egressOnly(
+      "GatewaySg",
+      `${prefix} gateway Lambda ENIs: 443 + DNS egress only`,
+    );
+
+    // MongoDB Atlas speaks the wire protocol on 27017, not HTTPS, so the
+    // agent needs one more egress rule to reach it. Without it every
+    // connection is dropped by this group and the driver reports a plain
+    // TIMEOUT — nothing anywhere says a firewall ate it. One instance ran
+    // with `mongodbReadonly` on and every query timing out for days on
+    // exactly that failure.
+    //
+    // The GATEWAY deliberately gets no such rule: only the agent queries
+    // Mongo. The destination is open because Atlas resolves an SRV record to
+    // shard hostnames whose addresses rotate, so there is no stable CIDR to
+    // name; the credential and Atlas's own IP allowlist are what actually
+    // gate access.
+    //
+    // Gated on the capability so an instance that does not use Mongo keeps
+    // the port shut. Turning `mongodbReadonly` ON is therefore a deploy, not
+    // just a config sync; turning it OFF still removes the tools on the next
+    // turn.
+    if (capabilityEnabled(props.configPath, "mongodbReadonly")) {
+      this.agentSecurityGroup.addEgressRule(
+        ec2.Peer.anyIpv4(),
+        ec2.Port.tcp(MONGODB_PORT),
+        "MongoDB Atlas",
+      );
+    }
+
+    // The persistent mount speaks NFS, not HTTPS, so the agent SG needs one
+    // extra egress rule and the mount targets one matching ingress. Both are
+    // scoped to the other security group — nothing else in the VPC can reach
+    // the file system, and the agent can reach nothing else on 2049.
+    this.mountTargetSecurityGroup = new ec2.SecurityGroup(this, "MountTargetSg", {
+      vpc: this.vpc,
+      description: `${prefix} S3 Files mount targets: NFS from the agent ENIs only`,
+      allowAllOutbound: false,
+    });
+    this.mountTargetSecurityGroup.addIngressRule(
+      this.agentSecurityGroup,
+      ec2.Port.tcp(2049),
+      "NFS from the AgentCore session ENIs",
+    );
+    this.agentSecurityGroup.addEgressRule(
+      this.mountTargetSecurityGroup,
+      ec2.Port.tcp(2049),
+      "NFS to the S3 Files mount targets",
+    );
+
+    if (!createVpcEndpoints) return;
+
+    const endpointSg = new ec2.SecurityGroup(this, "EndpointSg", {
+      vpc: this.vpc,
+      description: `${prefix} interface VPC endpoints: HTTPS from within the VPC only`,
+      allowAllOutbound: false,
+    });
+    endpointSg.addIngressRule(
+      ec2.Peer.ipv4(this.vpc.vpcCidrBlock),
+      ec2.Port.tcp(443),
+      "HTTPS from VPC",
+    );
+    this.endpointSecurityGroup = endpointSg;
+
+    // Interface endpoints sit in the isolated app tier when we created the
+    // VPC; on an imported VPC they land in its private subnets. Private DNS
+    // makes them authoritative for the whole VPC either way.
+    const endpointSubnets: ec2.SubnetSelection = importedVpcId
+      ? { subnetType: ec2.SubnetType.PRIVATE_WITH_EGRESS }
+      : { subnetGroupName: "app" };
+    // Gateway endpoints attach to every private route table (app + egress) so
+    // S3/DynamoDB traffic from the NAT tier also stays on AWS's network.
+    const gatewayEndpointSubnets: ec2.SubnetSelection[] = importedVpcId
+      ? [{ subnetType: ec2.SubnetType.PRIVATE_WITH_EGRESS }]
+      : [{ subnetGroupName: "app" }, { subnetGroupName: "egress" }];
+
+    // Endpoint policy: only principals from this account may use the endpoint
+    // (blocks exfiltration to foreign-account resources through our
+    // endpoints; per-resource authorization stays in the IAM roles).
+    const sameAccountOnly = new iam.PolicyStatement({
+      effect: iam.Effect.ALLOW,
+      principals: [new iam.AnyPrincipal()],
+      actions: ["*"],
+      resources: ["*"],
+      conditions: { StringEquals: { "aws:PrincipalAccount": this.account } },
+    });
+
+    // Endpoints an imported VPC already has must be skipped — a second S3
+    // gateway endpoint conflicts on the route-table prefix list, and a second
+    // interface endpoint with private DNS conflicts on the DNS name.
+    const skipEndpoints = new Set(
+      String(this.node.tryGetContext("skipEndpoints") ?? "")
+        .split(",")
+        .map((s) => s.trim().toLowerCase())
+        .filter(Boolean),
+    );
+
+    if (!skipEndpoints.has("s3")) {
+      const s3Endpoint = this.vpc.addGatewayEndpoint("S3Endpoint", {
+        service: ec2.GatewayVpcEndpointAwsService.S3,
+        subnets: gatewayEndpointSubnets,
+      });
+      s3Endpoint.addToPolicy(sameAccountOnly);
+      // ECR serves image layers from an ECR-OWNED bucket via presigned URLs.
+      // A same-account-only endpoint policy blocks that fetch (the request is
+      // signed by ECR, not by us) and every AgentCore cold start fails with
+      // `403 Forbidden` on `/v2/<repo>/blobs/<sha256>` (2026-09-05).
+      s3Endpoint.addToPolicy(
+        new iam.PolicyStatement({
+          sid: "EcrLayerBucket",
+          effect: iam.Effect.ALLOW,
+          principals: [new iam.AnyPrincipal()],
+          actions: ["s3:GetObject"],
+          resources: [`arn:${this.partition}:s3:::prod-${this.region}-starport-layer-bucket/*`],
+        }),
+      );
+    }
+    if (!skipEndpoints.has("dynamodb")) {
+      const dynamoEndpoint = this.vpc.addGatewayEndpoint("DynamoDbEndpoint", {
+        service: ec2.GatewayVpcEndpointAwsService.DYNAMODB,
+        subnets: gatewayEndpointSubnets,
+      });
+      dynamoEndpoint.addToPolicy(sameAccountOnly);
+    }
+
+    // No Bedrock Runtime endpoint: the agent talks to the Codex API over
+    // the NAT, never to a Bedrock model. Only the AgentCore control plane
+    // (InvokeAgentRuntime) needs a private path.
+    // Construct id, the name `-c skipEndpoints=` uses for it, and the service.
+    // One list rather than two parallel maps: a pair that disagreed would make
+    // an endpoint unskippable and the mismatch would be invisible.
+    const interfaceEndpoints: readonly [string, string, ec2.IInterfaceVpcEndpointService][] = [
+      [
+        "BedrockAgentCoreEndpoint",
+        "bedrock-agentcore",
+        new ec2.InterfaceVpcEndpointService(`com.amazonaws.${this.region}.bedrock-agentcore`, 443),
+      ],
+      [
+        "SecretsManagerEndpoint",
+        "secretsmanager",
+        ec2.InterfaceVpcEndpointAwsService.SECRETS_MANAGER,
+      ],
+      ["CloudWatchLogsEndpoint", "logs", ec2.InterfaceVpcEndpointAwsService.CLOUDWATCH_LOGS],
+    ];
+    for (const [endpointId, skipName, service] of interfaceEndpoints) {
+      if (skipEndpoints.has(skipName)) continue;
+      const endpoint = this.vpc.addInterfaceEndpoint(endpointId, {
+        service,
+        subnets: endpointSubnets,
+        securityGroups: [endpointSg],
+        privateDnsEnabled: true,
+      });
+      endpoint.addToPolicy(sameAccountOnly);
+    }
+  }
+}