@fjall/components-infrastructure 0.96.0 → 0.99.1

package/dist/lib/resources/aws/analytics/clickhouseUserData.d.ts

@@ -2,5 +2,5 @@ export interface ClickHouseUserDataOptions {
     /** Cloudflare account ID for R2 cold storage. If omitted, local-only storage is used. */
     cfAccountId?: string;
 }
-export declare const USERS_CONFIG_XML = "<clickhouse>\n    <users>\n        <default>\n            <networks>\n                <ip>127.0.0.1</ip>\n                <ip>::1</ip>\n            </networks>\n        </default>\n    </users>\n    <profiles>\n        <default>\n            <optimize_move_to_prewhere>1</optimize_move_to_prewhere>\n        </default>\n        <app_writer>\n            <max_threads>2</max_threads>\n            <max_insert_threads>1</max_insert_threads>\n            <max_concurrent_queries_for_user>4</max_concurrent_queries_for_user>\n            <log_queries_min_query_duration_ms>100</log_queries_min_query_duration_ms>\n            <optimize_move_to_prewhere>1</optimize_move_to_prewhere>\n            <use_query_condition_cache>1</use_query_condition_cache>\n            <!-- Re-enable skip indexes under FINAL (tenantQuery auto-FINALs RMT tables;\n                 default disables idx_aws_account, idx_application, idx_dedup, idx_fingerprint). -->\n            <use_skip_indexes_if_final>1</use_skip_indexes_if_final>\n            <async_insert>1</async_insert>\n            <wait_for_async_insert>1</wait_for_async_insert>\n            <async_insert_max_data_size>10000000</async_insert_max_data_size>\n            <!-- Adaptive batching: tune flush window between 50 ms (low-latency rare inserts)\n                 and 2 s (absorbs bursts). A single fixed value is silently overridden by the\n                 adaptive algorithm. -->\n            <async_insert_busy_timeout_min_ms>50</async_insert_busy_timeout_min_ms>\n            <async_insert_busy_timeout_max_ms>2000</async_insert_busy_timeout_max_ms>\n            <async_insert_use_adaptive_busy_timeout>1</async_insert_use_adaptive_busy_timeout>\n            <input_format_parallel_parsing>0</input_format_parallel_parsing>\n            <output_format_parallel_formatting>0</output_format_parallel_formatting>\n            <max_memory_usage_for_user>2684354560</max_memory_usage_for_user>\n            <max_bytes_before_external_sort>536870912</max_bytes_before_external_sort>\n            <max_bytes_before_external_group_by>536870912</max_bytes_before_external_group_by>\n        </app_writer>\n        <readonly>\n            <readonly>1</readonly>\n        </readonly>\n    </profiles>\n    <quotas>\n        <tenant_default>\n            <interval>\n                <duration>3600</duration>\n                <queries>1000</queries>\n                <result_rows>10000000</result_rows>\n            </interval>\n        </tenant_default>\n    </quotas>\n</clickhouse>";
+export declare const USERS_CONFIG_XML = "<clickhouse>\n    <users>\n        <default>\n            <networks>\n                <ip>127.0.0.1</ip>\n                <ip>::1</ip>\n            </networks>\n        </default>\n    </users>\n    <profiles>\n        <default>\n            <optimize_move_to_prewhere>1</optimize_move_to_prewhere>\n            <!-- ALTER TABLE ... MODIFY TTL on a 30-day-partitioned table would otherwise\n                 trigger an immediate full-table rewrite (default = 1). On the t4g.medium\n                 box that's a merge-pool starvation event. Keep TTL changes lazy: parts\n                 re-evaluate TTL on their next natural merge, no forced rewrite. -->\n            <materialize_ttl_after_modify>0</materialize_ttl_after_modify>\n        </default>\n        <app_writer>\n            <max_threads>2</max_threads>\n            <max_insert_threads>1</max_insert_threads>\n            <max_concurrent_queries_for_user>4</max_concurrent_queries_for_user>\n            <log_queries_min_query_duration_ms>100</log_queries_min_query_duration_ms>\n            <optimize_move_to_prewhere>1</optimize_move_to_prewhere>\n            <use_query_condition_cache>1</use_query_condition_cache>\n            <!-- Re-enable skip indexes under FINAL (tenantQuery auto-FINALs RMT tables;\n                 default disables idx_aws_account, idx_application, idx_dedup, idx_fingerprint). -->\n            <use_skip_indexes_if_final>1</use_skip_indexes_if_final>\n            <!-- Tenant-isolation guards (ClickHouse PR #91065 fix). Belt-and-braces with the\n                 per-user SQL SETTINGS in 002-users.sql \u2014 keep both so `CREATE OR REPLACE USER`\n                 cannot regress this. Without these flags, FINAL queries on un-merged\n                 ReplacingMergeTree parts can leak across tenants. -->\n            <apply_row_policy_after_final>1</apply_row_policy_after_final>\n            <apply_prewhere_after_final>1</apply_prewhere_after_final>\n            <do_not_merge_across_partitions_select_final>1</do_not_merge_across_partitions_select_final>\n            <async_insert>1</async_insert>\n            <wait_for_async_insert>1</wait_for_async_insert>\n            <async_insert_max_data_size>10000000</async_insert_max_data_size>\n            <!-- Adaptive batching: tune flush window between 50 ms (low-latency rare inserts)\n                 and 2 s (absorbs bursts). A single fixed value is silently overridden by the\n                 adaptive algorithm. -->\n            <async_insert_busy_timeout_min_ms>50</async_insert_busy_timeout_min_ms>\n            <async_insert_busy_timeout_max_ms>2000</async_insert_busy_timeout_max_ms>\n            <async_insert_use_adaptive_busy_timeout>1</async_insert_use_adaptive_busy_timeout>\n            <!-- Server-side deduplication of async inserts. Latent retry safety net:\n                 if a producer retries the same insert window (network hiccup, lambda re-run,\n                 SQS redelivery), the second attempt collapses against the first. As of CH 26.1\n                 this also propagates end-to-end through dependent materialised views \u2014 without\n                 it, a retried insert could double-count in metrics_hourly_mv / log_severity_hourly_mv\n                 even if the base table dedups. CH pin is 26.3 so the propagation fix is in. -->\n            <async_insert_deduplicate>1</async_insert_deduplicate>\n            <input_format_parallel_parsing>0</input_format_parallel_parsing>\n            <output_format_parallel_formatting>0</output_format_parallel_formatting>\n            <!-- Lazy materialisation (CH 25.4+): for `SELECT * ... LIMIT N` shapes the planner\n                 reads only the columns needed to evaluate ORDER BY / WHERE, then fetches the\n                 remaining columns for the surviving N rows. Order-of-magnitude I/O reduction\n                 on dashboard queries (e.g. getLatestMetrics LIMIT 1 BY application_id). -->\n            <query_plan_optimize_lazy_materialization>1</query_plan_optimize_lazy_materialization>\n            <!-- Per-query memory cap (overrides server-wide max_memory_usage of 1 GB\n                 to give app_writer 2 GB headroom). Belt-and-braces with the inline\n                 SETTINGS in 002-users.sql so neither layer can drift alone. -->\n            <max_memory_usage>2000000000</max_memory_usage>\n            <max_memory_usage_for_user>2684354560</max_memory_usage_for_user>\n            <max_bytes_before_external_sort>536870912</max_bytes_before_external_sort>\n            <max_bytes_before_external_group_by>536870912</max_bytes_before_external_group_by>\n            <!-- Per-query caps. Belt-and-braces with the inline SETTINGS in\n                 002-users.sql so `CREATE OR REPLACE USER` cannot regress the bound. -->\n            <max_execution_time>30</max_execution_time>\n            <max_rows_to_read>10000000</max_rows_to_read>\n        </app_writer>\n        <audit_writer>\n            <max_threads>1</max_threads>\n            <max_insert_threads>1</max_insert_threads>\n            <max_concurrent_queries_for_user>2</max_concurrent_queries_for_user>\n            <max_memory_usage>500000000</max_memory_usage>\n            <max_execution_time>10</max_execution_time>\n            <async_insert>1</async_insert>\n            <wait_for_async_insert>1</wait_for_async_insert>\n        </audit_writer>\n        <backup_reader>\n            <max_threads>2</max_threads>\n            <max_concurrent_queries_for_user>1</max_concurrent_queries_for_user>\n            <max_memory_usage>1000000000</max_memory_usage>\n            <max_execution_time>3600</max_execution_time>\n        </backup_reader>\n        <schema_admin>\n            <max_threads>2</max_threads>\n            <max_concurrent_queries_for_user>1</max_concurrent_queries_for_user>\n            <max_memory_usage>1000000000</max_memory_usage>\n            <max_execution_time>1800</max_execution_time>\n        </schema_admin>\n    </profiles>\n    <quotas>\n        <tenant_default>\n            <interval>\n                <duration>3600</duration>\n                <queries>1000</queries>\n                <result_rows>10000000</result_rows>\n            </interval>\n        </tenant_default>\n    </quotas>\n</clickhouse>";
 export declare function generateClickHouseUserData(options?: ClickHouseUserDataOptions): string;

