@fjall/components-infrastructure 0.96.0 → 0.99.1

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

@@ -0,0 +1,96 @@
+import { type BaseService, DeploymentLifecycleStage } from "aws-cdk-lib/aws-ecs";
+import { Construct } from "constructs";
+import { LambdaFunction } from "./lambda.js";
+/**
+ * Awsvpc network configuration consumed by the runner's `RunTask` call.
+ */
+export interface LifecycleHookNetworkConfiguration {
+    subnetIds: string[];
+    securityGroupIds: string[];
+    assignPublicIp: boolean;
+}
+/**
+ * Optional nested block describing a separate migration task definition.
+ *
+ * Three lockstep fields enforced by the type system — present-as-a-group or
+ * absent-as-a-group. This shape is the resources-layer mirror of
+ * `EcsLifecycleHookMigrationsSeparateTaskDef` at the patterns layer.
+ */
+export interface MigrationTaskDef {
+    /** ARN of the migration task definition (different from the service task def). */
+    definitionArn: string;
+    /** Family of the migration task definition — used to scope `ecs:RunTask`. */
+    family: string;
+    /** Task role ARN for the migration task. */
+    taskRoleArn: string;
+    /** Execution role ARN for the migration task. */
+    executionRoleArn: string;
+}
+export interface EcsLifecycleHookMigrationProps {
+    /**
+     * The ECS service this hook fires for.
+     */
+    service: BaseService;
+    /** Cluster ARN — used for both `ecs:RunTask`'s cluster condition and ListTasks scoping. */
+    clusterArn: string;
+    /** ARN of the task definition the migrate task launches from. */
+    taskDefinitionArn: string;
+    /** Family of the task definition — used in the `ecs:RunTask` resource ARN. */
+    taskDefinitionFamily: string;
+    /** Task execution role ARN (the role pulling the image, writing logs). */
+    taskExecutionRoleArn: string;
+    /** Task role ARN (the role the running container assumes). */
+    taskRoleArn: string;
+    /** Migration command, passed through to the runner. */
+    command: string[];
+    /** Synthetic container name used in `RunTask` overrides. */
+    containerName: string;
+    /** Optional image override (else the task definition's image is used). */
+    image?: string;
+    /**
+     * Optional container entrypoint override (else inherited from the image).
+     * Lets the patterns layer carry `["/usr/bin/tini", "--"]` shapes through to
+     * the runner's `ContainerOverrides` block.
+     */
+    entryPoint?: string[];
+    /** Optional environment override. */
+    environment?: Record<string, string>;
+    /**
+     * Lambda timeout in seconds. Defaults to 300, capped at 900 (Lambda max).
+     * Should comfortably exceed the migration command's expected runtime
+     * including a few re-invocation cycles.
+     */
+    timeoutSeconds?: number;
+    /** Awsvpc network configuration for the migrate task. */
+    networkConfiguration: LifecycleHookNetworkConfiguration;
+    /**
+     * Optional separate migration task definition. When present, `RunTask`
+     * targets THIS task def instead of the service's, and the Lambda's IAM
+     * policy expands to cover both task-def families + both role pairs.
+     *
+     * When absent, behaviour is unchanged — the migration runs in the service
+     * task def via `ContainerOverrides`.
+     */
+    migrationTaskDef?: MigrationTaskDef;
+    /**
+     * Which deployment lifecycle stage to fire at. Defaults to
+     * `PRE_SCALE_UP` (migration runs BEFORE the new revision scales up;
+     * service rollout blocks until the hook returns SUCCEEDED).
+     *
+     * Set to `POST_SCALE_UP` for post-deploy work (backfills, smoke tests)
+     * that should run AFTER new tasks are healthy; a FAILED return triggers
+     * deployment circuit-breaker rollback.
+     */
+    lifecycleStage?: DeploymentLifecycleStage;
+}
+/**
+ * ECS deployment lifecycle hook (PRE_SCALE_UP) that runs migrations as a
+ * one-off `RunTask` before the new revision scales up. Self-wires:
+ * synthesises the Lambda + IAM + LogGroup, then attaches the hook to the
+ * service via the typed CDK API. CDK auto-generates the hook-invocation
+ * role.
+ */
+export declare class EcsLifecycleHookMigration extends Construct {
+    readonly lambda: LambdaFunction;
+    constructor(scope: Construct, id: string, props: EcsLifecycleHookMigrationProps);
+}

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

