@fjall/components-infrastructure 0.89.5 → 0.89.6

package/dist/lib/resources/aws/compute/ecsCapacityProviderAspect.d.ts

@@ -0,0 +1,22 @@
+import { type Cluster as CdkCluster } from "aws-cdk-lib/aws-ecs";
+import type { IAspect } from "aws-cdk-lib";
+import type { IConstruct } from "constructs";
+/**
+ * CDK Aspect that fixes capacity provider deletion dependencies.
+ *
+ * This is a workaround for CDK bug #15366 where ECS services don't properly
+ * depend on CfnClusterCapacityProviderAssociations, causing "capacity provider
+ * is in use" errors during stack deletion.
+ *
+ * The aspect runs at synth time (when associations exist) and adds:
+ * - Service depends on CfnClusterCapacityProviderAssociations
+ *
+ * DELETE order becomes: Services -> Associations -> Cluster
+ *
+ * @see https://github.com/aws/aws-cdk/issues/15366
+ */
+export declare class CapacityProviderDependencyAspect implements IAspect {
+    private readonly cluster;
+    constructor(cluster: CdkCluster);
+    visit(node: IConstruct): void;
+}

package/dist/lib/resources/aws/compute/ecsCapacityProviderAspect.js

@@ -0,0 +1,35 @@
+import { FargateService, Ec2Service, CfnClusterCapacityProviderAssociations } from "aws-cdk-lib/aws-ecs";
+/**
+ * CDK Aspect that fixes capacity provider deletion dependencies.
+ *
+ * This is a workaround for CDK bug #15366 where ECS services don't properly
+ * depend on CfnClusterCapacityProviderAssociations, causing "capacity provider
+ * is in use" errors during stack deletion.
+ *
+ * The aspect runs at synth time (when associations exist) and adds:
+ * - Service depends on CfnClusterCapacityProviderAssociations
+ *
+ * DELETE order becomes: Services -> Associations -> Cluster
+ *
+ * @see https://github.com/aws/aws-cdk/issues/15366
+ */
+export class CapacityProviderDependencyAspect {
+    cluster;
+    constructor(cluster) {
+        this.cluster = cluster;
+    }
+    visit(node) {
+        // Find ECS services that belong to this cluster
+        if (node instanceof FargateService || node instanceof Ec2Service) {
+            // Find CfnClusterCapacityProviderAssociations in the cluster's descendants
+            const associations = this.cluster.node
+                .findAll()
+                .find((child) => child instanceof CfnClusterCapacityProviderAssociations);
+            if (associations) {
+                // Add dependency: Service -> Associations
+                // DELETE order: Service deleted first, then Associations
+                node.node.addDependency(associations);
+            }
+        }
+    }
+}

package/dist/lib/resources/aws/compute/ecsConstants.d.ts

@@ -0,0 +1,20 @@
+import { AmiHardwareType } from "aws-cdk-lib/aws-ecs";
+export declare const DEFAULT_EC2_INSTANCE_TYPE = "t4g.micro";
+export declare const DEFAULT_WARM_POOL_MIN_SIZE = 1;
+export declare const DEFAULT_WARM_POOL_REUSE_ON_SCALE_IN = true;
+export declare const DEFAULT_LOG_RETENTION_DAYS = 14;
+/**
+ * Instance type prefixes that use ARM64 architecture (Graviton processors).
+ * All other prefixes are assumed to be x86-64 (STANDARD).
+ *
+ * Keep in sync with @fjall/generator schemas/instanceTypeArchitecture.ts
+ */
+export declare const ARM_INSTANCE_PREFIXES: string[];
+/**
+ * Infer the AMI hardware type from an EC2 instance type.
+ * Uses the instance type prefix to determine if it's ARM (Graviton) or x86-64.
+ *
+ * @param instanceType - EC2 instance type (e.g., "t4g.micro", "t3.small")
+ * @returns AmiHardwareType.ARM for Graviton instances, AmiHardwareType.STANDARD for Intel/AMD
+ */
+export declare function inferAmiHardwareType(instanceType: string): AmiHardwareType;

package/dist/lib/resources/aws/compute/ecsConstants.js

