Fjall Docs — deploy AWS infrastructure into your own account

Overview

The Fjall Vpc construct extends the AWS CDK ec2.Vpc with defaults for network isolation. It creates public and private subnets across multiple availability zones, resolves NAT gateway count, configures flow logs, allocates IP ranges from IPAM, and provisions VPC endpoints, all through one set of Fjall props. Vpc extends ec2.Vpc, so most standard CDK VPC properties remain available. Five of them are owned by the construct and are overridden if you set them. See Props the construct owns.

Import

import { Vpc } from "@fjall/components-infrastructure/lib/resources/aws/networking/vpc";

Basic Usage

const vpc = new Vpc(this, "AppVpc", {
  maxAzs: 2,
  natGatewayConfig: { count: 1 },
});

Configuration Options

Core Properties

Property	Type	Description	Default
`vpcName`	`string`	VPC name tag	The construct id
`maxAzs`	`number`	Number of availability zones to use	`3`
`natGatewayConfig`	`{ count?: number } \| false`	NAT gateway count, or `false` for none	CDK default

natGatewayConfig resolves to a NAT gateway count: an object uses count (default 1), and false resolves to 0. Omitting it leaves the count unset, so CDK’s default of one NAT gateway per availability zone applies.

Props the construct owns

These props are set by the constructor after your props are spread, so a value you pass is silently discarded. Configure the Fjall equivalent instead.

CDK prop	Fjall equivalent	Behaviour
`availabilityZones`	`maxAzs`	Always the first `maxAzs` AZs of the stack’s region
`natGateways`	`natGatewayConfig`	Resolved from `natGatewayConfig`, or left to the CDK default
`ipAddresses`	`ipv4IpamPoolId`, `vpcCidrMask`	IPAM allocation when a pool id is set, otherwise CDK’s default `10.0.0.0/16`
`flowLogs`	`flowLogConfig`, `accountId`	Built from `flowLogConfig`, or the `accountId` default path
`gatewayEndpoints`	`endpointsConfig.gateway`	Built from `endpointsConfig`

Passing ipAddresses: ec2.IpAddresses.cidr("10.42.0.0/16") has no effect. The VPC falls back to CDK’s default 10.0.0.0/16, which collides with sibling VPCs on the same range and blocks VPC peering. Use IPAM (ipv4IpamPoolId) to control addressing.

Every other ec2.VpcProps passes through, including subnetConfiguration, natGatewayProvider, enableDnsHostnames, and enableDnsSupport.

Flow Log Properties

Property	Type	Description	Default
`flowLogConfig`	`VpcFlowLogConfig \| false`	Flow log settings, or `false` to disable	On when `accountId` is set
`flowLogConfig.destination`	`"cloudwatch" \| "s3"`	Where logs are written	`"cloudwatch"`
`flowLogConfig.retentionDays`	`number`	CloudWatch log retention, or S3 lifecycle expiry in days	`14` on CloudWatch, none on S3
`flowLogConfig.trafficType`	`"ALL" \| "ACCEPT" \| "REJECT"`	Traffic captured	`"ALL"`

retentionDays means two different things:

CloudWatch destination: log group retention. The value is rounded up to the nearest valid CloudWatch retention (1, 3, 5, 7, 14, 30, 60, 90, 120, 150, 180, 365, 400, 545, 731, and longer).
S3 destination: an S3 lifecycle expiration rule. Objects are deleted permanently after that many days, and noncurrent versions after 30 days. Omit it and no expiry rule is written.

Addressing and Account Properties

Property	Type	Description	Default
`accountId`	`string`	Account id. Turns on default flow logs when `flowLogConfig` is unset	-
`ipv4IpamPoolId`	`string`	IPAM pool id. A non-empty value is what switches addressing to IPAM	-
`vpcCidrMask`	`number`	Netmask length for the IPAM-allocated VPC CIDR	`20`
`subnetCidrMask`	`number`	Default subnet netmask length under IPAM	`23`

IPAM does not depend on accountId. A non-empty ipv4IpamPoolId is the sole signal of IPAM intent, so an IPAM-backed VPC still allocates correctly when the ambient account id fails to resolve.

VPC Endpoint Properties

Property	Type	Description	Default
`endpointsConfig`	`EndpointsConfig \| false`	`false` disables all endpoint types	Gateway endpoints only
`endpointsConfig.gateway`	`{ s3?, dynamodb? } \| false`	Gateway endpoints	S3 and DynamoDB enabled
`endpointsConfig.interface`	`{ ecr?, secretsManager?, kms?, cloudwatchLogs?, ssm?, sts? } \| false`	Interface endpoints	Off unless requested

Default Configuration

With no props, the construct creates:

3 availability zones, the first three in the stack’s region
Public and private-with-egress subnets, one of each per AZ
An internet gateway plus CDK’s default of one NAT gateway per AZ
Gateway endpoints for S3 and DynamoDB

Flow logs activate when you pass flowLogConfig or set accountId. IPAM allocation activates when you pass a non-empty ipv4IpamPoolId. The construct also emits a VpcCidrBlock output exported as <stack-name><id>-vpc-cidr. The Fjall webapp reads that export to record a linked application’s CIDR, so leave the suffix intact.

