@fjall/components-infrastructure 0.96.0 → 0.99.3

package/dist/lib/patterns/aws/computeEcsTypes.d.ts

@@ -1,14 +1,16 @@
 import { type Repository } from "aws-cdk-lib/aws-ecr";
-import { type RepositoryImage } from "aws-cdk-lib/aws-ecs";
-import { type IVpc } from "aws-cdk-lib/aws-ec2";
-import { type PolicyDocument, type IManagedPolicy } from "aws-cdk-lib/aws-iam";
+import { type RepositoryImage, type ContainerImage, type PortMapping, type Secret as EcsSecret, type NetworkMode } from "aws-cdk-lib/aws-ecs";
+import { type IPeer, type ISecurityGroup, type IVpc, type Port, type SubnetSelection } from "aws-cdk-lib/aws-ec2";
+import { type ILogGroup, type RetentionDays } from "aws-cdk-lib/aws-logs";
+import { type PolicyDocument, type IManagedPolicy, type PolicyStatement } from "aws-cdk-lib/aws-iam";
 import type { ITopic } from "aws-cdk-lib/aws-sns";
 import { type ConnectionSpec } from "./interfaces/connector.js";
 import { type RemoteConnectionSpec } from "../../resources/aws/compute/ecsRemoteConnections.js";
-import { type EcsRoutingConfig } from "../../resources/aws/compute/ecsTypes.js";
+import { type EcsRoutingConfig, type EcsContainerDependency } from "../../resources/aws/compute/ecsTypes.js";
 import { ScalingType, type DomainConfig, type EcsCapacityProvider, type Ec2CapacityConfig } from "../../resources/aws/compute/ecs.js";
 import type { EcsServiceAlarmThresholds } from "../../resources/aws/monitoring/index.js";
 import { type SecretImport } from "../../resources/aws/secrets/index.js";
+import type { DockerBuild } from "@fjall/util/manifest/schemas";
 export type { RemoteConnectionSpec };
 export { ScalingType };
 export type { EcsCapacityProvider, Ec2CapacityConfig };
@@ -21,6 +23,22 @@ export interface EcsCapacityProviderConfig {
     /** Whether this runs on EC2 instances (vs serverless Fargate) */
     usesEc2Instances: boolean;
 }
