Fjall Docs — deploy AWS infrastructure into your own account

Overview

The Fjall SecurityGroup construct extends the AWS CDK ec2.SecurityGroup. It adds exactly one thing: a default description of <id> Security Group when you omit one. Every other property, method and default comes straight from the CDK construct. Most applications never construct one directly. Fjall creates the security groups its resources need, and the connections array on a compute resource opens the rules between them.

There is no fjall add security-group. Security groups arrive with the resources that need them. Construct one by hand only when you write custom CDK in your application’s infrastructure.ts.

What Fjall Creates

Resource	Security groups	Rules applied at synth
RDS instance	One per instance, plus one each for proxy and replicas	Self-referencing rule on the database port for multi-AZ traffic
Aurora cluster	One per cluster, plus one for RDS Proxy	Self-referencing rule on the cluster port, proxy ingress into the cluster group
ClickHouse	One per cluster (`allowAllOutbound: false`)	Self-referencing native-port ingress, HTTPS egress to AWS service endpoints
ECS cluster on EC2 capacity	One for the Auto Scaling group, one for the ALB	ALB reaches instances on the bridge-mode ephemeral range `49152-65535`
Separate migration task	One per runner (`allowAllOutbound: false`)	Explicit egress to each declared peer, plus HTTPS for the ECR and Fargate agent

Opening Access Between Resources

Declare the resource on a service’s connections array. Fjall calls allowToDefaultPort on the target’s connections, so the database opens its port to that service only.

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

app.addCompute(
  ComputeFactory.build("Api", {
    type: "ecs",
    cluster: { domain: "api.example.com" },
    services: [
      {
        name: "api",
        capacityProvider: "FARGATE",
        containers: [{ port: 3000 }],
        connections: [database, jobsQueue],
      },
    ],
  }),
);

Connections dispatch by target type. Relational databases and security-group connectors produce ingress rules. Storage buckets, DynamoDB tables and queues produce IAM grants on the task role instead. A connector declaring additionalTcpPorts opens those extra ports on the same group.

Import

Every example below assumes these imports.

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

Basic Usage

const apiSg = new SecurityGroup(this, "ApiSecurityGroup", {
  vpc,
  description: "Security group for the API service",
});

Omit description and the group is described as ApiSecurityGroup Security Group.

Configuration Options

Property	Type	Description	Default
`vpc`	`IVpc`	VPC the group belongs to	Required
`description`	`string`	Security group description	`<id> Security Group`
`securityGroupName`	`string`	Physical name	CloudFormation-generated
`allowAllOutbound`	`boolean`	Single egress rule permitting all IPv4 traffic	`true`
`allowAllIpv6Outbound`	`boolean`	Single egress rule permitting all IPv6 traffic	`false`
`disableInlineRules`	`boolean`	Emit rules as standalone CloudFormation resources	`false`

Every other ec2.SecurityGroupProps field passes through unchanged.

Default Behaviour

Inbound: nothing is allowed. Add each ingress rule explicitly.
Outbound: all IPv4 traffic is allowed. Set allowAllOutbound: false to lock it down.
Rules are inlined into the AWS::EC2::SecurityGroup resource unless disableInlineRules is true.

Adding Rules

Use addIngressRule and addEgressRule for static rules, and the connections interface when both sides are CDK constructs.

const albSg = new SecurityGroup(this, "AlbSecurityGroup", {
  vpc,
  description: "Public load balancer",
});

albSg.addIngressRule(
  ec2.Peer.anyIpv4(),
  ec2.Port.tcp(443),
  "HTTPS from the internet",
);

const webSg = new SecurityGroup(this, "WebSecurityGroup", {
  vpc,
  description: "Web tier",
});

webSg.addIngressRule(albSg, ec2.Port.tcp(3000), "Traffic from the ALB");

const dashboardSg = new SecurityGroup(this, "DashboardSecurityGroup", {
  vpc,
  description: "Dashboard tier",
});

// connections opens the rule on both sides
dashboardSg.connections.allowTo(
  webSg,
  ec2.Port.tcp(3000),
  "Dashboard to web API",
);

Give every rule a description. It is the only record of why the rule exists once the stack is deployed.

Restricting Outbound Traffic

const workerSg = new SecurityGroup(this, "WorkerSecurityGroup", {
  vpc,
  description: "Background worker",
  allowAllOutbound: false,
});

