Fjall Docs — deploy AWS infrastructure into your own account

Overview

Fjall provisions an Application Load Balancer (ALB) automatically inside an ECS cluster. You do not create the ALB directly. You declare an ECS cluster, and the cluster builds one shared ALB for all of its services. The ALB operates at Layer 7 and distributes incoming traffic across tasks in multiple Availability Zones.

Behaviour	Detail
Creation	Automatic when a cluster has a service with a port
Sharing	One ALB per cluster, shared across services
Disable	Set `cluster.loadBalancer: false` for internal-only workers
HTTPS	Implied when `cluster.domain` is set and a hosted zone source resolves
Listener	One listener: port 443 with a certificate, port 80 without

Recommended Entry Point

Use ComputeFactory.build() to declare ECS compute. The factory validates props, wires defaults, and returns a construct you add to your application.

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

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

With cluster.domain set, the ALB serves HTTPS on port 443 and gets a Route 53 A record in the resolved hosted zone.

The domain needs a hosted zone source

Fjall never creates a hosted zone inside an application stack, so cluster.domain must name a zone that already exists. Synth throws when it cannot resolve one.

Zone source	How it resolves
Managed domain (default)	`fjall deploy` injects the binding for a domain declared under `fjall/domains/`. Certificate imported by ARN.
`domainConfig.managedDomain`	An explicit binding beats the injected one. Use the export-name form for bare-CDK synth.
`domainConfig.hostedZone`	`HostedZoneFactory.import(stack, hostedZoneId, zoneName)`. The cluster mints its own ACM certificate, validated by DNS in that zone.

A bare cdk synth outside the CLI has no injected binding, so it needs one of the two explicit forms. See Domain for how managed domains are declared and bound.

There is no HTTP-to-HTTPS redirect listener. The cluster creates exactly one listener. Permanent 301 redirects come from domainConfig.redirectHosts, which adds host-header rules on the HTTPS listener.

Direct EcsCluster Usage

For lower-level control, instantiate EcsCluster directly. The props shape nests cluster-wide settings under cluster and lists services under services.

import { EcsCluster } from "@fjall/components-infrastructure/lib/resources/aws/compute/ecs";

const cluster = new EcsCluster(this, "MyCluster", {
  clusterName: "my-cluster",
  vpc,
  ecrRepository: "my-app",
  cluster: {
    domain: "api.example.com",
  },
  services: [
    {
      name: "api",
      capacityProvider: "FARGATE",
      containers: [{ port: 3000 }],
    },
  ],
});

// getLoadBalancer() returns ApplicationLoadBalancer | undefined
const alb = cluster.getLoadBalancer();

getLoadBalancer() returns undefined when the ALB is disabled (cluster.loadBalancer: false or cluster.directAccess: true). Guard the result before use. getListener() returns the matching ApplicationListener | undefined.

const alb = cluster.getLoadBalancer();
if (alb !== undefined) {
  // safe to read alb.loadBalancerDnsName, etc.
}

Cluster Configuration

The cluster object controls the shared ALB for every service.

Field	Type	Description
`domain`	`string`	Domain for HTTPS access. Omit for default `*.elb.amazonaws.com` DNS.
`loadBalancer`	`false \| "public" \| "internal"`	`"public"` (default) internet-facing, `"internal"` VPC-only, `false` no ALB.
`directAccess`	`boolean`	EC2-only. Opens container ports directly, no ALB.
`domainConfig`	`DomainConfig`	Zone source, certificate, redirect hosts, and Route 53 routing policy.

// Public ALB with HTTPS (default loadBalancer is "public")
cluster: { domain: "app.example.com" }

// Internal ALB, reachable only inside the VPC
cluster: { loadBalancer: "internal", domain: "internal.example.com" }

// No ALB, for background workers
cluster: { loadBalancer: false }

Service and Health Checks

Each entry in services gets its own task definition and target group, all registered behind the cluster ALB. The first container with a port is the primary container that receives ALB traffic.

services: [
  {
    name: "api",
    capacityProvider: "FARGATE",
    containers: [
      {
        name: "app",
        port: 8080,
        healthCheck: {
          command: [
            "CMD-SHELL",
            "curl -f http://localhost:8080/health || exit 1",
          ],
          interval: 30,
          timeout: 10,
          retries: 3,
        },
      },
    ],
  },
];

The container healthCheck above runs inside the task. The ALB target group runs a separate HTTP health check, configured automatically per service:

Target-group setting	Fargate service	EC2 service
Path	`routing.healthCheckPath`, default `/`	Same
Port	The container port	`traffic-port`
Interval	120 seconds	30 seconds
Timeout	10 seconds	15 seconds
Healthy threshold	AWS default	3
Unhealthy threshold	AWS default	3

Multiple Services and Routing