+/**
+ * A dependency on another container in the same task definition.
+ * Maps directly to ECS `ContainerDependency` and the `addContainerDependencies`
+ * CDK API. `condition` corresponds to ECS's `ContainerDependencyCondition`:
+ *
+ * - `START` — dependency must have entered the running state
+ * - `COMPLETE` — dependency must have exited (any code); only valid for non-essential containers
+ * - `SUCCESS` — dependency must have exited 0; only valid for non-essential containers
+ * - `HEALTHY` — dependency must have passed its health check
+ *
+ * Public-facing alias for the canonical resource-layer `EcsContainerDependency`.
+ * Re-exported here so factory consumers can import it from the patterns barrel.
+ *
+ * @see https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_ContainerDependency.html
+ */
+export type ContainerDependency = EcsContainerDependency;
 /**
  * Configuration for a container in an ECS task.
  *
@@ -38,9 +56,20 @@ export interface EcsCapacityProviderConfig {
  *   { name: "app", port: 3000 },                    // Primary - receives ALB traffic
  *   { name: "datadog", image: "datadog/agent" }     // Sidecar - monitoring
  * ]
+ *
+ * @example
+ * // Init container with explicit dependsOn
+ * containers: [
+ *   { name: "migrate", essential: false, command: ["npx", "payload", "migrate"] },
+ *   { name: "app", port: 3000, dependsOn: [{ container: "migrate", condition: "SUCCESS" }] }
+ * ]
  */
 export interface EcsContainerConfig {
-    /** Container name. Optional for single-container services. */
+    /**
+     * Container name. Optional for single-container services.
+     * Required when this container is referenced by another's `dependsOn`,
+     * or when the `migrations` sugar would otherwise collide with this name.
+     */
     name?: string;
     /**
      * Container image. Options:
@@ -90,19 +119,383 @@ export interface EcsContainerConfig {
         retries?: number;
         startPeriod?: number;
     };
+    /**
+     * Containers in the same service that must reach a given state before this
+     * container starts. Resolved at synth time — referenced container names must
+     * match another container's `name` field in the same service.
+     *
+     * @example
+     * dependsOn: [{ container: "migrate", condition: "SUCCESS" }]
+     */
+    dependsOn?: ContainerDependency[];
+    /**
+     * Multi-port containers. CDK `PortMapping[]` verbatim. Mutually exclusive
+     * with `port` — supplying both throws a synth-time error (AC30).
+     */
+    portMappings?: PortMapping[];
+    /**
+     * Host-bind volumes mounted into this container. Each entry produces a
+     * matching `taskDefinition.addVolume(...)` + `container.addMountPoints(...)`
+     * pair (AC31).
+     */
+    volumes?: ContainerVolume[];
+    /**
+     * Time (seconds) ECS waits for the container to exit gracefully after
+     * sending SIGTERM before sending SIGKILL. Range: 1–120.
+     *
+     * Stateful containers (databases, queues mid-flush, anything with on-disk
+     * state) generally need longer than the CDK default (30s) to flush buffers,
+     * close connections, and persist state. Raise this when SIGTERM-to-SIGKILL
+     * inside the default window risks data loss or corruption (e.g. ClickHouse
+     * draining merges, Postgres flushing WAL).
+     *
+     * @default 30 (ECS default; CDK omits the field when unset)
+     */
+    stopTimeout?: number;
+}
+/**
+ * How the migration command is executed during deployment.
+ *
+ * - `"init-container"` (default) — synthesises a non-essential init container
+ *   in the service's task definition that runs to completion before any other
+ *   container starts. Every replica task pays the migration startup cost, but
+ *   the migration runs inside the same task family so the deployment cannot
+ *   move forward until migrations succeed. Recommended for ≤10-replica
+ *   services and any service whose `migrations.command` does work other than
+ *   migrations (seeding, cache warming, environment validation).
+ * - `"lifecycle-hook"` — runs the migration once per deployment via an ECS
+ *   `PRE_SCALE_UP` deployment lifecycle hook (AWS, September 2025). The hook
+ *   invokes a Lambda that launches the migration as a one-off task; the new
+ *   replica tasks scale up only after the hook reports `SUCCEEDED`. Cuts
+ *   per-replica startup latency at the cost of an extra Lambda + IAM role
+ *   per service. Suitable for high-replica services where the init-container
+ *   tax dominates rollout time.
+ *
+ * @see aiDocs/decisions/2026-04-29-ecs-init-container-over-runtask.md
+ * @see aiDocs/plans/2026-04-29-ecs-factory-hardening.md § 4.3.4 — threshold
+ *   guidance for choosing between modes.
+ * @see https://aws.amazon.com/blogs/containers/announcing-amazon-ecs-deployment-lifecycle-hooks/
+ */
+export type EcsMigrationsMode = "init-container" | "lifecycle-hook" | "post-deploy";
+/**
+ * Shorthand for the canonical "run migrations before the app starts" pattern.
+ *
+ * Default mode (`"init-container"`) synthesises a non-essential init container
+ * that runs to completion before any other container in the service starts.
+ * Optional `mode: "lifecycle-hook"` shifts the migration to an ECS deployment
+ * lifecycle hook — see {@link EcsMigrationsMode} for the trade-off.
+ *
+ * Defaults inherit from the primary container (first container with a `port`,
+ * or the first container if none have a port):
+ *
+ * - `image` → primary's `image`
+ * - `environment` → primary's `environment`
+ * - `secrets` → primary's `secrets` (SSM Parameter Store)
+ * - `secretsImport` → primary's `secretsImport` (Secrets Manager)
+ *
+ * Idempotency is the migration tool's responsibility — Payload, Prisma, Drizzle,
+ * Rails, Django, and Flyway are all idempotent by default.
+ *
+ * @example
+ * migrations: { command: ["npx", "payload", "migrate"] }
+ *
+ * @example
+ * migrations: {
+ *   command: ["prisma", "migrate", "deploy"],
+ *   timeoutSeconds: 600
+ * }
+ *
+ * @example
+ * // High-replica service: shift migration off the per-task startup path
+ * migrations: {
+ *   command: ["npx", "payload", "migrate"],
+ *   mode: "lifecycle-hook"
+ * }
+ *
+ * @see aiDocs/decisions/2026-04-29-ecs-init-container-over-runtask.md
+ */
+/**
+ * Discriminated on `mode`. The init-container variant keeps its narrow surface
+ * (no risk of authors setting CPU/memory/IAM overrides that would silently
+ * apply to the per-replica path). The lifecycle-hook variant carries `entryPoint?`
+ * and an opt-in `separateTaskDef?` sub-object for cross-cutting migrations
+ * that need permissions the service doesn't (e.g. RDS snapshot grants,
+ * cross-service Secrets Manager reads).
+ *
+ * Setting `separateTaskDef` on the init-container variant — or any
+ * lifecycle-hook-only field — is a typecheck error. This protects against
+ * the Pitfall-5 trap (silent field drift across union variants).
+ *
+ * @see aiDocs/designs/2026-05-12-migration-runner-abstraction-choice.md
+ * @see .claude/rules/typescript-standards.md § "Pitfall 5"
+ */
+export type EcsMigrationsConfig = EcsInitContainerMigrationsConfig | EcsLifecycleHookMigrationsConfig | EcsPostDeployMigrationsConfig;
+/**
+ * Union of the two lambda-driven deployment hook variants. Internal helper
+ * type — narrows from `EcsMigrationsConfig` once `expandMigrationsSugar` has
+ * established the migration runs out-of-band via a lifecycle hook (vs as an
+ * init container).
+ */
+export type EcsHookMigrationsConfig = EcsLifecycleHookMigrationsConfig | EcsPostDeployMigrationsConfig;
+/**
+ * Type-narrowing predicate for the two lambda-driven hook variants. Returns
+ * true for `"lifecycle-hook"` (PRE_SCALE_UP) and `"post-deploy"` (POST_SCALE_UP).
+ * Narrows the whole `EcsMigrationsConfig` to the hook-variant union, not just
+ * the `mode` property, so callers can read `separateTaskDef` / `entryPoint`
+ * etc. on the narrowed object.
+ */
+export declare function isHookMigrations(config: EcsMigrationsConfig): config is EcsHookMigrationsConfig;
+/**
+ * `mode: "init-container"` variant — migration runs as a non-essential init
+ * container inside each replica's task, dependsOn `COMPLETE` before main starts.
+ * `entryPoint` and `separateTaskDef` are intentionally absent — the per-replica
+ * init-container path has no separate IAM role to grant against.
+ */
+export interface EcsInitContainerMigrationsConfig {
+    /**
+     * Where the migration command runs during deployment. Defaults to
+     * `"init-container"`. Either omit (defaults) or set explicitly.
+     */
+    mode?: "init-container";
+    /** Migration command, e.g. `["npx", "payload", "migrate"]`. Required. */
+    command: string[];
+    /** Override timeout in seconds. Defaults to 300 (5 min). */
+    timeoutSeconds?: number;
+    /** Override image. Defaults to inheriting from the primary container. */
+    image?: string | Repository;
+    /** Override environment. Defaults to inheriting from the primary container. */
+    environment?: Record<string, string>;
+    /** Override Secrets-Manager imports. Defaults to inheriting from the primary container. */
+    secretsImport?: Record<string, SecretImport>;
+    /** Override SSM secret keys. Defaults to inheriting from the primary container. */
+    secrets?: string[];
+    /**
+     * Synthetic container name. Defaults to `"migrate"`.
+     * Override when a service container is already named `migrate`.
+     */
+    name?: string;
+}
+/**
+ * `mode: "lifecycle-hook"` variant — migration runs out-of-band via an ECS
+ * deployment lifecycle hook (PRE_SCALE_UP). The service rollout BLOCKS until
+ * the migration succeeds; one task per deploy.
+ *
+ * When `separateTaskDef` is present, `wireLifecycleHookMigrations` synthesises
+ * a SEPARATE migration task definition (its own IAM role, log group, runtime
+ * platform) instead of using `ContainerOverrides` on the service task def.
+ * Required when migrations need permissions the service doesn't.
+ */
+export interface EcsLifecycleHookMigrationsConfig {
+    /** Required for the lifecycle-hook variant. */
+    mode: "lifecycle-hook";
+    /** Migration command, e.g. `["node", "scripts/migration-runner.mjs"]`. Required. */
+    command: string[];
+    /** Override timeout in seconds. Defaults to 300 (5 min). Capped at 900s per Lambda invocation; longer migrations use the IN_PROGRESS callback chain. */
+    timeoutSeconds?: number;
+    /**
+     * Override image URI (string only). CDK `Repository` constructs cannot be
+     * JSON-serialised into the runner Lambda's `MIGRATE_CONFIG` env var; synth
+     * throws if a `Repository` is passed in lifecycle-hook mode.
+     */
+    image?: string;
+    /** Override environment. */
+    environment?: Record<string, string>;
+    /** Secrets-Manager imports for the migration container. */
+    secretsImport?: Record<string, SecretImport>;
+    /** SSM Parameter Store secret keys. */
+    secrets?: string[];
+    /** Synthetic container name. Defaults to `"migrate"`. */
+    name?: string;
+    /**
+     * Container entrypoint. Defaults to inheriting from the image. Set to
+     * `["/usr/bin/tini", "--"]` (or similar) to keep PID-1 signalling clean
+     * inside long-running migration containers.
+     */
+    entryPoint?: string[];
+    /**
+     * When present, synthesise a SEPARATE migration task definition (its own
+     * IAM role, log group, runtime platform) instead of using `ContainerOverrides`
+     * on the service task def. Required when migrations need permissions the
+     * service doesn't (e.g. `rds:CreateDBSnapshot`, cross-service Secrets Manager
+     * reads) — preserves least-privilege on the service task role.
+     *
+     * When absent, the lifecycle-hook runner uses the service's task def via
+     * ContainerOverrides — existing behaviour, unchanged.
+     */
+    separateTaskDef?: EcsLifecycleHookMigrationsSeparateTaskDef;
+}
+/**
+ * `mode: "post-deploy"` variant — runs out-of-band via an ECS deployment
+ * lifecycle hook on the POST_SCALE_UP stage. Fires AFTER the new task revision
+ * has scaled up and is healthy. A `FAILED` return from the hook triggers ECS
+ * deployment circuit-breaker rollback to the previous revision.
+ *
+ * Use cases: post-deploy data backfills that should run against the new code
+ * (not gate the rollout), cache warming, smoke tests that exercise the live
+ * service, sanity-check migrations that don't need to block traffic shift.
+ * Do NOT use for schema migrations that the new code depends on — use the
+ * pre-deploy `mode: "lifecycle-hook"` variant for those.
+ *
+ * Identical input shape to the lifecycle-hook variant; the only difference is
+ * the stage at which AWS fires the hook.
+ */
+export interface EcsPostDeployMigrationsConfig {
+    /** Required for the post-deploy variant. */
+    mode: "post-deploy";
+    /** Migration/backfill command. Required. */
+    command: string[];
+    /** Override timeout in seconds. Defaults to 300 (5 min). Capped at 900s per Lambda invocation. */
+    timeoutSeconds?: number;
+    /** Override image URI (string only). */
+    image?: string;
+    /** Override environment. */
+    environment?: Record<string, string>;
+    /** Secrets-Manager imports for the migration container. */
+    secretsImport?: Record<string, SecretImport>;
+    /** SSM Parameter Store secret keys. */
+    secrets?: string[];
+    /** Synthetic container name. Defaults to `"migrate"`. */
+    name?: string;
+    /** Container entrypoint. Defaults to inheriting from the image. */
+    entryPoint?: string[];
+    /**
+     * When present, synthesise a SEPARATE migration task definition. Same
+     * semantics as `EcsLifecycleHookMigrationsConfig.separateTaskDef`.
+     */
+    separateTaskDef?: EcsLifecycleHookMigrationsSeparateTaskDef;
+}
+/**
+ * Sub-config for `EcsLifecycleHookMigrationsConfig.separateTaskDef`. The
+ * migration container is parameterised exactly like every other container via
+ * the same `<ServiceName>ImageTag` CfnParameter — task-def revisions roll over
+ * whenever the parameter value changes.
+ */
+export interface EcsLifecycleHookMigrationsSeparateTaskDef {
+    /** Fargate task CPU (256, 512, 1024, 2048, 4096, 8192, 16384). */
+    cpu: number;
+    /** Task memory in MiB — must be compatible with `cpu` per the AWS Fargate task-size matrix. */
+    memoryLimitMiB: number;
+    /** Extra IAM statements appended to the migration task role only. */
+    taskRolePolicies?: PolicyStatement[];
+    /**
+     * Extra SG egress for the migration task. Omit to reuse the service's
+     * security group(s). Use this when the migration reaches a peer the
+     * service itself doesn't talk to.
+     */
+    egressTo?: Array<{
+        peer: IPeer;
+        port: Port;
+        description: string;
+    }>;
+    /**
+     * Runtime Secrets Manager reads — typed sugar that grants the migration task
+     * role `secretsmanager:GetSecretValue` on the named secrets, scoped to the
+     * specific ARNs (never `*`).
+     *
+     * Different from `secretsImport`: `secretsImport` mounts a secret value as
+     * an env var at container start via the ECS agent (execution role permission).
+     * `extraSecretReads` is for migrations that fetch secret values dynamically
+     * at runtime via the AWS SDK — e.g. when the secret name is computed inside
+     * the migration script, or when the migration writes back into Secrets
+     * Manager after rotation.
+     *
+     * Equivalent to passing the same statement via `taskRolePolicies`; this form
+     * is preferred for readability.
+     */
+    extraSecretReads?: Array<{
+        /** Secrets Manager secret name or ARN. */
+        secretName: string;
+        /** Optional human-facing description used in IAM statement Sid. */
+        description?: string;
+    }>;
+}
+/**
+ * Deployment circuit breaker policy for an ECS service.
+ *
+ * The circuit breaker watches a new deployment and, on detecting persistent
+ * task launch failures, marks the deployment as failed. With `rollback: true`
+ * the service automatically returns to the previous stable task definition.
+ *
+ * Defaults to `{ rollback: true }` when omitted — matches every example in
+ * AWS's own circuit-breaker documentation. CDK's default is `rollback: false`;
+ * we override to the safer shape.
+ *
+ * Set `circuitBreaker: false` to disable the breaker entirely (not recommended
+ * for production services).
+ *
+ * Set `circuitBreaker: { rollback: false }` to enable detection without
+ * automatic rollback — useful for first deploys where there is no prior
+ * baseline to roll back to.
+ *
+ * @see https://docs.aws.amazon.com/AmazonECS/latest/developerguide/deployment-circuit-breaker.html
+ */
+export interface EcsCircuitBreakerConfig {
+    /**
+     * Roll back to the previous stable deployment when the circuit breaker
+     * trips. Defaults to `true`.
+     */
+    rollback?: boolean;
 }
 /**
  * ECS scaling configuration.
- * - Omit: enabled with defaults
- * - `{}`: enabled with defaults
- * - `{ minCapacity: 2, maxCapacity: 10 }`: custom scaling
+ * - Omit: enabled, `minCapacity` tracks `desiredCount`, `maxCapacity` defaults to `Math.max(desiredCount + 1, 3)`
+ * - `{}`: same as omit
+ * - `{ minCapacity: 2, maxCapacity: 10 }`: custom scaling (explicit values win)
  * - `false`: explicitly disabled
+ *
+ * Setting `minCapacity > 0` while `desiredCount: 0` throws at synth — Application
+ * Auto Scaling would immediately scale the service back up, defeating the toggle.
  */
 export interface EcsScalingConfig {
     minCapacity?: number;
     maxCapacity?: number;
     scalingType?: ScalingType;
 }