@@ -0,0 +1,49 @@
+import { AmiHardwareType } from "aws-cdk-lib/aws-ecs";
+// Canonical source: @fjall/generator schemas/constants.ts — keep in sync
+export const DEFAULT_EC2_INSTANCE_TYPE = "t4g.micro";
+export const DEFAULT_WARM_POOL_MIN_SIZE = 1;
+export const DEFAULT_WARM_POOL_REUSE_ON_SCALE_IN = true;
+// 14 days balances cost against retaining enough history for post-mortem debugging
+export const DEFAULT_LOG_RETENTION_DAYS = 14;
+/**
+ * Instance type prefixes that use ARM64 architecture (Graviton processors).
+ * All other prefixes are assumed to be x86-64 (STANDARD).
+ *
+ * Keep in sync with @fjall/generator schemas/instanceTypeArchitecture.ts
+ */
+export const ARM_INSTANCE_PREFIXES = [
+    "t4g",
+    "c6g",
+    "c6gd",
+    "c6gn",
+    "c7g",
+    "c7gd",
+    "c7gn",
+    "r6g",
+    "r6gd",
+    "r7g",
+    "r7gd",
+    "m6g",
+    "m6gd",
+    "m7g",
+    "m7gd",
+    "a1",
+    "x2gd",
+    "im4gn",
+    "is4gen",
+    "i4g",
+    "hpc7g"
+];
+/**
+ * Infer the AMI hardware type from an EC2 instance type.
+ * Uses the instance type prefix to determine if it's ARM (Graviton) or x86-64.
+ *
+ * @param instanceType - EC2 instance type (e.g., "t4g.micro", "t3.small")
+ * @returns AmiHardwareType.ARM for Graviton instances, AmiHardwareType.STANDARD for Intel/AMD
+ */
+export function inferAmiHardwareType(instanceType) {
+    const prefix = instanceType.split(".")[0] ?? instanceType;
+    return ARM_INSTANCE_PREFIXES.includes(prefix)
+        ? AmiHardwareType.ARM
+        : AmiHardwareType.STANDARD;
+}

package/dist/lib/resources/aws/compute/ecsContext.d.ts

@@ -0,0 +1,12 @@
+import type { Construct } from "constructs";
+import type { Cluster as CdkCluster } from "aws-cdk-lib/aws-ecs";
+import type { EcsClusterProps } from "./ecsTypes.js";
+/** Shared state passed from EcsCluster to extracted helper functions. */
+export interface EcsConstructContext {
+    scope: Construct;
+    props: EcsClusterProps;
+    cluster: CdkCluster;
+    outputName: string;
+    loadBalancerDisabled: boolean;
+    directAccessEnabled: boolean;
+}

package/dist/lib/resources/aws/compute/ecsContext.js

@@ -0,0 +1 @@
+export {};

package/dist/lib/resources/aws/compute/ecsImages.d.ts

@@ -0,0 +1,4 @@
+import { ContainerImage } from "aws-cdk-lib/aws-ecs";
+import type { EcsConstructContext } from "./ecsContext.js";
+import type { EcsClusterContainerConfig, EcsServiceProps } from "./ecsTypes.js";
+export declare function getContainerImage(ctx: EcsConstructContext, serviceName: string, containerConfig: EcsClusterContainerConfig, serviceProps: EcsServiceProps): ContainerImage;

package/dist/lib/resources/aws/compute/ecsImages.js