When a cluster has more than one service with a port, each service needs a routing rule so the ALB knows which traffic to send where. Routing supports path patterns and host headers.

app.addCompute(
  ComputeFactory.build("ApiCluster", {
    type: "ecs",
    cluster: { domain: "api.example.com" },
    services: [
      {
        name: "users",
        capacityProvider: "FARGATE",
        containers: [{ port: 3000 }],
        routing: { path: "/users/*", priority: 100 },
      },
      {
        name: "orders",
        capacityProvider: "FARGATE",
        containers: [{ port: 3001 }],
        routing: { path: "/orders/*", priority: 200 },
      },
    ],
  }),
);

Routing field	Type	Description
`path`	`string`	Path pattern, e.g. `/api/*`.
`host`	`string`	Host header, e.g. `api.example.com`.
`priority`	`number`	1 to 50000. Lower wins.
`healthCheckPath`	`string`	Target-group health-check path. Default `/`.

routing also accepts an array of rules. Every rule maps to the same target group, so one service can answer several paths or hosts.

routing: [{ path: "/api/*" }, { host: "api.example.com" }];

Rules with no explicit priority are numbered automatically from 100 upwards. A single port-bearing service with at most one rule skips rules entirely and becomes the listener’s default action. Any other shape gives the listener a fixed 404 Not Found default, so unmatched requests fail cleanly instead of hitting an arbitrary service. Each routing.host must sit inside the cluster’s hosted zone. Synth throws for a host outside it, because its alias record and certificate SAN cannot be created there and TLS would fail after a green deploy.

Default ALB Settings

Fjall configures the cluster ALB with these defaults.

Setting	Value
Scheme	Internet-facing (`loadBalancer: "public"`, the default), internal for `"internal"`
Subnets	Public subnets when internet-facing, private-with-egress subnets when internal
Invalid header fields	Dropped (`dropInvalidHeaderFields: true`, Security Hub control ELB.4)
Idle timeout	60 seconds, pinned (see Keep-alive and the idle timeout)
Listener port	443 when a certificate resolves, otherwise 80
TLS policy	`ELBSecurityPolicy-TLS13-1-2-2021-06` on HTTPS listeners. TLS 1.0 and 1.1 clients are dropped.
IP address type	IPv4
Deletion protection	Disabled
Cross-zone load balancing	Always on for an ALB
Security group	Auto-created for Fargate-only clusters, paired with the EC2 ASG when a service uses EC2 capacity

Keep-Alive and the Idle Timeout

The ALB holds idle keep-alive connections to your containers open for up to its idle timeout and reuses them freely. Node’s default server.keepAliveTimeout is 5 seconds, far below the ALB’s 60, so the ALB can reuse a connection at the exact moment your server closes it. The symptom is intermittent, ALB-generated 502s that never appear in your application logs. The fix is server-side, and it is two timeouts:

Your server’s keep-alive timeout must exceed the ALB idle timeout, so the ALB always closes idle connections first.
Your server’s headers timeout must exceed its keep-alive timeout, so a request that starts arriving just before the keep-alive deadline is not truncated mid-headers.

Fjall pins every cluster ALB’s idle timeout to 60 seconds and injects that value into the ALB-registered container (the first container with a port) as the environment variable FJALL_ALB_IDLE_TIMEOUT_SECONDS. Services without an ALB (loadBalancer: false or directAccess: true) do not receive it, because there is no ALB to race.

Node servers

Install @fjall/util and apply the timeouts to the http.Server after listen():

import { applyAlbKeepAliveTimeouts } from "@fjall/util/httpKeepAlive";

// Express, Fastify's server property, or a bare node:http server.
// Anything exposing keepAliveTimeout and headersTimeout works.
const server = app.listen(process.env.PORT ?? 3000);
applyAlbKeepAliveTimeouts(server);

The helper reads FJALL_ALB_IDLE_TIMEOUT_SECONDS and sets keepAliveTimeout to the idle timeout plus a 5-second margin and headersTimeout one second above that (65 s and 66 s at the default). It returns the applied values in case you want to log them.

Variable absent (local development, images deployed before Fjall injected it): the helper assumes the AWS default of 60 seconds, which yields the same timeouts.
Variable malformed: the helper throws at boot. This is deliberate, because a misconfigured contract should fail loudly at startup rather than race the ALB in production.

resolveAlbKeepAliveTimeouts() returns the same values without touching a server, for runtimes that set the timeouts themselves.

Other runtimes

Read FJALL_ALB_IDLE_TIMEOUT_SECONDS (assume 60 when unset) and set your server’s keep-alive timeout above it:

Runtime	Setting
Gunicorn (Python)	`--keep-alive 65`
Uvicorn (Python)	`--timeout-keep-alive 65`
Go `net/http`	`IdleTimeout: 65 * time.Second`
nginx	`keepalive_timeout 65s;`