NAT Gateway Configuration

// Single NAT gateway (lower cost)
const devVpc = new Vpc(this, "DevVpc", {
  natGatewayConfig: { count: 1 },
});

// No NAT gateway (lowest cost)
const isolatedVpc = new Vpc(this, "IsolatedVpc", {
  natGatewayConfig: false,
});

When NAT gateways are disabled, the construct places interface endpoints in PRIVATE_ISOLATED subnets so private workloads can still reach AWS services. With NAT gateways present, they go in PRIVATE_WITH_EGRESS subnets.

Flow Logs

Flow logs turn on in two ways: pass a flowLogConfig object, or set accountId and let the default path run. Both write to a CloudWatch log group at /vpc/flowlogs/vpc-${id}/ with a DESTROY removal policy, so the group is deleted with the stack.

// CloudWatch flow logs, 14-day retention (default path via accountId)
const monitoredVpc = new Vpc(this, "MonitoredVpc", {
  accountId: "123456789012",
});

// CloudWatch flow logs without accountId
const explicitVpc = new Vpc(this, "ExplicitVpc", {
  flowLogConfig: { retentionDays: 30, trafficType: "REJECT" },
});

// S3 flow logs, objects expired after 90 days
const archivedVpc = new Vpc(this, "ArchivedVpc", {
  flowLogConfig: {
    destination: "s3",
    retentionDays: 90,
    trafficType: "REJECT",
  },
});

The S3 destination creates a versioned, S3-managed-encrypted bucket named vpc-flowlogs-<lowercased-id>-<account-id>. Set flowLogConfig: false to disable flow logs even when accountId is present.

IPAM Integration

Supply a non-empty ipv4IpamPoolId and the construct allocates the VPC CIDR from your IPAM pool.

const ipamVpc = new Vpc(this, "IpamVpc", {
  ipv4IpamPoolId: "ipam-pool-1234567890abcdef0",
});

IPAM allocation defaults to a /20 VPC CIDR and /23 subnet masks. Override them with vpcCidrMask and subnetCidrMask.

const largeIpamVpc = new Vpc(this, "LargeIpamVpc", {
  ipv4IpamPoolId: "ipam-pool-1234567890abcdef0",
  vpcCidrMask: 18,
  subnetCidrMask: 22,
});

VPC Endpoints

Gateway endpoints (S3, DynamoDB) are on by default. Request interface endpoints individually.

const endpointVpc = new Vpc(this, "EndpointVpc", {
  natGatewayConfig: false,
  endpointsConfig: {
    gateway: { s3: true, dynamodb: false },
    interface: {
      ecr: true,
      secretsManager: true,
      cloudwatchLogs: true,
    },
  },
});

// No endpoints of any kind
const bareVpc = new Vpc(this, "BareVpc", {
  endpointsConfig: false,
});

Interface endpoint keys: ecr, secretsManager, kms, cloudwatchLogs, ssm, sts. Enabling ecr provisions both the ECR API and ECR Docker endpoints. Enabling ssm provisions SSM, SSM Messages, and EC2 Messages. Every interface endpoint is created with private DNS enabled.

Custom Subnets

Pass standard CDK subnetConfiguration for a multi-tier layout. It is a pass-through prop, so your value is used as written.

const vpc = new Vpc(this, "MultiTierVpc", {
  maxAzs: 2,
  subnetConfiguration: [
    { name: "web", subnetType: ec2.SubnetType.PUBLIC, cidrMask: 24 },
    {
      name: "app",
      subnetType: ec2.SubnetType.PRIVATE_WITH_EGRESS,
      cidrMask: 23,
    },
    { name: "data", subnetType: ec2.SubnetType.PRIVATE_ISOLATED, cidrMask: 24 },
  ],
});

Factory and StackBuilder Patterns

Network Factory

The canonical way to add a VPC inside a Fjall application is NetworkFactory.build passed to app.addNetwork. The factory reads account, region, and IPAM pool id from CDK context and passes them to the construct.

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

const isolatedVpc = app.addNetwork(
  NetworkFactory.build("IsolatedVpc", {
    maxAzs: 2,
    natGateways: false,
    flowLogs: {},
    vpcEndpoints: { interface: { ecr: true } },
  }),
);

NetworkFactory props use natGateways, flowLogs, vpcEndpoints, cidrMask, and subnets, which it maps onto the construct’s natGatewayConfig, flowLogConfig, endpointsConfig, vpcCidrMask, and subnetCidrMask. The factory does not accept subnetConfiguration, so build the construct directly for a custom subnet layout. See the Network Factory pattern for the full prop reference.

StackBuilder

const vpc = Vpc.build("NetworkVpc", {
  maxAzs: 3,
})(stackBuilder);

Import an Existing VPC

Vpc.import resolves an existing VPC through ec2.Vpc.fromLookup, matching the Name tag <stack-name>/<id>.

const importedVpc = Vpc.import(
  "ImportedVpc",
  "existing-stack-name",
)(stackBuilder);

Static Helpers

The construct exposes the helpers it uses internally, so you can compute the same values in custom code.