@@ -0,0 +1,35 @@
+import { ContainerImage } from "aws-cdk-lib/aws-ecs";
+import { Repository } from "aws-cdk-lib/aws-ecr";
+export function getContainerImage(ctx, serviceName, containerConfig, serviceProps) {
+    const imageSource = containerConfig.image || serviceProps.image || ctx.props.ecrRepository;
+    if (!imageSource) {
+        return ContainerImage.fromRegistry("amazon/amazon-ecs-sample");
+    }
+    // Build image tag with optional dockerTarget suffix
+    // Format: <service>-[<target>-]<version>
+    // imageVersion comes from CDK context (git SHA) to ensure CloudFormation
+    // detects template changes when new code is deployed. Falls back to 'latest'
+    // for apps without Dockerfiles (welcome image) or local dev.
+    const rawVersion = ctx.scope.node.tryGetContext("imageVersion");
+    const imageVersion = (typeof rawVersion === "string" ? rawVersion : undefined) || "latest";
+    const targetSuffix = serviceProps.dockerTarget
+        ? `-${serviceProps.dockerTarget.toLowerCase()}`
+        : "";
+    const imageTag = `${serviceName.toLowerCase()}${targetSuffix}-${imageVersion}`;
+    if (typeof imageSource === "string") {
+        // Detect full registry URLs vs bare ECR repository names.
+        // Bare names (with or without namespace slashes) are treated as ECR repos.
+        // Docker Hub requires an explicit registry prefix (docker.io/).
+        const isFullRegistryUrl = /^(docker\.io|registry\.hub\.docker\.com|ghcr\.io)\//i.test(imageSource) || // Docker Hub / GHCR URLs
+            imageSource.startsWith("public.ecr.aws/") || // Public ECR: public.ecr.aws/fjall/welcome
+            imageSource.includes(".dkr.ecr."); // Private ECR full URL: 123456789012.dkr.ecr.us-east-2.amazonaws.com/repo:tag
+        if (isFullRegistryUrl) {
+            return ContainerImage.fromRegistry(imageSource);
+        }
+        return ContainerImage.fromEcrRepository(Repository.fromRepositoryName(ctx.scope, `${serviceName}${containerConfig.name}EcrRepo`, imageSource), imageTag);
+    }
+    if (imageSource instanceof Repository) {
+        return ContainerImage.fromEcrRepository(imageSource, imageTag);
+    }
+    return imageSource;
+}

package/dist/lib/resources/aws/compute/ecsNetworking.d.ts

@@ -0,0 +1,28 @@
+import { type ApplicationListener, ApplicationLoadBalancer, type IApplicationTargetGroup, ListenerCondition } from "aws-cdk-lib/aws-elasticloadbalancingv2";
+import { type ICertificate } from "aws-cdk-lib/aws-certificatemanager";
+import { ARecord, type IHostedZone } from "aws-cdk-lib/aws-route53";
+import type { AutoScalingGroup } from "aws-cdk-lib/aws-autoscaling";
+import type { ContainerDefinition, FargateService, Ec2Service } from "aws-cdk-lib/aws-ecs";
+import { SecurityGroup } from "../networking/securityGroup.js";
+import type { EcsConstructContext } from "./ecsContext.js";
+import type { EcsRoutingConfig, EcsServiceProps } from "./ecsTypes.js";
+/** Mutable priority state for ALB rule ordering. */
+export interface PriorityState {
+    nextPriority: number;
+    usedPriorities: Set<number>;
+}
+/** Returns the next unused auto-incremented ALB priority, skipping any manually assigned values. */
+export declare function getNextPriority(state: PriorityState): number;
+export declare function buildRoutingConditions(rule: EcsRoutingConfig | undefined): ListenerCondition[];
+export declare function addLoadBalancer(ctx: EcsConstructContext, anyServiceUsesEc2: boolean, asgSecurityGroup?: SecurityGroup): {
+    loadBalancer: ApplicationLoadBalancer;
+    loadBalancerSecurityGroup?: SecurityGroup;
+};
+export declare function addLoadBalancerListener(ctx: EcsConstructContext, loadBalancer: ApplicationLoadBalancer, certificate?: ICertificate): ApplicationListener;
+export declare function addHostedZone(ctx: EcsConstructContext, loadBalancer?: ApplicationLoadBalancer): {
+    hostedZone?: IHostedZone;
+    certificate?: ICertificate;
+    aRecord?: ARecord;
+};
+export declare function addDirectAccessOutputs(ctx: EcsConstructContext, autoScalingGroup?: AutoScalingGroup): void;
+export declare function registerServiceWithALB(ctx: EcsConstructContext, listener: ApplicationListener, serviceName: string, serviceProps: EcsServiceProps, service: FargateService | Ec2Service, primaryContainer: ContainerDefinition, priorityState: PriorityState): IApplicationTargetGroup;

package/dist/lib/resources/aws/compute/ecsNetworking.js

