@fjall/components-infrastructure 0.96.0 → 0.99.3

package/dist/lib/resources/aws/compute/ec2GracefulTerminationLambda.source.cjs

@@ -0,0 +1,458 @@
+/**
+ * EC2 graceful termination handler. Inlined into a Lambda at synth time by
+ * ec2GracefulTerminationHandler.ts. Triggered by an SQS queue fed by an
+ * EventBridge rule subscribed to the ASG EC2_INSTANCE_TERMINATING lifecycle
+ * event on the default bus.
+ *
+ * Wire format: the SQS message body is the EventBridge event envelope
+ *   `{ version, "detail-type", source, account, time, region, resources,
+ *      detail: { LifecycleActionToken, AutoScalingGroupName,
+ *                LifecycleHookName, EC2InstanceId, LifecycleTransition,
+ *                NotificationMetadata, ... } }`.
+ * The lifecycle payload lives at `body.detail`. Records whose envelope does
+ * not match (wrong source, missing detail, non-Lifecycle Action detail-type)
+ * are logged and skipped.
+ *
+ * Behaviour, in order:
+ *   1. (Conditional) ECS_CLUSTER_ARN set + non-empty → drain container
+ *      instance, wait for runningTasksCount=0, deregister.
+ *   2. (Always) Dissociate EIPs, deregister from any target groups,
+ *      detach non-primary ENIs.
+ *   3. CompleteLifecycleAction CONTINUE — even on partial failure, so the
+ *      ASG never stalls indefinitely. Better to terminate dirty than hang
+ *      the whole stack delete.
+ *
+ * CommonJS rather than ESM because Code.fromInline lands the source as
+ * `index.js`, which Lambda treats as CommonJS by default.
+ */
+const {
+  ECSClient,
+  ListContainerInstancesCommand,
+  DescribeContainerInstancesCommand,
+  UpdateContainerInstancesStateCommand,
+  DeregisterContainerInstanceCommand
+} = require("@aws-sdk/client-ecs");
+const {
+  EC2Client,
+  DescribeAddressesCommand,
+  DisassociateAddressCommand,
+  DescribeNetworkInterfacesCommand,
+  DetachNetworkInterfaceCommand,
+  DescribeVolumesCommand,
+  DetachVolumeCommand
+} = require("@aws-sdk/client-ec2");
+const {
+  ElasticLoadBalancingV2Client,
+  DescribeTargetGroupsCommand,
+  DescribeTargetHealthCommand,
+  DeregisterTargetsCommand
+} = require("@aws-sdk/client-elastic-load-balancing-v2");
+const {
+  AutoScalingClient,
+  CompleteLifecycleActionCommand
+} = require("@aws-sdk/client-auto-scaling");
+
+const DRAIN_POLL_INTERVAL_MS = 10_000;
+const DRAIN_DEADLINE_MS = 240_000;
+const DETACH_POLL_INTERVAL_MS = 5_000;
+const DETACH_DEADLINE_MS = 60_000;
+const TAG_OWNER_LOGICAL_ID = "fjall:OwnerLogicalId";
+const TAG_STACK_ID = "fjall:StackId";
+
+function errMessage(err) {
+  return err && err.message ? err.message : String(err);
+}
+
+let _ecs;
+let _ec2;
+let _elbv2;
+let _asg;
+function getEcs() {
+  if (!_ecs) _ecs = new ECSClient({});
+  return _ecs;
+}
+function getEc2() {
+  if (!_ec2) _ec2 = new EC2Client({});
+  return _ec2;
+}
+function getElbv2() {
+  if (!_elbv2) _elbv2 = new ElasticLoadBalancingV2Client({});
+  return _elbv2;
+}
+function getAsg() {
+  if (!_asg) _asg = new AutoScalingClient({});
+  return _asg;
+}
+
+function parseLifecycleMessage(record) {
+  const envelope = JSON.parse(record.body);
+  const detail = envelope && envelope.detail;
+  const source = envelope && envelope.source;
+  const detailType = envelope && envelope["detail-type"];
+  const valid =
+    detail !== undefined &&
+    detail !== null &&
+    typeof detail === "object" &&
+    source === "aws.autoscaling" &&
+    typeof detailType === "string" &&
+    detailType.endsWith("Lifecycle Action");
+  if (!valid) {
+    return { valid: false };
+  }
+  return {
+    valid: true,
+    instanceId: detail.EC2InstanceId,
+    asgName: detail.AutoScalingGroupName,
+    actionToken: detail.LifecycleActionToken,
+    hookName: detail.LifecycleHookName,
+    isTest: false
+  };
+}
+
+async function findContainerInstanceArn(ecsClient, clusterArn, instanceId) {
+  const list = await ecsClient.send(
+    new ListContainerInstancesCommand({
+      cluster: clusterArn,
+      filter: `ec2InstanceId == ${instanceId}`
+    })
+  );
+  if (!list.containerInstanceArns || list.containerInstanceArns.length === 0) {
+    return undefined;
+  }
+  return list.containerInstanceArns[0];
+}
+
+async function drainContainerInstance(
+  ecsClient,
+  clusterArn,
+  containerInstanceArn,
+  sleepFn,
+  nowFn
+) {
+  await ecsClient.send(
+    new UpdateContainerInstancesStateCommand({
+      cluster: clusterArn,
+      containerInstances: [containerInstanceArn],
+      status: "DRAINING"
+    })
+  );
+
+  const deadline = nowFn() + DRAIN_DEADLINE_MS;
+  while (nowFn() < deadline) {
+    const desc = await ecsClient.send(
+      new DescribeContainerInstancesCommand({
+        cluster: clusterArn,
+        containerInstances: [containerInstanceArn]
+      })
+    );
+    const instance =
+      desc.containerInstances && desc.containerInstances[0]
+        ? desc.containerInstances[0]
+        : undefined;
+    if (!instance) return;
+    if ((instance.runningTasksCount || 0) === 0) return;
+    await sleepFn(DRAIN_POLL_INTERVAL_MS);
+  }
+}
+
+async function dissociateInstanceEips(ec2Client, instanceId) {
+  const result = await ec2Client.send(
+    new DescribeAddressesCommand({
+      Filters: [{ Name: "instance-id", Values: [instanceId] }]
+    })
+  );
+  const addresses = result.Addresses || [];
+  for (const addr of addresses) {
+    if (!addr.AssociationId) continue;
+    await ec2Client.send(
+      new DisassociateAddressCommand({ AssociationId: addr.AssociationId })
+    );
+  }
+}
+
+async function deregisterFromTargetGroups(elbv2Client, instanceId) {
+  const groups = await elbv2Client.send(new DescribeTargetGroupsCommand({}));
+  const targetGroups = groups.TargetGroups || [];
+  for (const tg of targetGroups) {
+    if (!tg.TargetGroupArn) continue;
+    let health;
+    try {
+      health = await elbv2Client.send(
+        new DescribeTargetHealthCommand({ TargetGroupArn: tg.TargetGroupArn })
+      );
+    } catch (err) {
+      console.debug(
+        JSON.stringify({
+          message: "DescribeTargetHealth skipped",
+          targetGroupArn: tg.TargetGroupArn,
+          error: errMessage(err)
+        })
+      );
+      continue;
+    }
+    const matches = (health.TargetHealthDescriptions || []).filter(
+      (d) => d.Target && d.Target.Id === instanceId
+    );
+    if (matches.length === 0) continue;
+    await elbv2Client.send(
+      new DeregisterTargetsCommand({
+        TargetGroupArn: tg.TargetGroupArn,
+        Targets: matches.map((m) => ({
+          Id: m.Target.Id,
+          Port: m.Target.Port
+        }))
+      })
+    );
+  }
+}
+
+async function detachSecondaryEnis(ec2Client, instanceId) {
+  const result = await ec2Client.send(
+    new DescribeNetworkInterfacesCommand({
+      Filters: [{ Name: "attachment.instance-id", Values: [instanceId] }]
+    })
+  );
+  const enis = result.NetworkInterfaces || [];
+  for (const eni of enis) {
+    const attachment = eni.Attachment;
+    if (!attachment || !attachment.AttachmentId) continue;
+    // Skip the primary interface (DeviceIndex 0); it is destroyed with the
+    // instance and cannot be detached independently.
+    if (attachment.DeviceIndex === 0) continue;
+    try {
+      await ec2Client.send(
+        new DetachNetworkInterfaceCommand({
+          AttachmentId: attachment.AttachmentId,
+          Force: true
+        })
+      );
+    } catch (err) {
+      console.debug(
+        JSON.stringify({
+          message: "DetachNetworkInterface skipped",
+          attachmentId: attachment.AttachmentId,
+          error: errMessage(err)
+        })
+      );
+    }
+  }
+}
+
+async function detachDataVolume(
+  ec2Client,
+  instanceId,
+  ownerLogicalId,
+  stackId,
+  sleepFn,
+  nowFn
+) {
+  const described = await ec2Client.send(
+    new DescribeVolumesCommand({
+      Filters: [
+        { Name: `tag:${TAG_OWNER_LOGICAL_ID}`, Values: [ownerLogicalId] },
+        { Name: `tag:${TAG_STACK_ID}`, Values: [stackId] },
+        { Name: "attachment.instance-id", Values: [instanceId] }
+      ]
+    })
+  );
+  const volumes = described.Volumes || [];
+  if (volumes.length === 0) return;
+  const volumeId = volumes[0].VolumeId;
+  if (!volumeId) return;
+  await ec2Client.send(
+    new DetachVolumeCommand({ VolumeId: volumeId, InstanceId: instanceId })
+  );
+  const deadline = nowFn() + DETACH_DEADLINE_MS;
+  while (nowFn() < deadline) {
+    const desc = await ec2Client.send(
+      new DescribeVolumesCommand({ VolumeIds: [volumeId] })
+    );
+    const volume =
+      desc.Volumes && desc.Volumes[0] ? desc.Volumes[0] : undefined;
+    if (volume && volume.State === "available") return;
+    await sleepFn(DETACH_POLL_INTERVAL_MS);
+  }
+}
+
+async function completeLifecycle(asgClient, asgName, hookName, actionToken) {
+  await asgClient.send(
+    new CompleteLifecycleActionCommand({
+      AutoScalingGroupName: asgName,
+      LifecycleHookName: hookName,
+      LifecycleActionToken: actionToken,
+      LifecycleActionResult: "CONTINUE"
+    })
+  );
+}
+
+function readEnv(env, name) {
+  const value = env[name];
+  if (typeof value !== "string" || value === "") return undefined;
+  return value;
+}
+
+async function processRecord(record, deps) {
+  const ecsClient = (deps && deps.ecsClient) || getEcs();
+  const ec2Client = (deps && deps.ec2Client) || getEc2();
+  const elbv2Client = (deps && deps.elbv2Client) || getElbv2();
+  const asgClient = (deps && deps.asgClient) || getAsg();
+  const sleepFn =
+    (deps && deps.sleep) ||
+    ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+  const nowFn = (deps && deps.now) || (() => Date.now());
+  const env = (deps && deps.env) || process.env;
+  const log =
+    (deps && deps.log) ||
+    ((msg, fields) => {
+      console.log(JSON.stringify({ message: msg, ...(fields || {}) }));
+    });
+
+  const parsed = parseLifecycleMessage(record);
+  if (!parsed.valid) {
+    log("Record is not an aws.autoscaling Lifecycle Action; skipping", {
+      bodyPreview: record.body ? String(record.body).slice(0, 200) : undefined
+    });
+    return;
+  }
+  const { instanceId, asgName, actionToken, hookName } = parsed;
+
+  const clusterArn = readEnv(env, "ECS_CLUSTER_ARN");
+  if (clusterArn !== undefined) {
+    try {
+      const containerInstanceArn = await findContainerInstanceArn(
+        ecsClient,
+        clusterArn,
+        instanceId
+      );
+      if (containerInstanceArn !== undefined) {
+        await drainContainerInstance(
+          ecsClient,
+          clusterArn,
+          containerInstanceArn,
+          sleepFn,
+          nowFn
+        );
+        await ecsClient.send(
+          new DeregisterContainerInstanceCommand({
+            cluster: clusterArn,
+            containerInstance: containerInstanceArn,
+            force: true
+          })
+        );
+      }
+    } catch (err) {
+      log("ECS drain step failed; continuing to generic cleanup", {
+        instanceId,
+        error: errMessage(err)
+      });
+    }
+  }
+
+  try {
+    await dissociateInstanceEips(ec2Client, instanceId);
+  } catch (err) {
+    log("EIP dissociation failed", {
+      instanceId,
+      error: errMessage(err)
+    });
+  }
+  try {
+    await deregisterFromTargetGroups(elbv2Client, instanceId);
+  } catch (err) {
+    log("Target-group deregistration failed", {
+      instanceId,
+      error: errMessage(err)
+    });
+  }
+  try {
+    await detachSecondaryEnis(ec2Client, instanceId);
+  } catch (err) {
+    log("ENI detachment failed", {
+      instanceId,
+      error: errMessage(err)
+    });
+  }
+
+  const dataVolumeOwnerLogicalId = readEnv(env, "DATA_VOLUME_OWNER_LOGICAL_ID");
+  const dataVolumeStackId = readEnv(env, "DATA_VOLUME_STACK_ID");
+  if (
+    dataVolumeOwnerLogicalId !== undefined &&
+    dataVolumeStackId !== undefined
+  ) {
+    try {
+      await detachDataVolume(
+        ec2Client,
+        instanceId,
+        dataVolumeOwnerLogicalId,
+        dataVolumeStackId,
+        sleepFn,
+        nowFn
+      );
+    } catch (err) {
+      log("Data volume detach failed; AWS will force-detach after heartbeat", {
+        instanceId,
+        ownerLogicalId: dataVolumeOwnerLogicalId,
+        error: errMessage(err)
+      });
+    }
+  }
+
+  await completeLifecycle(asgClient, asgName, hookName, actionToken);
+}
+
+exports.handler = async (event) => {
+  const records = (event && event.Records) || [];
+  for (const record of records) {
+    try {
+      await processRecord(record);
+    } catch (err) {
+      // Last-resort: try to release the lifecycle action so the stack does
+      // not hang. Failure here is logged and the message will retry via SQS.
+      console.error(
+        JSON.stringify({
+          message: "Graceful termination handler crashed; attempting CONTINUE",
+          error: errMessage(err)
+        })
+      );
+      try {
+        const parsed = parseLifecycleMessage(record);
+        if (!parsed.valid) {
+          continue;
+        }
+        await completeLifecycle(
+          getAsg(),
+          parsed.asgName,
+          parsed.hookName,
+          parsed.actionToken
+        );
+      } catch (innerErr) {
+        console.error(
+          JSON.stringify({
+            message: "CompleteLifecycleAction also failed",
+            error: errMessage(innerErr)
+          })
+        );
+        throw err;
+      }
+    }
+  }
+};
+
+exports._internals = {
+  parseLifecycleMessage,
+  findContainerInstanceArn,
+  drainContainerInstance,
+  dissociateInstanceEips,
+  deregisterFromTargetGroups,
+  detachSecondaryEnis,
+  detachDataVolume,
+  completeLifecycle,
+  readEnv,
+  processRecord,
+  DRAIN_POLL_INTERVAL_MS,
+  DRAIN_DEADLINE_MS,
+  DETACH_POLL_INTERVAL_MS,
+  DETACH_DEADLINE_MS,
+  TAG_OWNER_LOGICAL_ID,
+  TAG_STACK_ID
+};

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

