@composurecdk/ec2 0.6.0 → 0.8.0

package/dist/esm/instance-alarm-defaults.d.ts

@@ -0,0 +1,20 @@
+import type { AlarmConfigDefaults } from "@composurecdk/cloudwatch";
+interface InstanceAlarmDefaults {
+    enabled: true;
+    cpuUtilization: AlarmConfigDefaults;
+    statusCheckFailed: AlarmConfigDefaults;
+    attachedEbsStatusCheckFailed: AlarmConfigDefaults;
+    cpuCreditBalance: AlarmConfigDefaults;
+}
+/**
+ * AWS-recommended default alarm configuration for EC2 instances.
+ *
+ * Thresholds are sourced from the CloudWatch Best Practice Recommended
+ * Alarms guide. Thresholds may reasonably be tuned per-workload; defaults
+ * bias toward catching obvious issues without excessive noise.
+ *
+ * @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#EC2
+ */
+export declare const INSTANCE_ALARM_DEFAULTS: InstanceAlarmDefaults;
+export {};
+//# sourceMappingURL=instance-alarm-defaults.d.ts.map

package/dist/esm/instance-alarm-defaults.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"instance-alarm-defaults.d.ts","sourceRoot":"","sources":["../../src/instance-alarm-defaults.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAEpE,UAAU,qBAAqB;IAC7B,OAAO,EAAE,IAAI,CAAC;IACd,cAAc,EAAE,mBAAmB,CAAC;IACpC,iBAAiB,EAAE,mBAAmB,CAAC;IACvC,4BAA4B,EAAE,mBAAmB,CAAC;IAClD,gBAAgB,EAAE,mBAAmB,CAAC;CACvC;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,uBAAuB,EAAE,qBAsDrC,CAAC"}

package/dist/esm/instance-alarm-defaults.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"instance-alarm-defaults.js","sourceRoot":"","sources":["../../src/instance-alarm-defaults.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAW9D;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAA0B;IAC5D,OAAO,EAAE,IAAI;IAEb;;;;OAIG;IACH,cAAc,EAAE;QACd,SAAS,EAAE,EAAE;QACb,iBAAiB,EAAE,CAAC;QACpB,iBAAiB,EAAE,CAAC;QACpB,gBAAgB,EAAE,gBAAgB,CAAC,aAAa;KACjD;IAED;;;;OAIG;IACH,iBAAiB,EAAE;QACjB,SAAS,EAAE,CAAC;QACZ,iBAAiB,EAAE,CAAC;QACpB,iBAAiB,EAAE,CAAC;QACpB,gBAAgB,EAAE,gBAAgB,CAAC,aAAa;KACjD;IAED;;;;;;OAMG;IACH,4BAA4B,EAAE;QAC5B,SAAS,EAAE,CAAC;QACZ,iBAAiB,EAAE,EAAE;QACrB,iBAAiB,EAAE,EAAE;QACrB,gBAAgB,EAAE,gBAAgB,CAAC,aAAa;KACjD;IAED;;;;;;OAMG;IACH,gBAAgB,EAAE;QAChB,SAAS,EAAE,EAAE;QACb,iBAAiB,EAAE,CAAC;QACpB,iBAAiB,EAAE,CAAC;QACpB,gBAAgB,EAAE,gBAAgB,CAAC,aAAa;KACjD;CACF,CAAC"}

package/dist/esm/instance-alarms.d.ts

@@ -0,0 +1,28 @@
+import { type Alarm } from "aws-cdk-lib/aws-cloudwatch";
+import type { Instance, InstanceProps } from "aws-cdk-lib/aws-ec2";
+import type { IConstruct } from "constructs";
+import type { AlarmDefinition } from "@composurecdk/cloudwatch";
+import { AlarmDefinitionBuilder } from "@composurecdk/cloudwatch";
+import type { InstanceAlarmConfig } from "./instance-alarm-config.js";
+/**
+ * Resolves the recommended alarm configuration into fully-resolved
+ * {@link AlarmDefinition}s, applying contextual logic for the
+ * burstable-only CPU credit alarm.
+ */
+export declare function resolveInstanceAlarmDefinitions(instance: Instance, config: InstanceAlarmConfig | undefined, props: Pick<InstanceProps, "instanceType">): AlarmDefinition[];
+/**
+ * Creates AWS-recommended CloudWatch alarms for an EC2 instance,
+ * merging recommended definitions with any custom alarm builders.
+ *
+ * @param scope - CDK construct scope for creating alarm constructs.
+ * @param id - Base identifier for alarm construct ids.
+ * @param instance - The EC2 instance to create alarms for.
+ * @param config - User-provided alarm configuration, or `false` to disable all.
+ * @param props - The merged instance props, used for contextual alarm thresholds.
+ * @param customAlarms - Custom alarm builders added via `addAlarm()`.
+ * @returns A record mapping alarm keys to their created Alarm constructs.
+ *
+ * @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#EC2
+ */
+export declare function createInstanceAlarms(scope: IConstruct, id: string, instance: Instance, config: InstanceAlarmConfig | false | undefined, props: Pick<InstanceProps, "instanceType">, customAlarms?: AlarmDefinitionBuilder<Instance>[]): Record<string, Alarm>;
+//# sourceMappingURL=instance-alarms.d.ts.map