@@ -0,0 +1,290 @@
+import { ApplicationLoadBalancer, ApplicationProtocol, ListenerAction, ListenerCondition } from "aws-cdk-lib/aws-elasticloadbalancingv2";
+import { Port, SubnetType } from "aws-cdk-lib/aws-ec2";
+import { CfnOutput, Duration, Fn } from "aws-cdk-lib";
+import { Certificate, CertificateValidation } from "aws-cdk-lib/aws-certificatemanager";
+import { ARecord, HostedZone as AWSHostedZone, RecordTarget } from "aws-cdk-lib/aws-route53";
+import { LoadBalancerTarget } from "aws-cdk-lib/aws-route53-targets";
+import { HostedZone as FjallHostedZone } from "../networking/hostedZone.js";
+import { SecurityGroup } from "../networking/securityGroup.js";
+import { isServiceEc2 } from "./ecsTaskDefinition.js";
+/** Returns the next unused auto-incremented ALB priority, skipping any manually assigned values. */
+export function getNextPriority(state) {
+    while (state.usedPriorities.has(state.nextPriority)) {
+        state.nextPriority++;
+    }
+    const priority = state.nextPriority++;
+    state.usedPriorities.add(priority);
+    return priority;
+}
+export function buildRoutingConditions(rule) {
+    const conditions = [];
+    if (rule?.path) {
+        conditions.push(ListenerCondition.pathPatterns([rule.path]));
+    }
+    if (rule?.host) {
+        conditions.push(ListenerCondition.hostHeaders([rule.host]));
+    }
+    return conditions;
+}
+export function addLoadBalancer(ctx, anyServiceUsesEc2, asgSecurityGroup) {
+    const props = ctx.props;
+    const defaultLoadBalancerName = `${props.clusterName}LoadBalancer`;
+    const supportedNameLength = 32;
+    let truncatedLoadBalancerName = defaultLoadBalancerName.length > supportedNameLength
+        ? defaultLoadBalancerName.substring(0, supportedNameLength)
+        : defaultLoadBalancerName;
+    truncatedLoadBalancerName = truncatedLoadBalancerName.replace(/-+$/, "");
+    const isInternal = props.cluster?.loadBalancer === "internal";
+    let loadBalancerSecurityGroup;
+    if (anyServiceUsesEc2) {
+        loadBalancerSecurityGroup = new SecurityGroup(ctx.scope, `${props.clusterName}LoadBalancerSecurityGroup`, {
+            vpc: ctx.cluster.vpc,
+            description: `Security group for the ${props.clusterName} load balancer`
+        });
+        if (asgSecurityGroup) {
+            loadBalancerSecurityGroup.connections.allowTo(asgSecurityGroup, Port.allTcp());
+            // ECS bridge-mode maps container ports to IANA ephemeral range (49152-65535).
+            // The ALB must reach these dynamic ports on the EC2 instances.
+            asgSecurityGroup.connections.allowFrom(loadBalancerSecurityGroup, Port.tcpRange(49152, 65535));
+        }
+    }
+    const loadBalancer = new ApplicationLoadBalancer(ctx.scope, `${props.clusterName}LoadBalancer`, {
+        vpc: ctx.cluster.vpc,
+        internetFacing: !isInternal,
+        ...(loadBalancerSecurityGroup && {
+            securityGroup: loadBalancerSecurityGroup
+        }),
+        loadBalancerName: truncatedLoadBalancerName,
+        vpcSubnets: {
+            subnetType: isInternal
+                ? SubnetType.PRIVATE_WITH_EGRESS
+                : SubnetType.PUBLIC
+        }
+    });
+    new CfnOutput(ctx.scope, `${ctx.outputName}LoadBalancerDnsName`, {
+        key: `${ctx.outputName}LoadBalancerDnsName`,
+        exportName: `${props.clusterName}LoadBalancerDnsName`,
+        value: loadBalancer.loadBalancerDnsName
+    });
+    // Cross-stack exports consumed by the Domain construct's `fjallApp(<name>)`
+    // alias target. Names mirror the consumer contract in `cross-system-parity`.
+    new CfnOutput(ctx.scope, `${ctx.outputName}AlbDnsName`, {
+        key: `${ctx.outputName}AlbDnsName`,
+        exportName: `${ctx.outputName}AlbDnsName`,
+        value: loadBalancer.loadBalancerDnsName,
+        description: `ALB DNS name for ${props.clusterName} (consumed by Domain alias targets)`
+    });
+    new CfnOutput(ctx.scope, `${ctx.outputName}AlbHostedZoneId`, {
+        key: `${ctx.outputName}AlbHostedZoneId`,
+        exportName: `${ctx.outputName}AlbHostedZoneId`,
+        value: loadBalancer.loadBalancerCanonicalHostedZoneId,
+        description: `ALB canonical hosted zone ID for ${props.clusterName}`
+    });
+    const customDomain = props.cluster?.domain || props.cluster?.domainConfig?.domainName;
+    new CfnOutput(ctx.scope, `${ctx.outputName}LoadBalancerUrl`, {
+        key: `${ctx.outputName}LoadBalancerUrl`,
+        exportName: `${props.clusterName}LoadBalancerUrl`,
+        value: customDomain
+            ? `https://${customDomain}`
+            : `http://${loadBalancer.loadBalancerDnsName}`,
+        description: `Load Balancer URL for ${props.clusterName}`
+    });
+    // Export load balancer ARN for monitoring
+    new CfnOutput(ctx.scope, `${ctx.outputName}LoadBalancerArn`, {
+        key: `${ctx.outputName}LoadBalancerArn`,
+        exportName: `${props.clusterName}LoadBalancerArn`,
+        value: loadBalancer.loadBalancerArn,
+        description: `Load Balancer ARN for ${props.clusterName}`
+    });
+    return { loadBalancer, loadBalancerSecurityGroup };
+}
+export function addLoadBalancerListener(ctx, loadBalancer, certificate) {
+    const port = certificate ? 443 : 80;
+    const defaultAction = ListenerAction.fixedResponse(404, {
+        contentType: "text/plain",
+        messageBody: "Not Found"
+    });
+    if (certificate) {
+        return loadBalancer.addListener(`${ctx.props.clusterName}Listener`, {
+            port,
+            certificates: [certificate],
+            defaultAction
+        });
+    }
+    else {
+        return loadBalancer.addListener(`${ctx.props.clusterName}Listener`, {
+            port,
+            defaultAction
+        });
+    }
+}
+export function addHostedZone(ctx, loadBalancer) {
+    const props = ctx.props;
+    const domainConfig = props.cluster?.domainConfig;
+    const simpleDomain = props.cluster?.domain;
+    const domainName = domainConfig?.domainName ?? simpleDomain;
+    if (!domainName)
+        return {};
+    let hostedZone;
+    let certificate;
+    let aRecord;
+    // Managed domain: import zone and cert from domain stack via Fn.importValue
+    if (domainConfig?.managedDomain) {
+        const managed = domainConfig.managedDomain;
+        hostedZone = AWSHostedZone.fromHostedZoneAttributes(ctx.scope, `${props.clusterName}ManagedHostedZone`, {
+            hostedZoneId: Fn.importValue(managed.hostedZoneIdExport),
+            zoneName: managed.zoneName
+        });
+        certificate = Certificate.fromCertificateArn(ctx.scope, `${props.clusterName}ManagedCertificate`, Fn.importValue(managed.certificateArnExport));
+    }
+    else if (!domainConfig?.hostedZone) {
+        const fjallHostedZone = new FjallHostedZone(ctx.scope, `${props.clusterName}HostedZone`, {
+            zoneName: domainName
+        });
+        hostedZone = fjallHostedZone.hostedZone;
+    }
+    else {
+        hostedZone = domainConfig.hostedZone.hostedZone;
+    }
+    if (domainConfig?.certificate) {
+        certificate = domainConfig.certificate;
+    }
+    else if (!domainConfig?.managedDomain) {
+        certificate = new Certificate(ctx.scope, `${props.clusterName}Certificate`, {
+            domainName,
+            validation: CertificateValidation.fromDns(hostedZone)
+        });
+    }
+    if (domainConfig) {
+        const region = "region" in domainConfig ? domainConfig.region : undefined;
+        const weight = "weight" in domainConfig ? domainConfig.weight : undefined;
+        const geoLocation = "geoLocation" in domainConfig ? domainConfig.geoLocation : undefined;
+        const hasRoutingPolicy = !!region || weight !== undefined || !!geoLocation;
+        let setIdentifier = domainConfig.setIdentifier;
+        if (hasRoutingPolicy && !setIdentifier) {
+            if (region) {
+                setIdentifier = `${props.clusterName}${region}`;
+            }
+            else if (weight !== undefined) {
+                setIdentifier = `${props.clusterName}Weight${weight}`;
+            }
+            else if (geoLocation) {
+                setIdentifier = `${props.clusterName}Geo`;
+            }
+        }
+        if (loadBalancer && hostedZone) {
+            aRecord = new ARecord(ctx.scope, `${props.clusterName}ARecord`, {
+                recordName: domainName,
+                zone: hostedZone,
+                target: RecordTarget.fromAlias(new LoadBalancerTarget(loadBalancer, {
+                    evaluateTargetHealth: hasRoutingPolicy
+                })),
+                region,
+                weight,
+                geoLocation,
+                setIdentifier: setIdentifier
+            });
+        }
+    }
+    else if (simpleDomain && loadBalancer && hostedZone) {
+        aRecord = new ARecord(ctx.scope, `${props.clusterName}ARecord`, {
+            recordName: domainName,
+            zone: hostedZone,
+            target: RecordTarget.fromAlias(new LoadBalancerTarget(loadBalancer))
+        });
+    }
+    return { hostedZone, certificate, aRecord };
+}
+export function addDirectAccessOutputs(ctx, autoScalingGroup) {
+    if (!ctx.directAccessEnabled || !autoScalingGroup)
+        return;
+    const props = ctx.props;
+    const containerPort = props.services.flatMap((s) => s.containers).find((c) => c.port)?.port ||
+        3000;
+    new CfnOutput(ctx.scope, `${ctx.outputName}AutoScalingGroupName`, {
+        key: `${ctx.outputName}AutoScalingGroupName`,
+        exportName: `${props.clusterName}AutoScalingGroupName`,
+        value: autoScalingGroup.autoScalingGroupName,
+        description: `Run: aws autoscaling describe-auto-scaling-groups --auto-scaling-group-names <name> to find instance IP`
+    });
+    new CfnOutput(ctx.scope, `${ctx.outputName}DirectAccessPort`, {
+        key: `${ctx.outputName}DirectAccessPort`,
+        exportName: `${props.clusterName}DirectAccessPort`,
+        value: String(containerPort),
+        description: `Access your app at http://<EC2-PUBLIC-IP>:${containerPort}`
+    });
+}
+export function registerServiceWithALB(ctx, listener, serviceName, serviceProps, service, primaryContainer, priorityState) {
+    const containerPort = primaryContainer.containerPort;
+    // Normalise routing to array
+    const routingRules = Array.isArray(serviceProps.routing)
+        ? serviceProps.routing
+        : serviceProps.routing
+            ? [serviceProps.routing]
+            : [];
+    const healthCheckPath = routingRules.find((r) => r.healthCheckPath)?.healthCheckPath ?? "/";
+    const servicesWithPorts = ctx.props.services.filter((s) => s.containers.some((c) => c.port !== undefined));
+    const isSingleService = servicesWithPorts.length === 1;
+    const healthCheckConfig = isServiceEc2(serviceProps)
+        ? {
+            interval: Duration.seconds(30),
+            healthyThresholdCount: 3,
+            unhealthyThresholdCount: 3,
+            path: healthCheckPath,
+            port: "traffic-port",
+            timeout: Duration.seconds(15)
+        }
+        : {
+            interval: Duration.seconds(120),
+            path: healthCheckPath,
+            port: `${containerPort}`,
+            timeout: Duration.seconds(10)
+        };
+    if (isSingleService && routingRules.length <= 1) {
+        return listener.addTargets(`${serviceName}TargetGroup`, {
+            targets: [
+                service.loadBalancerTarget({
+                    containerName: primaryContainer.containerName,
+                    containerPort
+                })
+            ],
+            port: containerPort,
+            protocol: ApplicationProtocol.HTTP,
+            healthCheck: healthCheckConfig
+        });
+    }
+    else {
+        const firstRule = routingRules[0];
+        const firstPriority = firstRule?.priority ?? getNextPriority(priorityState);
+        if (firstRule?.priority)
+            priorityState.usedPriorities.add(firstRule.priority);
+        const targetGroup = listener.addTargets(`${serviceName}Targets`, {
+            targets: [
+                service.loadBalancerTarget({
+                    containerName: primaryContainer.containerName,
+                    containerPort
+                })
+            ],
+            port: containerPort,
+            protocol: ApplicationProtocol.HTTP,
+            healthCheck: healthCheckConfig,
+            conditions: buildRoutingConditions(firstRule),
+            priority: firstPriority
+        });
+        // Additional rules reuse the same target group
+        for (let i = 1; i < routingRules.length; i++) {
+            const rule = routingRules[i];
+            if (!rule)
+                continue;
+            const priority = rule.priority ?? getNextPriority(priorityState);
+            if (rule.priority)
+                priorityState.usedPriorities.add(rule.priority);
+            listener.addAction(`${serviceName}Route${i}`, {
+                conditions: buildRoutingConditions(rule),
+                priority,
+                action: ListenerAction.forward([targetGroup])
+            });
+        }
+        return targetGroup;
+    }
+}