@@ -1,4 +1,4 @@
-import { Cluster as CdkCluster, type FargateService, type Ec2Service } from "aws-cdk-lib/aws-ecs";
+import { Cluster as CdkCluster, type FargateService, type Ec2Service, type TaskDefinition } from "aws-cdk-lib/aws-ecs";
 import { Connections, type IConnectable } from "aws-cdk-lib/aws-ec2";
 import { Construct } from "constructs";
 import type { StackBuilder } from "../base/awsStack.js";
@@ -56,6 +56,7 @@ export default class EcsCluster extends Construct implements IConnectable {
     private certificate?;
     private asgState;
     private services;
+    private scheduledTaskDefinitions;
     private scope;
     private props;
     private outputName;
@@ -72,8 +73,33 @@ export default class EcsCluster extends Construct implements IConnectable {
     getService(name: string): FargateService | Ec2Service | undefined;
     /** Get all services in this cluster. */
     getServices(): Map<string, FargateService | Ec2Service>;
+    /**
+     * Get the task definition for a service or a registered scheduled task.
+     * Used by Schedule / Subscription targets to construct the EcsTask adapter
+     * for EventBridge invocation. Returns undefined for unknown names — callers
+     * MUST validate before passing to `resolveTarget(...)`.
+     */
+    getTaskDefinition(serviceName: string): TaskDefinition | undefined;
+    /**
+     * Register a `Ec2TaskDefinition` under a synthetic name so it can be
+     * resolved by `app.addSchedule(...)` against the existing
+     * `EcsScheduleTarget` shape (AC34). Throws if `name` collides with any
+     * steady-state service name OR a previously-registered scheduled task.
+     */
+    registerScheduledTaskDefinition(name: string, taskDefinition: TaskDefinition): void;
     /** Get the ECS cluster construct. */
     getCluster(): CdkCluster;
+    /**
+     * Get the EC2 instance role for the cluster's ASG (D10). Returns undefined
+     * for Fargate-only clusters. Pulled from the shared ASG capacity state.
+     */
+    getInstanceRole(): import("aws-cdk-lib/aws-iam").IRole | undefined;
+    /**
+     * Get the underlying ASG's `autoScalingGroupName` token (string-only,
+     * not the ASG construct itself — D10 forbids ASG-typed accessors).
+     * Used by alarm helpers that need CloudWatch dimension keys.
+     */
+    getAutoScalingGroupName(): string | undefined;
     /** Get the ALB URL (http:// or https://). */
     getUrl(): string | undefined;
     /**

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

@@ -69,8 +69,8 @@ export default class EcsCluster extends Construct {
         autoScalingGroup: undefined,
         asgSecurityGroup: undefined
     };
-    // Per-service tracking
     services = new Map();
+    scheduledTaskDefinitions = new Map();
     // Configuration
     scope;
     props;
@@ -147,10 +147,50 @@ export default class EcsCluster extends Construct {
         }
         return result;
     }
+    /**
+     * Get the task definition for a service or a registered scheduled task.
+     * Used by Schedule / Subscription targets to construct the EcsTask adapter
+     * for EventBridge invocation. Returns undefined for unknown names — callers
+     * MUST validate before passing to `resolveTarget(...)`.
+     */
+    getTaskDefinition(serviceName) {
+        return (this.services.get(serviceName)?.taskDefinition ??
+            this.scheduledTaskDefinitions.get(serviceName));
+    }
+    /**
+     * Register a `Ec2TaskDefinition` under a synthetic name so it can be
+     * resolved by `app.addSchedule(...)` against the existing
+     * `EcsScheduleTarget` shape (AC34). Throws if `name` collides with any
+     * steady-state service name OR a previously-registered scheduled task.
+     */
+    registerScheduledTaskDefinition(name, taskDefinition) {
+        if (this.services.has(name)) {
+            throw new Error(`Scheduled task name '${name}' collides with a steady-state service in cluster '${this.props.clusterName}'.`);
+        }
+        if (this.scheduledTaskDefinitions.has(name)) {
+            throw new Error(`Scheduled task name '${name}' is already registered in cluster '${this.props.clusterName}'.`);
+        }
+        this.scheduledTaskDefinitions.set(name, taskDefinition);
+    }
     /** Get the ECS cluster construct. */
     getCluster() {
         return this.cluster;
     }
+    /**
+     * Get the EC2 instance role for the cluster's ASG (D10). Returns undefined
+     * for Fargate-only clusters. Pulled from the shared ASG capacity state.
+     */
+    getInstanceRole() {
+        return this.asgState.autoScalingGroup?.role;
+    }
+    /**
+     * Get the underlying ASG's `autoScalingGroupName` token (string-only,
+     * not the ASG construct itself — D10 forbids ASG-typed accessors).
+     * Used by alarm helpers that need CloudWatch dimension keys.
+     */
+    getAutoScalingGroupName() {
+        return this.asgState.autoScalingGroup?.autoScalingGroupName;
+    }
     /** Get the ALB URL (http:// or https://). */
     getUrl() {
         if (!this.loadBalancer)
@@ -199,7 +239,7 @@ export default class EcsCluster extends Construct {
                 );
             }
             catch (error) {
-                throw new Error(`Failed to process connections for ECS service '${serviceName}': ${error instanceof Error ? error.message : String(error)}`);
+                throw new Error(`Failed to process connections for ECS service '${serviceName}': ${error instanceof Error ? error.message : String(error)}`, { cause: error });
             }
         }
         // Per-service alarm wiring (shared topic on cluster, thresholds per service)

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

@@ -3,6 +3,15 @@ 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;
+export declare const DEFAULT_FARGATE_CPU = 256;
+export declare const DEFAULT_FARGATE_MEMORY_MIB = 512;
+export declare const DEFAULT_EC2_CONTAINER_MEMORY_MIB = 1024;
+export declare const DEFAULT_ECS_FALLBACK_IMAGE = "amazon/amazon-ecs-sample";
+export declare const DEFAULT_CUSTOM_RESOURCE_TIMEOUT_SECONDS = 300;
+export declare const DEFAULT_HEALTH_CHECK_GRACE_SECONDS = 120;
+export declare const DEFAULT_MIN_HEALTHY_PERCENT = 100;
+export declare const DEFAULT_MAX_HEALTHY_PERCENT = 200;
+export declare const DEFAULT_DESIRED_COUNT = 2;
 /**
  * Instance type prefixes that use ARM64 architecture (Graviton processors).
  * All other prefixes are assumed to be x86-64 (STANDARD).

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

@@ -5,6 +5,22 @@ 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;
+// Smallest valid (cpu, memory) pair on the Fargate matrix — must move together.
+export const DEFAULT_FARGATE_CPU = 256;
+export const DEFAULT_FARGATE_MEMORY_MIB = 512;
+export const DEFAULT_EC2_CONTAINER_MEMORY_MIB = 1024;
+// AWS sample image used when no ECR repository is provided. Consumed by both
+// the resources/ image resolver and the patterns/ defaults block — keep them
+// in lockstep via this single export.
+export const DEFAULT_ECS_FALLBACK_IMAGE = "amazon/amazon-ecs-sample";
+// 5 minutes matches the Lambda service default; CDK uses it for sync providers.
+export const DEFAULT_CUSTOM_RESOURCE_TIMEOUT_SECONDS = 300;
+// 100/200 must move together — the rolling-deploy window relies on the gap.
+export const DEFAULT_HEALTH_CHECK_GRACE_SECONDS = 120;
+export const DEFAULT_MIN_HEALTHY_PERCENT = 100;
+export const DEFAULT_MAX_HEALTHY_PERCENT = 200;
+// Read at two sites (createService initial count + addServiceScaling derive-base) that must agree.
+export const DEFAULT_DESIRED_COUNT = 2;
 /**
  * Instance type prefixes that use ARM64 architecture (Graviton processors).
  * All other prefixes are assumed to be x86-64 (STANDARD).

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

@@ -1,35 +1,47 @@
+import { CfnParameter, Stack } from "aws-cdk-lib";
 import { ContainerImage } from "aws-cdk-lib/aws-ecs";
 import { Repository } from "aws-cdk-lib/aws-ecr";
+import { DEFAULT_ECS_FALLBACK_IMAGE } from "./ecsConstants.js";
+import { toPascalCase } from "../../../utils/capitaliseString.js";
+function buildImageTagDescription(serviceName) {
+    return `Image tag for ECS service ${serviceName}. Set by fjall deploy to the content-hash tag.`;
+}
+function getOrCreateImageTagParameter(ctx, serviceName) {
+    const stack = Stack.of(ctx.scope);
+    const paramLogicalId = `${toPascalCase(serviceName)}ImageTag`;
+    const description = buildImageTagDescription(serviceName);
+    const existing = stack.node.tryFindChild(paramLogicalId);
+    if (existing instanceof CfnParameter) {
+        if (existing.description !== description) {
+            throw new Error(`CfnParameter logical-ID collision: "${paramLogicalId}" is already registered for a different service. ` +
+                `Distinct service names cannot share a PascalCase identifier — rename one of the conflicting services.`);
+        }
+        return existing;
+    }
+    return new CfnParameter(stack, paramLogicalId, {
+        type: "String",
+        default: "latest",
+        description
+    });
+}
 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");
+        return ContainerImage.fromRegistry(DEFAULT_ECS_FALLBACK_IMAGE);
     }
-    // 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
+        const isFullRegistryUrl = /^(docker\.io|registry\.hub\.docker\.com|ghcr\.io)\//i.test(imageSource) ||
+            imageSource.startsWith("public.ecr.aws/") ||
+            imageSource.includes(".dkr.ecr.");
         if (isFullRegistryUrl) {
             return ContainerImage.fromRegistry(imageSource);
         }
-        return ContainerImage.fromEcrRepository(Repository.fromRepositoryName(ctx.scope, `${serviceName}${containerConfig.name}EcrRepo`, imageSource), imageTag);
+        const param = getOrCreateImageTagParameter(ctx, serviceName);
+        return ContainerImage.fromEcrRepository(Repository.fromRepositoryName(ctx.scope, `${serviceName}${containerConfig.name}EcrRepo`, imageSource), param.valueAsString);
     }
     if (imageSource instanceof Repository) {
-        return ContainerImage.fromEcrRepository(imageSource, imageTag);
+        const param = getOrCreateImageTagParameter(ctx, serviceName);
+        return ContainerImage.fromEcrRepository(imageSource, param.valueAsString);
     }
     return imageSource;
 }