package/dist/lib/resources/aws/analytics/clickhouseUserData.js

@@ -156,6 +156,11 @@ export const USERS_CONFIG_XML = `<clickhouse>
     <profiles>
         <default>
             <optimize_move_to_prewhere>1</optimize_move_to_prewhere>
+            <!-- ALTER TABLE ... MODIFY TTL on a 30-day-partitioned table would otherwise
+                 trigger an immediate full-table rewrite (default = 1). On the t4g.medium
+                 box that's a merge-pool starvation event. Keep TTL changes lazy: parts
+                 re-evaluate TTL on their next natural merge, no forced rewrite. -->
+            <materialize_ttl_after_modify>0</materialize_ttl_after_modify>
         </default>
         <app_writer>
             <max_threads>2</max_threads>
@@ -167,6 +172,13 @@ export const USERS_CONFIG_XML = `<clickhouse>
             <!-- Re-enable skip indexes under FINAL (tenantQuery auto-FINALs RMT tables;
                  default disables idx_aws_account, idx_application, idx_dedup, idx_fingerprint). -->
             <use_skip_indexes_if_final>1</use_skip_indexes_if_final>
+            <!-- Tenant-isolation guards (ClickHouse PR #91065 fix). Belt-and-braces with the
+                 per-user SQL SETTINGS in 002-users.sql — keep both so \`CREATE OR REPLACE USER\`
+                 cannot regress this. Without these flags, FINAL queries on un-merged
+                 ReplacingMergeTree parts can leak across tenants. -->
+            <apply_row_policy_after_final>1</apply_row_policy_after_final>
+            <apply_prewhere_after_final>1</apply_prewhere_after_final>
+            <do_not_merge_across_partitions_select_final>1</do_not_merge_across_partitions_select_final>
             <async_insert>1</async_insert>
             <wait_for_async_insert>1</wait_for_async_insert>
             <async_insert_max_data_size>10000000</async_insert_max_data_size>
@@ -176,15 +188,53 @@ export const USERS_CONFIG_XML = `<clickhouse>
             <async_insert_busy_timeout_min_ms>50</async_insert_busy_timeout_min_ms>
             <async_insert_busy_timeout_max_ms>2000</async_insert_busy_timeout_max_ms>
             <async_insert_use_adaptive_busy_timeout>1</async_insert_use_adaptive_busy_timeout>
+            <!-- Server-side deduplication of async inserts. Latent retry safety net:
+                 if a producer retries the same insert window (network hiccup, lambda re-run,
+                 SQS redelivery), the second attempt collapses against the first. As of CH 26.1
+                 this also propagates end-to-end through dependent materialised views — without
+                 it, a retried insert could double-count in metrics_hourly_mv / log_severity_hourly_mv
+                 even if the base table dedups. CH pin is 26.3 so the propagation fix is in. -->
+            <async_insert_deduplicate>1</async_insert_deduplicate>
             <input_format_parallel_parsing>0</input_format_parallel_parsing>
             <output_format_parallel_formatting>0</output_format_parallel_formatting>
+            <!-- Lazy materialisation (CH 25.4+): for \`SELECT * ... LIMIT N\` shapes the planner
+                 reads only the columns needed to evaluate ORDER BY / WHERE, then fetches the
+                 remaining columns for the surviving N rows. Order-of-magnitude I/O reduction
+                 on dashboard queries (e.g. getLatestMetrics LIMIT 1 BY application_id). -->
+            <query_plan_optimize_lazy_materialization>1</query_plan_optimize_lazy_materialization>
+            <!-- Per-query memory cap (overrides server-wide max_memory_usage of 1 GB
+                 to give app_writer 2 GB headroom). Belt-and-braces with the inline
+                 SETTINGS in 002-users.sql so neither layer can drift alone. -->
+            <max_memory_usage>2000000000</max_memory_usage>
             <max_memory_usage_for_user>2684354560</max_memory_usage_for_user>
             <max_bytes_before_external_sort>536870912</max_bytes_before_external_sort>
             <max_bytes_before_external_group_by>536870912</max_bytes_before_external_group_by>
+            <!-- Per-query caps. Belt-and-braces with the inline SETTINGS in
+                 002-users.sql so \`CREATE OR REPLACE USER\` cannot regress the bound. -->
+            <max_execution_time>30</max_execution_time>
+            <max_rows_to_read>10000000</max_rows_to_read>
         </app_writer>
-        <readonly>
-            <readonly>1</readonly>
-        </readonly>
+        <audit_writer>
+            <max_threads>1</max_threads>
+            <max_insert_threads>1</max_insert_threads>
+            <max_concurrent_queries_for_user>2</max_concurrent_queries_for_user>
+            <max_memory_usage>500000000</max_memory_usage>
+            <max_execution_time>10</max_execution_time>
+            <async_insert>1</async_insert>
+            <wait_for_async_insert>1</wait_for_async_insert>
+        </audit_writer>
+        <backup_reader>
+            <max_threads>2</max_threads>
+            <max_concurrent_queries_for_user>1</max_concurrent_queries_for_user>
+            <max_memory_usage>1000000000</max_memory_usage>
+            <max_execution_time>3600</max_execution_time>
+        </backup_reader>
+        <schema_admin>
+            <max_threads>2</max_threads>
+            <max_concurrent_queries_for_user>1</max_concurrent_queries_for_user>
+            <max_memory_usage>1000000000</max_memory_usage>
+            <max_execution_time>1800</max_execution_time>
+        </schema_admin>
     </profiles>
     <quotas>
         <tenant_default>

package/dist/lib/resources/aws/base/awsStack.js

@@ -1,4 +1,4 @@
-import { Stack } from "aws-cdk-lib";
+import { Annotations, Stack } from "aws-cdk-lib";
 import { Port } from "aws-cdk-lib/aws-ec2";
 import { Construct } from "constructs";
 import App from "../../../app.js";
@@ -27,7 +27,9 @@ export class AwsStack {
         }
     }
     getCdkStack(id, props) {
-        return new Stack(App.getInstance(), id, this.getStackProps(props));
+        const stack = new Stack(App.getInstance(), id, this.getStackProps(props));
+        Annotations.of(stack).acknowledgeWarning("@aws-cdk/aws-ec2:ipv4IgnoreEgressRule");
+        return stack;
     }
     getStackProps(props) {
         // If no explicit props are provided, fall back to the account/region that

package/dist/lib/resources/aws/compute/__tmp__/regression-shape.d.ts

@@ -0,0 +1,2 @@
+import { AutoScalingGroup } from "aws-cdk-lib/aws-autoscaling";
+export declare function regression(asg: AutoScalingGroup, queue: any, id: string): void;

package/dist/lib/resources/aws/compute/__tmp__/regression-shape.js

@@ -0,0 +1,11 @@
+import { DefaultResult, LifecycleTransition } from "aws-cdk-lib/aws-autoscaling";
+import { QueueHook } from "aws-cdk-lib/aws-autoscaling-hooktargets";
+import { Duration } from "aws-cdk-lib";
+export function regression(asg, queue, id) {
+    asg.addLifecycleHook(`${id}LaunchingHook`, {
+        lifecycleTransition: LifecycleTransition.INSTANCE_LAUNCHING,
+        defaultResult: DefaultResult.ABANDON,
+        heartbeatTimeout: Duration.seconds(300),
+        notificationTarget: new QueueHook(queue)
+    });
+}

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

@@ -0,0 +1,52 @@
+import { type AutoScalingGroup, type DefaultResult, type LifecycleTransition } from "aws-cdk-lib/aws-autoscaling";
+import { type Construct } from "constructs";
+export interface InlineAsgLifecycleHookProps {
+    /** ASG to attach the hook to. */
+    autoScalingGroup: AutoScalingGroup;
+    /** Lifecycle hook name — must be unique within the ASG. */
+    hookName: string;
+    /** EC2_INSTANCE_LAUNCHING or EC2_INSTANCE_TERMINATING. */
+    lifecycleTransition: LifecycleTransition;
+    /** Action when heartbeat elapses. */
+    defaultResult: DefaultResult;
+    /** Heartbeat window before defaultResult fires, in seconds. */
+    heartbeatTimeoutSeconds: number;
+}
+/**
+ * Atomically attach an ASG lifecycle hook by appending a
+ * `LifecycleHookSpecification` to the ASG's `LifecycleHookSpecificationList`
+ * (CFN property on `AWS::AutoScaling::AutoScalingGroup`) instead of emitting
+ * a standalone `AWS::AutoScaling::LifecycleHook` resource.
+ *
+ * Standalone `AWS::AutoScaling::LifecycleHook` resources are created AFTER
+ * the ASG. CFN starts the ASG's desiredCapacity ramp as part of ASG creation,
+ * not as a separate step, so on a fresh stack the first instance launches
+ * BEFORE the hook is attached and the hook fires zero notifications for that
+ * instance. `LifecycleHookSpecificationList` is part of the ASG's own CFN
+ * payload — the ASG is never in a state where it has instances but no hooks.
+ *
+ * No `NotificationTargetARN` / `RoleARN` is set. AWS rejects ASG creation when
+ * the inline `LifecycleHookSpecificationList` contains two entries with
+ * different `NotificationTargetARN` values:
+ *
+ *   "NotificationTargetARN should be the same for all Lifecycle Hooks"
+ *
+ * The standalone-hook form permits per-hook targets, but inline does not. Two
+ * Fjall consumers (`PersistentDataVolume` LAUNCHING + `Ec2GracefulTerminationHandler`
+ * TERMINATING) each own their own SQS queue, so a shared target is impossible.
+ *
+ * Routing is therefore delegated to EventBridge. ASG natively emits
+ * `EC2 Instance-launch Lifecycle Action` / `EC2 Instance-terminate Lifecycle Action`
+ * events on the account+region default bus for every lifecycle hook regardless
+ * of whether a notification target is configured. Each consumer attaches a
+ * `Subscription` (from `lib/resources/aws/messaging/subscription.ts`) whose
+ * event pattern discriminates by `AutoScalingGroupName` + `LifecycleHookName`,
+ * targeting the consumer's own SQS queue. The Lambda sees the EventBridge event
+ * envelope and reads `detail.LifecycleActionToken` etc. from the unwrapped
+ * detail.
+ *
+ * Multiple consumers may call this helper against the same ASG — the existing
+ * spec list is read, the new entry appended, and the merged array assigned
+ * back. Synth is sequential per scope, so the merge is race-free.
+ */
+export declare function attachInlineAsgLifecycleHook(_scope: Construct, _id: string, props: InlineAsgLifecycleHookProps): void;

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

@@ -0,0 +1,60 @@
+/**
+ * Atomically attach an ASG lifecycle hook by appending a
+ * `LifecycleHookSpecification` to the ASG's `LifecycleHookSpecificationList`
+ * (CFN property on `AWS::AutoScaling::AutoScalingGroup`) instead of emitting
+ * a standalone `AWS::AutoScaling::LifecycleHook` resource.
+ *
+ * Standalone `AWS::AutoScaling::LifecycleHook` resources are created AFTER
+ * the ASG. CFN starts the ASG's desiredCapacity ramp as part of ASG creation,
+ * not as a separate step, so on a fresh stack the first instance launches
+ * BEFORE the hook is attached and the hook fires zero notifications for that
+ * instance. `LifecycleHookSpecificationList` is part of the ASG's own CFN
+ * payload — the ASG is never in a state where it has instances but no hooks.
+ *
+ * No `NotificationTargetARN` / `RoleARN` is set. AWS rejects ASG creation when
+ * the inline `LifecycleHookSpecificationList` contains two entries with
+ * different `NotificationTargetARN` values:
+ *
+ *   "NotificationTargetARN should be the same for all Lifecycle Hooks"
+ *
+ * The standalone-hook form permits per-hook targets, but inline does not. Two
+ * Fjall consumers (`PersistentDataVolume` LAUNCHING + `Ec2GracefulTerminationHandler`
+ * TERMINATING) each own their own SQS queue, so a shared target is impossible.
+ *
+ * Routing is therefore delegated to EventBridge. ASG natively emits
+ * `EC2 Instance-launch Lifecycle Action` / `EC2 Instance-terminate Lifecycle Action`
+ * events on the account+region default bus for every lifecycle hook regardless
+ * of whether a notification target is configured. Each consumer attaches a
+ * `Subscription` (from `lib/resources/aws/messaging/subscription.ts`) whose
+ * event pattern discriminates by `AutoScalingGroupName` + `LifecycleHookName`,
+ * targeting the consumer's own SQS queue. The Lambda sees the EventBridge event
+ * envelope and reads `detail.LifecycleActionToken` etc. from the unwrapped
+ * detail.
+ *
+ * Multiple consumers may call this helper against the same ASG — the existing
+ * spec list is read, the new entry appended, and the merged array assigned
+ * back. Synth is sequential per scope, so the merge is race-free.
+ */
+export function attachInlineAsgLifecycleHook(_scope, _id, props) {
+    const cfnAsg = props.autoScalingGroup.node
+        .defaultChild;
+    const existing = readLifecycleHookSpecList(cfnAsg);
+    cfnAsg.lifecycleHookSpecificationList = [
+        ...existing,
+        {
+            lifecycleHookName: props.hookName,
+            lifecycleTransition: props.lifecycleTransition,
+            defaultResult: props.defaultResult,
+            heartbeatTimeout: props.heartbeatTimeoutSeconds
+        }
+    ];
+}
+function readLifecycleHookSpecList(cfnAsg) {
+    const current = cfnAsg.lifecycleHookSpecificationList;
+    if (current === undefined)
+        return [];
+    if (Array.isArray(current)) {
+        return current;
+    }
+    throw new Error("Cannot append to lifecycleHookSpecificationList: existing value is an IResolvable — refactor the override to call attachInlineAsgLifecycleHook");
+}

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

@@ -0,0 +1,8 @@
+import { BlockDeviceVolume, EbsDeviceVolumeType } from "aws-cdk-lib/aws-ec2";
+export interface SafeEbsOptions {
+    volumeType?: EbsDeviceVolumeType;
+    iops?: number;
+    throughput?: number;
+    deleteOnTermination?: boolean;
+}
+export declare function safeEbs(sizeGiB: number, opts?: SafeEbsOptions): BlockDeviceVolume;

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

@@ -0,0 +1,10 @@
+import { BlockDeviceVolume, EbsDeviceVolumeType } from "aws-cdk-lib/aws-ec2";
+export function safeEbs(sizeGiB, opts = {}) {
+    return BlockDeviceVolume.ebs(sizeGiB, {
+        encrypted: true,
+        volumeType: opts.volumeType ?? EbsDeviceVolumeType.GP3,
+        iops: opts.iops,
+        throughput: opts.throughput,
+        deleteOnTermination: opts.deleteOnTermination
+    });
+}

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

@@ -1,9 +1,39 @@
-import { type BlockDevice, type IMachineImage, type IVpc, type UserData, SecurityGroup, type IConnectable, Connections, type SubnetConfiguration } from "aws-cdk-lib/aws-ec2";
+import { type BlockDevice, type IMachineImage, type IVpc, type UserData, type ISecurityGroup, type IConnectable, Connections, type SubnetConfiguration, type SubnetSelection } from "aws-cdk-lib/aws-ec2";
 import { Construct } from "constructs";
-import { Stack, type StackProps } from "aws-cdk-lib";
+import { Duration, Stack, type StackProps } from "aws-cdk-lib";
 import { type Role } from "aws-cdk-lib/aws-iam";
-import { AutoScalingGroup } from "aws-cdk-lib/aws-autoscaling";
-interface Ec2InstanceProps extends StackProps {
+import { AutoScalingGroup, Monitoring, type WarmPoolOptions } from "aws-cdk-lib/aws-autoscaling";
+import { type PersistentDataVolumeProps } from "./persistentDataVolume.js";
+export type Ec2InstancePersistentDataVolumeConfig = Omit<PersistentDataVolumeProps, "autoScalingGroup">;
+/**
+ * Caller-supplied ASG `UpdatePolicy` resolution. Default (`undefined`) →
+ * `rollingUpdate({ minInstancesInService: 0, maxBatchSize: 1, pauseTime:
+ * Duration.minutes(5) })`. The rolling shape propagates userdata mutations
+ * to running instances on every `LaunchTemplateVersion` change; data
+ * continuity for stateful patterns is preserved by `persistentDataVolume`.
+ *
+ * Variants:
+ * - `rollingUpdate` — single-instance roll; `pauseTime` overridable.
+ *   `minInstancesInService` and `maxBatchSize` are fixed at `0` and `1`.
+ * - `replacingUpdate` — explicit opt-in to the legacy full-replacement shape.
+ *   No Fjall consumer uses this today; retained for future bare-EC2 patterns.
+ * - `none` — no caller-driven `UpdatePolicy` (omits both
+ *   `AutoScalingRollingUpdate` and `AutoScalingReplacingUpdate`). CDK still
+ *   auto-emits `AutoScalingScheduledAction.IgnoreUnmodifiedGroupSizeProperties`
+ *   regardless. For callers owning rollout externally.
+ *
+ * See `aiDocs/troubleshooting/clickhouse-rolling-update-window.md` for the
+ * ClickHouse-specific downtime expectations.
+ */
+export type Ec2InstanceUpdatePolicyConfig = {
+    type: "rollingUpdate";
+    pauseTime?: Duration;
+} | {
+    type: "replacingUpdate";
+} | {
+    type: "none";
+};
+export interface Ec2InstanceProps extends StackProps {
     spotCapacityPercentage?: number;
     blockDevices?: BlockDevice[];
     accountId?: string;
@@ -12,32 +42,122 @@ interface Ec2InstanceProps extends StackProps {
     subnetConfiguration?: SubnetConfiguration[];
     minCapacity?: number;
     maxCapacity?: number;
+    /** CDK `AutoScalingGroupProps.desiredCapacity` — initial instance count. */
+    desiredCapacity?: number;
     instanceType: string;
     machineImage?: IMachineImage;
     userData?: UserData;
     role?: Role;
     enableSSH?: boolean;
     defaultPort?: number;
+    /**
+     * Caller-supplied EC2 instance monitoring resolution. Routes through the
+     * LaunchTemplate's `detailedMonitoring` field (the AWS-side source of truth
+     * for instances launched through a launch template — the ASG-level
+     * `instanceMonitoring` prop is silently ignored by CDK whenever a
+     * `launchTemplate` or `mixedInstancesPolicy` is set, which is always the
+     * case in this construct). Translation: `Monitoring.DETAILED` → `true`,
+     * `Monitoring.BASIC` → `false`. Absent → existing default of `true`
+     * (1-minute metrics) is preserved.
+     */
+    instanceMonitoring?: Monitoring;
+    /**
+     * Externally-supplied security group. When provided, `Ec2Instance` does not
+     * create its own `AsgSecurityGroup`; the supplied SG is used by the launch
+     * template, exposed via `this.asgSecurityGroup`, and threaded into the
+     * `IConnectable` view. Callers retain full ownership.
+     */
+    securityGroup?: ISecurityGroup;
+    /**
+     * CDK `AutoScalingGroupProps.vpcSubnets`. Overrides the default
+     * `enableSSH ? PUBLIC : resolvePrivateSubnetType(vpc)` inference. Use when
+     * the caller needs a precise subnet selection (e.g. AZ pinning).
+     */
+    vpcSubnets?: SubnetSelection;
+    /** CDK `AutoScalingGroupProps.capacityRebalance`. Absent → CDK default. */
+    capacityRebalance?: boolean;
+    /**
+     * CDK `aws-cdk-lib/aws-autoscaling.WarmPoolOptions` verbatim — `minSize`,
+     * `maxGroupPreparedCapacity`, `poolState`, `reuseOnScaleIn`. When present,
+     * `asg.addWarmPool(warmPool)` is called once after ASG construction.
+     */
+    warmPool?: WarmPoolOptions;
+    /**
+     * CDK `LaunchTemplateProps.associatePublicIpAddress`. When defined,
+     * overrides the `!!keyPair` auto-derivation; otherwise the existing
+     * keyPair-driven default applies.
+     */
+    associatePublicIpAddress?: boolean;
+    /**
+     * ECS cluster ARN — when set, the graceful-termination Lambda also drains
+     * and deregisters the container instance before generic cleanup. Empty
+     * string is treated as unset (rejecting Pitfall 9 / env-var-truthy traps).
+     * Bare-EC2 consumers (bastion, Fivetran) leave this unset.
+     */
+    ecsClusterArn?: string;
+    /**
+     * Pairs the ASG with a standalone EBS data volume that re-attaches across
+     * instance refreshes. When set, requires `vpcSubnets.availabilityZones` to
+     * be exactly one entry (matching `persistentDataVolume.availabilityZone`);
+     * the wrapper's volume is AZ-local and cannot follow a multi-AZ ASG.
+     * Forwards the wrapper's `ownerLogicalId` into the graceful-termination
+     * Lambda so the TERMINATING and LAUNCHING handlers locate the same volume.
+     */
+    persistentDataVolume?: Ec2InstancePersistentDataVolumeConfig;
+    /**
+     * ASG `UpdatePolicy` resolution. Absent →
+     * `UpdatePolicy.rollingUpdate({ minInstancesInService: 0, maxBatchSize: 1,
+     * pauseTime: Duration.minutes(5) })`. Userdata mutations propagate to
+     * running instances via a single-batch rolling roll. See
+     * `Ec2InstanceUpdatePolicyConfig` for the variant menu and
+     * `aiDocs/troubleshooting/clickhouse-rolling-update-window.md` for the
+     * downtime-window runbook.
+     */
+    updatePolicy?: Ec2InstanceUpdatePolicyConfig;
+    /**
+     * Tags applied to the underlying ASG with
+     * `applyToLaunchedInstances: true` so every launched EC2 instance carries
+     * the tags. Used for tag-based SSM `SendCommand` targeting
+     * (`Targets: [{ Key: "tag:<name>", Values: [<value>] }]`). Empty-string
+     * keys or values are rejected by `validateEc2InstanceProps`.
+     */
+    tags?: Record<string, string>;
 }
 export declare class Ec2Instance extends Construct implements IConnectable {
     private launchTemplate;
     vpc: IVpc;
-    asgSecurityGroup: SecurityGroup;
+    asgSecurityGroup: ISecurityGroup;
     private autoScalingGroup;
     private keyPair;
-    connections: Connections;
+    private persistentDataVolume?;
+    readonly connections: Connections;
     constructor(scope: Construct, id: string, props: Ec2InstanceProps);
-    addVpc(props: Ec2InstanceProps): void;
-    addKeyPair(props: Ec2InstanceProps): void;
-    addLaunchTemplate(props: Ec2InstanceProps): void;
-    addAutoScalingGroup(props: Ec2InstanceProps): void;
+    private addVpc;
+    private addKeyPair;
+    private addLaunchTemplate;
+    private addAutoScalingGroup;
+    /**
+     * Apply `props.tags` to the underlying ASG with
+     * `applyToLaunchedInstances: true` so the CFN ASG `Tags` array carries
+     * `{ Key, Value, PropagateAtLaunch: true }` for each entry. Enables
+     * tag-based SSM `SendCommand` targeting on the launched EC2 instances.
+     */
+    private applyInstanceTags;
     /**
      * Get the Auto Scaling Group.
      */
     getAutoScalingGroup(): AutoScalingGroup;
-    suspendAutoScaling(_props: Ec2InstanceProps): void;
+    /**
+     * Wire an ASG `EC2_INSTANCE_TERMINATING` hook + Lambda so instances
+     * terminate cleanly during stack updates and stack deletes. Drain ownership
+     * lives at the EC2 layer; ECS-specific drain plugs in via `ecsClusterArn`
+     * so a single hook handles bare-EC2 (bastion, Fivetran) and ECS-wired
+     * ASGs (ClickHouse) without duplicate plumbing in the ECS layer.
+     */
+    private addGracefulTerminationHandler;
+    private addPersistentDataVolume;
+    private suspendAutoScaling;
 }
 export declare class Ec2InstanceStack extends Stack {
     constructor(scope: Construct, id: string, props: Ec2InstanceProps);
 }
-export {};