+/**
+ * Host-bind volume mounted into one or more containers in the same task.
+ * Maps to ECS `Volume` + `MountPoint` pairs — see AC29 + AC31.
+ */
+export interface ContainerVolume {
+    /** Volume name. Used as `sourceVolume` on the container's mount point. */
+    name: string;
+    /**
+     * Host path bound into the container. Omit for an empty Docker volume that
+     * lives only for the task's lifetime (no host directory mount).
+     */
+    hostSourcePath?: string;
+    /** Path inside the container the volume is mounted at. */
+    mountPath: string;
+    /** Mount the volume read-only. Default: false. */
+    readOnly?: boolean;
+}
+/**
+ * Scheduled-task entry on the cluster. Each entry produces one
+ * `Ec2TaskDefinition` registered under the synthetic key `name` in
+ * `EcsCompute`'s task-definition map (collision-checked against steady-state
+ * service names) and an `app.addSchedule(...)` invocation. See AC27 + AC34.
+ */
+export interface EcsScheduledTaskConfig {
+    /** Synthetic name. Must not collide with any steady-state `serviceName`. */
+    name: string;
+    /** Cron or rate expression — passed verbatim to `app.addSchedule`. */
+    schedule: string;
+    /** CDK `ContainerImage` — typically `ContainerImage.fromRegistry(...)`. */
+    image: ContainerImage;
+    cpu: number;
+    memoryLimitMiB: number;
+    command?: string[];
+    /** Container secrets (Secrets Manager / SSM) — same shape as ECS `secrets`. */
+    secrets?: Record<string, EcsSecret>;
+    /** Pre-existing CDK log group. Mutually exclusive with `logRetention`. */
+    logGroup?: ILogGroup;
+    /** When `logGroup` is omitted, the awsLogs driver creates one with this retention. */
+    logRetention?: RetentionDays;
+    securityGroups?: ISecurityGroup[];
+    subnetSelection?: SubnetSelection;
+    networkMode?: NetworkMode;
+    /** Host-bind volumes mounted into the task's container. */
+    volumes?: ContainerVolume[];
+}
 /**
  * Cluster-level configuration.
  * Controls the shared ALB for all services in this cluster.
@@ -133,6 +526,19 @@ export interface EcsClusterConfig {
      * Allows for multi-region deployments with advanced DNS routing.
      */
     domainConfig?: DomainConfig;
