Fjall Docs — Deploy Production-Ready AWS Infrastructure in Minutes

Overview

The ECS Cluster resource deploys containerised applications on AWS ECS with a multi-service architecture. A single cluster hosts one or more services that share a load balancer. Each service specifies its own capacity provider (“FARGATE”, “FARGATE_SPOT”, or “EC2”), containers, CPU/memory, and scaling rules.

Resource Class

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

EcsCluster is the default export from the module.

Basic Usage

Single Service

const cluster = new EcsCluster(this, "WebCluster", {
  clusterName: "WebCluster",
  ecrRepository: ecr,
  services: [
    {
      name: "web",
      capacityProvider: "FARGATE",
      containers: [{ name: "app", port: 3000 }],
    },
  ],
});

Multi-Service with Routing

const cluster = new EcsCluster(this, "ApiCluster", {
  clusterName: "ApiCluster",
  ecrRepository: ecr,
  cluster: { domain: "api.example.com" },
  services: [
    {
      name: "users",
      capacityProvider: "FARGATE",
      containers: [{ name: "app", port: 3000 }],
      routing: { path: "/users/*" },
    },
    {
      name: "orders",
      capacityProvider: "FARGATE",
      containers: [{ name: "app", port: 3001 }],
      routing: { path: "/orders/*" },
    },
  ],
});

Worker Cluster (No Load Balancer)

const cluster = new EcsCluster(this, "Workers", {
  clusterName: "Workers",
  ecrRepository: ecr,
  cluster: { loadBalancer: false },
  services: [
    {
      name: "processor",
      capacityProvider: "FARGATE",
      containers: [{ name: "worker" }],
    },
  ],
});

Cluster Props

Property	Type	Description	Default
`clusterName`	`string`	Cluster name	Required
`ecrRepository`	`Repository \| RepositoryImage \| string`	Default container image	Required
`services`	`EcsServiceProps[]`	Services to deploy	Required
`vpc`	`IVpc`	VPC for deployment	-
`appName`	`string`	App name for SSM secrets namespace	-
`cluster`	`EcsClusterClusterConfig`	Cluster-level config (domain, ALB)	-

Cluster Configuration

Property	Type	Description	Default
`cluster.domain`	`string`	Domain for HTTPS access	-
`cluster.loadBalancer`	`false \| "public" \| "internal"`	ALB configuration	`"public"`
`cluster.directAccess`	`boolean`	Direct EC2 access without ALB (EC2 only)	`false`
`cluster.domainConfig`	`DomainConfig`	Advanced routing policy	-

Service Props

Each service in the services array has these properties:

Property	Type	Description	Default
`name`	`string`	Service name (unique within cluster)	Required
`capacityProvider`	`"FARGATE" \| "FARGATE_SPOT" \| "EC2"`	Capacity provider	Required
`containers`	`EcsClusterContainerConfig[]`	Container definitions	Required
`cpu`	`number`	CPU units (256-4096)	`256`
`memoryLimitMiB`	`number`	Memory in MiB (512-30720)	`512`
`desiredCount`	`number`	Desired number of tasks	`2`
`scalingType`	`ScalingType`	CPU or Memory auto-scaling	-
`minCapacity`	`number`	Minimum tasks for scaling	Tracks `desiredCount`
`maxCapacity`	`number`	Maximum tasks for scaling	`Math.max(desiredCount + 1, 3)`
`routing`	`EcsRoutingConfig \| EcsRoutingConfig[]`	ALB routing rules	-
`image`	`string \| Repository`	Service-specific image	Cluster default
`connections`	`ConnectionSpec[]`	Resources to connect to	-
`taskRoleInlinePolicies`	`{ [name: string]: PolicyDocument }`	Additional task role policies	-
`taskRoleManagedPolicies`	`IManagedPolicy[]`	Managed policies for task role	-
`ec2Config`	`Ec2CapacityConfig`	EC2 capacity settings (EC2 only)	-
`ssmSecretsPath`	`string`	SSM secrets base path	`/<appName>/<clusterName>/<service>`
`dockerTarget`	`string`	Docker build target stage	-

Routing Configuration

