@fjall/components-infrastructure 0.95.0 → 0.99.1

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;

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

@@ -1,11 +1,13 @@
-import { AwsLogDriver, FargateTaskDefinition, Ec2TaskDefinition, NetworkMode, CpuArchitecture, OperatingSystemFamily } from "aws-cdk-lib/aws-ecs";
+import { AwsLogDriver, ContainerDependencyCondition, FargateTaskDefinition, Ec2TaskDefinition, NetworkMode, CpuArchitecture, OperatingSystemFamily } from "aws-cdk-lib/aws-ecs";
 import { Duration } from "aws-cdk-lib";
 import { Secret as EcsSecret } from "aws-cdk-lib/aws-ecs";
 import { Secret } from "aws-cdk-lib/aws-secretsmanager";
 import { StringParameter } from "aws-cdk-lib/aws-ssm";
+import { resolveOrgId } from "../../../utils/cdkContext.js";
 import { validateSsmPathComponent } from "./ecsValidation.js";
-import { DEFAULT_LOG_RETENTION_DAYS } from "./ecsConstants.js";
+import { DEFAULT_LOG_RETENTION_DAYS, DEFAULT_FARGATE_CPU, DEFAULT_FARGATE_MEMORY_MIB, DEFAULT_EC2_CONTAINER_MEMORY_MIB } from "./ecsConstants.js";
 import { getContainerImage } from "./ecsImages.js";
+import { resolveRemoteConnections } from "./ecsRemoteConnections.js";
 // Re-export extracted functions so existing consumers are not broken
 export { createExecutionRole, createTaskRole } from "./ecsRoles.js";
 export { getContainerImage } from "./ecsImages.js";