package/dist/lib/resources/aws/compute/ecsRoles.d.ts

@@ -0,0 +1,15 @@
+import { Role } from "aws-cdk-lib/aws-iam";
+import type { EcsConstructContext } from "./ecsContext.js";
+import type { EcsServiceProps } from "./ecsTypes.js";
+/**
+ * Creates the execution role for ECS infrastructure operations.
+ * Used by the ECS agent to pull images, write logs, and inject secrets.
+ * NOT used by application code — that's the task role.
+ */
+export declare function createExecutionRole(ctx: EcsConstructContext, serviceName: string): Role;
+/**
+ * Creates the task role for application code running in the container.
+ * This role is assumed by the application, not the ECS agent.
+ * Includes default ECS Exec permissions plus any service-specific policies.
+ */
+export declare function createTaskRole(ctx: EcsConstructContext, serviceName: string, serviceProps: EcsServiceProps): Role;

package/dist/lib/resources/aws/compute/ecsRoles.js

@@ -0,0 +1,110 @@
+import { Stack } from "aws-cdk-lib";
+import { Effect, Policy, PolicyStatement, Role, ServicePrincipal } from "aws-cdk-lib/aws-iam";
+import { collectSecretsManagerSecretNames, deriveSsmSecretsPath } from "./ecsTaskDefinition.js";
+/**
+ * Creates the execution role for ECS infrastructure operations.
+ * Used by the ECS agent to pull images, write logs, and inject secrets.
+ * NOT used by application code — that's the task role.
+ */
+export function createExecutionRole(ctx, serviceName) {
+    const executionRole = new Role(ctx.scope, `${serviceName}ExecutionRole`, {
+        assumedBy: new ServicePrincipal("ecs-tasks.amazonaws.com")
+    });
+    // GetAuthorizationToken is an account-level API that requires resources: ["*"].
+    // The image-pull actions also use "*" because ecrRepository can be a string URI
+    // (cross-account or public ECR), not always a Repository construct with an ARN.
+    executionRole.addToPolicy(new PolicyStatement({
+        effect: Effect.ALLOW,
+        actions: [
+            "ecr:GetAuthorizationToken",
+            "ecr:BatchCheckLayerAvailability",
+            "ecr:GetDownloadUrlForLayer",
+            "ecr:BatchGetImage"
+        ],
+        resources: ["*"]
+    }));
+    const { partition, region, account } = Stack.of(ctx.scope);
+    const logGroupArn = `arn:${partition}:logs:${region}:${account}:log-group:/ecs/${ctx.props.clusterName}*`;
+    executionRole.addToPolicy(new PolicyStatement({
+        effect: Effect.ALLOW,
+        actions: [
+            "logs:CreateLogStream",
+            "logs:PutLogEvents",
+            "logs:CreateLogGroup"
+        ],
+        resources: [logGroupArn, `${logGroupArn}:*`]
+    }));
+    const secretNames = collectSecretsManagerSecretNames(ctx.props, serviceName);
+    if (secretNames.length > 0) {
+        const secretArns = secretNames.map((secretName) => `arn:${partition}:secretsmanager:${region}:${account}:secret:${secretName}-*`);
+        executionRole.addToPolicy(new PolicyStatement({
+            effect: Effect.ALLOW,
+            actions: [
+                "secretsmanager:GetSecretValue",
+                "secretsmanager:DescribeSecret"
+            ],
+            resources: secretArns
+        }));
+    }
+    const serviceProps = ctx.props.services.find((s) => s.name === serviceName);
+    const hasSsmSecrets = serviceProps?.containers.some((container) => container.secrets && container.secrets.length > 0) ?? false;
+    if (hasSsmSecrets && serviceProps) {
+        const ssmPath = deriveSsmSecretsPath(ctx.props, serviceName, serviceProps.ssmSecretsPath);
+        executionRole.addToPolicy(new PolicyStatement({
+            effect: Effect.ALLOW,
+            actions: ["ssm:GetParameters", "ssm:GetParameter"],
+            resources: [
+                `arn:${partition}:ssm:${region}:${account}:parameter${ssmPath}/*`
+            ]
+        }));
+    }
+    // KMS decrypt for SSM SecureString and Secrets Manager with customer-managed keys (CMKs)
+    executionRole.addToPolicy(new PolicyStatement({
+        effect: Effect.ALLOW,
+        actions: ["kms:Decrypt"],
+        resources: ["*"],
+        conditions: {
+            StringEquals: {
+                "kms:ViaService": [
+                    `ssm.${region}.amazonaws.com`,
+                    `secretsmanager.${region}.amazonaws.com`
+                ]
+            }
+        }
+    }));
+    return executionRole;
+}
+/**
+ * Creates the task role for application code running in the container.
+ * This role is assumed by the application, not the ECS agent.
+ * Includes default ECS Exec permissions plus any service-specific policies.
+ */
+export function createTaskRole(ctx, serviceName, serviceProps) {
+    const taskRole = new Role(ctx.scope, `${serviceName}TaskRole`, {
+        assumedBy: new ServicePrincipal("ecs-tasks.amazonaws.com")
+    });
+    // SSM permissions for ECS Exec (ecs execute-command)
+    taskRole.addToPolicy(new PolicyStatement({
+        effect: Effect.ALLOW,
+        actions: [
+            "ssmmessages:CreateControlChannel",
+            "ssmmessages:CreateDataChannel",
+            "ssmmessages:OpenControlChannel",
+            "ssmmessages:OpenDataChannel"
+        ],
+        resources: ["*"]
+    }));
+    if (serviceProps.taskRoleInlinePolicies) {
+        for (const [policyName, policyDocument] of Object.entries(serviceProps.taskRoleInlinePolicies)) {
+            taskRole.attachInlinePolicy(new Policy(ctx.scope, `${serviceName}${policyName}`, {
+                document: policyDocument
+            }));
+        }
+    }
+    if (serviceProps.taskRoleManagedPolicies) {
+        for (const policy of serviceProps.taskRoleManagedPolicies) {
+            taskRole.addManagedPolicy(policy);
+        }
+    }
+    return taskRole;
+}

