@fjall/components-infrastructure 0.95.0 → 0.99.1

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

@@ -0,0 +1,889 @@
+import { type Repository } from "aws-cdk-lib/aws-ecr";
+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, 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 };
+/**
+ * Configuration for ECS capacity providers.
+ */
+export interface EcsCapacityProviderConfig {
+    /** Whether this uses Spot pricing */
+    usesSpot: boolean;
+    /** 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.
+ *
+ * For single-container services, `name` is optional and defaults to `${serviceName}Container`.
+ * For multi-container tasks, the first container with a `port` is the **primary container**
+ * that receives load balancer traffic.
+ *
+ * @example
+ * // Single container (name auto-generated)
+ * containers: [{ port: 3000 }]
+ *
+ * @example
+ * // Multi-container with sidecars
+ * containers: [
+ *   { 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.
+     * 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:
+     * - Omit: Uses app's default ECR repository (primary container only)
+     * - string: ECR repository name or public image URL
+     * - Repository: CDK ECR Repository construct
+     */
+    image?: string | Repository;
+    /**
+     * Port the container listens on.
+     * The first container with a port becomes the **primary container**
+     * and is registered with the load balancer.
+     */
+    port?: number;
+    /** Environment variables */
+    environment?: Record<string, string>;
+    /**
+     * Secrets from AWS SSM Parameter Store.
+     * Array of secret names that will be fetched from the service's SSM namespace.
+     * The namespace path is auto-determined from app/cluster/service names.
+     *
+     * @example
+     * // Secrets at /myapp/api-cluster/users/API_KEY and /myapp/api-cluster/users/DB_PASSWORD
+     * secrets: ["API_KEY", "DB_PASSWORD"]
+     */
+    secrets?: string[];
+    /** Secrets imported from other CDK resources (AWS Secrets Manager) */
+    secretsImport?: Record<string, SecretImport>;
+    /** Command to run in the container */
+    command?: string[];
+    /** Entry point for the container */
+    entryPoint?: string[];
+    /**
+     * Whether this container is essential.
+     * If an essential container stops, all containers in the task stop.
+     * Default: true
+     */
+    essential?: boolean;
+    /**
+     * Health check configuration.
+     * Default: For primary container with port, uses curl health check.
+     */
+    healthCheck?: {
+        command: string[];
+        interval?: number;
+        timeout?: number;
+        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, `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.
+ */
+export interface EcsClusterConfig {
+    /**
+     * Domain for HTTPS access.
+     * - Omit: ALB created with default DNS (*.elb.amazonaws.com)
+     * - Specified: Creates ACM certificate + Route53 DNS A record
+     */
+    domain?: string;
+    /**
+     * Load balancer configuration.
+     * - Omit or "public": Internet-facing ALB (default)
+     * - "internal": VPC-only ALB
+     * - false: No ALB (for workers/background processors)
+     */
+    loadBalancer?: false | "public" | "internal";
+    /**
+     * Enable direct EC2 access without ALB.
+     * Uses host network mode for predictable ports.
+     * Access via EC2 public IP at container port.
+     */
+    directAccess?: boolean;
+    /**
+     * Advanced domain configuration for routing policies (latency, weighted, geo).
+     * Only used when domain is specified.
+     * 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 };
+/**
+ * Configuration for a service in an ECS cluster.
+ * Each service gets its own task definition, scaling config, and target group.
+ *
+ * @example
+ * // Simple service
+ * { name: "api", containers: [{ port: 3000 }] }
+ *
+ * @example
+ * // Service with routing (for multi-service clusters)
+ * { name: "users", containers: [{ port: 3000 }], routing: { path: "/users/*", priority: 100 } }
+ *
+ * @example
+ * // Service with multiple routing rules (same target group)
+ * { name: "web", containers: [{ port: 3000 }], routing: [
+ *   { path: "/api/v2/*", priority: 50 },
+ *   { path: "/*", priority: 200 },
+ * ]}
+ *
+ * @example
+ * // Service with sidecars
+ * {
+ *   name: "api",
+ *   containers: [
+ *     { name: "app", port: 3000 },
+ *     { name: "datadog", image: "datadog/agent" }
+ *   ]
+ * }
+ */
+export interface EcsServiceConfig {
+    /** Service name (unique within cluster) */
+    name: string;
+    /**
+     * Container image for this service (applies to first container without explicit image).
+     * - Omit: Uses app's default ECR repository
+     * - string: ECR repository name or public image URL
+     * - Repository: CDK ECR Repository construct
+     */
+    image?: string | Repository;
+    /**
+     * Container configuration(s) for this service.
+     * For single-container services, container name is optional and auto-generated.
+     * For multi-container services, the first container with a port is the primary container.
+     */
+    containers?: EcsContainerConfig[];
+    /**
+     * Routing rules for this service on the cluster's ALB.
+     * Required when cluster has multiple services with ports.
+     * Optional for single service (gets /* automatically).
+     * Can be a single rule or an array of rules pointing to the same target group.
+     *
+     * @example
+     * // Multiple routes for the same service
+     * routing: [
+     *   { path: "/api/v2/*", priority: 50 },
+     *   { path: "/*", priority: 200 },
+     * ]
+     */
+    routing?: EcsRoutingConfig | EcsRoutingConfig[];
+    /** CPU units for this service's tasks (256-4096) */
+    cpu?: number;
+    /** Memory in MiB for this service's tasks (512-30720) */
+    memoryLimitMiB?: number;
+    /** Desired number of tasks. Default: 2 */
+    desiredCount?: number;
+    /**
+     * Scaling configuration.
+     * - Omit: enabled with defaults
+     * - false: disabled
+     */
+    scaling?: EcsScalingConfig | false;
+    /**
+     * 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`.
+     *
+     * Tagged image suffix when `target` is set: `<service>-<target>-latest`.
+     * Mutually exclusive with `image` (pre-built URI).
+     */
+    docker?: DockerBuild;
+    /**
+     * Additional inline policies for this service's task role.
+     * Added on top of the default ECS Exec permissions.
+     * Use for service-specific AWS permissions (S3, DynamoDB, SQS, etc.).
+     */
+    taskRoleInlinePolicies?: Record<string, PolicyDocument>;
+    /**
+     * Additional managed policies for this service's task role.
+     * Added on top of the default ECS Exec permissions.
+     */
+    taskRoleManagedPolicies?: IManagedPolicy[];
+    /**
+     * Resources this service needs to connect to (e.g., databases, S3 buckets, SQS queues).
+     * Creates security group rules for IConnectable resources and IAM grants for IAM resources.
+     * Follows least-privilege - only this service gets access, not all services in the cluster.
+     *
+     * Supports:
+     * - IConnectable: Security group resources (RDS, ECS, etc.)
+     * - IStorageConnector: S3 buckets (IAM grants)
+     * - IDynamoDBConnector: DynamoDB tables (IAM grants)
+     * - IQueueConnector: SQS queues (IAM grants)
+     * - ConnectionConfig: Explicit access level configuration
+     *
+     * @example
+     * // Simple connections (default permissions)
+     * connections: [database, bucket, cache, queue]
+     *
+     * @example
+     * // Explicit access levels
+     * connections: [
+     *   database,                              // Security group (RDS)
+     *   { resource: cache, access: "read" },   // Read-only DynamoDB
+     *   { resource: bucket, access: "write" }, // Write-only S3
+     *   { resource: queue, access: "consume" } // Consume-only SQS
+     * ]
+     */
+    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`
+     * reads) and injects `${PREFIX}_HOST` + `${PREFIX}_PORT` env vars into every
+     * container in this service's task definition.
+     *
+     * @example
+     * remoteConnections: [
+     *   { peer, resource: "MainDatabase" },
+     *   { peer, resource: "CoreApi", envPrefix: "DATA_PLATFORM_API" }
+     * ]
+     */
+    remoteConnections?: RemoteConnectionSpec[];
+    /**
+     * Capacity provider for this service. REQUIRED.
+     * Each service specifies its own capacity provider.
+     *
+     * @example
+     * // Mixed FARGATE and EC2 services in same cluster
+     * {
+     *   services: [
+     *     { name: "api", capacityProvider: "FARGATE" },
+     *     { name: "worker", capacityProvider: "EC2", ec2Config: { instanceType: "t4g.micro" } }
+     *   ]
+     * }
+     */
+    capacityProvider: EcsCapacityProvider;
+    /**
+     * EC2 capacity configuration for this service.
+     * Only used when service capacityProvider is "EC2".
+     * Services with matching ec2Config share an ASG for efficiency.
+     */
+    ec2Config?: Ec2CapacityConfig;
+    /**
+     * SSM Parameter Store path for secrets.
+     * If not specified, secrets are fetched from /<app>/<cluster>/<service>.
+     * Use this to override the default convention.
+     *
+     * @example
+     * // Override default path
+     * ssmSecretsPath: "/custom/path/to/secrets"
+     */
+    ssmSecretsPath?: string;
+    /**
+     * Per-service alarm configuration.
+     * - undefined: use defaults (CPU, memory, running tasks, 5xx if ALB)
+     * - false: disable alarms for this service
+     * - 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.
+ * Creates an ECS cluster with one or more services sharing a load balancer.
+ *
+ * @example
+ * // Single service
+ * app.addCompute(ComputeFactory.build("WebApp", {
+ *   type: "ecs",
+ *   cluster: { domain: "app.example.com" },
+ *   services: [{ name: "web", containers: [{ port: 3000 }] }]
+ * }));
+ *
+ * @example
+ * // Multi-service cluster with routing
+ * app.addCompute(ComputeFactory.build("ApiCluster", {
+ *   type: "ecs",
+ *   cluster: { domain: "api.example.com" },
+ *   services: [
+ *     { name: "users", containers: [{ port: 3000 }], routing: { path: "/users/*" } },
+ *     { name: "orders", containers: [{ port: 3001 }], routing: { path: "/orders/*" } }
+ *   ]
+ * }));
+ *
+ * @example
+ * // Internal workers (no ALB)
+ * app.addCompute(ComputeFactory.build("Workers", {
+ *   type: "ecs",
+ *   cluster: { loadBalancer: false },
+ *   services: [{ name: "processor" }, { name: "emailer" }]
+ * }));
+ */
+export interface EcsComputeProps {
+    type: "ecs";
+    vpc?: IVpc;
+    /**
+     * Application name for SSM secrets namespace.
+     * When containers use secrets, the path is derived as: /<appName>/<clusterName>/<serviceName>
+     * Auto-derived from App.getName() if not specified.
+     */
+    appName?: string;
+    /**
+     * Cluster configuration.
+     * Controls the shared ALB for all services in this cluster.
+     * - Omit: ALB created with default settings
+     * - `{ domain: "..." }`: ALB with HTTPS + DNS
+     * - `{ loadBalancer: false }`: No ALB (internal workers)
+     */
+    cluster?: EcsClusterConfig;
+    /**
+     * Services in this cluster.
+     * Each service gets its own task definition, scaling, and target group.
+     * Each service MUST specify its own capacityProvider.
+     * All services share the cluster's ALB (unless disabled).
+     */
+    services: EcsServiceConfig[];
+    /**
+     * ECR repository for all services (default image).
+     * Individual services can override with their own `image` property.
+     */
+    ecrRepository?: Repository | RepositoryImage;
+    /**
+     * Cluster-level Dockerfile build configuration. Used when no service-level
+     * `docker` is set. Metadata for the CLI build process; not used during synth.
+     */
+    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).
+     */
+    alertsTopic?: ITopic | string;
+    /** Application ID for alarm tagging (used by webhook to map alarms to applications). */
+    applicationId?: string;
+}