+    /**
+     * Externally-supplied security group for the cluster's EC2 capacity. When
+     * provided, the ECS service factory wires this SG onto the underlying
+     * `Ec2Instance` instead of creating its own. Used by stateful workloads
+     * (e.g. ClickHouseDatabase) that own their security group lifecycle.
+     */
+    securityGroup?: ISecurityGroup;
+    /**
+     * Scheduled tasks materialised into `Ec2TaskDefinition`s and registered via
+     * `app.addSchedule(...)` against the existing `EcsScheduleTarget` shape
+     * ({ ecs, serviceName, taskCount }). See AC34.
+     */
+    scheduledTasks?: EcsScheduledTaskConfig[];
 }
 export type { EcsRoutingConfig };
 /**
@@ -207,21 +613,14 @@ export interface EcsServiceConfig {
      */
     scaling?: EcsScalingConfig | false;
     /**
-     * Path to Dockerfile for building this service's image.
-     * Metadata for CLI build process, not used during CDK synthesis.
-     */
-    dockerfilePath?: string;
-    /**
-     * Docker build target stage for multi-stage Dockerfiles.
-     * When specified, the CLI builds with `--target <dockerTarget>`.
-     * The image tag suffix is also updated: `<service>-<target>-latest`.
+     * Dockerfile build configuration for this service. Carries the path
+     * (absolute or relative), an optional build `context` for monorepo
+     * layouts, and an optional multi-stage `target`.
      *
-     * @example
-     * // Dockerfile: FROM node AS base ... FROM base AS api ... FROM base AS worker
-     * { name: "api", dockerTarget: "api" }   // builds: myapp-api-api-latest
-     * { name: "worker", dockerTarget: "worker" }  // builds: myapp-worker-worker-latest
+     * Tagged image suffix when `target` is set: `<service>-<target>-latest`.
+     * Mutually exclusive with `image` (pre-built URI).
      */
