@composurecdk/ec2 0.5.1 → 0.7.0

package/README.md

@@ -120,6 +120,51 @@ const server = createInstanceBuilder()
   );
 ```
 
+### Attaching persistent volumes
+
+`attachVolume(key, volumeRef, opts)` mirrors the call shape of `addAlarm` and produces an `AWS::EC2::VolumeAttachment` for an externally-managed EBS volume. The volume reference accepts either a `Resolvable<VolumeBuilderResult>` (drop a `ref<VolumeBuilderResult>("data")` straight in) or a `Resolvable<IVolume>`.
+
+```ts
+import { compose, ref } from "@composurecdk/core";
+import {
+  createInstanceBuilder,
+  createVolumeBuilder,
+  createVpcBuilder,
+  type VolumeBuilderResult,
+  type VpcBuilderResult,
+} from "@composurecdk/ec2";
+import { Size } from "aws-cdk-lib";
+import { InstanceClass, InstanceSize, InstanceType, MachineImage } from "aws-cdk-lib/aws-ec2";
+
+compose(
+  {
+    network: createVpcBuilder().maxAzs(2).natGateways(0),
+
+    data: createVolumeBuilder()
+      .availabilityZone(ref<VpcBuilderResult>("network").map((r) => r.vpc.availabilityZones[0]))
+      .size(Size.gibibytes(50)),
+
+    agent: createInstanceBuilder()
+      .vpc(ref<VpcBuilderResult>("network").map((r) => r.vpc))
+      .instanceType(InstanceType.of(InstanceClass.T3, InstanceSize.MICRO))
+      .machineImage(MachineImage.latestAmazonLinux2023())
+      .attachVolume("AgentData", ref<VolumeBuilderResult>("data"), { device: "/dev/sdf" }),
+  },
+  { network: [], data: ["network"], agent: ["network", "data"] },
+).build(stack, "AgentApp");
+```
+
+The result exposes the attachment under `result.agent.volumeAttachments.AgentData` and emits a per-attachment `volumeStalledIo` alarm under `result.agent.alarms["AgentData.volumeStalledIo"]`. When both AZs are concrete strings at synth, the builder asserts the instance and volume share an Availability Zone — synth-time failure beats boot-time failure.
+
+`VolumeStalledIOCheck` 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. To disable the alarm per attachment:
+
+```ts
+.attachVolume("AgentData", ref<VolumeBuilderResult>("data"), {
+  device: "/dev/sdf",
+  recommendedAlarms: false,
+})
+```
+
 ## VPC Builder
 
 ```ts
@@ -175,6 +220,82 @@ createVpcBuilder().flowLogs(false);
 
 For multiple flow logs against the same VPC, omit this config and create additional `FlowLog` constructs directly against the returned `vpc`.
 