package/dist/esm/instance-alarms.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"instance-alarms.d.ts","sourceRoot":"","sources":["../../src/instance-alarms.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,KAAK,EAAqC,MAAM,4BAA4B,CAAC;AAC3F,OAAO,KAAK,EAAa,QAAQ,EAAE,aAAa,EAAgB,MAAM,qBAAqB,CAAC;AAC5F,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAChE,OAAO,EAAE,sBAAsB,EAAoC,MAAM,0BAA0B,CAAC;AACpG,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AA6CtE;;;;GAIG;AACH,wBAAgB,+BAA+B,CAC7C,QAAQ,EAAE,QAAQ,EAClB,MAAM,EAAE,mBAAmB,GAAG,SAAS,EACvC,KAAK,EAAE,IAAI,CAAC,aAAa,EAAE,cAAc,CAAC,GACzC,eAAe,EAAE,CA2EnB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,UAAU,EACjB,EAAE,EAAE,MAAM,EACV,QAAQ,EAAE,QAAQ,EAClB,MAAM,EAAE,mBAAmB,GAAG,KAAK,GAAG,SAAS,EAC/C,KAAK,EAAE,IAAI,CAAC,aAAa,EAAE,cAAc,CAAC,EAC1C,YAAY,GAAE,sBAAsB,CAAC,QAAQ,CAAC,EAAO,GACpD,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAUvB"}

package/dist/esm/instance-alarms.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"instance-alarms.js","sourceRoot":"","sources":["../../src/instance-alarms.ts"],"names":[],"mappings":"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"}

package/dist/esm/instance-builder.d.ts