package/dist/lib/resources/aws/compute/ecsServiceFactory.d.ts

@@ -0,0 +1,33 @@
+import { FargateService, Ec2Service, AsgCapacityProvider } from "aws-cdk-lib/aws-ecs";
+import type { FargateTaskDefinition, Ec2TaskDefinition } from "aws-cdk-lib/aws-ecs";
+import { TargetTrackingScalingPolicy } from "aws-cdk-lib/aws-applicationautoscaling";
+import { AutoScalingGroup } from "aws-cdk-lib/aws-autoscaling";
+import { SecurityGroup } from "../networking/securityGroup.js";
+import { type EcsServiceProps, type Ec2CapacityConfig } from "./ecsTypes.js";
+import type { EcsConstructContext } from "./ecsContext.js";
+/** Mutable state for ASG capacity provider deduplication. */
+export interface AsgCapacityState {
+    providers: Map<string, AsgCapacityProvider>;
+    autoScalingGroup?: AutoScalingGroup;
+    asgSecurityGroup?: SecurityGroup;
+}
+/**
+ * Generates a unique key for EC2 config so services with matching
+ * configurations share an ASG.
+ */
+export declare function getEc2ConfigKey(ec2Config: Ec2CapacityConfig): string;
+/**
+ * Gets or creates an ASG capacity provider for an EC2-backed service.
+ * Services with matching EC2 configs share the same ASG.
+ *
+ * Mutates `state` to track the provider and first ASG/security group.
+ */
+export declare function getOrCreateAsgCapacityProvider(ctx: EcsConstructContext, serviceProps: EcsServiceProps, state: AsgCapacityState): AsgCapacityProvider;
+/**
+ * Creates a Fargate or EC2 service and emits a CfnOutput for its ARN.
+ */
+export declare function createService(ctx: EcsConstructContext, serviceName: string, serviceProps: EcsServiceProps, taskDefinition: FargateTaskDefinition | Ec2TaskDefinition, asgState: AsgCapacityState): FargateService | Ec2Service;
+/**
+ * Adds auto-scaling to an ECS service based on CPU or memory utilisation.
+ */
+export declare function addServiceScaling(ctx: EcsConstructContext, serviceName: string, serviceProps: EcsServiceProps, service: FargateService | Ec2Service): TargetTrackingScalingPolicy;