// First `maxAzs` AZs in the stack's region
const azs = Vpc.availabilityZones(this, 3);

// CloudWatch or S3 flow log options
const flowLogs = Vpc.flowLogs(this, "MyVpc", { accountId: "123456789012" });

// IPAM-backed ipAddresses provider (returns undefined with no pool id)
const ipConfig = Vpc.ipAddresses(this, "MyVpc", {
  ipv4IpamPoolId: "ipam-pool-1234567890abcdef0",
});

Complete Example

import { Vpc } from "@fjall/components-infrastructure/lib/resources/aws/networking/vpc";
import * as ec2 from "aws-cdk-lib/aws-ec2";
import { CfnOutput } from "aws-cdk-lib";

const prodVpc = new Vpc(this, "ProductionVpc", {
  maxAzs: 3,
  natGatewayConfig: { count: 2 },
  accountId: this.account,
  ipv4IpamPoolId: props.ipamPoolId,
  endpointsConfig: {
    interface: { ecr: true, secretsManager: true },
  },
  subnetConfiguration: [
    { name: "web", subnetType: ec2.SubnetType.PUBLIC, cidrMask: 24 },
    {
      name: "app",
      subnetType: ec2.SubnetType.PRIVATE_WITH_EGRESS,
      cidrMask: 23,
    },
    { name: "data", subnetType: ec2.SubnetType.PRIVATE_ISOLATED, cidrMask: 24 },
  ],
});

// Pass prodVpc to downstream constructs:
//   ECS Cluster  -> /resources/compute/ecs-cluster
//   RDS Aurora   -> /resources/database/rds-aurora

new CfnOutput(this, "VpcId", {
  value: prodVpc.vpcId,
  description: "VPC ID",
});

Cost Considerations

Resource	Cost	Optimisation
NAT gateway	~$45/month plus data	Use a single NAT gateway or `natGatewayConfig: false`
Interface endpoints	~$7/month per AZ	Saves on NAT data transfer for AWS-service traffic
Flow logs	Storage costs	Use S3 for cheaper long-term storage

Troubleshooting

Issue	Check
VPC uses `10.0.0.0/16` instead of your CIDR	`ipAddresses` is overridden. Set `ipv4IpamPoolId` to control addressing
CIDR conflicts	Plan IP ranges across accounts, or allocate every VPC from one IPAM pool
Wrong availability zones	`availabilityZones` is overridden. The first `maxAzs` AZs of the region are used
Private workloads cannot reach AWS services	Enable the matching interface endpoints when `natGatewayConfig: false`
Flow logs missing	Pass a `flowLogConfig` object, or set `accountId` with `flowLogConfig` left unset
Flow log objects deleted early	S3 `retentionDays` is a lifecycle expiry, not a retention floor

# Describe the VPC
aws ec2 describe-vpcs --vpc-ids vpc-12345

# Check route tables
aws ec2 describe-route-tables --filters "Name=vpc-id,Values=vpc-12345"

Run AWS commands against a connected account with Fjall-minted credentials:

fjall aws exec --target production-use1 -- aws ec2 describe-vpcs --vpc-ids vpc-12345

Next Steps

Network Factory

Compose VPCs declaratively with NetworkFactory props.

Security Group

Control inbound and outbound traffic for VPC resources.

ECS Cluster

Run containers inside your VPC’s private subnets.

RDS Aurora

Deploy a managed database into VPC subnets.

Compute Resources

Database Resources

Storage Resources

Networking Resources

Messaging Resources

Security Resources

VPC

Overview

Import

Basic Usage

Configuration Options

Core Properties

Props the construct owns

Flow Log Properties

Addressing and Account Properties

VPC Endpoint Properties

Default Configuration

NAT Gateway Configuration

Flow Logs

IPAM Integration

VPC Endpoints

Custom Subnets

Factory and StackBuilder Patterns

Network Factory

StackBuilder

Import an Existing VPC

Static Helpers

Complete Example

Cost Considerations

Troubleshooting

Next Steps

Network Factory

Security Group

ECS Cluster

RDS Aurora

​Overview

​Import

​Basic Usage

​Configuration Options

​Core Properties

​Props the construct owns

​Flow Log Properties

​Addressing and Account Properties

​VPC Endpoint Properties

​Default Configuration

​NAT Gateway Configuration

​Flow Logs

​IPAM Integration

​VPC Endpoints

​Custom Subnets

​Factory and StackBuilder Patterns

​Network Factory

​StackBuilder

​Import an Existing VPC

​Static Helpers

​Complete Example

​Cost Considerations

​Troubleshooting

​Next Steps

Network Factory

Security Group

ECS Cluster

RDS Aurora

Overview

Import

Basic Usage

Configuration Options

Core Properties

Props the construct owns

Flow Log Properties

Addressing and Account Properties

VPC Endpoint Properties

Default Configuration

NAT Gateway Configuration

Flow Logs

IPAM Integration

VPC Endpoints

Custom Subnets

Factory and StackBuilder Patterns

Network Factory

StackBuilder

Import an Existing VPC

Static Helpers

Complete Example

Cost Considerations

Troubleshooting

Next Steps