@@ -0,0 +1,113 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { Stack } from "aws-cdk-lib";
+import { Code, Runtime } from "aws-cdk-lib/aws-lambda";
+import { PolicyStatement, Effect } from "aws-cdk-lib/aws-iam";
+import { RetentionDays } from "aws-cdk-lib/aws-logs";
+import { DeploymentLifecycleLambdaTarget, DeploymentLifecycleStage } from "aws-cdk-lib/aws-ecs";
+import { Construct } from "constructs";
+import { LambdaFunction } from "./lambda.js";
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const LAMBDA_SOURCE_FILE = "lifecycleHookLambda.source.cjs";
+const LAMBDA_TIMEOUT_DEFAULT_SECONDS = 300;
+const LAMBDA_TIMEOUT_MAX_SECONDS = 900;
+/**
+ * ECS deployment lifecycle hook (PRE_SCALE_UP) that runs migrations as a
+ * one-off `RunTask` before the new revision scales up. Self-wires:
+ * synthesises the Lambda + IAM + LogGroup, then attaches the hook to the
+ * service via the typed CDK API. CDK auto-generates the hook-invocation
+ * role.
+ */
+export class EcsLifecycleHookMigration extends Construct {
+    lambda;
+    constructor(scope, id, props) {
+        super(scope, id);
+        const stack = Stack.of(scope);
+        const timeoutSeconds = Math.min(props.timeoutSeconds ?? LAMBDA_TIMEOUT_DEFAULT_SECONDS, LAMBDA_TIMEOUT_MAX_SECONDS);
+        const sourcePath = path.resolve(__dirname, LAMBDA_SOURCE_FILE);
+        const source = readFileSync(sourcePath, "utf-8");
+        const migrationTaskDef = props.migrationTaskDef;
+        const targetTaskDefinitionArn = migrationTaskDef?.definitionArn ?? props.taskDefinitionArn;
+        const runTaskResources = [
+            `arn:aws:ecs:${stack.region}:${stack.account}:task-definition/${props.taskDefinitionFamily}:*`
+        ];
+        if (migrationTaskDef !== undefined) {
+            runTaskResources.push(`arn:aws:ecs:${stack.region}:${stack.account}:task-definition/${migrationTaskDef.family}:*`);
+        }
+        const passRoleResources = [props.taskExecutionRoleArn, props.taskRoleArn];
+        if (migrationTaskDef !== undefined) {
+            passRoleResources.push(migrationTaskDef.taskRoleArn, migrationTaskDef.executionRoleArn);
+        }
+        // ECS RunTask awsvpcConfiguration uses subnets/securityGroups and
+        // assignPublicIp as "ENABLED"/"DISABLED" string, not boolean.
+        const awsvpcConfiguration = {
+            subnets: props.networkConfiguration.subnetIds,
+            securityGroups: props.networkConfiguration.securityGroupIds,
+            assignPublicIp: props.networkConfiguration.assignPublicIp
+                ? "ENABLED"
+                : "DISABLED"
+        };
+        this.lambda = new LambdaFunction(this, `${id}Fn`, {
+            runtime: Runtime.NODEJS_22_X,
+            handler: "index.handler",
+            code: Code.fromInline(source),
+            lambdaDescription: `${id} ECS deployment lifecycle hook for migration`,
+            roleDescription: `Execution role for ${id} migration lifecycle-hook runner`,
+            timeout: timeoutSeconds,
+            memorySize: 256,
+            logGroupRetention: RetentionDays.ONE_MONTH,
+            environment: {
+                MIGRATE_CONFIG: JSON.stringify({
+                    clusterArn: props.clusterArn,
+                    taskDefinitionArn: targetTaskDefinitionArn,
+                    name: props.containerName,
+                    command: props.command,
+                    ...(props.image !== undefined ? { image: props.image } : {}),
+                    ...(props.entryPoint !== undefined
+                        ? { entryPoint: props.entryPoint }
+                        : {}),
+                    ...(props.environment !== undefined
+                        ? { environment: props.environment }
+                        : {}),
+                    networkConfiguration: awsvpcConfiguration,
+                    ...(migrationTaskDef !== undefined
+                        ? { hasSeparateMigrationTaskDef: true }
+                        : {})
+                })
+            },
+            inlinePolicy: [
+                new PolicyStatement({
+                    effect: Effect.ALLOW,
+                    actions: ["ecs:RunTask"],
+                    resources: runTaskResources,
+                    conditions: {
+                        ArnEquals: { "ecs:cluster": props.clusterArn }
+                    }
+                }),
+                // ListTasks/DescribeTasks do not support resource-level ARN scoping;
+                // restrict via the `ecs:cluster` condition key instead.
+                new PolicyStatement({
+                    effect: Effect.ALLOW,
+                    actions: ["ecs:ListTasks", "ecs:DescribeTasks"],
+                    resources: ["*"],
+                    conditions: {
+                        ArnEquals: { "ecs:cluster": props.clusterArn }
+                    }
+                }),
+                new PolicyStatement({
+                    effect: Effect.ALLOW,
+                    actions: ["iam:PassRole"],
+                    resources: passRoleResources,
+                    conditions: {
+                        StringEquals: { "iam:PassedToService": "ecs-tasks.amazonaws.com" }
+                    }
+                })
+            ]
+        });
+        const lifecycleStage = props.lifecycleStage ?? DeploymentLifecycleStage.PRE_SCALE_UP;
+        props.service.addLifecycleHook(new DeploymentLifecycleLambdaTarget(this.lambda, id, {
+            lifecycleStages: [lifecycleStage]
+        }));
+    }
+}

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