+## Volume Builder
+
+```ts
+import { createVolumeBuilder } from "@composurecdk/ec2";
+import { Size } from "aws-cdk-lib";
+
+const data = createVolumeBuilder()
+  .availabilityZone("us-east-1a")
+  .size(Size.gibibytes(50))
+  .build(stack, "AgentData");
+```
+
+Every [VolumeProps](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_ec2.VolumeProps.html) property is available as a fluent setter on the builder, except `availabilityZone` which is set via the dedicated `.availabilityZone()` method (so it can be wired from a sibling `VpcBuilder` via `ref`) and `encryptionKey` which accepts a `Resolvable<IKey>` for cross-component KMS-key wiring.
+
+### Volume Defaults
+
+| Property        | Default                | Rationale                                                                                                 |
+| --------------- | ---------------------- | --------------------------------------------------------------------------------------------------------- |
+| `volumeType`    | `GP3`                  | Current-generation general-purpose SSD — cheaper and faster than GP2 at equivalent sizes.                 |
+| `encrypted`     | `true`                 | Encryption at rest with the account's default EBS KMS key. Pass `encryptionKey` for a CMK.                |
+| `autoEnableIo`  | `true`                 | Lets I/O resume on suspected inconsistency so the instance can come up unattended.                        |
+| `removalPolicy` | `RemovalPolicy.RETAIN` | A destroyed volume is unrecoverable; an orphaned volume is a $/month nuisance. Mirrors `BUCKET_DEFAULTS`. |
+
+Three properties intentionally have no default — they are application-specific and must be supplied explicitly:
+
+- `availabilityZone` (via the `.availabilityZone()` method)
+- `size`
+- `iops` / `throughput` (only when opting into a volume type that requires them)
+
+The defaults are exported as `VOLUME_DEFAULTS` for visibility and testing:
+
+```ts
+import { VOLUME_DEFAULTS } from "@composurecdk/ec2";
+```
+
+### Recommended Volume Alarms
+
+The builder creates [AWS-recommended CloudWatch alarms](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#EBS) by default. No alarm actions are configured — wire actions via `alarmActionsPolicy` from `@composurecdk/cloudwatch`.
+
+| Alarm          | Metric                        | Default threshold    | Created when                                    |
+| -------------- | ----------------------------- | -------------------- | ----------------------------------------------- |
+| `burstBalance` | BurstBalance (Average, 5 min) | < 20% over 3 × 5 min | `volumeType` is burstable (`gp2`, `st1`, `sc1`) |
+
+The defaults are exported as `VOLUME_ALARM_DEFAULTS` for visibility and testing:
+
+```ts
+import { VOLUME_ALARM_DEFAULTS } from "@composurecdk/ec2";
+```
+
+`VolumeQueueLength` and `VolumeIdleTime` are deferred — both need per-`volumeType`/per-workload tuning to be a defensible default. Wire them via `addAlarm` until first-class support lands:
+
+```ts
+import { Metric, Stats } from "aws-cdk-lib/aws-cloudwatch";
+import { Duration } from "aws-cdk-lib";
+
+const data = createVolumeBuilder()
+  .availabilityZone("us-east-1a")
+  .size(Size.gibibytes(50))
+  .addAlarm("volumeQueueLength", (alarm) =>
+    alarm
+      .metric(
+        (volume) =>
+          new Metric({
+            namespace: "AWS/EBS",
+            metricName: "VolumeQueueLength",
+            dimensionsMap: { VolumeId: volume.volumeId },
+            statistic: Stats.AVERAGE,
+            period: Duration.minutes(5),
+          }),
+      )
+      .threshold(10)
+      .greaterThan()
+      .description("EBS volume queue length is high"),
+  );
+```
+
 ## Composing EC2 + VPC
 
 Compose the builders into a single system — the instance is wired to the VPC via `ref`:

package/dist/index.d.ts

@@ -2,6 +2,13 @@ export { createInstanceBuilder, type IInstanceBuilder, type InstanceBuilderProps
 export { INSTANCE_DEFAULTS } from "./instance-defaults.js";
 export { type InstanceAlarmConfig } from "./instance-alarm-config.js";
 export { INSTANCE_ALARM_DEFAULTS } from "./instance-alarm-defaults.js";
+export { type AttachVolumeOptions } from "./instance-volume-attachments.js";
+export { type VolumeAttachmentAlarmConfig } from "./instance-volume-attachment-config.js";
+export { VOLUME_ATTACHMENT_ALARM_DEFAULTS } from "./instance-volume-attachment-defaults.js";
+export { createVolumeBuilder, type IVolumeBuilder, type VolumeBuilderProps, type VolumeBuilderResult, } from "./volume-builder.js";
+export { VOLUME_DEFAULTS } from "./volume-defaults.js";
+export { type VolumeAlarmConfig } from "./volume-alarm-config.js";
+export { VOLUME_ALARM_DEFAULTS } from "./volume-alarm-defaults.js";
 export { createVpcBuilder, type FlowLogsConfig, type IVpcBuilder, type VpcBuilderProps, type VpcBuilderResult, } from "./vpc-builder.js";
 export { VPC_DEFAULTS } from "./vpc-defaults.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,qBAAqB,EACrB,KAAK,gBAAgB,EACrB,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,GAC3B,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,EAAE,KAAK,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACtE,OAAO,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AAEvE,OAAO,EACL,gBAAgB,EAChB,KAAK,cAAc,EACnB,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,KAAK,gBAAgB,GACtB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,qBAAqB,EACrB,KAAK,gBAAgB,EACrB,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,GAC3B,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,EAAE,KAAK,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACtE,OAAO,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AACvE,OAAO,EAAE,KAAK,mBAAmB,EAAE,MAAM,kCAAkC,CAAC;AAC5E,OAAO,EAAE,KAAK,2BAA2B,EAAE,MAAM,wCAAwC,CAAC;AAC1F,OAAO,EAAE,gCAAgC,EAAE,MAAM,0CAA0C,CAAC;AAE5F,OAAO,EACL,mBAAmB,EACnB,KAAK,cAAc,EACnB,KAAK,kBAAkB,EACvB,KAAK,mBAAmB,GACzB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,EAAE,KAAK,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AAEnE,OAAO,EACL,gBAAgB,EAChB,KAAK,cAAc,EACnB,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,KAAK,gBAAgB,GACtB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/index.js

@@ -1,6 +1,10 @@
 export { createInstanceBuilder, } from "./instance-builder.js";
 export { INSTANCE_DEFAULTS } from "./instance-defaults.js";
 export { INSTANCE_ALARM_DEFAULTS } from "./instance-alarm-defaults.js";
+export { VOLUME_ATTACHMENT_ALARM_DEFAULTS } from "./instance-volume-attachment-defaults.js";
+export { createVolumeBuilder, } from "./volume-builder.js";
+export { VOLUME_DEFAULTS } from "./volume-defaults.js";
+export { VOLUME_ALARM_DEFAULTS } from "./volume-alarm-defaults.js";
 export { createVpcBuilder, } from "./vpc-builder.js";
 export { VPC_DEFAULTS } from "./vpc-defaults.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,qBAAqB,GAItB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAE3D,OAAO,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AAEvE,OAAO,EACL,gBAAgB,GAKjB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,qBAAqB,GAItB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAE3D,OAAO,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AAGvE,OAAO,EAAE,gCAAgC,EAAE,MAAM,0CAA0C,CAAC;AAE5F,OAAO,EACL,mBAAmB,GAIpB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAEvD,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AAEnE,OAAO,EACL,gBAAgB,GAKjB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/instance-builder.d.ts

@@ -1,10 +1,12 @@
 import { type Alarm } from "aws-cdk-lib/aws-cloudwatch";
-import { Instance, type IKeyPair, type ISecurityGroup, type IVpc, type InstanceProps } from "aws-cdk-lib/aws-ec2";
+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 { type IBuilder, type Lifecycle, type Resolvable } from "@composurecdk/core";
+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.
  *
@@ -82,9 +84,10 @@ export interface InstanceBuilderResult {
     /**
      * CloudWatch alarms created for the instance, keyed by alarm name.
      *
-     * Includes both AWS-recommended alarms and any custom alarms added
-     * via {@link IInstanceBuilder.addAlarm}. Access individual alarms by
-     * key (e.g., `result.alarms.cpuUtilization`).
+     * 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.
@@ -92,6 +95,14 @@ export interface InstanceBuilderResult {
      * @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.
@@ -125,7 +136,7 @@ export interface InstanceBuilderResult {
  *   .machineImage(MachineImage.latestAmazonLinux2023());
  * ```
  */
-export type IInstanceBuilder = IBuilder<InstanceBuilderProps, InstanceBuilder>;
+export type IInstanceBuilder = ITaggedBuilder<InstanceBuilderProps, InstanceBuilder>;
 declare class InstanceBuilder implements Lifecycle<InstanceBuilderResult> {
     #private;
     props: Partial<InstanceBuilderProps>;
@@ -150,6 +161,33 @@ declare class InstanceBuilder implements Lifecycle<InstanceBuilderResult> {
      * @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;
 }
 /**

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

@@ -1 +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,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,EAEL,KAAK,QAAQ,EACb,KAAK,SAAS,EAEd,KAAK,UAAU,EAChB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAItE;;;;;;;;;;;;;;;;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;;;;;;;;;;;OAWG;IACH,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;CAC/B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,MAAM,gBAAgB,GAAG,QAAQ,CAAC,oBAAoB,EAAE,eAAe,CAAC,CAAC;AAE/E,cAAM,eAAgB,YAAW,SAAS,CAAC,qBAAqB,CAAC;;IAC/D,KAAK,EAAE,OAAO,CAAC,oBAAoB,CAAC,CAAM;IAI1C;;;;;;;;;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,KAAK,CAAC,KAAK,EAAE,UAAU,EAAE,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,qBAAqB;CAuC9F;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,qBAAqB,IAAI,gBAAgB,CAExD"}
+{"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

@@ -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/instance-builder.js.map

@@ -1 +1 @@
-{"version":3,"file":"instance-builder.js","sourceRoot":"","sources":["../src/instance-builder.ts"],"names":[],"mappings":"AACA,OAAO,EACL,QAAQ,GAKT,MAAM,qBAAqB,CAAC;AAG7B,OAAO,EACL,OAAO,EAGP,OAAO,GAER,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAElE,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAqI3D,MAAM,eAAe;IACnB,KAAK,GAAkC,EAAE,CAAC;IACjC,aAAa,GAAuC,EAAE,CAAC;IAChE,IAAI,CAAoB;IAExB;;;;;;;;;OASG;IACH,GAAG,CAAC,GAAqB;QACvB,IAAI,CAAC,IAAI,GAAG,GAAG,CAAC;QAChB,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;;;;;OAQG;IACH,QAAQ,CACN,GAAW,EACX,SAAwF;QAExF,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,sBAAsB,CAAW,GAAG,CAAC,CAAC,CAAC,CAAC;QAC9E,OAAO,IAAI,CAAC;IACd,CAAC;IAED,KAAK,CAAC,KAAiB,EAAE,EAAU,EAAE,OAAgC;QACnE,MAAM,WAAW,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QAExE,IAAI,CAAC,WAAW,EAAE,CAAC;YACjB,MAAM,IAAI,KAAK,CACb,oBAAoB,EAAE,6DAA6D,CACpF,CAAC;QACJ,CAAC;QAED,MAAM,EACJ,iBAAiB,EAAE,WAAW,EAC9B,IAAI,EACJ,OAAO,EACP,aAAa,EACb,GAAG,aAAa,EACjB,GAAG,IAAI,CAAC,KAAK,CAAC;QAEf,MAAM,WAAW,GAAG;YAClB,GAAG,iBAAiB;YACpB,GAAG,aAAa;YAChB,GAAG,EAAE,WAAW;YAChB,GAAG,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC/D,GAAG,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACxE,GAAG,CAAC,aAAa,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,OAAO,CAAC,aAAa,EAAE,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC1E,CAAC;QAEnB,MAAM,QAAQ,GAAG,IAAI,QAAQ,CAAC,KAAK,EAAE,EAAE,EAAE,WAAW,CAAC,CAAC;QAEtD,MAAM,MAAM,GAAG,oBAAoB,CACjC,KAAK,EACL,EAAE,EACF,QAAQ,EACR,WAAW,EACX,WAAW,EACX,IAAI,CAAC,aAAa,CACnB,CAAC;QAEF,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;IAC9B,CAAC;CACF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,UAAU,qBAAqB;IACnC,OAAO,OAAO,CAAwC,eAAe,CAAC,CAAC;AACzE,CAAC"}
+{"version":3,"file":"instance-builder.js","sourceRoot":"","sources":["../src/instance-builder.ts"],"names":[],"mappings":"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"}

package/dist/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/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/instance-volume-attachment-config.js

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

package/dist/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/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/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/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/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/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/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"}

package/dist/instance-volume-attachments.js

@@ -0,0 +1,104 @@
+import { Duration, Token } from "aws-cdk-lib";
+import { ComparisonOperator, Metric, Stats } from "aws-cdk-lib/aws-cloudwatch";
+import { CfnVolumeAttachment, } from "aws-cdk-lib/aws-ec2";
+import { resolve } from "@composurecdk/core";
+import { createAlarms, resolveAlarmConfig } from "@composurecdk/cloudwatch";
+import { VOLUME_ATTACHMENT_ALARM_DEFAULTS } from "./instance-volume-attachment-defaults.js";
+const STALLED_IO_PERIOD = Duration.minutes(1);
+const STALLED_IO_PERIOD_LABEL = `${String(STALLED_IO_PERIOD.toMinutes())} minute`;
+function resolveInstanceAz(instanceProps) {
+    if (instanceProps.availabilityZone && !Token.isUnresolved(instanceProps.availabilityZone)) {
+        return instanceProps.availabilityZone;
+    }
+    let selected;
+    try {
+        selected = instanceProps.vpc.selectSubnets(instanceProps.vpcSubnets);
+    }
+    catch {
+        // selectSubnets() throws for several unrelated reasons (no matching subnets,
+        // unresolved tokens, etc.). The validation is best-effort — if we can't
+        // resolve a concrete AZ, fall through and let CFN surface the real failure.
+        return undefined;
+    }
+    return selected.availabilityZones.find((az) => !Token.isUnresolved(az));
+}
+function unwrapVolume(resolved) {
+    if ("volumeId" in resolved) {
+        return resolved;
+    }
+    return resolved.volume;
+}
+function volumeAttachmentMetric(volume, instance, metricName, statistic, period) {
+    return new Metric({
+        namespace: "AWS/EBS",
+        metricName,
+        dimensionsMap: {
+            VolumeId: volume.volumeId,
+            InstanceId: instance.instanceId,
+        },
+        statistic,
+        period,
+    });
+}
+function resolveVolumeAttachmentAlarmDefinitions(attachmentKey, volume, instance, config) {
+    if (config === false)
+        return [];
+    const enabled = config?.enabled ?? VOLUME_ATTACHMENT_ALARM_DEFAULTS.enabled;
+    if (!enabled)
+        return [];
+    if (config?.volumeStalledIo === false)
+        return [];
+    const cfg = resolveAlarmConfig(config?.volumeStalledIo, VOLUME_ATTACHMENT_ALARM_DEFAULTS.volumeStalledIo);
+    return [
+        {
+            key: `${attachmentKey}.volumeStalledIo`,
+            alarmName: cfg.alarmName,
+            metric: volumeAttachmentMetric(volume, instance, "VolumeStalledIOCheck", Stats.MAXIMUM, STALLED_IO_PERIOD),
+            threshold: cfg.threshold,
+            comparisonOperator: ComparisonOperator.GREATER_THAN_OR_EQUAL_TO_THRESHOLD,
+            evaluationPeriods: cfg.evaluationPeriods,
+            datapointsToAlarm: cfg.datapointsToAlarm,
+            treatMissingData: cfg.treatMissingData,
+            description: `EBS volume attachment "${attachmentKey}" is reporting a stalled I/O condition. ` +
+                `Threshold: >= ${String(cfg.threshold)} (max) over ${String(cfg.evaluationPeriods)} x ${STALLED_IO_PERIOD_LABEL}. ` +
+                `Note: VolumeStalledIOCheck is published only for Nitro-instance attachments.`,
+        },
+    ];
+}
+/**
+ * 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 function createVolumeAttachments(scope, id, instance, instanceProps, attachments, context) {
+    const attachmentRecords = {};
+    const alarmDefinitions = [];
+    // Resolve the instance AZ once — it is the same for every attachment.
+    const instanceAz = attachments.length > 0 ? resolveInstanceAz(instanceProps) : undefined;
+    for (const pending of attachments) {
+        const resolved = resolve(pending.volumeRef, context);
+        const volume = unwrapVolume(resolved);
+        if (instanceAz !== undefined && !Token.isUnresolved(volume.availabilityZone)) {
+            if (volume.availabilityZone !== instanceAz) {
+                throw new Error(`attachVolume "${pending.key}": volume is in availability zone "${volume.availabilityZone}" ` +
+                    `but the instance is in "${instanceAz}". ` +
+                    `EBS volumes can only attach to instances in the same AZ.`);
+            }
+        }
+        const attachment = new CfnVolumeAttachment(scope, `${id}${pending.key}Attachment`, {
+            device: pending.options.device,
+            instanceId: instance.instanceId,
+            volumeId: volume.volumeId,
+        });
+        attachmentRecords[pending.key] = attachment;
+        alarmDefinitions.push(...resolveVolumeAttachmentAlarmDefinitions(pending.key, volume, instance, pending.options.recommendedAlarms));
+    }
+    const alarms = alarmDefinitions.length > 0 ? createAlarms(scope, id, alarmDefinitions) : {};
+    return { attachments: attachmentRecords, alarms };
+}
+//# sourceMappingURL=instance-volume-attachments.js.map

package/dist/instance-volume-attachments.js.map

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