Fjall Docs — deploy AWS infrastructure into your own account

Overview

NetworkFactory builds the VPC your application deploys into: subnets across availability zones, NAT gateways for egress, gateway and interface VPC endpoints, and flow logs. fjall create app writes a network block into infrastructure.ts for you. Edit that block to tune the default VPC, and use NetworkFactory directly when the application needs a second, separate VPC.

Where the VPC comes from

The default VPC and any additional VPC take the same props type, INetworkProps.

Entry point	Creates	Retrieve with
`App.getApp(name, { network: { ... } })`	The application’s default VPC	`app.getVpc()`
`app.addNetwork(NetworkFactory.build("Id", { ... }))`	An additional VPC in the network stack	`app.getVpc("Id")`
`App.getApp(name, { network: false })`	No VPC (S3-only, CDN-only, Lambda applications)	Nothing
`App.getApp(name, { network: { useExisting } })`	An import of an existing VPC by id	`app.getVpc()`

Default VPC

This is the shape fjall create app scaffolds, and the block you edit day to day.

import { App } from "@fjall/components-infrastructure";

const app = App.getApp("api", {
  network: {
    maxAzs: 2,
    natGateways: { count: 1 },
    vpcEndpoints: {
      interface: { secretsManager: true, kms: true },
    },
    flowLogs: false,
  },
});

Additional VPC

import { App, NetworkFactory } from "@fjall/components-infrastructure";

const app = App.getApp("api", { network: { maxAzs: 2 } });

app.addNetwork(
  NetworkFactory.build("Isolated", {
    maxAzs: 2,
    natGateways: false,
  }),
);

const isolatedVpc = app.getVpc("Isolated");

Existing VPC

const app = App.getApp("api", {
  network: { useExisting: "vpc-0123456789abcdef0" },
});

What an omitted field deploys

Leaving a field out is not the same as turning it off. With network: {}, Fjall deploys:

Setting	Value when the field is omitted
Availability zones	3
NAT gateways	One per AZ, so three at the default `maxAzs`
Subnets	One public and one private-with-egress subnet per AZ
Gateway VPC endpoints	S3 and DynamoDB, both on
Interface VPC endpoints	None
Flow logs	CloudWatch, 14-day retention, all traffic
CIDR range	`10.0.0.0/16` (the CDK default), unless IPAM supplies one

Three NAT gateways is the largest recurring charge in a small VPC. Set natGateways: { count: 1 } for anything that is not production, and natGateways: false for workloads that never dial out to the internet.

Each of the three cost-bearing groups takes false as an explicit opt-out: natGateways: false, flowLogs: false, vpcEndpoints: false.

Parameters

Parameter	Type	Description	Default
`vpcName`	`string`	Name tag on the VPC	Construct id, or the application name for the default VPC
`maxAzs`	`number`	Availability zones to spread subnets across, 1 to 3	`3`
`natGateways`	`{ count?: number }` or `false`	NAT gateways for private-subnet egress. `false` removes them and makes private subnets isolated	One per AZ
`flowLogs`	`{ destination?, retentionDays?, trafficType? }` or `false`	VPC flow logs	CloudWatch, 14 days
`flowLogs.destination`	`"cloudwatch" \| "s3"`	Where flow logs land	`"cloudwatch"`
`flowLogs.retentionDays`	`number`	CloudWatch retention, or S3 object expiry	`14` on CloudWatch, no expiry on S3
`flowLogs.trafficType`	`"ALL" \| "ACCEPT" \| "REJECT"`	Traffic captured	`"ALL"`
`vpcEndpoints`	`object` or `false`	Endpoint configuration. `false` removes every endpoint	`{ gateway: { s3: true, dynamodb: true } }`
`vpcEndpoints.gateway`	`{ s3?, dynamodb? }` or `false`	Gateway endpoints, no hourly charge	Both on
`vpcEndpoints.interface`	`{ ecr?, secretsManager?, kms?, ssm?, sts?, cloudwatchLogs? }` or `false`	Interface endpoints, charged hourly per endpoint per AZ	None
`cidrMask`	`number`	VPC netmask length. Applies on IPAM deploys only	`20`
`subnets.private.cidrMask`	`number`	Private subnet netmask length. Applies on IPAM deploys only	`23`

The AZ count is also capped by the availability zones the target region actually offers.

Accepted but not implemented

These fields typecheck and are accepted at synth, then discarded. Do not build on them.

Field	Behaviour
`transitGateway`	Validated (a missing `id` throws), then ignored. No attachment is created.
`subnets.public`, `subnets.isolated`	Read by the type, never applied. Only `subnets.private.cidrMask` reaches the VPC.

Tier presets

fjall create app writes the network block that matches the tier you pick.

Tier	`maxAzs`	`natGateways`	Flow logs	Interface endpoints
Tinkerer	2	`false`	Off	None
Lightweight	2	`{ count: 1 }`	Off	None
Standard	3	`{ count: 1 }`	CloudWatch, 14 days	`ecr`
Resilient	3	`{ count: 3 }`	CloudWatch, 90 days	`ecr`, `secretsManager`
Enterprise	3	`{ count: 3 }`	S3, 365 days	`ecr`, `secretsManager`, `kms`, `cloudwatchLogs`

NAT gateways