@@ -0,0 +1,223 @@
+import { type Alarm } from "aws-cdk-lib/aws-cloudwatch";
+import { type CfnVolumeAttachment, Instance, type IKeyPair, type ISecurityGroup, type IVpc, type InstanceProps } from "aws-cdk-lib/aws-ec2";
+import { type IRole } from "aws-cdk-lib/aws-iam";
+import { type IConstruct } from "constructs";
+import { COPY_STATE, type Lifecycle, type Resolvable } from "@composurecdk/core";
+import { type ITaggedBuilder } from "@composurecdk/cloudformation";
+import { AlarmDefinitionBuilder } from "@composurecdk/cloudwatch";
+import type { InstanceAlarmConfig } from "./instance-alarm-config.js";
+import { type AttachVolumeOptions, type AttachVolumeRef } from "./instance-volume-attachments.js";
+/**
+ * Configuration properties for the EC2 instance builder.
+ *
+ * Extends the CDK {@link InstanceProps} but lifts the cross-component-wiring
+ * props to {@link Resolvable} so they can be supplied as either concrete
+ * values or {@link Ref}s to sibling components in a {@link compose}d system:
+ *
+ * - `vpc` is supplied via the dedicated
+ *   {@link IInstanceBuilder.vpc | .vpc()} method.
+ * - `role`, `keyPair`, and `securityGroup` are exposed on the builder as
+ *   `Resolvable<T>` setters.
+ *
+ * Other props (`instanceType`, `machineImage`, `userData`, `blockDevices`,
+ * etc.) are passed through with their CDK types unchanged because they are
+ * almost always constructed inline rather than referenced from another
+ * component.
+ */
+export interface InstanceBuilderProps extends Omit<InstanceProps, "vpc" | "role" | "keyPair" | "securityGroup"> {
+    /**
+     * IAM role assumed by the instance via its instance profile.
+     *
+     * Accepts a concrete {@link IRole} or a {@link Ref} that resolves to one
+     * at build time, e.g. a sibling `RoleBuilder` in the same composed system.
+     *
+     * @default - CDK creates a role and attaches `AmazonSSMManagedInstanceCore`,
+     *   driven by the `ssmSessionPermissions: true` default in
+     *   {@link INSTANCE_DEFAULTS}.
+     */
+    role?: Resolvable<IRole>;
+    /**
+     * Key pair to associate with the instance.
+     *
+     * Accepts a concrete {@link IKeyPair} or a {@link Ref} that resolves to
+     * one at build time.
+     *
+     * @default - no key pair is associated; SSM Session Manager is the
+     *   recommended access path.
+     */
+    keyPair?: Resolvable<IKeyPair>;
+    /**
+     * Primary security group for the instance.
+     *
+     * Accepts a concrete {@link ISecurityGroup} or a {@link Ref} that resolves
+     * to one at build time. Additional security groups can be attached via
+     * `instance.addSecurityGroup()` after build.
+     *
+     * @default - CDK creates a security group allowing all outbound traffic.
+     */
+    securityGroup?: Resolvable<ISecurityGroup>;
+    /**
+     * Configuration for AWS-recommended CloudWatch alarms.
+     *
+     * By default, the builder creates recommended alarms with sensible
+     * thresholds for every applicable metric. Individual alarms can be
+     * customized or disabled. Set to `false` to disable all alarms.
+     *
+     * No alarm actions are configured by default since notification methods
+     * are user-specific. Access alarms from the build result or use an
+     * `afterBuild` hook to apply actions.
+     *
+     * Contextual alarms (`cpuCreditBalance`) are only created when the
+     * corresponding instance configuration is present — e.g., burstable
+     * T-family instance types.
+     *
+     * @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#EC2
+     */
+    recommendedAlarms?: InstanceAlarmConfig | false;
+}
+/**
+ * The build output of a {@link IInstanceBuilder}. Contains the CDK
+ * constructs created during {@link Lifecycle.build}, keyed by role.
+ */
+export interface InstanceBuilderResult {
+    instance: Instance;
+    /**
+     * CloudWatch alarms created for the instance, keyed by alarm name.
+     *
+     * Includes AWS-recommended instance alarms, any custom alarms added
+     * via {@link IInstanceBuilder.addAlarm}, and per-attachment alarms
+     * added by {@link IInstanceBuilder.attachVolume} (keyed
+     * `${attachmentKey}.${alarmKey}`, e.g. `AgentData.volumeStalledIo`).
+     *
+     * No alarm actions are configured — apply them via the result or an
+     * `afterBuild` hook.
+     *
+     * @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#EC2
+     */
+    alarms: Record<string, Alarm>;
+    /**
+     * `AWS::EC2::VolumeAttachment` constructs created via
+     * {@link IInstanceBuilder.attachVolume}, keyed by the attachment key
+     * supplied in that call.
+     *
+     * Empty when no volumes were attached.
+     */
+    volumeAttachments: Record<string, CfnVolumeAttachment>;
+}
+/**
+ * A fluent builder for configuring and creating an AWS EC2 instance.
+ *
+ * Each configuration property from the CDK {@link InstanceProps} is exposed
+ * as an overloaded method: call with a value to set it (returns the builder
+ * for chaining), or call with no arguments to read the current value.
+ *
+ * The `vpc` is set via the dedicated {@link IInstanceBuilder.vpc | .vpc()}
+ * method that accepts a {@link Resolvable} value for cross-component wiring
+ * (e.g., to a sibling {@link IVpcBuilder}). The `role`, `keyPair`, and
+ * `securityGroup` setters likewise accept {@link Resolvable} values so they
+ * can be supplied by sibling builders' outputs via {@link ref}.
+ *
+ * The builder implements {@link Lifecycle}, so it can be used directly as a
+ * component in a {@link compose | composed system}. When built, it creates
+ * an EC2 instance with the configured properties and returns an
+ * {@link InstanceBuilderResult}.
+ *
+ * AWS-recommended CloudWatch alarms are created by default. Alarms can be
+ * customized or disabled via the `recommendedAlarms` property. Custom
+ * alarms can be added via the {@link addAlarm} method.
+ *
+ * @see https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_ec2-readme.html
+ *
+ * @example
+ * ```ts
+ * const server = createInstanceBuilder()
+ *   .vpc(vpc)
+ *   .instanceType(InstanceType.of(InstanceClass.T3, InstanceSize.MICRO))
+ *   .machineImage(MachineImage.latestAmazonLinux2023());
+ * ```
+ */
+export type IInstanceBuilder = ITaggedBuilder<InstanceBuilderProps, InstanceBuilder>;
+declare class InstanceBuilder implements Lifecycle<InstanceBuilderResult> {
+    #private;
+    props: Partial<InstanceBuilderProps>;
+    /**
+     * Sets the VPC the instance will be launched into.
+     *
+     * Accepts a concrete {@link IVpc} or a {@link Ref} that resolves to one
+     * at build time. This is how cross-component wiring works — e.g., to a
+     * sibling {@link IVpcBuilder} in the same composed system.
+     *
+     * @param vpc - The VPC or a Ref to one.
+     * @returns This builder for chaining.
+     */
+    vpc(vpc: Resolvable<IVpc>): this;
+    /**
+     * Adds a custom CloudWatch alarm to be created alongside the recommended
+     * alarms. The provided callback receives an {@link AlarmDefinitionBuilder}
+     * scoped to the built {@link Instance}; configure it fluently and return it.
+     *
+     * @param key - A unique key for the alarm (used to generate the alarm id).
+     * @param configure - Callback that configures the alarm definition.
+     * @returns This builder for chaining.
+     */
+    addAlarm(key: string, configure: (alarm: AlarmDefinitionBuilder<Instance>) => AlarmDefinitionBuilder<Instance>): this;
+    /**
+     * Attaches an externally-managed EBS volume to the instance via an
+     * `AWS::EC2::VolumeAttachment` resource, mirroring the call shape of
+     * {@link addAlarm}.
+     *
+     * The `volumeRef` accepts either a `Resolvable<VolumeBuilderResult>`
+     * (drop a `ref<VolumeBuilderResult>("data")` straight in) or a
+     * `Resolvable<IVolume>` for an externally-managed volume — the builder
+     * unwraps either at build time.
+     *
+     * When both AZs are concrete at synth time, the builder asserts the
+     * instance and the volume are in the same Availability Zone — synth-
+     * time failure beats boot-time failure for AZ mismatches.
+     *
+     * Per-attachment AWS-recommended alarms (e.g. `volumeStalledIo`) are
+     * created by default and merged into the result's `alarms` record
+     * under prefixed keys (`${attachmentKey}.${alarmKey}`).
+     *
+     * @param key - Unique key for the attachment (used as the result-map
+     *   field name and as the construct id suffix).
+     * @param volumeRef - Resolvable to the volume to attach.
+     * @param options - Attachment options (`device`, `recommendedAlarms`).
+     * @returns This builder for chaining.
+     */
+    attachVolume(key: string, volumeRef: AttachVolumeRef, options: AttachVolumeOptions): this;
+    /** @internal — see ADR-0005. */
+    [COPY_STATE](target: InstanceBuilder): void;
+    build(scope: IConstruct, id: string, context?: Record<string, object>): InstanceBuilderResult;
+}
+/**
+ * Creates a new {@link IInstanceBuilder} for configuring an AWS EC2 instance.
+ *
+ * This is the entry point for defining an EC2 instance component. The
+ * returned builder exposes every {@link InstanceBuilderProps} property as a
+ * fluent setter/getter, plus {@link IInstanceBuilder.vpc | .vpc()} for
+ * cross-component VPC wiring with Ref support. It implements
+ * {@link Lifecycle} for use with {@link compose}.
+ *
+ * @returns A fluent builder for an AWS EC2 instance.
+ *
+ * @example
+ * ```ts
+ * const server = createInstanceBuilder()
+ *   .vpc(ref<VpcBuilderResult>("network").get("vpc"))
+ *   .instanceType(InstanceType.of(InstanceClass.T3, InstanceSize.MICRO))
+ *   .machineImage(MachineImage.latestAmazonLinux2023());
+ *
+ * // Use standalone:
+ * const result = server.build(stack, "MyInstance");
+ *
+ * // Or compose into a system:
+ * const system = compose(
+ *   { network: createVpcBuilder(), server },
+ *   { network: [], server: ["network"] },
+ * );
+ * ```
+ */
+export declare function createInstanceBuilder(): IInstanceBuilder;
+export {};
+//# sourceMappingURL=instance-builder.d.ts.map

