@fjall/components-infrastructure 39.0.5 → 39.0.6

package/dist/lib/patterns/aws/computeEcs.js

@@ -1,7 +1,7 @@
 import { AwsLogDriver, ContainerImage, DeploymentLifecycleStage, NetworkMode, Secret as EcsSecret } from "aws-cdk-lib/aws-ecs";
-import { Peer, Port, SubnetType } from "aws-cdk-lib/aws-ec2";
+import { Peer, Port } from "aws-cdk-lib/aws-ec2";
 import { Effect, PolicyStatement, ServicePrincipal } from "aws-cdk-lib/aws-iam";
-import { Annotations, Aws, Stack, Token } from "aws-cdk-lib";
+import { Annotations, Aws, Stack, Tags, Token } from "aws-cdk-lib";
 import { RetentionDays } from "aws-cdk-lib/aws-logs";
 import { StringParameter } from "aws-cdk-lib/aws-ssm";
 import { Construct } from "constructs";
@@ -13,20 +13,20 @@ import { isMigrationContributor } from "./interfaces/migrationContributor.js";
 import { resolveImportedSecret } from "../../resources/aws/secrets/index.js";
 import App from "../../app.js";
 import EcsCluster from "../../resources/aws/compute/ecs.js";
-import { createScheduledTaskDefinition, createMigrationTaskDefinition } from "../../resources/aws/compute/ecsTaskDefinition.js";
+import { createScheduledTaskDefinition, createMigrationTaskDefinition, taskSize } from "../../resources/aws/compute/ecsTaskDefinition.js";
 import { DEFAULT_LOG_RETENTION } from "../../resources/aws/compute/ecsConstants.js";
 import { EcsLifecycleHookMigration } from "../../resources/aws/compute/ecsLifecycleHookMigration.js";
+import { EcsRolloutBarrier } from "../../resources/aws/compute/ecsRolloutBarrier.js";
 import { Role } from "../../resources/aws/iam/role.js";
 import { LogGroup } from "../../resources/aws/logging/logGroup.js";
 import { Schedule } from "../../resources/aws/messaging/schedule.js";
 import { SecurityGroup } from "../../resources/aws/networking/securityGroup.js";
-import { vpcHasNatGateways } from "../../utils/vpcUtils.js";
 import { toPascalCase } from "../../utils/capitaliseString.js";
 import { FjallLogger } from "../../utils/validationLogger.js";
 import { VALIDATION_PATTERNS } from "@fjall/generator";
 import { evaluateBakeGuard } from "@fjall/util/docker";
 import { toKebab, buildParameterPath } from "@fjall/util";
-import { SCHEMA_GATE_CH_CA_CERT_ENV, SCHEMA_GATE_CH_DATABASE_ENV, SCHEMA_GATE_CH_URL_ENV, SCHEMA_GATE_CONTAINER_NAME, SCHEMA_GATE_DB_URL_BASE_ENV, SCHEMA_GATE_ECR_REPO_NAME, SCHEMA_GATE_START_TIMEOUT_SECONDS } from "@fjall/util/migration";
+import { MIGRATION_SECURITY_GROUPS_TAG_KEY, SCHEMA_GATE_CH_CA_CERT_ENV, SCHEMA_GATE_CH_DATABASE_ENV, SCHEMA_GATE_CH_URL_ENV, SCHEMA_GATE_CONTAINER_NAME, SCHEMA_GATE_DB_URL_BASE_ENV, SCHEMA_GATE_ECR_REPO_NAME, SCHEMA_GATE_START_TIMEOUT_SECONDS } from "@fjall/util/migration";
 import { CONSTRUCTS_VERSION } from "../../utils/engineCompat.js";
 import { validateEc2ServiceSizing, validateEc2TaskMemoryFit, validateEcsDomainConfig, validateSecretName } from "../../resources/aws/compute/ecsValidation.js";
 import { validateSharedEc2CapacityConfig } from "../../resources/aws/compute/ecsCapacityConfig.js";
@@ -355,7 +355,7 @@ export function expandMigrationsSugar(service, userContainers) {
                 `migrate container created by 'migrations'. Set 'migrations.name' to a different value.`);
         }
     }
-    const primary = containers.find((c) => c.port !== undefined) ?? containers[0];
+    const primary = primaryContainerConfig(containers);
     const migrateContainer = {
         name: migrateName,
         essential: false,
@@ -641,7 +641,18 @@ function mergeContributionsIntoMigrations(migrations, contributions, scope, serv
         }
         mergedEnv[key] = value;
     }