import type { INetworkProps } from "@fjall/components-infrastructure";

// One shared NAT gateway across all AZs
const shared: INetworkProps = { maxAzs: 3, natGateways: { count: 1 } };

// No egress at all
const noEgress: INetworkProps = { maxAzs: 2, natGateways: false };

natGateways: false gives you public subnets plus private isolated subnets. Workloads in the isolated subnets reach AWS services through VPC endpoints only, never the public internet. A count above maxAzs is clamped to maxAzs and logs a warning at synth.

VPC endpoints

Gateway endpoints carry no hourly charge and are on by default. Interface endpoints are opt-in and bill per endpoint per AZ, plus data processing. Two flags create more than one endpoint each:

Flag	Endpoints created
`ecr: true`	`ECR_DOCKER` and `ECR` (2)
`ssm: true`	`SSM`, `SSM_MESSAGES`, `EC2_MESSAGES` (3)
`secretsManager`, `kms`, `sts`, `cloudwatchLogs`	1 each

const app = App.getApp("api", {
  network: {
    vpcEndpoints: {
      gateway: { s3: true, dynamodb: true },
      interface: {
        ecr: true,
        secretsManager: true,
        kms: true,
        ssm: true,
        sts: true,
        cloudwatchLogs: true,
      },
    },
  },
});

Six flags there create nine interface endpoints, each with one network interface per AZ. At the default maxAzs of 3 that is 27 network interfaces billed hourly. Enable the services you actually call. To drop the default gateway endpoints, pass vpcEndpoints: { gateway: false }. To drop every endpoint, pass vpcEndpoints: false. Endpoints land in the private subnets the workload uses: private-with-egress when NAT gateways exist, private-isolated when they do not.

Flow logs

import type { INetworkProps } from "@fjall/components-infrastructure";

// CloudWatch, 90-day retention, rejected traffic only
const audited: INetworkProps = {
  flowLogs: { retentionDays: 90, trafficType: "REJECT" },
};

// S3, one-year object expiry
const archived: INetworkProps = {
  flowLogs: { destination: "s3", retentionDays: 365 },
};

// Off
const quiet: INetworkProps = { flowLogs: false };

CloudWatch retention rounds up to the nearest retention period CloudWatch supports. An S3 destination creates a versioned, encrypted bucket. Without retentionDays, its objects never expire.

CIDR ranges and IPAM

cidrMask sets the VPC netmask and subnets.private.cidrMask sets the subnet netmask. Both apply only when an IPAM pool id reaches the synth as the ipamPoolId CDK context value. fjall org deploy reads that pool from the platform tier and passes it into the account deployments it cascades to, which is what keeps CIDR ranges from colliding across an organisation. Outside that path no pool id is supplied, both masks are ignored, and the VPC takes the CDK default 10.0.0.0/16.

Validation

Condition	Result
`maxAzs` outside 1 to 3	Warning, synth continues
`natGateways.count` above `maxAzs`	Warning, the count is clamped to `maxAzs`
`transitGateway` without `id`	Throws at synth

What Fjall wires for you

You rarely touch security groups or subnets directly.

ComputeFactory creates the shared Application Load Balancer for an ECS cluster, plus a target group and health check per service.
DatabaseFactory creates the subnet group and security group, placing the database in private subnets unless you set publiclyAccessible: true.
Connections open the security-group rules between two resources.

Declare the connection on the service and the rules follow:

import {
  App,
  ComputeFactory,
  StorageFactory,
} from "@fjall/components-infrastructure";

const app = App.getApp("api", { network: { maxAzs: 2 } });

const assets = app.addStorage(StorageFactory.build("Assets"));

app.addCompute(
  ComputeFactory.build("web", {
    type: "ecs",
    services: [
      {
        name: "web",
        capacityProvider: "FARGATE",
        containers: [{ port: 3000 }],
        connections: [assets],
      },
    ],
  }),
);

Next Steps

VPC Construct

Drop below the factory to the CDK VPC construct and its full prop surface.

Compute Factory

Deploy ECS services and Lambda functions into the VPC.

Database Factory

Provision Aurora and RDS instances in the private subnets.

Standard Pattern

Compose a full application with networking already configured.

Factory Patterns

Application Patterns

Architecture Patterns

Network Factory

Overview

Where the VPC comes from

Default VPC

Additional VPC

Existing VPC

What an omitted field deploys

Parameters

Accepted but not implemented

Tier presets

NAT gateways

VPC endpoints

Flow logs

CIDR ranges and IPAM

Validation

What Fjall wires for you

Next Steps

VPC Construct

Compute Factory

Database Factory

Standard Pattern

​Overview

​Where the VPC comes from

​Default VPC

​Additional VPC

​Existing VPC

​What an omitted field deploys

​Parameters

​Accepted but not implemented

​Tier presets

​NAT gateways

​VPC endpoints

​Flow logs

​CIDR ranges and IPAM

​Validation

​What Fjall wires for you

​Next Steps

VPC Construct

Compute Factory

Database Factory

Standard Pattern

Overview

Where the VPC comes from

Default VPC

Additional VPC

Existing VPC

What an omitted field deploys

Parameters

Accepted but not implemented

Tier presets

NAT gateways

VPC endpoints

Flow logs

CIDR ranges and IPAM

Validation

What Fjall wires for you

Next Steps