package/dist/esm/instance-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"instance-builder.d.ts","sourceRoot":"","sources":["../../src/instance-builder.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,KAAK,EAAE,MAAM,4BAA4B,CAAC;AACxD,OAAO,EACL,KAAK,mBAAmB,EACxB,QAAQ,EACR,KAAK,QAAQ,EACb,KAAK,cAAc,EACnB,KAAK,IAAI,EACT,KAAK,aAAa,EACnB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,KAAK,KAAK,EAAE,MAAM,qBAAqB,CAAC;AACjD,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EAAE,UAAU,EAAE,KAAK,SAAS,EAAW,KAAK,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAC1F,OAAO,EAAE,KAAK,cAAc,EAAiB,MAAM,8BAA8B,CAAC;AAClF,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAGtE,OAAO,EACL,KAAK,mBAAmB,EACxB,KAAK,eAAe,EAGrB,MAAM,kCAAkC,CAAC;AAE1C;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,oBAAqB,SAAQ,IAAI,CAChD,aAAa,EACb,KAAK,GAAG,MAAM,GAAG,SAAS,GAAG,eAAe,CAC7C;IACC;;;;;;;;;OASG;IACH,IAAI,CAAC,EAAE,UAAU,CAAC,KAAK,CAAC,CAAC;IAEzB;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE,UAAU,CAAC,QAAQ,CAAC,CAAC;IAE/B;;;;;;;;OAQG;IACH,aAAa,CAAC,EAAE,UAAU,CAAC,cAAc,CAAC,CAAC;IAE3C;;;;;;;;;;;;;;;;OAgBG;IACH,iBAAiB,CAAC,EAAE,mBAAmB,GAAG,KAAK,CAAC;CACjD;AAED;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,EAAE,QAAQ,CAAC;IAEnB;;;;;;;;;;;;OAYG;IACH,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IAE9B;;;;;;OAMG;IACH,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC;CACxD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,MAAM,gBAAgB,GAAG,cAAc,CAAC,oBAAoB,EAAE,eAAe,CAAC,CAAC;AAErF,cAAM,eAAgB,YAAW,SAAS,CAAC,qBAAqB,CAAC;;IAC/D,KAAK,EAAE,OAAO,CAAC,oBAAoB,CAAC,CAAM;IAK1C;;;;;;;;;OASG;IACH,GAAG,CAAC,GAAG,EAAE,UAAU,CAAC,IAAI,CAAC,GAAG,IAAI;IAKhC;;;;;;;;OAQG;IACH,QAAQ,CACN,GAAG,EAAE,MAAM,EACX,SAAS,EAAE,CAAC,KAAK,EAAE,sBAAsB,CAAC,QAAQ,CAAC,KAAK,sBAAsB,CAAC,QAAQ,CAAC,GACvF,IAAI;IAKP;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,eAAe,EAAE,OAAO,EAAE,mBAAmB,GAAG,IAAI;IAQzF,gCAAgC;IAChC,CAAC,UAAU,CAAC,CAAC,MAAM,EAAE,eAAe,GAAG,IAAI;IAM3C,KAAK,CAAC,KAAK,EAAE,UAAU,EAAE,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,qBAAqB;CAoD9F;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,qBAAqB,IAAI,gBAAgB,CAExD"}