Property	Type	Description	Default
`path`	`string`	Path pattern (e.g., “/api/*”)	-
`host`	`string`	Host header (e.g., “api.example.com”)	-
`priority`	`number`	Rule priority (1-50000, lower = higher)	Auto-assigned
`healthCheckPath`	`string`	Target group health check path	`"/"`

Container Configuration

Each container in the containers array has these properties:

Property	Type	Description	Default
`name`	`string`	Container name	Required
`port`	`number`	Port the container listens on	-
`image`	`string \| Repository`	Container image	Cluster default ECR
`environment`	`Record<string, string>`	Environment variables	-
`secrets`	`string[]`	SSM Parameter Store secret names	-
`secretsImport`	`{ [key: string]: SecretImport }`	Secrets Manager imports	-
`command`	`string[]`	Container command	-
`entryPoint`	`string[]`	Container entry point	-
`essential`	`boolean`	Stop task if this container stops	`true`
`healthCheck`	`object`	Health check configuration	Auto for primary

The first container with a port is the primary container and receives load balancer traffic. All other containers act as sidecars.

Capacity Providers

FARGATE

Serverless containers. No infrastructure to manage.

{
  name: "api",
  capacityProvider: "FARGATE",
  cpu: 512,
  memoryLimitMiB: 1024,
  containers: [{ name: "app", port: 3000 }]
}

FARGATE_SPOT

Up to 70% cheaper than standard Fargate. Tasks may be interrupted.

{
  name: "batch",
  capacityProvider: "FARGATE_SPOT",
  cpu: 1024,
  memoryLimitMiB: 2048,
  containers: [{ name: "worker" }]
}

EC2

Run containers on EC2 instances you control.

{
  name: "gpu-worker",
  capacityProvider: "EC2",
  ec2Config: {
    instanceType: "t4g.micro",   // Default: "t4g.micro"
    minCapacity: 1,
    maxCapacity: 3,
    desiredCapacity: 2,
    memoryLimitMiB: 1024
  },
  containers: [{ name: "worker" }]
}

Auto-Scaling

CPU-Based Scaling

{
  name: "api",
  capacityProvider: "FARGATE",
  containers: [{ name: "app", port: 3000 }],
  scalingType: ScalingType.CPU,
  minCapacity: 2,
  maxCapacity: 20
}

Memory-Based Scaling

{
  name: "cache",
  capacityProvider: "FARGATE",
  containers: [{ name: "app", port: 8080 }],
  scalingType: ScalingType.MEMORY,
  minCapacity: 1,
  maxCapacity: 10
}

Secrets and Environment Variables

Environment Variables

{
  name: "api",
  capacityProvider: "FARGATE",
  containers: [{
    name: "app",
    port: 3000,
    environment: {
      NODE_ENV: "production",
      LOG_LEVEL: "info"
    }
  }]
}

SSM Parameter Store Secrets

{
  name: "api",
  capacityProvider: "FARGATE",
  ssmSecretsPath: "/myapp/api-cluster/api",
  containers: [{
    name: "app",
    port: 3000,
    secrets: ["API_KEY", "DB_PASSWORD"]
  }]
}

Secrets Manager Imports

{
  name: "api",
  capacityProvider: "FARGATE",
  containers: [{
    name: "app",
    port: 3000,
    secretsImport: {
      DB_PASSWORD: { name: "prod/database", field: "password" }
    }
  }]
}

Multi-Container Tasks

The first container with a port is the primary container. Additional containers run as sidecars.

{
  name: "api",
  capacityProvider: "FARGATE",
  cpu: 512,
  memoryLimitMiB: 1024,
  containers: [
    {
      name: "app",
      port: 3000,
      environment: { NODE_ENV: "production" }
    },
    {
      name: "datadog",
      image: "datadog/agent:latest",
      environment: { DD_API_KEY: "..." }
    }
  ]
}

Connections

Services can declare resources they need to connect to. The construct creates security group rules for network resources and IAM grants for storage resources.

{
  name: "api",
  capacityProvider: "FARGATE",
  containers: [{ name: "app", port: 3000 }],
  connections: [
    database,                              // Security group (RDS)
    { resource: cache, access: "read" },   // Read-only DynamoDB
    { resource: bucket, access: "write" }, // Write-only S3
    { resource: queue, access: "consume" } // Consume-only SQS
  ]
}

Methods

Get Load Balancer

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

Get Service

const service = cluster.getService("api");
// Returns: FargateService | Ec2Service | undefined

Get All Services

const services = cluster.getServices();
// Returns: Map<string, FargateService | Ec2Service>

Get Cluster

const cdkCluster = cluster.getCluster();
// Returns: Cluster (CDK ECS Cluster)

Get URL

const url = cluster.getUrl();
// Returns: "https://api.example.com" or "http://..." or undefined

Complete Example

import EcsCluster, {
  ScalingType,
} from "@fjall/components-infrastructure/lib/resources/aws/compute/ecs";
import { Repository } from "aws-cdk-lib/aws-ecr";

const repo = new Repository(this, "AppRepo");

const cluster = new EcsCluster(this, "ProductionCluster", {
  clusterName: "prod-cluster",
  ecrRepository: repo,
  vpc: vpc,
  appName: "myapp",
  cluster: {
    domain: "api.example.com",
    loadBalancer: "public",
  },
  services: [
    {
      name: "api",
      capacityProvider: "FARGATE",
      cpu: 1024,
      memoryLimitMiB: 2048,
      scalingType: ScalingType.CPU,
      minCapacity: 2,
      maxCapacity: 10,
      containers: [
        {
          name: "app",
          port: 8080,
          environment: {
            NODE_ENV: "production",
            PORT: "8080",
          },
          secrets: ["API_KEY"],
        },
      ],
      routing: { path: "/api/*", healthCheckPath: "/health" },
      connections: [database],
    },
    {
      name: "worker",
      capacityProvider: "FARGATE_SPOT",
      cpu: 512,
      memoryLimitMiB: 1024,
      containers: [{ name: "worker" }],
      connections: [queue, database],
    },
  ],
});

Best Practices

Use FARGATE for production workloads requiring isolation
Use FARGATE_SPOT for batch processing and fault-tolerant workloads
Set appropriate CPU/memory based on application needs
Enable auto-scaling for production with min 2 tasks
Use secrets for sensitive data, not environment variables
Configure routing when deploying multiple services with ports
Use connections for declarative resource access

Next Steps

Compute Factory

Provision an ECS cluster through the higher-level compute factory pattern.

Application Load Balancer

Configure the ALB that fronts your cluster services.

ECR Repository

Store the container images your services pull at deploy time.

Security Group

Control network access to and from your ECS services.

​Overview

​Resource Class

​Basic Usage

​Single Service

​Multi-Service with Routing

​Worker Cluster (No Load Balancer)

​Cluster Props

​Cluster Configuration

​Service Props

​Routing Configuration

​Container Configuration

​Capacity Providers

​FARGATE

​FARGATE_SPOT

​EC2

​Auto-Scaling

​CPU-Based Scaling

​Memory-Based Scaling

​Secrets and Environment Variables

​Environment Variables

​SSM Parameter Store Secrets

​Secrets Manager Imports

​Multi-Container Tasks

​Connections

​Methods

​Get Load Balancer

​Get Service

​Get All Services

​Get Cluster

​Get URL

​Complete Example

​Best Practices

​Next Steps