-    dockerTarget?: string;
+    docker?: DockerBuild;
     /**
      * Additional inline policies for this service's task role.
      * Added on top of the default ECS Exec permissions.
@@ -259,6 +658,21 @@ export interface EcsServiceConfig {
      * ]
      */
     connections?: ConnectionSpec[];
+    /**
+     * Schema-version gate opt-out. Defaults `true`.
+     *
+     * When any database in `connections` carries a `migrations` block, every
+     * container in this service receives `EXPECTED_SCHEMA_VERSION` resolved
+     * from that database's migration tool at synth time. Set `false` to skip
+     * the injection — intended for sidecars that intentionally tolerate
+     * schema drift or one-shot maintenance tasks.
+     *
+     * Named opt-out is auditable: grep-recoverable across the monorepo. Note
+     * the spelling collision with `@fjall/generator`'s codemod pipeline gate
+     * at `validationGate/gates/schema.ts` — different surface, different
+     * concept.
+     */
+    schemaGate?: boolean;
     /**
      * Cross-app resources reachable via VPC peering. Each entry resolves the
      * peered app's exposed resource at synth time (SSM `valueForStringParameter`
@@ -309,6 +723,96 @@ export interface EcsServiceConfig {
      * - object: override specific thresholds
      */
     alarms?: EcsServiceAlarmThresholds | false;