-    const mergedSecrets = { ...contributedSecrets };
+    // An authored SSM secret is author-explicit too: the contributor's import
+    // of that name is dropped, so no variable resolves from both kinds.
+    const authoredSsm = new Set(migrations.secrets ?? []);
+    const mergedSecrets = {};
+    for (const [key, value] of Object.entries(contributedSecrets)) {
+        if (authoredSsm.has(key)) {
+            Annotations.of(scope).addWarning(`Service '${serviceName}': author-set migrations.secrets entry ${key} ` +
+                `overrides contributor secret ('${value.name ?? ""}').`);
+            continue;
+        }
+        mergedSecrets[key] = value;
+    }
     for (const [key, value] of Object.entries(authoredSecrets)) {
         if (contributedSecrets[key] !== undefined &&
             contributedSecrets[key]?.name !== value.name) {
@@ -805,7 +816,7 @@ export function buildContainerConfigs(service, schemaVersionEnv, annotationsScop
     if (expanded) {
         return wireSchemaGate(expanded.map((c, index) => {
             return {
-                name: c.name || `${service.name}Container${index > 0 ? index : ""}`,
+                name: builtContainerName(service.name, c, index),
                 image: c.image,
                 port: c.port,
                 environment: mergeAllSchemaEnv(c.environment),
@@ -830,6 +841,64 @@ export function buildContainerConfigs(service, schemaVersionEnv, annotationsScop
         }
     ]);
 }
+/**
+ * The service's primary container: the first with a port, else the first.
+ * Its migration inherits from it, and its definition carries the migration's
+ * label.
+ */
+function primaryContainerConfig(containers) {
+    return containers?.find((c) => c.port !== undefined) ?? containers?.[0];
+}
+/**
+ * The name a service's container is built under: its own, or, when it has
+ * none (an empty name included), one derived from its place in the list.
+ */
+function builtContainerName(serviceName, container, index) {
+    return container.name || `${serviceName}Container${index > 0 ? index : ""}`;
+}
+/**
+ * The task definition's container for the service's primary container, or
+ * its default container when the service authors none. Hook migrations only:
+ * their containers are built in the order they are authored, so the
+ * primary's place in `containers` is its place when built.
+ */
+function primaryContainerDefinition(svcConfig, taskDefinition) {
+    const containers = svcConfig.containers ?? [];
+    const primary = primaryContainerConfig(containers);
+    if (primary === undefined)
+        return taskDefinition.defaultContainer;
+    const name = builtContainerName(svcConfig.name, primary, containers.indexOf(primary));
+    const definition = taskDefinition.findContainer(name);
+    if (definition === undefined) {
+        throw new Error(`Service '${svcConfig.name}': its task definition has no container '${name}' for its primary container`);
+    }
+    return definition;
+}
+/**
+ * The migration's secrets with its primary container's beneath them, by
+ * variable name: a name the migration gives a secret of either kind is its
+ * own, and the primary's secret of that name, of either kind, is dropped.
+ */
+function secretsBeneathMigration(authored, primary) {
+    const own = new Set([
+        ...(authored.secrets ?? []),
+        ...Object.keys(authored.secretsImport ?? {})
+    ]);
+    const secrets = [
+        ...new Set([
+            ...(authored.secrets ?? []),
+            ...(primary?.secrets ?? []).filter((name) => !own.has(name))
+        ])
+    ];
+    const secretsImport = {
+        ...Object.fromEntries(Object.entries(primary?.secretsImport ?? {}).filter(([name]) => !own.has(name))),
+        ...(authored.secretsImport ?? {})
+    };
+    return {
+        ...(secrets.length > 0 && { secrets }),
+        ...(Object.keys(secretsImport).length > 0 && { secretsImport })
+    };
+}
 function resolveMigrationImage(svcConfig, migrations, inheritedImage) {
     if (migrations.image !== undefined)
         return migrations.image;
@@ -837,15 +906,14 @@ function resolveMigrationImage(svcConfig, migrations, inheritedImage) {
     // CfnParameter token; checked before raw svcConfig.image strings.
     if (inheritedImage !== undefined)
         return inheritedImage;
-    const primary = svcConfig.containers?.find((c) => c.port !== undefined) ??
-        svcConfig.containers?.[0];
+    const primary = primaryContainerConfig(svcConfig.containers);
     const containerImage = primary?.image ?? svcConfig.image;
     if (containerImage !== undefined && typeof containerImage !== "string") {
-        throw new Error(`Service '${svcConfig.name}': migrations.separateTaskDef requires a string image URI ` +
+        throw new Error(`Service '${svcConfig.name}': a lifecycle-hook migration needs a string image URI ` +
             `(got CDK Repository). Pass migrations.image as a string.`);
     }
     if (containerImage === undefined) {
-        throw new Error(`Service '${svcConfig.name}': migrations.separateTaskDef requires a resolvable image — ` +
+        throw new Error(`Service '${svcConfig.name}': a lifecycle-hook migration needs a resolvable image — ` +
             `set migrations.image, service.image, or a container.image (string URI).`);
     }
     return containerImage;
@@ -890,6 +958,10 @@ export class EcsCompute extends Construct {
     clusterId;
     appName;
     migrationTaskDefinitions = new Map();
+    /** The cluster's physical name, as a literal. */
+    clusterName;
+    /** Service name → its rollout barrier, made on first use. */
+    rolloutBarriers = new Map();
     /**
      * Service name → exact `@fjall/schema-gate` semver, for every service that
      * materialised the gate container with the DEFAULT image this synth.
@@ -999,6 +1071,7 @@ export class EcsCompute extends Construct {
                 appBackupTier: props.appBackupTier
             })
         };
+        this.clusterName = ecsProps.clusterName;
         this.ecsCluster = new EcsCluster(this, `${id}Ecs`, ecsProps);
         this.connections = this.ecsCluster.connections;
         this.wireLifecycleHookMigrations(props.services);
@@ -1075,11 +1148,6 @@ export class EcsCompute extends Construct {
      * - `migrations.mode: "post-deploy"` — expected is deliberately ahead of
      *   the DB during scale-up, so a materialised gate would refuse every task
      *   (synth warning)
-     * - `migrations.mode: "lifecycle-hook"` WITHOUT `separateTaskDef` — the
-     *   hook's migration RunTask reuses the service task definition, so a
-     *   materialised gate would refuse the migration task itself while the DB
-     *   still holds the pre-migration schema (synth warning; adding
-     *   `separateTaskDef` restores full gating)
      * - No eligible half survives the v1 scope filters: the relational half
      *   requires `tool: "prisma"` and a postgres-family connection scheme
      *   (per-half synth warnings; env injection into app containers stays on)
@@ -1109,17 +1177,6 @@ export class EcsCompute extends Construct {
                 `Env injection stays on. Set schemaGate: false to silence.`);
             return undefined;
         }
-        if (service.migrations?.mode === "lifecycle-hook" &&
-            service.migrations.separateTaskDef === undefined) {
-            Annotations.of(this).addWarning(`Service '${service.name}': schema-gate materialisation is disabled ` +
-                `because migrations.mode is "lifecycle-hook" without ` +
-                `separateTaskDef — the migration RunTask reuses the service task ` +
-                `definition, so a materialised gate would refuse the migration ` +
-                `task itself during the pre-migration window. Add ` +
-                `migrations.separateTaskDef to run migrations in their own task ` +
-                `definition and restore full gating. Env injection stays on.`);
-            return undefined;
-        }
         const environment = {};
         const secretsImport = {};
         let eligibleHalves = 0;
@@ -1312,8 +1369,8 @@ export class EcsCompute extends Construct {
      * Without `awaitMigrationsFrom` the sibling rolls out in parallel with the
      * owner, so its gate-refused task churn can trip the deployment circuit
      * breaker before the migration lands. The gate refusing is by design (new
-     * code must not serve the old schema); the missing DependsOn is the
-     * author-fixable part — warn, don't disable.
+     * code must not serve the old schema); the missing ordering on the owner's
+     * rollout barrier is the author-fixable part — warn, don't disable.
      */
     warnUngatedSiblingsOfHookOwners(services) {
         for (const owner of services) {
@@ -1342,18 +1399,27 @@ export class EcsCompute extends Construct {
                     `not declare awaitMigrationsFrom: "${owner.name}". Its ` +
                     `materialised schema gate will refuse tasks that scale up ` +
                     `before the migration lands, which can trip the deployment ` +
-                    `circuit breaker. Add awaitMigrationsFrom to order the ` +
-                    `rollouts, or set schemaGate: { materialise: false }.`);
+                    `circuit breaker. Add awaitMigrationsFrom: "${owner.name}" so ` +
+                    `it rolls out only once '${owner.name}''s deployment has ` +
+                    `finished; if it already awaits another service, depend on ` +
+                    `getRolloutBarrier("${owner.name}") instead. Or set ` +
+                    `schemaGate: { materialise: false }.`);
             }
         }
     }
     /**
      * For each service whose `migrations.mode` is a lambda-hook variant
      * (`"lifecycle-hook"` for PRE_SCALE_UP, `"post-deploy"` for POST_SCALE_UP),
-     * synthesise the Lambda + IAM role + log group that backs the deployment
-     * lifecycle hook. The init-container path is unaffected — services without
-     * `mode` (or with `mode: "init-container"`) still get the synthetic
-     * migrate container injected by `expandMigrationsSugar`.
+     * synthesise the migration's own task definition and the Lambda + IAM role
+     * + log group that backs the deployment lifecycle hook. Every hook
+     * migration runs from a task definition of its own, which the service's
+     * task definition names in its `fjall:migration-task-definition` tag and
+     * its primary container's docker label: the hook reads the tag from the
+     * revision each deployment targets, and the label where a copy carries no
+     * tag. The
+     * init-container path is unaffected — services without `mode` (or with
+     * `mode: "init-container"`) still get the synthetic migrate container
+     * injected by `expandMigrationsSugar`.
      */
     wireLifecycleHookMigrations(services) {
         this.warnUngatedSiblingsOfHookOwners(services);
@@ -1380,12 +1446,9 @@ export class EcsCompute extends Construct {
                 throw new Error(`Service '${svcConfig.name}': task definition has no execution role — cannot grant iam:PassRole for the migrate Lambda.`);
             }
             const cluster = this.ecsCluster.getCluster();
-            const hasNat = vpcHasNatGateways(cluster.vpc);
-            const subnets = cluster.vpc.selectSubnets({
-                subnetType: hasNat ? SubnetType.PRIVATE_WITH_EGRESS : SubnetType.PUBLIC
-            });
-            const securityGroupIds = service.connections.securityGroups.map((sg) => sg.securityGroupId);
-            if (securityGroupIds.length === 0) {
+            // The hook runs the migration in the network of the revision it serves,
+            // the service's own, unless the migration has security groups of its own.
+            if (service.connections.securityGroups.length === 0) {
                 throw new Error(`EcsCompute: service "${svcConfig.name}" has no security groups; lifecycle-hook migration RunTask requires at least one.`);
             }
             const contributions = collectMigrationContributions(svcConfig);
@@ -1395,63 +1458,68 @@ export class EcsCompute extends Construct {
                 ? mergeContributionsIntoSeparateTaskDef(migrations.separateTaskDef, contributions)
                 : undefined;
             const schemaVersionEnv = this.resolveSchemaVersionEnv(svcConfig);
-            const migrationTaskDef = effectiveSeparateTaskDef !== undefined
+            const migrationTaskDefinition = effectiveSeparateTaskDef !== undefined
                 ? this.synthesiseMigrationTaskDef(svcConfig, effectiveMigrations, effectiveSeparateTaskDef, service, cluster.vpc, schemaVersionEnv)
-                : undefined;
-            const effectiveSecurityGroupIds = migrationTaskDef?.securityGroupIds ?? securityGroupIds;
+                : this.synthesiseInheritedMigrationTaskDef(svcConfig, migrations, effectiveMigrations, service, schemaVersionEnv);
             new EcsLifecycleHookMigration(this, `${toPascalCase(svcConfig.name)}Migrate`, {
                 service,
+                primaryContainer: primaryContainerDefinition(svcConfig, taskDefinition),
+                serviceName: svcConfig.name,
+                clusterName: this.clusterName,
                 clusterArn: cluster.clusterArn,
-                taskDefinitionArn: taskDefinition.taskDefinitionArn,
-                taskDefinitionFamily: taskDefinition.family,
-                taskExecutionRoleArn: taskDefinition.executionRole.roleArn,
-                taskRoleArn: taskDefinition.taskRole.roleArn,
-                command: effectiveMigrations.command,
-                containerName: effectiveMigrations.name ?? DEFAULT_MIGRATE_CONTAINER_NAME,
-                image: effectiveMigrations.image,
-                ...(effectiveMigrations.entryPoint !== undefined && {
-                    entryPoint: effectiveMigrations.entryPoint
-                }),
-                environment: effectiveMigrations.environment,
+                migrationTaskDefinition,
                 timeoutSeconds: effectiveMigrations.timeoutSeconds,
-                networkConfiguration: {
-                    subnetIds: subnets.subnetIds,
-                    securityGroupIds: effectiveSecurityGroupIds,
-                    assignPublicIp: !hasNat
-                },
-                ...(migrationTaskDef !== undefined && {
-                    migrationTaskDef: {
-                        definitionArn: migrationTaskDef.taskDefinitionArn,
-                        family: migrationTaskDef.family,
-                        taskRoleArn: migrationTaskDef.taskRoleArn,
-                        executionRoleArn: migrationTaskDef.executionRoleArn
-                    }
-                }),
                 lifecycleStage: lifecycleStageForHookMode(effectiveMigrations.mode)
             });
         }
     }
     /**
-     * Wire a native CloudFormation `DependsOn` from each service that declares
-     * `awaitMigrationsFrom` to the named migrate-owning service, so CFN does not
-     * roll out the dependent service until the target's ECS deployment — including
-     * its PRE_SCALE_UP migrate hook — has completed. Prevents the RDS-IAM auth /
-     * schema-mismatch race when a DB-connecting worker starts before the app's
-     * migrations have applied, and enables a single-pass greenfield deploy.
-     * Shape (target exists, declares hook migrations, no self / cycle) is already
-     * guaranteed by `validateEcsProps`; the undefined guards are synth invariants.
+     * Orders each service that declares `awaitMigrationsFrom` after the named
+     * migrate-owning service's rollout, so a DB-connecting worker never starts
+     * before the owner's migrations have applied. Each owner gets one rollout
+     * barrier (`EcsRolloutBarrier`): a custom resource that completes only once
+     * ECS reports the owner's deployment of its task definition finished, its
+     * lifecycle-hook migration included, and fails once ECS rolled that
+     * deployment back. Every dependant's `DependsOn` names the barrier.
+     *
+     * A `DependsOn` on the owner service itself no longer orders this: since
+     * 2026-10-01 CloudFormation starts the dependants of an updating ECS
+     * service at its eventual-consistency check, 20-31 s into the update, while
+     * a custom resource's dependants wait for its response (FJL-901).
+     *
+     * Shape (target exists, declares hook migrations, no self / cycle) is
+     * already guaranteed by `validateEcsProps`.
      */
     wireServiceMigrationDependencies(services) {
         for (const svcConfig of services) {
-            if (svcConfig.awaitMigrationsFrom === undefined)
+            const ownerName = svcConfig.awaitMigrationsFrom;
+            if (ownerName === undefined)
                 continue;
             const dependent = this.ecsCluster.getService(svcConfig.name);
-            const dependency = this.ecsCluster.getService(svcConfig.awaitMigrationsFrom);
-            if (dependent !== undefined && dependency !== undefined) {
-                dependent.node.addDependency(dependency);
+            if (dependent === undefined) {
+                throw new Error(`Service '${svcConfig.name}' not found in cluster after synthesis — cannot order its rollout.`);
             }
+            dependent.node.addDependency(this.rolloutBarrierOf(ownerName));
         }
     }
+    /** The service's one rollout barrier, made on first use. */
+    rolloutBarrierOf(serviceName) {
+        const existing = this.rolloutBarriers.get(serviceName);
+        if (existing !== undefined)
+            return existing;
+        const service = this.ecsCluster.getService(serviceName);
+        if (service === undefined) {
+            throw new Error(`Service '${serviceName}' is not a service of this cluster, so it has no rollout barrier.`);
+        }
+        const barrier = new EcsRolloutBarrier(this, `${toPascalCase(serviceName)}RolloutBarrier`, {
+            service,
+            serviceName,
+            clusterName: this.clusterName,
+            taskDefinitionArn: service.taskDefinition.taskDefinitionArn
+        });
+        this.rolloutBarriers.set(serviceName, barrier);
+        return barrier;
+    }
     /**
      * Synthesise a dedicated migration task definition for a lifecycle-hook
      * migration when `separateTaskDef` is set. Creates the migration's own
@@ -1464,7 +1532,7 @@ export class EcsCompute extends Construct {
         const idPrefix = `${toPascalCase(svcConfig.name)}Migrate`;
         const containerName = migrations.name ?? DEFAULT_MIGRATE_CONTAINER_NAME;
         const family = `${this.clusterId}-${svcConfig.name}-migrate`;
-        const inheritedImage = service.taskDefinition.defaultContainer?.imageName;
+        const inheritedImage = primaryContainerDefinition(svcConfig, service.taskDefinition)?.imageName;
         const image = resolveMigrationImage(svcConfig, migrations, inheritedImage);
         const logGroup = new LogGroup(this, `${idPrefix}LogGroup`, {
             retention: RetentionDays.ONE_MONTH,
@@ -1573,7 +1641,6 @@ export class EcsCompute extends Construct {
                 }
             }));
         }
-        let securityGroupIds;
         if (separateTaskDef.egressTo !== undefined &&
             separateTaskDef.egressTo.length > 0) {
             const migrationSg = new SecurityGroup(this, `${idPrefix}SecurityGroup`, {
@@ -1592,24 +1659,86 @@ export class EcsCompute extends Construct {
             }
             // Fargate agent pre-container 443 fetches; ECR API needs NAT egress.
             migrationSg.addEgressRule(Peer.anyIpv4(), Port.tcp(443), "Fargate agent HTTPS for ECR / secrets / logs");
-            securityGroupIds = [migrationSg.securityGroupId];
-        }
-        else {
-            securityGroupIds = service.connections.securityGroups.map((sg) => sg.securityGroupId);
+            // The hook reads the migration's own group here; without one, the
+            // migration runs in the service's groups, from the revision it serves.
+            Tags.of(taskDefinition).add(MIGRATION_SECURITY_GROUPS_TAG_KEY, migrationSg.securityGroupId, { includeResourceTypes: ["AWS::ECS::TaskDefinition"] });
         }
         this.migrationTaskDefinitions.set(svcConfig.name, taskDefinition);
-        return {
-            taskDefinitionArn: taskDefinition.taskDefinitionArn,
-            family: taskDefinition.family,
-            taskRoleArn: taskRole.roleArn,
-            executionRoleArn: executionRole.roleArn,
-            securityGroupIds
+        return taskDefinition;
+    }
+    /**
+     * The migration task definition of a lifecycle-hook migration without
+     * `separateTaskDef`. It runs what the hook's `RunTask` of the service's
+     * own task definition, its command and environment overridden, ran until
+     * FJL-901: as the service's own roles, at the service's size, in the
+     * service's log group, from the service's image, with the primary
+     * container's environment, entry point and secrets beneath the
+     * migration's own. A connected database's contributed secrets and role
+     * policies, such as its schema administrator's, reach only a
+     * `separateTaskDef` migration, whose roles are its own, so they never
+     * widen the service's.
+     */
+    synthesiseInheritedMigrationTaskDef(svcConfig, authored, migrations, service, schemaVersionEnv) {
+        const idPrefix = `${toPascalCase(svcConfig.name)}Migrate`;
+        const serviceTaskDefinition = service.taskDefinition;
+        const executionRole = serviceTaskDefinition.executionRole;
+        if (executionRole === undefined) {
+            throw new Error(`Service '${svcConfig.name}': task definition has no execution role — its migration runs as the service's roles.`);
+        }
+        const logGroup = this.ecsCluster.getServiceLogGroup(svcConfig.name);
+        if (logGroup === undefined) {
+            throw new Error(`Service '${svcConfig.name}' has no log group after synthesis — cannot route its migration's logs.`);
+        }
+        const primary = primaryContainerConfig(svcConfig.containers);
+        const taskDefinition = createMigrationTaskDefinition(this, `${idPrefix}TaskDefinition`, {
+            family: `${this.clusterId}-${svcConfig.name}-migrate`,
+            ...taskSize(svcConfig),
+            executionRole,
+            taskRole: serviceTaskDefinition.taskRole
+        });
+        const image = resolveMigrationImage(svcConfig, migrations, primaryContainerDefinition(svcConfig, serviceTaskDefinition)?.imageName);
+        const { secretsResolved } = this.resolveMigrationSecrets(svcConfig, { ...authored, ...secretsBeneathMigration(authored, primary) }, idPrefix);
+        const containerEnvironment = {
+            ...(primary?.environment ?? {}),
+            ...(migrations.environment ?? {})
         };
+        if (schemaVersionEnv !== undefined) {
+            for (const [key, value] of Object.entries(schemaVersionEnv)) {
+                if (migrations.environment?.[key] === undefined) {
+                    containerEnvironment[key] = value;
+                }
+            }
+        }
+        const entryPoint = migrations.entryPoint ?? primary?.entryPoint;
+        taskDefinition.addContainer(`${idPrefix}Container`, {
+            containerName: migrations.name ?? DEFAULT_MIGRATE_CONTAINER_NAME,
+            image: ContainerImage.fromRegistry(image),
+            command: migrations.command,
+            ...(entryPoint !== undefined && { entryPoint }),
+            environment: containerEnvironment,
+            secrets: secretsResolved,
+            logging: new AwsLogDriver({
+                streamPrefix: `/ecs-migrate/${svcConfig.name}`,
+                logGroup
+            })
+        });
+        return taskDefinition;
     }
     resolveMigrationSecrets(svcConfig, migrations, idPrefix) {
         const secretsResolved = {};
         const hasSecretsManagerSecrets = migrations.secretsImport !== undefined &&
             Object.keys(migrations.secretsImport).length > 0;
+        const secretsImport = migrations.secretsImport;
+        const namedTwice = secretsImport === undefined
+            ? []
+            : [...new Set(migrations.secrets ?? [])].filter((key) => Object.hasOwn(secretsImport, key));
+        if (namedTwice.length > 0) {
+            // Both kinds resolve into one record keyed by variable name, and the SSM
+            // secret, resolved second, replaces the import, as before 39.0.6.
+            Annotations.of(this).addWarning(`The migration of service '${svcConfig.name}' names ${namedTwice.join(", ")} ` +
+                `in both secrets and secretsImport. The SSM secret is used and the ` +
+                `secretsImport entry is not; name each variable once. Fjall 40 refuses this at synth.`);
+        }
         if (migrations.secretsImport) {
             for (const [key, secretImport] of Object.entries(migrations.secretsImport)) {
                 const secret = resolveImportedSecret(this, `${idPrefix}${key}Secret`, secretImport);
@@ -1633,7 +1762,7 @@ export class EcsCompute extends Construct {
                     service: svcConfig.name
                 });
             }
-            for (const secretName of migrations.secrets) {
+            for (const secretName of new Set(migrations.secrets)) {
                 validateSecretName(secretName, `migrations of service '${svcConfig.name}'`);
                 const param = StringParameter.fromSecureStringParameterAttributes(this, `${idPrefix}${secretName}SsmParam`, { parameterName: `${ssmPath}/${secretName}` });
                 secretsResolved[secretName] = EcsSecret.fromSsmParameter(param);
@@ -1675,11 +1804,30 @@ export class EcsCompute extends Construct {
      * Get the migration task definition for a service. Returns `undefined` when
      * the service has no `migrations: { mode: "lifecycle-hook", separateTaskDef }`
      * configured — escape hatch for callers that need to attach grants (e.g.
-     * `bucket.grantReadWrite(td.taskRole)`) to the migration task role.
+     * `bucket.grantReadWrite(td.taskRole)`) to the migration task role. Without
+     * `separateTaskDef` the migration runs in a task definition of its own that
+     * this does not return: its task role is the service's, so a grant to it
+     * would widen the service.
      */
     getMigrationTaskDefinition(serviceName) {
         return this.migrationTaskDefinitions.get(serviceName);
     }
+    /**
+     * The rollout barrier of a service: a custom resource that completes only
+     * once ECS reports the service's deployment of its task definition
+     * finished, and fails once ECS rolled that deployment back. A construct
+     * that depends on it is created or updated only after the service has
+     * rolled out, for orderings `awaitMigrationsFrom` cannot express:
+     * `compute.getService("worker")?.node.addDependency(compute.getRolloutBarrier("app"))`.
+     * A `DependsOn` on the service itself does not order this: CloudFormation
+     * may start a service's dependants at its eventual-consistency check, long
+     * before its deployment finishes (FJL-901). A service has one barrier,
+     * shared with `awaitMigrationsFrom`; one the cluster does not run is
+     * refused.
+     */
+    getRolloutBarrier(serviceName) {
+        return this.rolloutBarrierOf(serviceName);
+    }
     /** Get the security group for the cluster. */
     getSecurityGroup() {
         const sg = this.connections.securityGroups[0];