Outputs

The cluster emits five CloudFormation outputs for the ALB. Output keys use the cluster name in PascalCase.

Output key	Value
`<Cluster>LoadBalancerDnsName`	ALB DNS name.
`<Cluster>LoadBalancerUrl`	`https://<domain>` when a domain is set, otherwise `http://<alb-dns-name>`.
`<Cluster>LoadBalancerArn`	ALB ARN, for monitoring.
`<Cluster>AlbDnsName`	ALB DNS name, consumed by Domain alias targets.
`<Cluster>AlbHostedZoneId`	ALB canonical hosted zone ID, consumed by Domain alias targets.

Export names are not the output keys. CloudFormation export names are unique per account per region, so Fjall qualifies them:

Output	Export name
`LoadBalancerDnsName`, `LoadBalancerUrl`, `LoadBalancerArn`	`<StackName><clusterName><Suffix>`
`AlbDnsName`, `AlbHostedZoneId`	`<appName>-<computeName>-<Suffix>`

The stack-name prefix is added automatically. Build a cross-stack Fn.importValue from the export name, never from the output key.

// Stack "MyAppCompute", cluster "web"
// Output key:  WebLoadBalancerDnsName
// Export name: MyAppComputewebLoadBalancerDnsName
Fn.importValue("MyAppComputewebLoadBalancerDnsName");

When an application fronts exactly one ALB, Fjall also emits the unqualified application-level pair (<appName>AlbDnsName, <appName>AlbHostedZoneId) so a Domain can alias it without naming the compute.

Cost

Component	Approximate cost
ALB hour	~$0.0225/hour
LCU hour	~$0.008/LCU

Load Balancer Capacity Units (LCUs) bill on the highest of new connections, active connections, processed bytes, and rule evaluations. Save cost by:

Consolidating services behind one cluster ALB with path or host routing.
Disabling the ALB (loadBalancer: false) for services that never receive external traffic.
Keeping health-check frequency reasonable for the workload.

Troubleshooting

Symptom	Check
Unhealthy targets	Security group rules and the target-group health-check path (`routing.healthCheckPath`, default `/`)
502 errors	Server keep-alive timeout below the ALB idle timeout (see keep-alive)
404 on every path	Two or more port-bearing services with no matching `routing` rule, so the listener’s fixed 404 default answers
Synth throws on `domain`	`cluster.domain` names no hosted zone source, or the domain sits outside the resolved zone
Slow responses	ALB target-response-time metrics
Certificate errors	`cluster.domain` and every `routing.host` are covered by the resolved certificate. Fjall cannot add SANs to an imported one.

Inspect the deployed ALB with Fjall-minted credentials:

# Describe the load balancer
fjall aws exec --app my-app -- aws elbv2 describe-load-balancers --names my-cluster-LoadBalancer

# Check target health
fjall aws exec --app my-app -- aws elbv2 describe-target-health --target-group-arn arn:aws:elasticloadbalancing:...

# View listeners
fjall aws exec --app my-app -- aws elbv2 describe-listeners --load-balancer-arn arn:aws:elasticloadbalancing:...

Next Steps

ECS Cluster

Configure the cluster that owns the load balancer.

Domain

Declare the hosted zone and certificate the ALB serves HTTPS from.

VPC

Choose the network the ALB and tasks run in.

Security Group

Control inbound and outbound traffic to the ALB.

Compute Factory

Declare ECS compute with the recommended factory entry point.

Compute Resources

Database Resources

Storage Resources

Networking Resources

Messaging Resources

Security Resources

Application Load Balancer

Overview

Recommended Entry Point

The domain needs a hosted zone source

Direct EcsCluster Usage

Cluster Configuration

Service and Health Checks

Multiple Services and Routing

Default ALB Settings

Keep-Alive and the Idle Timeout

Node servers

Other runtimes

Outputs

Cost

Troubleshooting

Next Steps

ECS Cluster

Domain

VPC

Security Group

Compute Factory

​Overview

​Recommended Entry Point

​The domain needs a hosted zone source

​Direct EcsCluster Usage

​Cluster Configuration

​Service and Health Checks

​Multiple Services and Routing

​Default ALB Settings

​Keep-Alive and the Idle Timeout

​Node servers

​Other runtimes

​Outputs

​Cost

​Troubleshooting

​Next Steps

ECS Cluster

Domain

VPC

Security Group

Compute Factory

Overview

Recommended Entry Point

The domain needs a hosted zone source

Direct EcsCluster Usage

Cluster Configuration

Service and Health Checks

Multiple Services and Routing

Default ALB Settings

Keep-Alive and the Idle Timeout

Node servers

Other runtimes

Outputs

Cost

Troubleshooting

Next Steps