@@ -1,4 +1,5 @@
 import { type ApplicationListener, ApplicationLoadBalancer, type IApplicationTargetGroup, ListenerCondition } from "aws-cdk-lib/aws-elasticloadbalancingv2";
+import { type ISecurityGroup } from "aws-cdk-lib/aws-ec2";
 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";
@@ -14,7 +15,7 @@ export interface PriorityState {
 /** 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): {
+export declare function addLoadBalancer(ctx: EcsConstructContext, anyServiceUsesEc2: boolean, asgSecurityGroup?: ISecurityGroup): {
     loadBalancer: ApplicationLoadBalancer;
     loadBalancerSecurityGroup?: SecurityGroup;
 };

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

@@ -100,21 +100,33 @@ export function addLoadBalancer(ctx, anyServiceUsesEc2, asgSecurityGroup) {
 }
 export function addLoadBalancerListener(ctx, loadBalancer, certificate) {
     const port = certificate ? 443 : 80;
-    const defaultAction = ListenerAction.fixedResponse(404, {
-        contentType: "text/plain",
-        messageBody: "Not Found"
-    });
+    const servicesWithPorts = ctx.props.services.filter((s) => s.containers.some((c) => c.port !== undefined));
+    const willHaveMultipleRoutes = servicesWithPorts.length > 1 ||
+        servicesWithPorts.some((s) => {
+            const rules = Array.isArray(s.routing)
+                ? s.routing
+                : s.routing
+                    ? [s.routing]
+                    : [];
+            return rules.length > 1;
+        });
+    const defaultAction = willHaveMultipleRoutes
+        ? ListenerAction.fixedResponse(404, {
+            contentType: "text/plain",
+            messageBody: "Not Found"
+        })
+        : undefined;
     if (certificate) {
         return loadBalancer.addListener(`${ctx.props.clusterName}Listener`, {
             port,
             certificates: [certificate],
-            defaultAction
+            ...(defaultAction !== undefined && { defaultAction })
         });
     }
     else {
         return loadBalancer.addListener(`${ctx.props.clusterName}Listener`, {
             port,
-            defaultAction
+            ...(defaultAction !== undefined && { defaultAction })
         });
     }
 }

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

@@ -1,15 +1,24 @@
-import { FargateService, Ec2Service, AsgCapacityProvider } from "aws-cdk-lib/aws-ecs";
+import { FargateService, Ec2Service, AsgCapacityProvider, type DeploymentCircuitBreaker } from "aws-cdk-lib/aws-ecs";
 import type { FargateTaskDefinition, Ec2TaskDefinition } from "aws-cdk-lib/aws-ecs";
+import { type ISecurityGroup } from "aws-cdk-lib/aws-ec2";
 import { TargetTrackingScalingPolicy } from "aws-cdk-lib/aws-applicationautoscaling";
-import { AutoScalingGroup } from "aws-cdk-lib/aws-autoscaling";
-import { SecurityGroup } from "../networking/securityGroup.js";
+import { type AutoScalingGroup } from "aws-cdk-lib/aws-autoscaling";
 import { type EcsServiceProps, type Ec2CapacityConfig } from "./ecsTypes.js";
 import type { EcsConstructContext } from "./ecsContext.js";
+/**
+ * Resolves the user's `circuitBreaker` config to the CDK
+ * `DeploymentCircuitBreaker` shape. `undefined` resolves to the safe default
+ * `{ enable: true, rollback: true }`; `false` resolves to `undefined` (CDK
+ * omits the breaker block from CFN output entirely).
+ */
+export declare function resolveCircuitBreaker(config: false | {
+    rollback?: boolean;
+} | undefined): DeploymentCircuitBreaker | undefined;
 /** Mutable state for ASG capacity provider deduplication. */
 export interface AsgCapacityState {
     providers: Map<string, AsgCapacityProvider>;
     autoScalingGroup?: AutoScalingGroup;
-    asgSecurityGroup?: SecurityGroup;
+    asgSecurityGroup?: ISecurityGroup;
 }
 /**
  * Generates a unique key for EC2 config so services with matching

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

@@ -1,14 +1,29 @@
-import { FargateService, Ec2Service, PropagatedTagSource, PlacementStrategy, AsgCapacityProvider, EcsOptimizedImage, AmiHardwareType } from "aws-cdk-lib/aws-ecs";
-import { InstanceType, Peer, Port, SubnetType } from "aws-cdk-lib/aws-ec2";
-import { CfnOutput, Duration } from "aws-cdk-lib";
+import { FargateService, Ec2Service, PropagatedTagSource, PlacementStrategy, AsgCapacityProvider, EcsOptimizedImage, AmiHardwareType, NetworkMode } from "aws-cdk-lib/aws-ecs";
+import { Peer, Port, SubnetType, UserData } from "aws-cdk-lib/aws-ec2";
+import { ServicePrincipal } from "aws-cdk-lib/aws-iam";
+import { Role } from "../iam/role.js";
+import { CfnOutput, Duration, Token } from "aws-cdk-lib";
 import { PredefinedMetric, ScalableTarget, ServiceNamespace, TargetTrackingScalingPolicy } from "aws-cdk-lib/aws-applicationautoscaling";
-import { AutoScalingGroup, Monitoring } from "aws-cdk-lib/aws-autoscaling";
+import { Monitoring } from "aws-cdk-lib/aws-autoscaling";
 import { SecurityGroup } from "../networking/securityGroup.js";
+import { Ec2Instance } from "./ec2.js";
 import { vpcHasNatGateways } from "../../../utils/vpcUtils.js";
 import { toPascalCase } from "../../../utils/capitaliseString.js";
-import { DEFAULT_EC2_INSTANCE_TYPE, DEFAULT_WARM_POOL_MIN_SIZE, DEFAULT_WARM_POOL_REUSE_ON_SCALE_IN, inferAmiHardwareType } from "./ecsConstants.js";
+import { DEFAULT_EC2_INSTANCE_TYPE, DEFAULT_WARM_POOL_MIN_SIZE, DEFAULT_WARM_POOL_REUSE_ON_SCALE_IN, DEFAULT_HEALTH_CHECK_GRACE_SECONDS, DEFAULT_MIN_HEALTHY_PERCENT, DEFAULT_MAX_HEALTHY_PERCENT, DEFAULT_DESIRED_COUNT, inferAmiHardwareType } from "./ecsConstants.js";
 import { ScalingType } from "./ecsTypes.js";
 import { isServiceFargate, isServiceEc2 } from "./ecsTaskDefinition.js";
+/**
+ * Resolves the user's `circuitBreaker` config to the CDK
+ * `DeploymentCircuitBreaker` shape. `undefined` resolves to the safe default
+ * `{ enable: true, rollback: true }`; `false` resolves to `undefined` (CDK
+ * omits the breaker block from CFN output entirely).
+ */
+export function resolveCircuitBreaker(config) {
+    if (config === false)
+        return undefined;
+    const rollback = config?.rollback ?? true;
+    return { enable: true, rollback };
+}
 /**
  * Generates a unique key for EC2 config so services with matching
  * configurations share an ASG.
@@ -22,7 +37,26 @@ export function getEc2ConfigKey(ec2Config) {
     const warmPoolKey = ec2Config.warmPool
         ? `wp${ec2Config.warmPool.minSize ?? DEFAULT_WARM_POOL_MIN_SIZE}-${ec2Config.warmPool.reuseOnScaleIn ?? DEFAULT_WARM_POOL_REUSE_ON_SCALE_IN}`
         : "nowp";
-    return `${instanceType}-${amiHardwareType}-${warmPoolKey}`;
+    const baseKey = `${instanceType}-${amiHardwareType}-${warmPoolKey}`;
+    // PDV services are implicit singletons — sharing an ASG would let two tasks race for the same EBS volume.
+    const pdv = ec2Config.persistentDataVolume;
+    const extras = [];
+    if (pdv !== undefined) {
+        extras.push(`pdv-${pdv.deviceName}-${pdv.sizeGb}-${stableAzSegment(pdv.availabilityZone)}`);
+    }
+    // Serialise actual AZ names — `az${length}` would let services pinned to different AZs collide on `az1`.
+    // CDK Tokens (env-agnostic stacks) substitute a stable sentinel to keep logical IDs deterministic.
+    if (ec2Config.availabilityZones !== undefined) {
+        const azKey = [...ec2Config.availabilityZones]
+            .map(stableAzSegment)
+            .sort()
+            .join(",");
+        extras.push(`az-${azKey}`);
+    }
+    return extras.length === 0 ? baseKey : `${baseKey}-${extras.join("-")}`;
+}
+function stableAzSegment(az) {
+    return Token.isUnresolved(az) ? "synthAz" : az;
 }
 /**
  * Gets or creates an ASG capacity provider for an EC2-backed service.
@@ -46,10 +80,11 @@ export function getOrCreateAsgCapacityProvider(ctx, serviceProps, state) {
         : inferAmiHardwareType(instanceType);
     const minCapacity = ec2Config.minCapacity ?? 2;
     const maxCapacity = ec2Config.maxCapacity ?? 3;
-    const asgSecurityGroup = new SecurityGroup(ctx.scope, `${safeKey}AsgSecurityGroup`, {
-        vpc: ctx.cluster.vpc,
-        description: `Security group for ${key} auto scaling group`
-    });
+    const asgSecurityGroup = ctx.props.cluster?.securityGroup ??
+        new SecurityGroup(ctx.scope, `${safeKey}AsgSecurityGroup`, {
+            vpc: ctx.cluster.vpc,
+            description: `Security group for ${key} auto scaling group`
+        });
     if (ctx.directAccessEnabled) {
         for (const service of ctx.props.services) {
             if (isServiceEc2(service)) {
@@ -62,29 +97,61 @@ export function getOrCreateAsgCapacityProvider(ctx, serviceProps, state) {
         }
     }
     const hasNat = vpcHasNatGateways(ctx.cluster.vpc);
-    const asg = new AutoScalingGroup(ctx.scope, `${safeKey}AutoScalingGroup`, {
-        autoScalingGroupName: `${ctx.props.clusterName}-${safeKey}-Asg`,
+    const resolvedWarmPool = ec2Config.warmPool
+        ? {
+            minSize: ec2Config.warmPool.minSize ?? DEFAULT_WARM_POOL_MIN_SIZE,
+            reuseOnScaleIn: ec2Config.warmPool.reuseOnScaleIn ??
+                DEFAULT_WARM_POOL_REUSE_ON_SCALE_IN
+        }
+        : undefined;
+    // userData + role must be set on the LaunchTemplate or AsgCapacityProvider
+    // throws at synth (ProvidedLaunchTemplateExposeUser/ExposeDefine).
+    const instanceRole = new Role(ctx.scope, `${safeKey}InstanceRole`, {
+        assumedBy: new ServicePrincipal("ec2.amazonaws.com"),
+        description: `EC2 instance role for ${key} ECS capacity`
+    });
+    const ec2Instance = new Ec2Instance(ctx.scope, `${safeKey}Ec2Instance`, {
+        serviceName: `${ctx.props.clusterName}${safeKey}`,
         vpc: ctx.cluster.vpc,
         vpcSubnets: {
-            subnetType: hasNat ? SubnetType.PRIVATE_WITH_EGRESS : SubnetType.PUBLIC
+            subnetType: hasNat ? SubnetType.PRIVATE_WITH_EGRESS : SubnetType.PUBLIC,
+            ...(ec2Config.availabilityZones !== undefined && {
+                availabilityZones: ec2Config.availabilityZones
+            })
         },
         securityGroup: asgSecurityGroup,
         minCapacity,
         maxCapacity,
-        instanceType: new InstanceType(instanceType),
+        instanceType,
+        machineImage: ec2Config.machineImage ??
+            EcsOptimizedImage.amazonLinux2023(amiHardwareType),
+        userData: ec2Config.userData ?? UserData.forLinux(),
+        role: instanceRole,
+        instanceMonitoring: ec2Config.instanceMonitoring ?? Monitoring.BASIC,
         capacityRebalance: true,
-        instanceMonitoring: Monitoring.BASIC,
-        machineImage: EcsOptimizedImage.amazonLinux2023(amiHardwareType)
+        ecsClusterArn: ctx.cluster.clusterArn,
+        ...(ec2Config.desiredCapacity !== undefined && {
+            desiredCapacity: ec2Config.desiredCapacity
+        }),
+        ...(ec2Config.blockDevices !== undefined && {
+            blockDevices: ec2Config.blockDevices
+        }),
+        ...(ec2Config.associatePublicIpAddress !== undefined && {
+            associatePublicIpAddress: ec2Config.associatePublicIpAddress
+        }),
+        ...(resolvedWarmPool !== undefined && { warmPool: resolvedWarmPool }),
+        ...(ec2Config.persistentDataVolume !== undefined && {
+            persistentDataVolume: ec2Config.persistentDataVolume
+        }),
+        ...(ec2Config.tags !== undefined && { tags: ec2Config.tags })
     });
-    if (ec2Config.warmPool) {
-        asg.addWarmPool({
-            minSize: ec2Config.warmPool.minSize ?? DEFAULT_WARM_POOL_MIN_SIZE,
-            reuseOnScaleIn: ec2Config.warmPool.reuseOnScaleIn ?? DEFAULT_WARM_POOL_REUSE_ON_SCALE_IN
-        });
-    }
+    const asg = ec2Instance.getAutoScalingGroup();
     const provider = new AsgCapacityProvider(ctx.scope, `${safeKey}AsgCapacityProvider`, {
         autoScalingGroup: asg,
         enableManagedDraining: true,
+        // MTP's ProtectedFromScaleIn flag does NOT clear on CP deletion, so
+        // CFN rollback wedges on a stranded protected instance. The drain
+        // path is Ec2GracefulTerminationHandler instead.
         enableManagedTerminationProtection: false
     });
     ctx.cluster.addAsgCapacityProvider(provider);
@@ -101,8 +168,13 @@ export function getOrCreateAsgCapacityProvider(ctx, serviceProps, state) {
  * Creates a Fargate or EC2 service and emits a CfnOutput for its ARN.
  */
 export function createService(ctx, serviceName, serviceProps, taskDefinition, asgState) {
-    const desiredCount = serviceProps.desiredCount ?? 2;
+    const desiredCount = serviceProps.desiredCount ?? DEFAULT_DESIRED_COUNT;
     let service;
+    // CDK's Ec2Service rejects `securityGroups` unless networkMode is AWS_VPC
+    // (HOST/BRIDGE share the instance ENI). FargateService is always awsvpc.
+    const explicitSecurityGroups = serviceProps.securityGroups && serviceProps.securityGroups.length > 0
+        ? serviceProps.securityGroups
+        : undefined;
     if (isServiceFargate(serviceProps)) {
         const hasNat = vpcHasNatGateways(ctx.cluster.vpc);
         service = new FargateService(ctx.scope, `${serviceName}Service`, {
@@ -121,12 +193,17 @@ export function createService(ctx, serviceName, serviceProps, taskDefinition, as
                 }
             ],
             propagateTags: PropagatedTagSource.SERVICE,
-            circuitBreaker: { enable: true, rollback: true },
+            circuitBreaker: resolveCircuitBreaker(serviceProps.circuitBreaker),
             enableECSManagedTags: true,
             enableExecuteCommand: true,
-            healthCheckGracePeriod: Duration.seconds(120),
-            minHealthyPercent: 100,
-            maxHealthyPercent: 200
+            healthCheckGracePeriod: Duration.seconds(DEFAULT_HEALTH_CHECK_GRACE_SECONDS),
+            minHealthyPercent: serviceProps.deployment?.minHealthyPercent ??
+                DEFAULT_MIN_HEALTHY_PERCENT,
+            maxHealthyPercent: serviceProps.deployment?.maxHealthyPercent ??
+                DEFAULT_MAX_HEALTHY_PERCENT,
+            ...(explicitSecurityGroups !== undefined && {
+                securityGroups: explicitSecurityGroups
+            })
         });
     }
     else {
@@ -143,15 +220,59 @@ export function createService(ctx, serviceName, serviceProps, taskDefinition, as
                 }
             ],
             propagateTags: PropagatedTagSource.SERVICE,
-            circuitBreaker: { enable: true, rollback: true },
+            circuitBreaker: resolveCircuitBreaker(serviceProps.circuitBreaker),
             placementStrategies: [PlacementStrategy.spreadAcrossInstances()],
             enableECSManagedTags: true,
             enableExecuteCommand: true,
-            healthCheckGracePeriod: Duration.seconds(120),
-            minHealthyPercent: 100,
-            maxHealthyPercent: 200
+            healthCheckGracePeriod: Duration.seconds(DEFAULT_HEALTH_CHECK_GRACE_SECONDS),
+            minHealthyPercent: serviceProps.deployment?.minHealthyPercent ??
+                DEFAULT_MIN_HEALTHY_PERCENT,
+            maxHealthyPercent: serviceProps.deployment?.maxHealthyPercent ??
+                DEFAULT_MAX_HEALTHY_PERCENT,
+            ...(explicitSecurityGroups !== undefined && {
+                securityGroups: explicitSecurityGroups
+            })
         });
     }