+    /**
+     * Run an init container before any other container in this service starts.
+     * Synthesises a non-essential container with the given migration command,
+     * inherits image / env / secrets from the primary container, and auto-wires
+     * every other container to wait on `SUCCESS`.
+     *
+     * @example
+     * migrations: { command: ["npx", "payload", "migrate"] }
+     */
+    migrations?: EcsMigrationsConfig;
+    /**
+     * Deployment circuit breaker policy. Omit for the safe default
+     * `{ enable: true, rollback: true }` — failed deployments automatically
+     * roll back to the previous stable task definition.
+     *
+     * Set to `false` to disable the breaker entirely. Set to
+     * `{ rollback: false }` for detection without automatic rollback (useful
+     * for first deploys where there is no prior baseline).
+     *
+     * @see https://docs.aws.amazon.com/AmazonECS/latest/developerguide/deployment-circuit-breaker.html
+     */
+    circuitBreaker?: false | EcsCircuitBreakerConfig;
+    /**
+     * Rolling-deploy capacity bounds (percent of `desiredCount`).
+     *
+     * - `minHealthyPercent` (0–100): floor of healthy tasks during a deploy.
+     *   `0` allows full task drain before the new task starts (recreate
+     *   semantics — required for singletons backed by an EBS volume that only
+     *   one task can attach to at a time, e.g. ClickHouse).
+     * - `maxHealthyPercent` (100–200): ceiling of running tasks during a
+     *   deploy. `100` forbids overlap (matches the singleton/recreate shape).
+     *   The default `200` allows a fresh task to start before the old one
+     *   drains (rolling shape — fits stateless services).
+     *
+     * Both must satisfy `min <= max`, and they cannot both be `100`
+     * (a no-op deploy that can't drain or expand).
+     *
+     * @default `{ minHealthyPercent: 100, maxHealthyPercent: 200 }` (CDK default)
+     */
+    deployment?: {
+        minHealthyPercent?: number;
+        maxHealthyPercent?: number;
+    };
+    /**
+     * Cloud Map service discovery for this service. When provided, the pattern
+     * registers the service against the application-level Cloud Map namespace
+     * (`app.getNamespace().registerService({ name })`) and threads the resulting
+     * `IService` to the resources layer, which calls `associateCloudMapService`
+     * after service construction. The namespace is `<appName>.local` and is
+     * lazily created on first registration — no cluster-level configuration.
+     *
+     * `dnsRecordType` defaults to `"A"` (paired with the AWS_VPC networkMode
+     * default). Set to `"SRV"` only when explicitly overriding `networkMode` to
+     * `HOST` or `BRIDGE` — CDK's `Ec2Service.associateCloudMapService(...)`
+     * rejects A records under those modes (the task shares the host's ENI IP,
+     * so the published port must travel with the record).
+     */
+    serviceDiscovery?: {
+        name: string;
+        dnsRecordType?: "A" | "SRV";
+    };
+    /**
+     * Override the task definition's `NetworkMode`. Defaults:
+     * - EC2 services: `AWS_VPC` (per-task ENI → per-task SG, A-record service
+     *   discovery works, current AWS recommendation for new workloads).
+     * - EC2 services with `cluster.directAccess: true`: `HOST` (direct port
+     *   binding to the instance, required for ECS Exec → host-port flows).
+     * - Fargate services: `AWS_VPC` (CDK requirement, not overridable).
+     *
+     * Cloud Map service discovery works under all three modes:
+     * - `AWS_VPC`: A records (default `serviceDiscovery.dnsRecordType`).
+     * - `HOST` / `BRIDGE`: SRV records — set
+     *   `serviceDiscovery.dnsRecordType: "SRV"` so the published port travels
+     *   with the record.
+     *
+     * ENI quota: each task under `AWS_VPC` attaches an ENI to the host
+     * instance. Instance ENI limits cap tasks-per-instance (e.g. t4g.medium
+     * → 2 tasks). For scale beyond the limit, enable ENI trunking at the
+     * account+instance level, pick larger instances, or override to `BRIDGE`.
+     */
+    networkMode?: NetworkMode;
+    /**
+     * Pre-existing security groups attached to this service's task ENIs (AWS_VPC
+     * mode). When omitted, CDK auto-creates a default service SG. Stateful
+     * patterns that own a wrapper SG (e.g. `ClickHouseDatabase`) set this so
+     * `this.connections.securityGroups[0]` is honest — the SG it points at is
+     * the SG the task ENI actually wears, not a CDK-autogenerated sibling that
+     * arbitrates no traffic.
+     */
+    securityGroups?: ISecurityGroup[];
 }
 /**
  * ECS compute configuration.
@@ -371,11 +875,10 @@ export interface EcsComputeProps {
      */
     ecrRepository?: Repository | RepositoryImage;
     /**
-     * Path to Dockerfile for building custom image.
-     * Note: This is metadata for the CLI build process,
-     * not used during CDK synthesis.
+     * Cluster-level Dockerfile build configuration. Used when no service-level
+     * `docker` is set. Metadata for the CLI build process; not used during synth.
      */
