@fjall/components-infrastructure 0.95.0 → 0.99.1

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

@@ -1,2 +1,4 @@
 export { default as ClickHouse } from "./clickhouse.js";
 export type { ClickHouseProps, ClickHouseR2Config, ClickHouseOutputs } from "./clickhouseTypes.js";
+export { createClickHouseAlarms } from "./clickhouseAlarms.js";
+export type { ClickHouseAlarmThresholds, ClickHouseAlarmsProps } from "./clickhouseAlarms.js";

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

@@ -1 +1,2 @@
 export { default as ClickHouse } from "./clickhouse.js";
+export { createClickHouseAlarms } from "./clickhouseAlarms.js";

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 {};

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

@@ -1,27 +1,75 @@
 import { InstanceType, LaunchTemplate, SubnetType, MachineImage, LaunchTemplateHttpTokens, KeyPair, SecurityGroup, Peer, Port, Connections } from "aws-cdk-lib/aws-ec2";
 import { Construct } from "constructs";
 import { resolvePrivateSubnetType } from "../../../utils/vpcUtils.js";
-import { Duration, Stack } from "aws-cdk-lib";
-import { AutoScalingGroup, GroupMetrics, TerminationPolicy, UpdatePolicy, OnDemandAllocationStrategy, SpotAllocationStrategy } from "aws-cdk-lib/aws-autoscaling";
+import { safeEbs } from "./blockDeviceVolume.js";
+import { Duration, Stack, Tags } from "aws-cdk-lib";
+import { AutoScalingGroup, GroupMetrics, Monitoring, TerminationPolicy, UpdatePolicy, OnDemandAllocationStrategy, SpotAllocationStrategy } from "aws-cdk-lib/aws-autoscaling";
 import { AwsCustomResource } from "../utilities/awsCustomResource.js";
 import { PhysicalResourceId } from "aws-cdk-lib/custom-resources";
 import { Vpc } from "../networking/vpc.js";