+    if (serviceProps.cloudMapService !== undefined) {
+        const isSrv = serviceProps.cloudMapDnsRecordType === "SRV";
+        const isHostOrBridge = taskDefinition.networkMode === NetworkMode.HOST ||
+            taskDefinition.networkMode === NetworkMode.BRIDGE;
+        // AWS forbids A-typed serviceRegistries under HOST/BRIDGE networkMode.
+        if (isHostOrBridge && !isSrv) {
+            throw new Error(`Service '${serviceName}': cloudMapDnsRecordType '${serviceProps.cloudMapDnsRecordType ?? "A"}' ` +
+                `is not supported with networkMode '${taskDefinition.networkMode}'. ` +
+                'Use dnsRecordType: "SRV" or change networkMode to AWS_VPC.');
+        }
+        const primaryWithPort = serviceProps.containers.find((c) => c.port !== undefined);
+        const primaryWithMappings = serviceProps.containers.find((c) => c.portMappings !== undefined &&
+            c.portMappings[0]?.containerPort !== undefined);
+        const primary = primaryWithPort ?? primaryWithMappings;
+        const primaryPort = primaryWithPort?.port ??
+            primaryWithMappings?.portMappings?.[0]?.containerPort;
+        if (isSrv && (primary === undefined || primaryPort === undefined)) {
+            throw new Error(`Service '${serviceName}': cloudMapDnsRecordType: "SRV" requires at ` +
+                "least one container with a port — SRV records carry the published " +
+                "port and cannot be registered without one.");
+        }
+        if (primary !== undefined && primaryPort !== undefined) {
+            const containerDef = taskDefinition.findContainer(primary.name);
+            if (containerDef === undefined) {
+                throw new Error(`Service '${serviceName}': could not resolve container '${primary.name}' ` +
+                    "from task definition for Cloud Map registration.");
+            }
+            service.associateCloudMapService({
+                service: serviceProps.cloudMapService,
+                container: containerDef,
+                containerPort: primaryPort
+            });
+        }
+        else {
+            service.associateCloudMapService({
+                service: serviceProps.cloudMapService
+            });
+        }
+    }
     new CfnOutput(ctx.scope, `${ctx.outputName}${toPascalCase(serviceName)}ServiceArn`, {
         key: `${ctx.outputName}${toPascalCase(serviceName)}ServiceArn`,
         exportName: `${ctx.props.clusterName}${serviceName}ServiceArn`,
@@ -164,12 +285,13 @@ export function createService(ctx, serviceName, serviceProps, taskDefinition, as
  * Adds auto-scaling to an ECS service based on CPU or memory utilisation.
  */
 export function addServiceScaling(ctx, serviceName, serviceProps, service) {
+    const desiredCount = serviceProps.desiredCount ?? DEFAULT_DESIRED_COUNT;
     const scalableTarget = new ScalableTarget(ctx.scope, `${serviceName}ScalableTarget`, {
         serviceNamespace: ServiceNamespace.ECS,
         resourceId: `service/${ctx.cluster.clusterName}/${service.serviceName}`,
         scalableDimension: "ecs:service:DesiredCount",
-        minCapacity: serviceProps.minCapacity ?? 2,
-        maxCapacity: serviceProps.maxCapacity ?? 10
+        minCapacity: serviceProps.minCapacity ?? desiredCount,
+        maxCapacity: serviceProps.maxCapacity ?? Math.max(desiredCount + 1, 3)
     });
     return new TargetTrackingScalingPolicy(ctx.scope, `${serviceName}ScalingPolicy`, {
         scalingTarget: scalableTarget,

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

@@ -1,4 +1,5 @@
-import { FargateTaskDefinition, Ec2TaskDefinition, type ContainerDefinition } from "aws-cdk-lib/aws-ecs";
+import { FargateTaskDefinition, Ec2TaskDefinition, NetworkMode, type ContainerDefinition } from "aws-cdk-lib/aws-ecs";
+import type { Construct } from "constructs";
 import { type Role } from "aws-cdk-lib/aws-iam";
 import type { EcsConstructContext } from "./ecsContext.js";
 import type { EcsClusterProps, EcsServiceProps, EcsCapacityProvider } from "./ecsTypes.js";
@@ -24,6 +25,35 @@ export declare function collectSecretsManagerSecretNames(props: EcsClusterProps,
  */
 export declare function deriveSsmSecretsPath(props: EcsClusterProps, serviceName: string, explicitPath?: string): string;
 export declare function createTaskDefinition(ctx: EcsConstructContext, serviceName: string, serviceProps: EcsServiceProps, executionRole: Role, taskRole: Role): FargateTaskDefinition | Ec2TaskDefinition;
+/**
+ * Routing point for `Ec2TaskDefinition`s used by EventBridge-triggered scheduled
+ * tasks (per `EcsClusterConfig.scheduledTasks`). Pattern-layer callers MUST
+ * reach `Ec2TaskDefinition` through this wrapper rather than instantiating the
+ * raw CDK class — a future SOC2-relevant default (encryption, retention,
+ * uniform tags) added here propagates to every scheduled-task task def at once.
+ *
+ * Compare with `createTaskDefinition()` above, which is the per-service path;
+ * this is the per-schedule path and intentionally kept narrow (no execution /
+ * task roles — scheduled tasks use task-definition defaults).
+ */
+export declare function createScheduledTaskDefinition(scope: Construct, id: string, props: {
+    family: string;
+    networkMode?: NetworkMode;
+}): Ec2TaskDefinition;
+/**
+ * Routing point for `FargateTaskDefinition`s used by the lifecycle-hook
+ * migration runner when `migrations.separateTaskDef` is set. Synthesises a
+ * dedicated Fargate task definition with caller-supplied CPU/memory and the
+ * supplied execution + task roles. Runtime platform pinned to ARM64/Linux to
+ * match the service task def default.
+ */
+export declare function createMigrationTaskDefinition(scope: Construct, id: string, props: {
+    family: string;
+    cpu: number;
+    memoryLimitMiB: number;
+    executionRole: Role;
+    taskRole: Role;
+}): FargateTaskDefinition;
 export declare function addContainersToTask(ctx: EcsConstructContext, serviceName: string, serviceProps: EcsServiceProps, taskDefinition: FargateTaskDefinition | Ec2TaskDefinition): {
     containers: ContainerDefinition[];
     primaryContainer?: ContainerDefinition;