workerSg.addEgressRule(
  ec2.Peer.anyIpv4(),
  ec2.Port.tcp(443),
  "HTTPS to AWS service endpoints",
);

workerSg.addEgressRule(ec2.Peer.anyIpv4(), ec2.Port.udp(53), "DNS queries");

Port Ranges and Protocols

webSg.addIngressRule(
  albSg,
  ec2.Port.tcpRange(8000, 8999),
  "Application port range",
);

webSg.addIngressRule(albSg, ec2.Port.udp(500), "IPSec");

Prefer the ec2.Port factory methods (tcp, udp, tcpRange, allTcp, allTraffic). The new ec2.Port({ ... }) constructor also requires a stringRepresentation field.

Prefix Lists

Managed prefix-list IDs are opaque and region-specific, so look yours up rather than hardcoding a name.

fjall aws exec --target production-use1 -- \
  aws ec2 describe-managed-prefix-lists \
  --filters "Name=prefix-list-name,Values=com.amazonaws.us-east-1.s3"

webSg.addEgressRule(
  ec2.Peer.prefixList("pl-63a5400a"),
  ec2.Port.tcp(443),
  "HTTPS to S3 via the gateway endpoint",
);

Least Privilege

Instead of	Write
`ec2.Peer.anyIpv4()` with `ec2.Port.allTraffic()`	The specific peer group and the single port it needs
A CIDR block for an internal caller	The caller’s security group as the peer
`allowAllOutbound: true` on a database or worker	`allowAllOutbound: false` plus explicit egress rules

Referencing another security group rather than a CIDR keeps rules correct when instances scale or IPs change.

Troubleshooting

Symptom	Check
Connection times out	Both sides. Egress on the caller and ingress on the target are separate rules
`Circular dependency between resources`	Two groups referencing each other. See the cross-stack note below
Rule count rejected at deploy	The default quota is 60 inbound and 60 outbound rules per group, adjustable in AWS
Ping or traceroute fails while TCP works	ICMP needs its own rule (`ec2.Port.icmpPing()`)

Cross-Stack References

Adding an ingress rule to a security group that lives in another stack makes that stack reference back into yours, which CloudFormation rejects as a cycle. Import the peer into the local stack first, which is what Fjall does for separate migration tasks.

// databaseSg is a SecurityGroup declared in another stack
const localPeer = SecurityGroup.fromSecurityGroupId(
  this,
  "DatabasePeer",
  databaseSg.securityGroupId,
  { mutable: true },
);

localPeer.addIngressRule(workerSg, ec2.Port.tcp(5432), "Worker to database");

Inspecting Deployed Rules

# Resolve your deployment targets
fjall target list

# List a group's rules with Fjall-minted credentials
fjall aws exec --target production-use1 -- \
  aws ec2 describe-security-group-rules \
  --filters "Name=group-id,Values=sg-0123456789abcdef0"

Next Steps

VPC

Define the network the security group attaches to.

ECS Cluster

Declare services and their connections array.

RDS Instance

Restrict database access to the tiers that need it.

Lambda Function

Place functions inside a secured VPC.

Compute Resources

Database Resources

Storage Resources

Networking Resources

Messaging Resources

Security Resources

Security Group

Overview

What Fjall Creates

Opening Access Between Resources

Import

Basic Usage

Configuration Options

Default Behaviour

Adding Rules

Restricting Outbound Traffic

Port Ranges and Protocols

Prefix Lists

Least Privilege

Troubleshooting

Cross-Stack References

Inspecting Deployed Rules

Next Steps

VPC

ECS Cluster

RDS Instance

Lambda Function

​Overview

​What Fjall Creates

​Opening Access Between Resources

​Import

​Basic Usage

​Configuration Options

​Default Behaviour

​Adding Rules

​Restricting Outbound Traffic

​Port Ranges and Protocols

​Prefix Lists

​Least Privilege

​Troubleshooting

​Cross-Stack References

​Inspecting Deployed Rules

​Next Steps

VPC

ECS Cluster

RDS Instance

Lambda Function

Overview

What Fjall Creates

Opening Access Between Resources

Import

Basic Usage

Configuration Options

Default Behaviour

Adding Rules

Restricting Outbound Traffic

Port Ranges and Protocols

Prefix Lists

Least Privilege

Troubleshooting

Cross-Stack References

Inspecting Deployed Rules

Next Steps