+import { Ec2GracefulTerminationHandler } from "./ec2GracefulTerminationHandler.js";
+import { PersistentDataVolume } from "./persistentDataVolume.js";
+/**
+ * SOC2-uniform default root device when callers omit `blockDevices`.
+ * `/dev/xvda` is the AL2023 / EcsOptimizedImage root device name and matches
+ * every Linux AMI consumed by `Ec2Instance` today (ECS, Buildkite, ClickHouse).
+ * `encrypted: true` enforces EBS encryption at the wrapper layer rather than
+ * relying on the AWS account-level "encryption by default" setting — the
+ * propagation contract documented in
+ * `.claude/rules/generator-standards.md § "Wrapper Routing Discipline"`.
+ */
+const DEFAULT_ROOT_DEVICE_NAME = "/dev/xvda";
+const DEFAULT_ROOT_VOLUME_SIZE_GIB = 30;
+/**
+ * Resolve the caller's `updatePolicy` prop to a CDK `UpdatePolicy`. Default
+ * (`config` absent) → single-instance rolling roll on every
+ * `LaunchTemplateVersion` change. The `none` branch returns `undefined` so
+ * `addAutoScalingGroup` can conditionally spread the field — passing
+ * `updatePolicy: undefined` directly emits an empty `UpdatePolicy: {}` block
+ * on some CDK versions.
+ *
+ * Free function rather than a private method: `this` state is not read, and
+ * a free function is easier to reach from focused tests.
+ */
+function resolveUpdatePolicy(config) {
+    const resolved = config ?? { type: "rollingUpdate" };
+    switch (resolved.type) {
+        case "none":
+            return undefined;
+        case "replacingUpdate":
+            return UpdatePolicy.replacingUpdate();
+        case "rollingUpdate":
+            return UpdatePolicy.rollingUpdate({
+                minInstancesInService: 0,
+                maxBatchSize: 1,
+                pauseTime: resolved.pauseTime ?? Duration.minutes(5)
+            });
+        default:
+            return assertNever(resolved);
+    }
+}
+function assertNever(value) {
+    throw new Error(`Ec2Instance.updatePolicy: unrecognised config ${JSON.stringify(value)}`);
+}
 export class Ec2Instance extends Construct {
     launchTemplate;
     vpc;
     asgSecurityGroup;
     autoScalingGroup;
     keyPair;
+    persistentDataVolume;
     connections;
     constructor(scope, id, props) {
         super(scope, id);
+        validateEc2InstanceProps(props);
         this.addVpc(props);
         this.addKeyPair(props);
         this.addLaunchTemplate(props);
         this.addAutoScalingGroup(props);
+        this.applyInstanceTags(props);
         this.suspendAutoScaling(props);
-        // Initialise connections with the security group and optional defaultPort
-        // When defaultPort is set, other resources can use allowToDefaultPort(ec2Instance)
+        this.addPersistentDataVolume(props);
+        this.addGracefulTerminationHandler(props);
         this.connections = new Connections({
             securityGroups: [this.asgSecurityGroup],
             defaultPort: props.defaultPort ? Port.tcp(props.defaultPort) : undefined
@@ -43,52 +91,76 @@ export class Ec2Instance extends Construct {
             this.keyPair = undefined;
         }
         else {
-            // TODO: Break out into a separate construct for use with better prop handling
             this.keyPair = new KeyPair(this, "KeyPair", {
                 keyPairName: `${props.serviceName}KeyPair`
             });
         }
     }
     addLaunchTemplate(props) {
-        this.asgSecurityGroup = new SecurityGroup(this, `AsgSecurityGroup`, {
-            vpc: this.vpc,
-            description: `Security group for the ${props.serviceName} auto scaling group`
-        });
+        if (props.securityGroup !== undefined) {
+            this.asgSecurityGroup = props.securityGroup;
+        }
+        else {
+            this.asgSecurityGroup = new SecurityGroup(this, `AsgSecurityGroup`, {
+                vpc: this.vpc,
+                description: `Security group for the ${props.serviceName} auto scaling group`
+            });
+        }
         if (props.enableSSH) {
             this.asgSecurityGroup.addIngressRule(Peer.anyIpv4(), Port.tcp(22), "Allow SSH");
         }
         this.launchTemplate = new LaunchTemplate(this, "LaunchTemplate", {
             launchTemplateName: `${props.serviceName}LaunchTemplate`,
-            instanceType: new InstanceType(`${props.instanceType}`),
-            machineImage: props.machineImage || MachineImage.latestAmazonLinux2023(),
+            instanceType: new InstanceType(props.instanceType),
+            machineImage: props.machineImage ?? MachineImage.latestAmazonLinux2023(),
             userData: props.userData,
             role: props.role,
-            blockDevices: props?.blockDevices,
+            blockDevices: props.blockDevices ?? [
+                {
+                    deviceName: DEFAULT_ROOT_DEVICE_NAME,
+                    volume: safeEbs(DEFAULT_ROOT_VOLUME_SIZE_GIB)
+                }
+            ],
             securityGroup: this.asgSecurityGroup,
-            detailedMonitoring: true,
+            detailedMonitoring: props.instanceMonitoring === undefined
+                ? true
+                : props.instanceMonitoring === Monitoring.DETAILED,
             requireImdsv2: true,
             httpPutResponseHopLimit: 2,
             httpTokens: LaunchTemplateHttpTokens.REQUIRED,
             instanceMetadataTags: true,
             keyPair: this.keyPair,
-            associatePublicIpAddress: !!this.keyPair
+            associatePublicIpAddress: props.associatePublicIpAddress ?? !!this.keyPair
         });
     }
     addAutoScalingGroup(props) {
-        // TODO: Handle terminating EC2 instances when updating, currently hangs.
+        const vpcSubnets = props.vpcSubnets ?? {
+            subnetType: props.enableSSH
+                ? SubnetType.PUBLIC
+                : resolvePrivateSubnetType(this.vpc)
+        };
+        const resolvedUpdatePolicy = resolveUpdatePolicy(props.updatePolicy);
         const baseAsgProps = {
             vpc: this.vpc,
-            vpcSubnets: {
-                subnetType: props.enableSSH
-                    ? SubnetType.PUBLIC
-                    : resolvePrivateSubnetType(this.vpc)
-            },
+            vpcSubnets,
             minCapacity: props.minCapacity,
             maxCapacity: props.maxCapacity,
+            ...(props.desiredCapacity !== undefined && {
+                desiredCapacity: props.desiredCapacity
+            }),
+            ...(props.capacityRebalance !== undefined && {
+                capacityRebalance: props.capacityRebalance
+            }),
             cooldown: Duration.seconds(60),
             groupMetrics: [GroupMetrics.all()],
-            updatePolicy: UpdatePolicy.replacingUpdate(),
-            newInstancesProtectedFromScaleIn: true,
+            ...(resolvedUpdatePolicy !== undefined && {
+                updatePolicy: resolvedUpdatePolicy
+            }),
+            // ECS task drain on terminate is handled by the EC2_INSTANCE_TERMINATING
+            // lifecycle hook + Ec2GracefulTerminationHandler (300s heartbeat), not by
+            // managed termination protection. Leaving instances scale-in-protected
+            // wedges CFN rollback because ASG cannot terminate the instance.
+            newInstancesProtectedFromScaleIn: false,
             terminationPolicies: [
                 TerminationPolicy.OLDEST_LAUNCH_CONFIGURATION,
                 TerminationPolicy.CLOSEST_TO_NEXT_INSTANCE_HOUR
@@ -98,7 +170,7 @@ export class Ec2Instance extends Construct {
         // Support spot instances via mixed instances policy
         if (props.spotCapacityPercentage !== undefined &&
             props.spotCapacityPercentage > 0) {
-            const spotPercentage = Math.min(100, Math.max(0, props.spotCapacityPercentage));
+            const spotPercentage = Math.min(100, props.spotCapacityPercentage);
             const onDemandPercentage = 100 - spotPercentage;
             this.autoScalingGroup = new AutoScalingGroup(this, "AutoScalingGroup", {
                 ...baseAsgProps,
@@ -119,6 +191,24 @@ export class Ec2Instance extends Construct {
                 launchTemplate: this.launchTemplate
             });
         }
+        if (props.warmPool !== undefined) {
+            this.autoScalingGroup.addWarmPool(props.warmPool);
+        }
+    }
+    /**
+     * 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.
+     */
+    applyInstanceTags(props) {
+        if (props.tags === undefined)
+            return;
+        for (const [key, value] of Object.entries(props.tags)) {
+            Tags.of(this.autoScalingGroup).add(key, value, {
+                applyToLaunchedInstances: true
+            });
+        }
     }
     /**
      * Get the Auto Scaling Group.
@@ -126,6 +216,34 @@ export class Ec2Instance extends Construct {
     getAutoScalingGroup() {
         return this.autoScalingGroup;
     }
+    /**
+     * 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.
+     */
+    addGracefulTerminationHandler(props) {
+        const dataVolumeOwnerLogicalId = this.persistentDataVolume?.ownerLogicalId;
+        new Ec2GracefulTerminationHandler(this, `${props.serviceName}GracefulTermination`, {
+            autoScalingGroup: this.autoScalingGroup,
+            ...(props.ecsClusterArn !== undefined &&
+                props.ecsClusterArn !== "" && {
+                ecsClusterArn: props.ecsClusterArn
+            }),
+            ...(dataVolumeOwnerLogicalId !== undefined && {
+                dataVolumeOwnerLogicalId
+            })
+        });
+    }
+    addPersistentDataVolume(props) {
+        if (props.persistentDataVolume === undefined)
+            return;
+        this.persistentDataVolume = new PersistentDataVolume(this, `${props.serviceName}PersistentDataVolume`, {
+            autoScalingGroup: this.autoScalingGroup,
+            ...props.persistentDataVolume
+        });
+    }
     suspendAutoScaling(_props) {
         const suspendCall = {
             service: "AutoScaling",
@@ -143,9 +261,31 @@ export class Ec2Instance extends Construct {
         });
     }
 }
+function validateEc2InstanceProps(props) {
+    if (props.persistentDataVolume !== undefined) {
+        const azs = props.vpcSubnets?.availabilityZones;
+        if (azs === undefined || azs.length !== 1) {
+            throw new Error(`Ec2Instance.persistentDataVolume requires vpcSubnets.availabilityZones to be exactly 1 entry; got ${azs?.length ?? 0}`);
+        }
+        if (azs[0] !== props.persistentDataVolume.availabilityZone) {
+            throw new Error(`Ec2Instance.persistentDataVolume.availabilityZone must match vpcSubnets.availabilityZones[0]; got '${props.persistentDataVolume.availabilityZone}' vs '${azs[0]}'`);
+        }
+    }
+    if (props.tags !== undefined) {
+        for (const [key, value] of Object.entries(props.tags)) {
+            if (key === "") {
+                throw new Error("Ec2Instance.tags: empty-string keys are not permitted");
+            }
+            if (value === "") {
+                throw new Error(`Ec2Instance.tags['${key}']: empty-string values are not permitted`);
+            }
+        }
+    }
+}
 export class Ec2InstanceStack extends Stack {
     constructor(scope, id, props) {
         super(scope, id, props);
+        validateEc2InstanceProps(props);
         new Ec2Instance(this, id, {
             ...props
         });