@fjall/components-infrastructure 2.16.0 → 2.18.0

package/dist/lib/lambda-assets/cert-generator/asset/index.js

@@ -17897,6 +17897,15 @@ ${body}
 -----END PRIVATE KEY-----
 `;
 }
+function certPhysicalResourceId(event, caSecretArn, serverSecretArn) {
+  if (event.RequestType === "Update" && event.PhysicalResourceId) {
+    return event.PhysicalResourceId;
+  }
+  const digest = createHash("sha256").update(`${caSecretArn}
+${serverSecretArn}`).digest("hex").slice(0, 16);
+  return `tls-cert-${digest}`;
+}
+exports.certPhysicalResourceId = certPhysicalResourceId;
 exports.handler = async (event) => {
   if (event.RequestType === "Delete") {
     const props2 = event.ResourceProperties || {};
@@ -17964,7 +17973,11 @@ exports.handler = async (event) => {
     throw err;
   }
   return {
-    PhysicalResourceId: `tls-cert-${caCertSha256.slice(0, 16)}`,
+    PhysicalResourceId: certPhysicalResourceId(
+      event,
+      caSecretArn,
+      serverSecretArn
+    ),
     Data: { CaCertSha256: caCertSha256 }
   };
 };

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

@@ -5,6 +5,7 @@ import { Construct } from "constructs";
 import { Secret, type SecretImport } from "../../resources/aws/secrets/secret.js";
 import { type ClickHouseSchemaAdmin, type ProfileSpec } from "../../resources/aws/database/clickhouseSchemas.js";
 import { type ISecret } from "aws-cdk-lib/aws-secretsmanager";
+import { type ITopic } from "aws-cdk-lib/aws-sns";
 import type { ClickHouseTlsOptions } from "./clickhouseTls/index.js";
 import { type ClickHouseMigrationsConfig, type IClickHouseDatabase } from "./interfaces/database.js";
 import { type ISecurityGroupConnector } from "./interfaces/connector.js";
@@ -115,6 +116,22 @@ export interface ClickHouseDatabaseProps {
      * See ./clickhouseTls/types.ts.
      */
     tls?: ClickHouseTlsOptions;
+    /**
+     * Ops alarm SNS topic for the ClickHouse host-posture alarms (CPU / memory /
+     * disk warn+critical) and — when `backupSchedule` is enabled — the
+     * backup-failure alarm. Accepts an `ITopic`, an `arn:` string, or the
+     * `"import:<ExportName>"` form the generator scaffolds onto production apps
+     * (`"import:SharedAlarmTopicArn"`). Forwarded automatically by
+     * `DatabaseFactory.build` from `BaseDatabaseProps.alertsTopic`. Omitted (the
+     * default) → no host alarms, matching the dormant pre-dogfood behaviour.
+     *
+     * Resolved internally via `resolveAlertsTopic`; the construct owns the
+     * `instanceRole` / `asgName` / `backupTaskLogGroup` the alarms need, so no
+     * caller wiring is required. The stuck-merge alarm is NOT declared here —
+     * `"Stuck merge detected"` is emitted by the webapp app process, so it lives
+     * on the app service's declarative `logAlarms` instead.
+     */
+    alertsTopic?: ITopic | string;
 }
 /**
  * ClickHouse analytics database wrapper implementing IClickHouseDatabase.

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

@@ -18,6 +18,8 @@ import { LogGroup } from "../../resources/aws/logging/logGroup.js";
 import { createClickHouseSecurityGroup } from "../../resources/aws/database/clickhouseSecurityGroup.js";
 import { buildClickHouseEntrypointWrapper, buildClickHouseUserData, generateUsersConfigXml } from "../../resources/aws/database/clickhouseUserData.js";
 import { toPascalCase } from "../../utils/capitaliseString.js";
+import { resolveAlertsTopic } from "../../utils/resolveAlertsTopic.js";
+import { createClickHouseAlarms } from "../../resources/aws/monitoring/index.js";
 import { ClickHouseSchemaAdminSchema, ManagedPasswordNameSchema, ProfileSpecSchema, ClickHouseDefaultProfiles, PROFILE_NAME_PATTERN } from "../../resources/aws/database/clickhouseSchemas.js";
 import { inferAmiHardwareType } from "../../resources/aws/compute/ecsConstants.js";
 import { CLICKHOUSE_DATABASE_NAME, DEFAULT_CLICKHOUSE_INSTANCE_TYPE, CLICKHOUSE_IMAGE, CLICKHOUSE_EBS_VOLUME_SIZE_GB, CLICKHOUSE_EBS_IOPS, CLICKHOUSE_EBS_THROUGHPUT_MBPS, CLICKHOUSE_TASK_MEMORY_MIB, CLICKHOUSE_HTTP_PORT, CLICKHOUSE_HTTPS_PORT, CLICKHOUSE_NATIVE_PORT, CLICKHOUSE_TCP_SECURE_PORT, CLICKHOUSE_TLS_CERT_MOUNT_PATH, CLICKHOUSE_PROMETHEUS_PORT, CLICKHOUSE_DATA_MOUNT_PATH, CLICKHOUSE_SECRET_OPTIONS, CLICKHOUSE_SERVER_ROLE_TAG, clickHouseUserSecretName, CLICKHOUSE_HEALTH_CHECK, CLICKHOUSE_STOP_TIMEOUT_SECONDS, CLICKHOUSE_EBS_DEVICE_NAME, CLICKHOUSE_CONFIG_SUBDIR, CLICKHOUSE_USERS_SUBDIR, userPasswordEnvName, OPTIMISE_FINAL_SCHEDULE, REPLACING_MERGE_TREE_TABLES, OPTIMISE_MV_TABLES, CLICKHOUSE_CLOUDMAP_SERVICE_NAME, CLICKHOUSE_SERVER_CONTAINER_NAME, OPTIMISE_TASK_MEMORY_MIB, OPTIMISE_TASK_CPU_UNITS, BACKUP_SCHEDULE, BACKUP_TASK_MEMORY_MIB, BACKUP_TASK_CPU_UNITS, BACKUP_RETENTION_DAYS } from "../../resources/aws/database/clickhouseConstants.js";
@@ -480,6 +482,20 @@ export class ClickHouseDatabase extends Construct {
             tlsCaSecret.grantRead(instanceRole);
         if (tlsServerSecret !== undefined)
             tlsServerSecret.grantRead(instanceRole);
+        // asgName is the CloudWatch dimension the host metrics key off, so without
+        // it the alarms cannot be built; no topic is the default, so skip silently
+        // rather than throw.
+        const resolvedAlertsTopic = resolveAlertsTopic(this, "AlertsTopic", props.alertsTopic);
+        const asgName = ecsCompute.getAutoScalingGroupName();
+        if (resolvedAlertsTopic !== undefined && asgName !== undefined) {
+            createClickHouseAlarms({
+                scope: this,
+                instanceRole,
+                asgName,
+                alarmTopic: resolvedAlertsTopic,
+                ...(backupTaskLogGroup !== undefined && { backupTaskLogGroup })
+            });
+        }
         const adminSecretName = clickHouseUserSecretName(schemaAdmin.name);
         // Password via CLICKHOUSE_CLIENT_PASSWORD env, not --password on argv
         // (argv → /proc/<pid>/cmdline). `jq -r .password` on an empty pipeline

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

@@ -3,10 +3,10 @@ import { type Construct } from "constructs";
 import { type SecretImport } from "../../resources/aws/secrets/index.js";
 import { type ComputeType, type IEcsCompute, type ILambdaCompute, type IEc2Compute, type AnyCompute, isCompute, isEcsCompute, isLambdaCompute, isEc2Compute } from "./interfaces/compute.js";
 import type App from "../../app.js";
-import { EcsCompute, type EcsComputeProps, type EcsServiceConfig, type EcsContainerConfig, type EcsScalingConfig, type EcsClusterConfig, type EcsRoutingConfig, type EcsCapacityProviderConfig, type ContainerDependency, type EcsMigrationsConfig, ECS_CAPACITY_PROVIDER_CONFIG, getEcsCapacityProviderConfig, ScalingType, type EcsCapacityProvider, type Ec2CapacityConfig, validateEcsProps, buildContainerConfigs, expandMigrationsSugar, type ResolvedScalingConfig, resolveScalingConfig } from "./computeEcs.js";
+import { EcsCompute, type EcsComputeProps, type EcsServiceConfig, type ServiceLogAlarm, type EcsContainerConfig, type EcsScalingConfig, type EcsClusterConfig, type EcsRoutingConfig, type EcsCapacityProviderConfig, type ContainerDependency, type EcsMigrationsConfig, ECS_CAPACITY_PROVIDER_CONFIG, getEcsCapacityProviderConfig, ScalingType, type EcsCapacityProvider, type Ec2CapacityConfig, validateEcsProps, buildContainerConfigs, expandMigrationsSugar, type ResolvedScalingConfig, resolveScalingConfig } from "./computeEcs.js";
 import { LambdaCompute, type LambdaComputeProps, type ContainerLambdaProps, type CodeLambdaProps, type FunctionUrlConfig, type ResolvedLambdaDeployment, resolveLambdaDeployment, Architecture, HttpMethod, InvokeMode, type FunctionUrlCorsOptions } from "./computeLambda.js";
 import { Ec2Compute, type Ec2ComputeProps, type SshConfig } from "./computeEc2.js";
-export { EcsCompute, type EcsComputeProps, type EcsServiceConfig, type EcsContainerConfig, type EcsScalingConfig, type EcsClusterConfig, type EcsRoutingConfig, type EcsCapacityProviderConfig, ECS_CAPACITY_PROVIDER_CONFIG, getEcsCapacityProviderConfig, ScalingType, type EcsCapacityProvider, type Ec2CapacityConfig, type ContainerDependency, type EcsMigrationsConfig, validateEcsProps, buildContainerConfigs, expandMigrationsSugar, type ResolvedScalingConfig, resolveScalingConfig, LambdaCompute, type LambdaComputeProps, type ContainerLambdaProps, type CodeLambdaProps, type FunctionUrlConfig, type ResolvedLambdaDeployment, resolveLambdaDeployment, Architecture, HttpMethod, InvokeMode, type FunctionUrlCorsOptions, Ec2Compute, type Ec2ComputeProps, type SshConfig };
+export { EcsCompute, type EcsComputeProps, type EcsServiceConfig, type ServiceLogAlarm, type EcsContainerConfig, type EcsScalingConfig, type EcsClusterConfig, type EcsRoutingConfig, type EcsCapacityProviderConfig, ECS_CAPACITY_PROVIDER_CONFIG, getEcsCapacityProviderConfig, ScalingType, type EcsCapacityProvider, type Ec2CapacityConfig, type ContainerDependency, type EcsMigrationsConfig, validateEcsProps, buildContainerConfigs, expandMigrationsSugar, type ResolvedScalingConfig, resolveScalingConfig, LambdaCompute, type LambdaComputeProps, type ContainerLambdaProps, type CodeLambdaProps, type FunctionUrlConfig, type ResolvedLambdaDeployment, resolveLambdaDeployment, Architecture, HttpMethod, InvokeMode, type FunctionUrlCorsOptions, Ec2Compute, type Ec2ComputeProps, type SshConfig };
 export type { ComputeType } from "./interfaces/compute.js";
 /**
  * Configuration defaults for each compute type.

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

@@ -7,7 +7,7 @@ import { type IEcsCompute } from "./interfaces/compute.js";
 import { type SecretImport } from "../../resources/aws/secrets/index.js";
 import EcsCluster, { type EcsClusterProps } from "../../resources/aws/compute/ecs.js";
 export { ScalingType } from "./computeEcsTypes.js";
-export type { EcsCapacityProvider, Ec2CapacityConfig, RemoteConnectionSpec, EcsCapacityProviderConfig, EcsContainerConfig, ContainerDependency, ContainerVolume, EcsScheduledTaskConfig, EcsLifecycleHookMigrationsConfig, EcsPostDeployMigrationsConfig, EcsHookMigrationsConfig, EcsMigrationsConfig, EcsMigrationsMode, EcsCircuitBreakerConfig, EcsScalingConfig, EcsClusterConfig, EcsRoutingConfig, EcsServiceConfig, EcsComputeProps } from "./computeEcsTypes.js";
+export type { EcsCapacityProvider, Ec2CapacityConfig, RemoteConnectionSpec, EcsCapacityProviderConfig, EcsContainerConfig, ContainerDependency, ContainerVolume, EcsScheduledTaskConfig, EcsLifecycleHookMigrationsConfig, EcsPostDeployMigrationsConfig, EcsHookMigrationsConfig, EcsMigrationsConfig, EcsMigrationsMode, EcsCircuitBreakerConfig, EcsScalingConfig, EcsClusterConfig, EcsRoutingConfig, EcsServiceConfig, ServiceLogAlarm, EcsComputeProps } from "./computeEcsTypes.js";
 import { ScalingType, type EcsCapacityProviderConfig, type EcsCapacityProvider, type EcsContainerConfig, type EcsScalingConfig, type EcsServiceConfig, type EcsComputeProps, type QueueScalingConfig } from "./computeEcsTypes.js";
 export declare const ECS_CAPACITY_PROVIDER_CONFIG: Record<EcsCapacityProvider, EcsCapacityProviderConfig>;
 export declare function getEcsCapacityProviderConfig(provider: EcsCapacityProvider): EcsCapacityProviderConfig;
@@ -124,6 +124,17 @@ export declare class EcsCompute extends Construct implements IEcsCompute {
      * migrate container injected by `expandMigrationsSugar`.
      */
     private wireLifecycleHookMigrations;
+    /**
+     * 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.
+     */
+    private wireServiceMigrationDependencies;
     /**
      * Synthesise a dedicated migration task definition for a lifecycle-hook
      * migration when `separateTaskDef` is set. Creates the migration's own

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

@@ -154,6 +154,39 @@ export function validateEcsProps(props) {
             validateSeparateTaskDef(service.name, service.migrations.separateTaskDef);
         }
     }
+    // Validate awaitMigrationsFrom cross-service migration ordering.
+    const serviceByName = new Map(props.services.map((s) => [s.name, s]));
+    for (const service of props.services) {
+        const target = service.awaitMigrationsFrom;
+        if (target === undefined)
+            continue;
+        if (target === service.name) {
+            throw new Error(`Service '${service.name}': awaitMigrationsFrom cannot reference its own migrations.`);
+        }
+        const targetService = serviceByName.get(target);
+        if (targetService === undefined) {
+            throw new Error(`Service '${service.name}': awaitMigrationsFrom names unknown service '${target}'. ` +
+                "It must name another service in the same cluster.");
+        }
+        if (targetService.migrations === undefined ||
+            !isHookMigrations(targetService.migrations)) {
+            throw new Error(`Service '${service.name}': awaitMigrationsFrom names service '${target}', which does not ` +
+                "declare lifecycle-hook or post-deploy migrations. Only those modes have a single " +
+                "completion point to await (init-container migrations run per-replica).");
+        }
+    }
+    // Detect cycles in the awaitMigrationsFrom graph (each service awaits <=1 other).
+    for (const service of props.services) {
+        const seen = new Set();
+        let current = service.name;
+        while (current !== undefined) {
+            if (seen.has(current)) {
+                throw new Error(`Service '${service.name}': awaitMigrationsFrom forms a dependency cycle.`);
+            }
+            seen.add(current);
+            current = serviceByName.get(current)?.awaitMigrationsFrom;
+        }
+    }
     if (props.cluster?.directAccess === true) {
         const hasEc2Service = props.services.some((s) => s.capacityProvider === "EC2");
         if (!hasEc2Service) {
@@ -722,6 +755,8 @@ export class EcsCompute extends Construct {
                 ssmSecretsPath: service.ssmSecretsPath,
                 docker: service.docker,
                 alarms: service.alarms,
+                logAlarms: service.logAlarms,
+                logMetricNamespace: service.logMetricNamespace,
                 circuitBreaker: service.circuitBreaker,
                 ...(service.deployment !== undefined && {
                     deployment: service.deployment
@@ -763,6 +798,7 @@ export class EcsCompute extends Construct {
         this.ecsCluster = new EcsCluster(this, `${id}Ecs`, ecsProps);
         this.connections = this.ecsCluster.connections;
         this.wireLifecycleHookMigrations(props.services);
+        this.wireServiceMigrationDependencies(props.services);
         this.materialiseScheduledTasks(id, props);
     }
     /**
@@ -985,6 +1021,27 @@ export class EcsCompute extends Construct {
             });
         }
     }
+    /**
+     * 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.
+     */
+    wireServiceMigrationDependencies(services) {
+        for (const svcConfig of services) {
+            if (svcConfig.awaitMigrationsFrom === 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);
+            }
+        }
+    }
     /**
      * Synthesise a dedicated migration task definition for a lifecycle-hook
      * migration when `separateTaskDef` is set. Creates the migration's own

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

@@ -8,7 +8,7 @@ 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, type QueueScalingConfig } from "../../resources/aws/compute/ecs.js";
-import type { EcsServiceAlarmThresholds } from "../../resources/aws/monitoring/index.js";
+import type { EcsServiceAlarmThresholds, LogPatternAlarmSpec } 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 };
@@ -39,6 +39,13 @@ export interface EcsCapacityProviderConfig {
  * @see https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_ContainerDependency.html
  */
 export type ContainerDependency = EcsContainerDependency;
+/**
+ * A log-pattern alarm declared on a service: a CloudWatch metric filter over the
+ * service's log group plus the alarm that fires on a match. Public-facing alias
+ * for the canonical resource-layer `LogPatternAlarmSpec`, re-exported so factory
+ * consumers can declare `logAlarms` from the patterns barrel.
+ */
+export type ServiceLogAlarm = LogPatternAlarmSpec;
 /**
  * Configuration for a container in an ECS task.
  *
@@ -729,6 +736,20 @@ export interface EcsServiceConfig {
      * - object: override specific thresholds
      */
     alarms?: EcsServiceAlarmThresholds | false;
+    /**
+     * Log-pattern alarms for this service. Each entry creates a CloudWatch metric
+     * filter over the service's log group plus an alarm wired to the cluster's
+     * `alertsTopic` — so it materialises only when `alertsTopic` is set and
+     * `alarms !== false`. Declarative: describe the match with `literal` or
+     * `anyTerms`.
+     */
+    logAlarms?: ServiceLogAlarm[];
+    /**
+     * Default CloudWatch metric namespace for this service's `logAlarms`. Each
+     * entry may override it per-alarm (e.g. `Fjall/WebApp` for app alarms,
+     * `Fjall/ClickHouse` for a relocated stuck-merge alarm on the same service).
+     */
+    logMetricNamespace?: string;
     /**
      * Run an init container before any other container in this service starts.
      * Synthesises a non-essential container with the given migration command,
@@ -739,6 +760,35 @@ export interface EcsServiceConfig {
      * migrations: { command: ["npx", "payload", "migrate"] }
      */
     migrations?: EcsMigrationsConfig;
+    /**
+     * Names another service in the same cluster whose **lifecycle-hook** (or
+     * post-deploy) migrations must finish before this service rolls out.
+     *
+     * Implemented as a native CloudFormation `DependsOn`: CFN will not begin
+     * creating or updating this service until the named service's ECS deployment
+     * — including its PRE_SCALE_UP migrate hook — has completed. Use it for
+     * DB-connecting workers that must not start until the migrate-owning service
+     * has applied role / grant / schema migrations; without it, a worker can
+     * attempt RDS-IAM auth before the migrate task has run `GRANT rds_iam` (the
+     * race that aborts a migration-bearing deploy). Also enables a single-pass
+     * greenfield deploy (app migrates, then workers come up, in one `cdk deploy`).
+     *
+     * Works for EC2-capacity services — it is a resource-ordering edge, not a
+     * worker-side lifecycle hook, so the FARGATE-only restriction on hook
+     * migrations does not apply here.
+     *
+     * The named service MUST declare `migrations` in `lifecycle-hook` or
+     * `post-deploy` mode — init-container migrations run per-replica and have no
+     * single completion point to await. Validated at synth (target exists,
+     * declares hook migrations, no self-reference, no cycle).
+     *
+     * Escape hatch for orderings this field can't express: drop to the L2 API,
+     * `cluster.getService("x")?.node.addDependency(cluster.getService("y")!)`.
+     *
+     * @example
+     * awaitMigrationsFrom: "app"
+     */
+    awaitMigrationsFrom?: string;
     /**
      * Deployment circuit breaker policy. Omit for the safe default
      * `{ enable: true, rollback: true }` — failed deployments automatically

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

@@ -131,6 +131,14 @@ export interface InstanceDatabaseProps extends BaseDatabaseProps {
     credentials?: CredentialsConfig;
     encryption?: EncryptionConfig;
     publiclyAccessible?: boolean;
+    /**
+     * Enable RDS IAM database authentication (opt-in; default off). Instance
+     * databases only. When true, IAM principals granted via
+     * {@link RelationalDatabase.grantIamConnect} connect with short-lived
+     * `rds-db:connect` tokens instead of a stored password. See ADR
+     * decisions/2026-06-17-rls-role-auth-and-launch-gating.md.
+     */
+    iamAuthentication?: boolean;
     /** ARN or identifier of DB instance snapshot to restore from */
     snapshotIdentifier?: string;
     /** Username from the snapshot (required when restoring from snapshot to reset password) */
@@ -247,7 +255,7 @@ export declare class RelationalDatabase extends Construct implements IRelational
     private database;
     constructor(scope: Construct, id: string, props: IRelationalDatabaseProps);
     private resolveAlertsTopic;
-    addDatabase(props: IRelationalDatabaseProps): void;
+    private addDatabase;
     private addAurora;
     private addAuroraGlobal;
     private addRdsInstance;
@@ -278,6 +286,16 @@ export declare class RelationalDatabase extends Construct implements IRelational
      * @param grantee The connectable principal to grant connect permissions to
      */
     grantConnect(grantee: IConnectable): void;
+    /**
+     * Grant an IAM principal permission to connect as `dbUsername` via RDS IAM
+     * database authentication. Instance databases only — Aurora uses a different
+     * mechanism, so this throws for non-Instance databases. Requires the instance
+     * to be created with `iamAuthentication: true`. The L2 `grantConnect` scopes
+     * `rds-db:connect` to the exact `dbuser:<resourceId>/<dbUsername>` ARN — never
+     * a bare wildcard. See ADR
+     * decisions/2026-06-17-rls-role-auth-and-launch-gating.md.
+     */
+    grantIamConnect(grantee: IGrantable, dbUsername: string): Grant;
 }
 export { ClickHouseDatabase, type ClickHouseDatabaseProps };
 export { ClickHouseDefaultProfiles, ClickHouseSchemaAdminSchema, ManagedPasswordNameSchema, ProfileSpecSchema, type ClickHouseSchemaAdmin, type ManagedPasswordName, type ProfileSpec } from "../../resources/aws/database/clickhouseSchemas.js";

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

@@ -118,7 +118,7 @@ function validateRelationalDatabaseProps(props) {
             "Specify the AWS region where the primary cluster will be created.");
     }
     // Instance-only options on Aurora/GlobalAurora
-    warnIfPropertiesIgnored(props, ["readReplica", "multiAz", "allocatedStorage"], "Instance", "Instance database");
+    warnIfPropertiesIgnored(props, ["readReplica", "multiAz", "allocatedStorage", "iamAuthentication"], "Instance", "Instance database");
     // Aurora-only options on Instance
     warnIfPropertiesIgnored(props, ["readers", "writer", "backupRetention"], ["Aurora", "GlobalAurora"], "Aurora database");
     // GlobalAurora-only options on non-global databases
@@ -328,6 +328,8 @@ export class RelationalDatabase extends Construct {
         return resolveAlertsTopicShared(this, "AlertsTopic", alertsTopic);
     }
     addDatabase(props) {
+        // Re-asserted here (the constructor already validates) to narrow
+        // `props.vpc` to `IVpc` for the type-specific add* dispatch below.
         validateRelationalDatabaseProps(props);
         switch (props.type) {
             case "Aurora":
@@ -440,7 +442,8 @@ export class RelationalDatabase extends Construct {
             snapshotUsername: props.snapshotUsername,
             alertsTopic: this.resolveAlertsTopic(props.alertsTopic),
             alarms: props.alarms,
-            applicationId: props.applicationId
+            applicationId: props.applicationId,
+            iamAuthentication: props.iamAuthentication
         });
         this.connections = this.database.connections;
         this.addDatabaseOutputs(props);
@@ -595,6 +598,22 @@ export class RelationalDatabase extends Construct {
     grantConnect(grantee) {
         this.connections.allowDefaultPortFrom(grantee);
     }
+    /**
+     * Grant an IAM principal permission to connect as `dbUsername` via RDS IAM
+     * database authentication. Instance databases only — Aurora uses a different
+     * mechanism, so this throws for non-Instance databases. Requires the instance
+     * to be created with `iamAuthentication: true`. The L2 `grantConnect` scopes
+     * `rds-db:connect` to the exact `dbuser:<resourceId>/<dbUsername>` ARN — never
+     * a bare wildcard. See ADR
+     * decisions/2026-06-17-rls-role-auth-and-launch-gating.md.
+     */
+    grantIamConnect(grantee, dbUsername) {
+        if (!(this.database instanceof RdsInstance)) {
+            throw new Error(`grantIamConnect is only supported for Instance databases; ` +
+                `'${this._databaseName}' is a ${this.databaseType} database.`);
+        }
+        return this.database.grantIamConnect(grantee, dbUsername);
+    }
 }
 export { ClickHouseDatabase };
 export { ClickHouseDefaultProfiles, ClickHouseSchemaAdminSchema, ManagedPasswordNameSchema, ProfileSpecSchema } from "../../resources/aws/database/clickhouseSchemas.js";

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

@@ -43,8 +43,13 @@ export class Ec2GracefulTerminationHandler extends Construct {
         const dataVolumeOwnerLogicalId = resolveOptionalString(props.dataVolumeOwnerLogicalId);
         this.queue = new SQSQueue(this, `${id}Queue`, {
             visibilityTimeout: QUEUE_VISIBILITY_TIMEOUT_SECONDS,
-            deadLetterQueue: { enabled: true, maxReceiveCount: 5 }
+            deadLetterQueue: { enabled: true, maxReceiveCount: 5 },
+            // Transient instance-drain signals — no durable state. Pinned DESTROY
+            // (now also the SQSQueue wrapper default) so a replacing deploy of the
+            // parent Ec2Instance reclaims this queue + DLQ instead of orphaning them.
+            removalPolicy: "DESTROY"
         });
+        const stack = Stack.of(this);
         const ecsPolicies = ecsClusterArn !== undefined
             ? [
                 new PolicyStatement({
@@ -66,6 +71,9 @@ export class Ec2GracefulTerminationHandler extends Construct {
                 })
             ]
             : [];
+        // EIP/ENI mutations cannot be ARN-scoped (the resources are not known at
+        // synth), but the Lambda only ever drains instances in its own region — a
+        // region clamp removes the cross-region blast radius a bare "*" would allow.
         const ec2Policies = new PolicyStatement({
             effect: Effect.ALLOW,
             actions: [
@@ -74,7 +82,10 @@ export class Ec2GracefulTerminationHandler extends Construct {
                 "ec2:DescribeNetworkInterfaces",
                 "ec2:DetachNetworkInterface"
             ],
-            resources: ["*"]
+            resources: ["*"],
+            conditions: {
+                StringEquals: { "aws:RequestedRegion": stack.region }
+            }
         });
         const elbReadPolicy = new PolicyStatement({
             effect: Effect.ALLOW,
@@ -94,7 +105,6 @@ export class Ec2GracefulTerminationHandler extends Construct {
                 }
             }
         });
-        const stack = Stack.of(this);
         // Account/region-scoped wildcard rather than the specific ASG ARN —
         // see PersistentDataVolume for the full deadlock writeup. Same gotcha:
         // a specific ARN creates a CFN Ref to the ASG, the Lambda's IAM Policy

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

@@ -4,7 +4,7 @@ import { Construct } from "constructs";
 import { CfnOutput, Aspects } from "aws-cdk-lib";
 import { processConnections } from "../../../utils/connections.js";
 import { toPascalCase } from "../../../utils/capitaliseString.js";
-import { createEcsServiceAlarms } from "../monitoring/index.js";
+import { createEcsServiceAlarms, createLogPatternAlarms } from "../monitoring/index.js";
 // Extracted modules
 import { CapacityProviderDependencyAspect } from "./ecsCapacityProviderAspect.js";
 import { validateEcsClusterProps } from "./ecsValidation.js";
@@ -210,7 +210,7 @@ export default class EcsCluster extends Construct {
         const executionRole = createExecutionRole(this.ctx, serviceName);
         const taskRole = createTaskRole(this.ctx, serviceName, serviceProps);
         const taskDefinition = createTaskDefinition(this.ctx, serviceName, serviceProps, executionRole, taskRole);
-        const { containers, primaryContainer } = addContainersToTask(this.ctx, serviceName, serviceProps, taskDefinition);
+        const { containers, primaryContainer, logGroup } = addContainersToTask(this.ctx, serviceName, serviceProps, taskDefinition);
         const service = createService(this.ctx, serviceName, serviceProps, taskDefinition, this.asgState);
         let targetGroup;
         if (!this.loadBalancerDisabled &&
@@ -230,7 +230,8 @@ export default class EcsCluster extends Construct {
             containers,
             primaryContainer,
             targetGroup,
-            scalingPolicy
+            scalingPolicy,
+            logGroup
         });
         if (serviceProps.connections && serviceProps.connections.length > 0) {
             try {
@@ -253,6 +254,16 @@ export default class EcsCluster extends Construct {
                 alarmTopic: this.props.alertsTopic,
                 applicationId: this.props.applicationId
             });
+            if (serviceProps.logAlarms && serviceProps.logAlarms.length > 0) {
+                createLogPatternAlarms({
+                    scope: this,
+                    logGroup,
+                    alarmTopic: this.props.alertsTopic,
+                    metricNamespace: serviceProps.logMetricNamespace,
+                    specs: serviceProps.logAlarms,
+                    applicationId: this.props.applicationId
+                });
+            }
         }
     }
     setupConnections(props) {

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

@@ -1,8 +1,10 @@
 import { AmiHardwareType } from "aws-cdk-lib/aws-ecs";
+import { RetentionDays } from "aws-cdk-lib/aws-logs";
 export declare const DEFAULT_EC2_INSTANCE_TYPE = "t4g.micro";
 export declare const DEFAULT_WARM_POOL_MIN_SIZE = 1;
 export declare const DEFAULT_WARM_POOL_REUSE_ON_SCALE_IN = false;
 export declare const DEFAULT_LOG_RETENTION_DAYS = 14;
+export declare const DEFAULT_LOG_RETENTION = RetentionDays.TWO_WEEKS;
 export declare const DEFAULT_FARGATE_CPU = 256;
 export declare const DEFAULT_FARGATE_MEMORY_MIB = 512;
 export declare const DEFAULT_EC2_CONTAINER_MEMORY_MIB = 1024;

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

@@ -1,4 +1,5 @@
 import { AmiHardwareType } from "aws-cdk-lib/aws-ecs";
+import { RetentionDays } from "aws-cdk-lib/aws-logs";
 // Canonical source: @fjall/generator schemas/constants.ts — keep in sync
 export const DEFAULT_EC2_INSTANCE_TYPE = "t4g.micro";
 export const DEFAULT_WARM_POOL_MIN_SIZE = 1;
@@ -8,6 +9,9 @@ export const DEFAULT_WARM_POOL_MIN_SIZE = 1;
 export const DEFAULT_WARM_POOL_REUSE_ON_SCALE_IN = false;
 // 14 days balances cost against retaining enough history for post-mortem debugging
 export const DEFAULT_LOG_RETENTION_DAYS = 14;
+// The RetentionDays enum the explicit service LogGroup needs. Coupled to
+// DEFAULT_LOG_RETENTION_DAYS (TWO_WEEKS === 14) — the two must move together.
+export const DEFAULT_LOG_RETENTION = RetentionDays.TWO_WEEKS;
 // Smallest valid (cpu, memory) pair on the Fargate matrix — must move together.
 export const DEFAULT_FARGATE_CPU = 256;
 export const DEFAULT_FARGATE_MEMORY_MIB = 512;

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

@@ -1,5 +1,6 @@
 import { FargateTaskDefinition, Ec2TaskDefinition, NetworkMode, type ContainerDefinition } from "aws-cdk-lib/aws-ecs";
 import type { Construct } from "constructs";
+import type { ILogGroup } from "aws-cdk-lib/aws-logs";
 import { type Role } from "aws-cdk-lib/aws-iam";
 import type { EcsConstructContext } from "./ecsContext.js";
 import type { EcsClusterProps, EcsServiceProps, EcsCapacityProvider } from "./ecsTypes.js";
@@ -52,4 +53,5 @@ export declare function createMigrationTaskDefinition(scope: Construct, id: stri
 export declare function addContainersToTask(ctx: EcsConstructContext, serviceName: string, serviceProps: EcsServiceProps, taskDefinition: FargateTaskDefinition | Ec2TaskDefinition): {
     containers: ContainerDefinition[];
     primaryContainer?: ContainerDefinition;
+    logGroup: ILogGroup;
 };

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

@@ -1,10 +1,11 @@
 import { AwsLogDriver, ContainerDependencyCondition, FargateTaskDefinition, Ec2TaskDefinition, NetworkMode, CpuArchitecture, OperatingSystemFamily } from "aws-cdk-lib/aws-ecs";
-import { Duration } from "aws-cdk-lib";
+import { Duration, RemovalPolicy } from "aws-cdk-lib";
 import { Secret as EcsSecret } from "aws-cdk-lib/aws-ecs";
 import { StringParameter } from "aws-cdk-lib/aws-ssm";
 import { resolveOrgId } from "../../../utils/cdkContext.js";
 import { validateSsmPathComponent } from "./ecsValidation.js";
-import { DEFAULT_LOG_RETENTION_DAYS, DEFAULT_FARGATE_CPU, DEFAULT_FARGATE_MEMORY_MIB, DEFAULT_EC2_CONTAINER_MEMORY_MIB } from "./ecsConstants.js";
+import { DEFAULT_LOG_RETENTION, DEFAULT_FARGATE_CPU, DEFAULT_FARGATE_MEMORY_MIB, DEFAULT_EC2_CONTAINER_MEMORY_MIB } from "./ecsConstants.js";
+import { LogGroup } from "../logging/logGroup.js";
 import { getContainerImage } from "./ecsImages.js";
 import { resolveRemoteConnections } from "./ecsRemoteConnections.js";
 import { resolveImportedSecret } from "../secrets/index.js";
@@ -124,6 +125,14 @@ export function addContainersToTask(ctx, serviceName, serviceProps, taskDefiniti
     const orgId = resolveOrgId(ctx.scope.node);
     const remoteEnvByService = resolveRemoteConnections([serviceProps], ctx.scope, orgId);
     const remoteEnv = remoteEnvByService[serviceName] ?? {};
+    // Explicit so the cluster can attach metric filters (createLogPatternAlarms).
+    // No logGroupName: CDK auto-names from the logical ID so it cannot collide
+    // with the orphaned-retained old group during the implicit→explicit replace.
+    // RETAIN (never DESTROY): preserves fail-closed evidence and supports rollback.
+    const logGroup = new LogGroup(ctx.scope, `${ctx.props.clusterName}${serviceName}LogGroup`, {
+        retention: DEFAULT_LOG_RETENTION,
+        removalPolicy: RemovalPolicy.RETAIN
+    });
     for (const containerConfig of serviceProps.containers) {
         const image = getContainerImage(ctx, serviceName, containerConfig, serviceProps);
         const isFirstWithPort = !primaryContainer && containerConfig.port !== undefined;
@@ -156,7 +165,7 @@ export function addContainersToTask(ctx, serviceName, serviceProps, taskDefiniti
             containerName: containerConfig.name,
             logging: new AwsLogDriver({
                 streamPrefix: `/ecs/${ctx.props.clusterName}/${serviceName}`,
-                logRetention: DEFAULT_LOG_RETENTION_DAYS
+                logGroup
             }),
             // remoteEnv (cross-app `${PREFIX}_HOST/_PORT`) intentionally overrides user
             // values — a stale manual setting must not mask the resolved peer.
@@ -250,5 +259,5 @@ export function addContainersToTask(ctx, serviceName, serviceProps, taskDefiniti
             });
         }
     }
-    return { containers, primaryContainer };
+    return { containers, primaryContainer, logGroup };
 }

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

@@ -19,7 +19,8 @@ import { type RemoteConnectionSpec } from "./ecsRemoteConnections.js";
 import { type SecretImport } from "../secrets/index.js";
 import type { ManagedDomainExports } from "../../../utils/domainTypes.js";
 import type { ITopic } from "aws-cdk-lib/aws-sns";
-import type { EcsServiceAlarmThresholds } from "../monitoring/index.js";
+import type { ILogGroup } from "aws-cdk-lib/aws-logs";
+import type { EcsServiceAlarmThresholds, LogPatternAlarmSpec } from "../monitoring/index.js";
 import { type Ec2InstancePersistentDataVolumeConfig } from "./ec2.js";
 export declare enum Protocol {
     HTTP = 0,
@@ -437,6 +438,19 @@ export interface EcsServiceProps {
      * - object: override specific thresholds
      */
     alarms?: EcsServiceAlarmThresholds | false;
+    /**
+     * Log-pattern alarms for this service's log group. Each spec creates a
+     * CloudWatch metric filter + alarm (see `createLogPatternAlarms`). Materialised
+     * only when the cluster carries `alertsTopic` and `alarms !== false` — the same
+     * gate as the per-service metric alarms.
+     */
+    logAlarms?: LogPatternAlarmSpec[];
+    /**
+     * Default CloudWatch metric namespace for this service's `logAlarms`. Each
+     * spec may override it per-entry, so one service can emit alarms in different
+     * namespaces (e.g. `Fjall/WebApp` for RLS, `Fjall/ClickHouse` for stuck-merge).
+     */
+    logMetricNamespace?: string;
     /**
      * Deployment circuit breaker policy.
      * - undefined (default): `{ enable: true, rollback: true }`
@@ -543,4 +557,6 @@ export interface ServiceData {
     primaryContainer?: ContainerDefinition;
     targetGroup?: IApplicationTargetGroup;
     scalingPolicy?: TargetTrackingScalingPolicy | StepScalingPolicy;
+    /** Explicit log group shared by all of the service's containers. */
+    logGroup: ILogGroup;
 }

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

@@ -12,6 +12,13 @@ import type { EcsClusterProps } from "./ecsTypes.js";
  * layer consumers never see a `migrations` field, so duplicating the
  * validation here would be unreachable.
  *
+ * Same applies to `service.awaitMigrationsFrom`: it is a patterns-layer
+ * cross-service ordering knob, resolved into a `node.addDependency(...)` edge
+ * (`wireServiceMigrationDependencies` in `computeEcs.ts`) BEFORE reaching the
+ * resources layer. It is not a field on `EcsServiceProps`, so a direct
+ * `new EcsCluster(...)` consumer cannot pass it — there is no resources-layer
+ * code path to validate.
+ *
  * @param props - The cluster props to validate
  * @throws Error if validation fails
  */