-    dockerfilePath?: string;
+    docker?: DockerBuild;
     /**
      * SNS topic for alarm notifications. Resolved to ITopic and passed to EcsCluster.
      * Accepts either an ITopic directly or a topic ARN string (resolved internally).

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

@@ -1,2 +1,12 @@
 import { ScalingType } from "../../resources/aws/compute/ecs.js";
 export { ScalingType };
+/**
+ * Type-narrowing predicate for the two lambda-driven hook variants. Returns
+ * true for `"lifecycle-hook"` (PRE_SCALE_UP) and `"post-deploy"` (POST_SCALE_UP).
+ * Narrows the whole `EcsMigrationsConfig` to the hook-variant union, not just
+ * the `mode` property, so callers can read `separateTaskDef` / `entryPoint`
+ * etc. on the narrowed object.
+ */
+export function isHookMigrations(config) {
+    return config.mode === "lifecycle-hook" || config.mode === "post-deploy";
+}

package/dist/lib/patterns/aws/computeLambda.d.ts

@@ -106,11 +106,6 @@ interface BaseLambdaProps {
      * ]
      */
     connections?: ConnectionSpec[];
-    /**
-     * EventBridge schedule expression for scheduled Lambda invocations.
-     * Uses cron or rate syntax: "rate(1 hour)" or "cron(0 12 * * ? *)".
-     */
-    scheduleExpression?: string;
 }
 /**
  * Container-based Lambda using ECR image.

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

@@ -68,7 +68,6 @@ export class LambdaCompute extends Construct {
             functionUrlAuthType,
             functionUrlCors,
             functionUrlInvokeMode,
-            scheduleExpression: props.scheduleExpression,
             ephemeralStorageSize: props.ephemeralStorageSize,
             secrets: props.secrets,
             ssmSecretsPath: props.ssmSecretsPath,
@@ -96,7 +95,7 @@ export class LambdaCompute extends Construct {
                 );
             }
             catch (error) {
-                throw new Error(`Failed to process connections for Lambda '${id}': ${error instanceof Error ? error.message : String(error)}`);
+                throw new Error(`Failed to process connections for Lambda '${id}': ${error instanceof Error ? error.message : String(error)}`, { cause: error });
             }
         }
     }