package/dist/{instance-builder.js → esm/instance-builder.js}

@@ -1,11 +1,14 @@
 import { Instance, } from "aws-cdk-lib/aws-ec2";
-import { Builder, resolve, } from "@composurecdk/core";
+import { COPY_STATE, resolve } from "@composurecdk/core";
+import { taggedBuilder } from "@composurecdk/cloudformation";
 import { AlarmDefinitionBuilder } from "@composurecdk/cloudwatch";
 import { createInstanceAlarms } from "./instance-alarms.js";
 import { INSTANCE_DEFAULTS } from "./instance-defaults.js";
+import { createVolumeAttachments, } from "./instance-volume-attachments.js";
 class InstanceBuilder {
     props = {};
     #customAlarms = [];
+    #volumeAttachments = [];
     #vpc;
     /**
      * Sets the VPC the instance will be launched into.
@@ -34,6 +37,43 @@ class InstanceBuilder {
         this.#customAlarms.push(configure(new AlarmDefinitionBuilder(key)));
         return this;
     }
+    /**
+     * Attaches an externally-managed EBS volume to the instance via an
+     * `AWS::EC2::VolumeAttachment` resource, mirroring the call shape of
+     * {@link addAlarm}.
+     *
+     * The `volumeRef` accepts either a `Resolvable<VolumeBuilderResult>`
+     * (drop a `ref<VolumeBuilderResult>("data")` straight in) or a
+     * `Resolvable<IVolume>` for an externally-managed volume — the builder
+     * unwraps either at build time.
+     *
+     * When both AZs are concrete at synth time, the builder asserts the
+     * instance and the volume are in the same Availability Zone — synth-
+     * time failure beats boot-time failure for AZ mismatches.
+     *
+     * Per-attachment AWS-recommended alarms (e.g. `volumeStalledIo`) are
+     * created by default and merged into the result's `alarms` record
+     * under prefixed keys (`${attachmentKey}.${alarmKey}`).
+     *
+     * @param key - Unique key for the attachment (used as the result-map
+     *   field name and as the construct id suffix).
+     * @param volumeRef - Resolvable to the volume to attach.
+     * @param options - Attachment options (`device`, `recommendedAlarms`).
+     * @returns This builder for chaining.
+     */
+    attachVolume(key, volumeRef, options) {
+        if (this.#volumeAttachments.some((a) => a.key === key)) {
+            throw new Error(`attachVolume: duplicate attachment key "${key}".`);
+        }
+        this.#volumeAttachments.push({ key, volumeRef, options });
+        return this;
+    }
+    /** @internal — see ADR-0005. */
+    [COPY_STATE](target) {
+        target.#vpc = this.#vpc;
+        target.#customAlarms.push(...this.#customAlarms);
+        target.#volumeAttachments.push(...this.#volumeAttachments);
+    }
     build(scope, id, context) {
         const resolvedVpc = this.#vpc ? resolve(this.#vpc, context) : undefined;
         if (!resolvedVpc) {
@@ -49,8 +89,13 @@ class InstanceBuilder {
             ...(securityGroup !== undefined ? { securityGroup: resolve(securityGroup, context) } : {}),
         };
         const instance = new Instance(scope, id, mergedProps);
-        const alarms = createInstanceAlarms(scope, id, instance, alarmConfig, mergedProps, this.#customAlarms);
-        return { instance, alarms };
+        const instanceAlarms = createInstanceAlarms(scope, id, instance, alarmConfig, mergedProps, this.#customAlarms);
+        const { attachments, alarms: attachmentAlarms } = createVolumeAttachments(scope, id, instance, mergedProps, this.#volumeAttachments, context);
+        return {
+            instance,
+            alarms: { ...instanceAlarms, ...attachmentAlarms },
+            volumeAttachments: attachments,
+        };
     }
 }
 /**
@@ -82,6 +127,6 @@ class InstanceBuilder {
  * ```
  */
 export function createInstanceBuilder() {
-    return Builder(InstanceBuilder);
+    return taggedBuilder(InstanceBuilder);
 }
 //# sourceMappingURL=instance-builder.js.map

package/dist/esm/instance-builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"instance-builder.js","sourceRoot":"","sources":["../../src/instance-builder.ts"],"names":[],"mappings":"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"}

package/dist/esm/instance-defaults.d.ts

@@ -0,0 +1,14 @@
+import { type InstanceProps } from "aws-cdk-lib/aws-ec2";
+/**
+ * Secure, AWS-recommended defaults applied to every EC2 instance built with
+ * {@link createInstanceBuilder}. Each property can be individually overridden
+ * via the builder's fluent API.
+ *
+ * Three required properties intentionally have no default — they are
+ * application-specific and must be supplied explicitly:
+ *   - `vpc` (via the builder's `.vpc()` method)
+ *   - `instanceType`
+ *   - `machineImage`
+ */
+export declare const INSTANCE_DEFAULTS: Partial<InstanceProps>;
+//# sourceMappingURL=instance-defaults.d.ts.map

package/dist/esm/instance-defaults.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"instance-defaults.d.ts","sourceRoot":"","sources":["../../src/instance-defaults.ts"],"names":[],"mappings":"AAAA,OAAO,EAA0C,KAAK,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEjG;;;;;;;;;;GAUG;AACH,eAAO,MAAM,iBAAiB,EAAE,OAAO,CAAC,aAAa,CAiDpD,CAAC"}

package/dist/esm/instance-defaults.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"instance-defaults.js","sourceRoot":"","sources":["../../src/instance-defaults.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,mBAAmB,EAAsB,MAAM,qBAAqB,CAAC;AAEjG;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAA2B;IACvD;;;;;OAKG;IACH,aAAa,EAAE,IAAI;IAEnB;;;;;OAKG;IACH,kBAAkB,EAAE,IAAI;IAExB;;;;;OAKG;IACH,qBAAqB,EAAE,IAAI;IAE3B;;;;;OAKG;IACH,YAAY,EAAE,IAAI;IAElB;;;;;;OAMG;IACH,YAAY,EAAE;QACZ;YACE,UAAU,EAAE,WAAW;YACvB,MAAM,EAAE,iBAAiB,CAAC,GAAG,CAAC,CAAC,EAAE;gBAC/B,SAAS,EAAE,IAAI;gBACf,UAAU,EAAE,mBAAmB,CAAC,GAAG;aACpC,CAAC;SACH;KACF;CACF,CAAC"}

package/dist/esm/instance-volume-attachment-config.d.ts

@@ -0,0 +1,34 @@
+import type { AlarmConfig } from "@composurecdk/cloudwatch";
+/**
+ * Controls which recommended alarms are created for a per-attachment EBS
+ * volume on an EC2 instance.
+ *
+ * Default thresholds are sourced from the AWS-recommended CloudWatch
+ * alarm guide. Set the master switch or individual alarms to `false` to
+ * disable them, or provide an {@link AlarmConfig} to tune thresholds.
+ *
+ * @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#EBS
+ */
+export interface VolumeAttachmentAlarmConfig {
+    /**
+     * Master switch: set to `false` to disable all per-attachment alarms.
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * Alarm when the per-attachment EBS volume status check reports a
+     * stalled I/O condition — typically a host or storage-subsystem issue
+     * for that specific attachment.
+     *
+     * Metric: `AWS/EBS VolumeStalledIOCheck`, statistic Maximum,
+     * period 1 minute. Default threshold: >= 1 over 10 consecutive minutes.
+     *
+     * The metric is published only for Nitro-instance attachments. On
+     * non-Nitro instances the alarm sits at `INSUFFICIENT_DATA`, which the
+     * `treatMissingData: NOT_BREACHING` default makes harmless.
+     *
+     * @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#EBS
+     */
+    volumeStalledIo?: AlarmConfig | false;
+}
+//# sourceMappingURL=instance-volume-attachment-config.d.ts.map

package/dist/esm/instance-volume-attachment-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"instance-volume-attachment-config.d.ts","sourceRoot":"","sources":["../../src/instance-volume-attachment-config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAE5D;;;;;;;;;GASG;AACH,MAAM,WAAW,2BAA2B;IAC1C;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB;;;;;;;;;;;;;OAaG;IACH,eAAe,CAAC,EAAE,WAAW,GAAG,KAAK,CAAC;CACvC"}

package/dist/esm/instance-volume-attachment-config.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=instance-volume-attachment-config.js.map

package/dist/esm/instance-volume-attachment-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"instance-volume-attachment-config.js","sourceRoot":"","sources":["../../src/instance-volume-attachment-config.ts"],"names":[],"mappings":""}

package/dist/esm/instance-volume-attachment-defaults.d.ts

@@ -0,0 +1,14 @@
+import type { AlarmConfigDefaults } from "@composurecdk/cloudwatch";
+interface VolumeAttachmentAlarmDefaults {
+    enabled: true;
+    volumeStalledIo: AlarmConfigDefaults;
+}
+/**
+ * AWS-recommended default alarm configuration for per-attachment EBS
+ * volumes.
+ *
+ * @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#EBS
+ */
+export declare const VOLUME_ATTACHMENT_ALARM_DEFAULTS: VolumeAttachmentAlarmDefaults;
+export {};
+//# sourceMappingURL=instance-volume-attachment-defaults.d.ts.map

package/dist/esm/instance-volume-attachment-defaults.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"instance-volume-attachment-defaults.d.ts","sourceRoot":"","sources":["../../src/instance-volume-attachment-defaults.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAEpE,UAAU,6BAA6B;IACrC,OAAO,EAAE,IAAI,CAAC;IACd,eAAe,EAAE,mBAAmB,CAAC;CACtC;AAED;;;;;GAKG;AACH,eAAO,MAAM,gCAAgC,EAAE,6BAgB9C,CAAC"}

package/dist/esm/instance-volume-attachment-defaults.js

@@ -0,0 +1,24 @@
+import { TreatMissingData } from "aws-cdk-lib/aws-cloudwatch";
+/**
+ * AWS-recommended default alarm configuration for per-attachment EBS
+ * volumes.
+ *
+ * @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#EBS
+ */
+export const VOLUME_ATTACHMENT_ALARM_DEFAULTS = {
+    enabled: true,
+    /**
+     * The single AWS-recommended EBS alarm. Complements the existing
+     * `attachedEbsStatusCheckFailed` on the instance: the EC2-side metric
+     * pages on instance-level reachability, this one on per-volume health.
+     * The 10-of-10 evaluation window matches AWS guidance — EBS
+     * infrastructure usually self-heals within a few minutes.
+     */
+    volumeStalledIo: {
+        threshold: 1,
+        evaluationPeriods: 10,
+        datapointsToAlarm: 10,
+        treatMissingData: TreatMissingData.NOT_BREACHING,
+    },
+};
+//# sourceMappingURL=instance-volume-attachment-defaults.js.map

package/dist/esm/instance-volume-attachment-defaults.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"instance-volume-attachment-defaults.js","sourceRoot":"","sources":["../../src/instance-volume-attachment-defaults.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAQ9D;;;;;GAKG;AACH,MAAM,CAAC,MAAM,gCAAgC,GAAkC;IAC7E,OAAO,EAAE,IAAI;IAEb;;;;;;OAMG;IACH,eAAe,EAAE;QACf,SAAS,EAAE,CAAC;QACZ,iBAAiB,EAAE,EAAE;QACrB,iBAAiB,EAAE,EAAE;QACrB,gBAAgB,EAAE,gBAAgB,CAAC,aAAa;KACjD;CACF,CAAC"}

package/dist/esm/instance-volume-attachments.d.ts

@@ -0,0 +1,59 @@
+import { type Alarm } from "aws-cdk-lib/aws-cloudwatch";
+import { CfnVolumeAttachment, type Instance, type InstanceProps, type IVolume } from "aws-cdk-lib/aws-ec2";
+import type { IConstruct } from "constructs";
+import { type Resolvable } from "@composurecdk/core";
+import type { VolumeBuilderResult } from "./volume-builder.js";
+import type { VolumeAttachmentAlarmConfig } from "./instance-volume-attachment-config.js";
+/**
+ * Reference to the volume to be attached. Either a sibling
+ * {@link VolumeBuilderResult} (the common composed-system case) or a
+ * concrete {@link IVolume} (for externally-managed volumes).
+ */
+export type AttachVolumeRef = Resolvable<VolumeBuilderResult> | Resolvable<IVolume>;
+/**
+ * Configuration for a single `attachVolume` call.
+ */
+export interface AttachVolumeOptions {
+    /**
+     * Linux device name to attach the volume as (e.g. `/dev/sdf`).
+     *
+     * The Linux kernel may rename this to `xvdf` etc. on the instance —
+     * resolve mounts via UUID rather than the device path.
+     *
+     * @see https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/device_naming.html
+     */
+    device: string;
+    /**
+     * Configuration for the per-attachment recommended alarms.
+     *
+     * @default - alarms enabled with the defaults in
+     *   {@link VOLUME_ATTACHMENT_ALARM_DEFAULTS}.
+     */
+    recommendedAlarms?: VolumeAttachmentAlarmConfig | false;
+}
+/**
+ * Internal config captured by {@link IInstanceBuilder.attachVolume} and
+ * forwarded to {@link createVolumeAttachments} at build time.
+ *
+ * @internal
+ */
+export interface PendingVolumeAttachment {
+    key: string;
+    volumeRef: AttachVolumeRef;
+    options: AttachVolumeOptions;
+}
+/**
+ * Creates a {@link CfnVolumeAttachment} for each pending attachment and
+ * (when configured) the per-attachment recommended alarms. Synth-time AZ
+ * alignment is validated when both the volume's AZ and the instance's
+ * effective AZ are concrete strings.
+ *
+ * @returns The created `CfnVolumeAttachment`s keyed by attachment key,
+ *   plus the per-attachment alarms keyed by `${attachmentKey}.${alarmKey}`
+ *   so they can be flat-merged into the instance's `alarms` record.
+ */
+export declare function createVolumeAttachments(scope: IConstruct, id: string, instance: Instance, instanceProps: InstanceProps, attachments: PendingVolumeAttachment[], context?: Record<string, object>): {
+    attachments: Record<string, CfnVolumeAttachment>;
+    alarms: Record<string, Alarm>;
+};
+//# sourceMappingURL=instance-volume-attachments.d.ts.map

package/dist/esm/instance-volume-attachments.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"instance-volume-attachments.d.ts","sourceRoot":"","sources":["../../src/instance-volume-attachments.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,KAAK,EAAqC,MAAM,4BAA4B,CAAC;AAC3F,OAAO,EACL,mBAAmB,EACnB,KAAK,QAAQ,EACb,KAAK,aAAa,EAClB,KAAK,OAAO,EAEb,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EAAW,KAAK,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAE9D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC/D,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,wCAAwC,CAAC;AAM1F;;;;GAIG;AACH,MAAM,MAAM,eAAe,GAAG,UAAU,CAAC,mBAAmB,CAAC,GAAG,UAAU,CAAC,OAAO,CAAC,CAAC;AAEpF;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;;;;OAOG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,2BAA2B,GAAG,KAAK,CAAC;CACzD;AAED;;;;;GAKG;AACH,MAAM,WAAW,uBAAuB;IACtC,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,eAAe,CAAC;IAC3B,OAAO,EAAE,mBAAmB,CAAC;CAC9B;AAsFD;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,UAAU,EACjB,EAAE,EAAE,MAAM,EACV,QAAQ,EAAE,QAAQ,EAClB,aAAa,EAAE,aAAa,EAC5B,WAAW,EAAE,uBAAuB,EAAE,EACtC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC/B;IAAE,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAA;CAAE,CAwCrF"}