@@ -64,8 +66,8 @@ export function deriveSsmSecretsPath(props, serviceName, explicitPath) {
     return `/${appName}/${props.clusterName}/${serviceName}`;
 }
 export function createTaskDefinition(ctx, serviceName, serviceProps, executionRole, taskRole) {
-    const cpu = serviceProps.cpu ?? 256;
-    const memoryLimitMiB = serviceProps.memoryLimitMiB ?? 512;
+    const cpu = serviceProps.cpu ?? DEFAULT_FARGATE_CPU;
+    const memoryLimitMiB = serviceProps.memoryLimitMiB ?? DEFAULT_FARGATE_MEMORY_MIB;
     if (isServiceFargate(serviceProps)) {
         return new FargateTaskDefinition(ctx.scope, `${serviceName}TaskDefinition`, {
             family: `${ctx.props.clusterName}-${serviceName}`,
@@ -80,17 +82,66 @@ export function createTaskDefinition(ctx, serviceName, serviceProps, executionRo
         });
     }
     else {
+        const networkMode = serviceProps.networkMode ??
+            (ctx.directAccessEnabled ? NetworkMode.HOST : NetworkMode.AWS_VPC);
         return new Ec2TaskDefinition(ctx.scope, `${serviceName}TaskDefinition`, {
             family: `${ctx.props.clusterName}-${serviceName}`,
             executionRole,
             taskRole,
-            ...(ctx.directAccessEnabled && { networkMode: NetworkMode.HOST })
+            ...(networkMode !== undefined && { networkMode })
         });
     }
 }
+/**
+ * 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 function createScheduledTaskDefinition(scope, id, props) {
+    return new Ec2TaskDefinition(scope, id, {
+        family: props.family,
+        ...(props.networkMode !== undefined && { networkMode: props.networkMode })
+    });
+}
+/**
+ * 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 function createMigrationTaskDefinition(scope, id, props) {
+    return new FargateTaskDefinition(scope, id, {
+        family: props.family,
+        cpu: props.cpu,
+        memoryLimitMiB: props.memoryLimitMiB,
+        executionRole: props.executionRole,
+        taskRole: props.taskRole,
+        runtimePlatform: {
+            cpuArchitecture: CpuArchitecture.ARM64,
+            operatingSystemFamily: OperatingSystemFamily.LINUX
+        }
+    });
+}
+const CONTAINER_DEPENDENCY_CONDITIONS = {
+    START: ContainerDependencyCondition.START,
+    COMPLETE: ContainerDependencyCondition.COMPLETE,
+    SUCCESS: ContainerDependencyCondition.SUCCESS,
+    HEALTHY: ContainerDependencyCondition.HEALTHY
+};
 export function addContainersToTask(ctx, serviceName, serviceProps, taskDefinition) {
     const containers = [];
+    const containerByName = new Map();
     let primaryContainer;
+    const orgId = resolveOrgId(ctx.scope.node);
+    const remoteEnvByService = resolveRemoteConnections([serviceProps], ctx.scope, orgId);
+    const remoteEnv = remoteEnvByService[serviceName] ?? {};
     for (const containerConfig of serviceProps.containers) {
         const image = getContainerImage(ctx, serviceName, containerConfig, serviceProps);
         const isFirstWithPort = !primaryContainer && containerConfig.port !== undefined;
@@ -125,8 +176,11 @@ export function addContainersToTask(ctx, serviceName, serviceProps, taskDefiniti
                 streamPrefix: `/ecs/${ctx.props.clusterName}/${serviceName}`,
                 logRetention: DEFAULT_LOG_RETENTION_DAYS
             }),
+            // remoteEnv (cross-app `${PREFIX}_HOST/_PORT`) intentionally overrides user
+            // values — a stale manual setting must not mask the resolved peer.
             environment: {
                 ...containerConfig.environment,
+                ...remoteEnv,
                 ...(containerConfig.port
                     ? { PORT: String(containerConfig.port) }
                     : {})
@@ -150,19 +204,69 @@ export function addContainersToTask(ctx, serviceName, serviceProps, taskDefiniti
                         : undefined
                 }
                 : undefined,
+            stopTimeout: containerConfig.stopTimeout !== undefined
+                ? Duration.seconds(containerConfig.stopTimeout)
+                : undefined,
             ...(isServiceEc2(serviceProps) && {
-                memoryLimitMiB: serviceProps.ec2Config?.memoryLimitMiB ?? 1024
+                memoryLimitMiB: serviceProps.ec2Config?.memoryLimitMiB ??
+                    DEFAULT_EC2_CONTAINER_MEMORY_MIB
             })
         });
+        if (containerConfig.port !== undefined &&
+            containerConfig.portMappings !== undefined &&
+            containerConfig.portMappings.length > 0) {
+            throw new Error(`Container '${containerConfig.name}' in service '${serviceName}': ` +
+                `"port" and "portMappings" are mutually exclusive on EcsContainerConfig — supply one or the other, not both.`);
+        }
         if (containerConfig.port) {
             container.addPortMappings({
                 containerPort: containerConfig.port
             });
         }
+        else if (containerConfig.portMappings &&
+            containerConfig.portMappings.length > 0) {
+            container.addPortMappings(...containerConfig.portMappings);
+        }
+        if (containerConfig.volumes && containerConfig.volumes.length > 0) {
+            for (const volume of containerConfig.volumes) {
+                taskDefinition.addVolume({
+                    name: volume.name,
+                    ...(volume.hostSourcePath !== undefined && {
+                        host: { sourcePath: volume.hostSourcePath }
+                    })
+                });
+                container.addMountPoints({
+                    sourceVolume: volume.name,
+                    containerPath: volume.mountPath,
+                    readOnly: volume.readOnly ?? false
+                });
+            }
+        }
         if (isFirstWithPort) {
             primaryContainer = container;
         }
         containers.push(container);
+        containerByName.set(containerConfig.name, container);
+    }
+    for (const containerConfig of serviceProps.containers) {
+        if (!containerConfig.dependsOn || containerConfig.dependsOn.length === 0) {
+            continue;
+        }
+        const dependent = containerByName.get(containerConfig.name);
+        if (!dependent)
+            continue;
+        for (const dep of containerConfig.dependsOn) {
+            const target = containerByName.get(dep.container);
+            if (!target) {
+                const available = [...containerByName.keys()].join(", ");
+                throw new Error(`Service '${serviceName}': container '${containerConfig.name}' dependsOn ` +
+                    `unknown container '${dep.container}'. Available containers: ${available}.`);
+            }
+            dependent.addContainerDependencies({
+                container: target,
+                condition: CONTAINER_DEPENDENCY_CONDITIONS[dep.condition]
+            });
+        }
     }
     return { containers, primaryContainer };
 }