@composurecdk/ec2 0.6.0 → 0.8.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/commonjs/index.d.ts

@@ -0,0 +1,14 @@
+export { createInstanceBuilder, type IInstanceBuilder, type InstanceBuilderProps, type InstanceBuilderResult, } from "./instance-builder.js";
+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/commonjs/index.d.ts.map

@@ -0,0 +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;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/commonjs/index.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VPC_DEFAULTS = exports.createVpcBuilder = exports.VOLUME_ALARM_DEFAULTS = exports.VOLUME_DEFAULTS = exports.createVolumeBuilder = exports.VOLUME_ATTACHMENT_ALARM_DEFAULTS = exports.INSTANCE_ALARM_DEFAULTS = exports.INSTANCE_DEFAULTS = exports.createInstanceBuilder = void 0;
+var instance_builder_js_1 = require("./instance-builder.js");
+Object.defineProperty(exports, "createInstanceBuilder", { enumerable: true, get: function () { return instance_builder_js_1.createInstanceBuilder; } });
+var instance_defaults_js_1 = require("./instance-defaults.js");
+Object.defineProperty(exports, "INSTANCE_DEFAULTS", { enumerable: true, get: function () { return instance_defaults_js_1.INSTANCE_DEFAULTS; } });
+var instance_alarm_defaults_js_1 = require("./instance-alarm-defaults.js");
+Object.defineProperty(exports, "INSTANCE_ALARM_DEFAULTS", { enumerable: true, get: function () { return instance_alarm_defaults_js_1.INSTANCE_ALARM_DEFAULTS; } });
+var instance_volume_attachment_defaults_js_1 = require("./instance-volume-attachment-defaults.js");
+Object.defineProperty(exports, "VOLUME_ATTACHMENT_ALARM_DEFAULTS", { enumerable: true, get: function () { return instance_volume_attachment_defaults_js_1.VOLUME_ATTACHMENT_ALARM_DEFAULTS; } });
+var volume_builder_js_1 = require("./volume-builder.js");
+Object.defineProperty(exports, "createVolumeBuilder", { enumerable: true, get: function () { return volume_builder_js_1.createVolumeBuilder; } });
+var volume_defaults_js_1 = require("./volume-defaults.js");
+Object.defineProperty(exports, "VOLUME_DEFAULTS", { enumerable: true, get: function () { return volume_defaults_js_1.VOLUME_DEFAULTS; } });
+var volume_alarm_defaults_js_1 = require("./volume-alarm-defaults.js");
+Object.defineProperty(exports, "VOLUME_ALARM_DEFAULTS", { enumerable: true, get: function () { return volume_alarm_defaults_js_1.VOLUME_ALARM_DEFAULTS; } });
+var vpc_builder_js_1 = require("./vpc-builder.js");
+Object.defineProperty(exports, "createVpcBuilder", { enumerable: true, get: function () { return vpc_builder_js_1.createVpcBuilder; } });
+var vpc_defaults_js_1 = require("./vpc-defaults.js");
+Object.defineProperty(exports, "VPC_DEFAULTS", { enumerable: true, get: function () { return vpc_defaults_js_1.VPC_DEFAULTS; } });
+//# sourceMappingURL=index.js.map

package/dist/commonjs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;;AAAA,6DAK+B;AAJ7B,4HAAA,qBAAqB,OAAA;AAKvB,+DAA2D;AAAlD,yHAAA,iBAAiB,OAAA;AAE1B,2EAAuE;AAA9D,qIAAA,uBAAuB,OAAA;AAGhC,mGAA4F;AAAnF,0JAAA,gCAAgC,OAAA;AAEzC,yDAK6B;AAJ3B,wHAAA,mBAAmB,OAAA;AAKrB,2DAAuD;AAA9C,qHAAA,eAAe,OAAA;AAExB,uEAAmE;AAA1D,iIAAA,qBAAqB,OAAA;AAE9B,mDAM0B;AALxB,kHAAA,gBAAgB,OAAA;AAMlB,qDAAiD;AAAxC,+GAAA,YAAY,OAAA"}

package/dist/commonjs/instance-alarm-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"instance-alarm-config.d.ts","sourceRoot":"","sources":["../../src/instance-alarm-config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAE5D;;;;;;;GAOG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB;;;;;;;OAOG;IACH,cAAc,CAAC,EAAE,WAAW,GAAG,KAAK,CAAC;IAErC;;;;;;;OAOG;IACH,iBAAiB,CAAC,EAAE,WAAW,GAAG,KAAK,CAAC;IAExC;;;;;;;;;;OAUG;IACH,4BAA4B,CAAC,EAAE,WAAW,GAAG,KAAK,CAAC;IAEnD;;;;;;;;;;;;OAYG;IACH,gBAAgB,CAAC,EAAE,WAAW,GAAG,KAAK,CAAC;CACxC"}

package/dist/commonjs/instance-alarm-config.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=instance-alarm-config.js.map

package/dist/commonjs/instance-alarm-config.js.map

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

package/dist/commonjs/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/commonjs/instance-alarm-defaults.js

@@ -0,0 +1,65 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.INSTANCE_ALARM_DEFAULTS = void 0;
+const aws_cloudwatch_1 = require("aws-cdk-lib/aws-cloudwatch");
+/**
+ * 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
+ */
+exports.INSTANCE_ALARM_DEFAULTS = {
+    enabled: true,
+    /**
+     * Sustained high CPU indicates the instance is a bottleneck and may
+     * need to be scaled up. 80% over 5 consecutive minutes avoids
+     * alarming on brief workload spikes.
+     */
+    cpuUtilization: {
+        threshold: 80,
+        evaluationPeriods: 5,
+        datapointsToAlarm: 5,
+        treatMissingData: aws_cloudwatch_1.TreatMissingData.NOT_BREACHING,
+    },
+    /**
+     * Any status check failure is actionable — it indicates instance or
+     * host impairment. 2-of-2 evaluation filters transient single-minute
+     * noise while keeping time-to-detect low.
+     */
+    statusCheckFailed: {
+        threshold: 0,
+        evaluationPeriods: 2,
+        datapointsToAlarm: 2,
+        treatMissingData: aws_cloudwatch_1.TreatMissingData.NOT_BREACHING,
+    },
+    /**
+     * Attached EBS volumes are unreachable or unable to complete I/O —
+     * typically a host or storage-subsystem issue. The 10-of-10 evaluation
+     * window matches AWS guidance: EBS infrastructure usually self-heals
+     * within a few minutes, so a longer window avoids paging on transient
+     * issues that resolve without intervention.
+     */
+    attachedEbsStatusCheckFailed: {
+        threshold: 1,
+        evaluationPeriods: 10,
+        datapointsToAlarm: 10,
+        treatMissingData: aws_cloudwatch_1.TreatMissingData.NOT_BREACHING,
+    },
+    /**
+     * Low CPU credit balance on burstable instances means imminent
+     * throttling to baseline performance. Threshold < 50 at 5-minute
+     * minimum gives an early warning to investigate or switch instance
+     * family. Credit balance metrics are only emitted at 5-minute
+     * granularity regardless of detailed monitoring.
+     */
+    cpuCreditBalance: {
+        threshold: 50,
+        evaluationPeriods: 3,
+        datapointsToAlarm: 3,
+        treatMissingData: aws_cloudwatch_1.TreatMissingData.NOT_BREACHING,
+    },
+};
+//# sourceMappingURL=instance-alarm-defaults.js.map

package/dist/commonjs/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,+DAA8D;AAW9D;;;;;;;;GAQG;AACU,QAAA,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,iCAAgB,CAAC,aAAa;KACjD;IAED;;;;OAIG;IACH,iBAAiB,EAAE;QACjB,SAAS,EAAE,CAAC;QACZ,iBAAiB,EAAE,CAAC;QACpB,iBAAiB,EAAE,CAAC;QACpB,gBAAgB,EAAE,iCAAgB,CAAC,aAAa;KACjD;IAED;;;;;;OAMG;IACH,4BAA4B,EAAE;QAC5B,SAAS,EAAE,CAAC;QACZ,iBAAiB,EAAE,EAAE;QACrB,iBAAiB,EAAE,EAAE;QACrB,gBAAgB,EAAE,iCAAgB,CAAC,aAAa;KACjD;IAED;;;;;;OAMG;IACH,gBAAgB,EAAE;QAChB,SAAS,EAAE,EAAE;QACb,iBAAiB,EAAE,CAAC;QACpB,iBAAiB,EAAE,CAAC;QACpB,gBAAgB,EAAE,iCAAgB,CAAC,aAAa;KACjD;CACF,CAAC"}

package/dist/commonjs/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/commonjs/instance-alarms.js

@@ -0,0 +1,132 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveInstanceAlarmDefinitions = resolveInstanceAlarmDefinitions;
+exports.createInstanceAlarms = createInstanceAlarms;
+const aws_cdk_lib_1 = require("aws-cdk-lib");
+const aws_cloudwatch_1 = require("aws-cdk-lib/aws-cloudwatch");
+const cloudwatch_1 = require("@composurecdk/cloudwatch");
+const instance_alarm_defaults_js_1 = require("./instance-alarm-defaults.js");
+const METRIC_PERIOD = aws_cdk_lib_1.Duration.minutes(1);
+const METRIC_PERIOD_LABEL = `${String(METRIC_PERIOD.toMinutes())} minute`;
+/**
+ * CPU credit metrics are emitted by EC2 at 5-minute granularity regardless
+ * of whether detailed monitoring is enabled. Using a shorter period yields
+ * missing data rather than higher resolution.
+ *
+ * @see https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/viewing_credits_CPU.html
+ */
+const CREDIT_METRIC_PERIOD = aws_cdk_lib_1.Duration.minutes(5);
+const CREDIT_METRIC_PERIOD_LABEL = `${String(CREDIT_METRIC_PERIOD.toMinutes())} minute`;
+/**
+ * Instance type family prefixes that accrue CPU credits (burstable).
+ * Used to decide whether to emit the contextual {@link InstanceAlarmConfig.cpuCreditBalance}
+ * alarm. Other families bill at a flat CPU rate and have no credit metric.
+ *
+ * @see https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/burstable-performance-instances.html
+ */
+const BURSTABLE_FAMILY_PREFIXES = ["t2.", "t3.", "t3a.", "t4g."];
+function isBurstableInstanceType(instanceType) {
+    const identifier = instanceType.toString();
+    return BURSTABLE_FAMILY_PREFIXES.some((prefix) => identifier.startsWith(prefix));
+}
+function instanceMetric(instance, metricName, statistic, period = METRIC_PERIOD) {
+    return new aws_cloudwatch_1.Metric({
+        namespace: "AWS/EC2",
+        metricName,
+        dimensionsMap: { InstanceId: instance.instanceId },
+        statistic,
+        period,
+    });
+}
+/**
+ * Resolves the recommended alarm configuration into fully-resolved
+ * {@link AlarmDefinition}s, applying contextual logic for the
+ * burstable-only CPU credit alarm.
+ */
+function resolveInstanceAlarmDefinitions(instance, config, props) {
+    if (config?.enabled === false)
+        return [];
+    const definitions = [];
+    if (config?.cpuUtilization !== false) {
+        const cfg = (0, cloudwatch_1.resolveAlarmConfig)(config?.cpuUtilization, instance_alarm_defaults_js_1.INSTANCE_ALARM_DEFAULTS.cpuUtilization);
+        definitions.push({
+            key: "cpuUtilization",
+            alarmName: cfg.alarmName,
+            metric: instanceMetric(instance, "CPUUtilization", aws_cloudwatch_1.Stats.AVERAGE),
+            threshold: cfg.threshold,
+            comparisonOperator: aws_cloudwatch_1.ComparisonOperator.GREATER_THAN_THRESHOLD,
+            evaluationPeriods: cfg.evaluationPeriods,
+            datapointsToAlarm: cfg.datapointsToAlarm,
+            treatMissingData: cfg.treatMissingData,
+            description: `EC2 instance CPU utilization is sustained at a high level. Threshold: > ${String(cfg.threshold)}% average over ${String(cfg.evaluationPeriods)} x ${METRIC_PERIOD_LABEL}.`,
+        });
+    }
+    if (config?.statusCheckFailed !== false) {
+        const cfg = (0, cloudwatch_1.resolveAlarmConfig)(config?.statusCheckFailed, instance_alarm_defaults_js_1.INSTANCE_ALARM_DEFAULTS.statusCheckFailed);
+        definitions.push({
+            key: "statusCheckFailed",
+            alarmName: cfg.alarmName,
+            metric: instanceMetric(instance, "StatusCheckFailed", aws_cloudwatch_1.Stats.SUM),
+            threshold: cfg.threshold,
+            comparisonOperator: aws_cloudwatch_1.ComparisonOperator.GREATER_THAN_THRESHOLD,
+            evaluationPeriods: cfg.evaluationPeriods,
+            datapointsToAlarm: cfg.datapointsToAlarm,
+            treatMissingData: cfg.treatMissingData,
+            description: `EC2 instance is failing its status checks. Threshold: > ${String(cfg.threshold)} failed checks over ${String(cfg.evaluationPeriods)} x ${METRIC_PERIOD_LABEL}.`,
+        });
+    }
+    if (config?.attachedEbsStatusCheckFailed !== false) {
+        const cfg = (0, cloudwatch_1.resolveAlarmConfig)(config?.attachedEbsStatusCheckFailed, instance_alarm_defaults_js_1.INSTANCE_ALARM_DEFAULTS.attachedEbsStatusCheckFailed);
+        definitions.push({
+            key: "attachedEbsStatusCheckFailed",
+            alarmName: cfg.alarmName,
+            metric: instanceMetric(instance, "StatusCheckFailed_AttachedEBS", aws_cloudwatch_1.Stats.MAXIMUM),
+            threshold: cfg.threshold,
+            comparisonOperator: aws_cloudwatch_1.ComparisonOperator.GREATER_THAN_OR_EQUAL_TO_THRESHOLD,
+            evaluationPeriods: cfg.evaluationPeriods,
+            datapointsToAlarm: cfg.datapointsToAlarm,
+            treatMissingData: cfg.treatMissingData,
+            description: `EC2 instance attached EBS volume(s) are unreachable or unable to complete I/O. Threshold: >= ${String(cfg.threshold)} failed checks (max) over ${String(cfg.evaluationPeriods)} x ${METRIC_PERIOD_LABEL}.`,
+        });
+    }
+    if (config?.cpuCreditBalance !== false && isBurstableInstanceType(props.instanceType)) {
+        const cfg = (0, cloudwatch_1.resolveAlarmConfig)(config?.cpuCreditBalance, instance_alarm_defaults_js_1.INSTANCE_ALARM_DEFAULTS.cpuCreditBalance);
+        definitions.push({
+            key: "cpuCreditBalance",
+            alarmName: cfg.alarmName,
+            metric: instanceMetric(instance, "CPUCreditBalance", aws_cloudwatch_1.Stats.MINIMUM, CREDIT_METRIC_PERIOD),
+            threshold: cfg.threshold,
+            comparisonOperator: aws_cloudwatch_1.ComparisonOperator.LESS_THAN_THRESHOLD,
+            evaluationPeriods: cfg.evaluationPeriods,
+            datapointsToAlarm: cfg.datapointsToAlarm,
+            treatMissingData: cfg.treatMissingData,
+            description: `EC2 burstable instance CPU credit balance is low — baseline throttling is imminent. Threshold: < ${String(cfg.threshold)} credits (minimum) over ${String(cfg.evaluationPeriods)} x ${CREDIT_METRIC_PERIOD_LABEL}.`,
+        });
+    }
+    return definitions;
+}
+/**
+ * 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
+ */
+function createInstanceAlarms(scope, id, instance, config, props, customAlarms = []) {
+    if (config === false)
+        return {};
+    const enabled = config?.enabled ?? instance_alarm_defaults_js_1.INSTANCE_ALARM_DEFAULTS.enabled;
+    if (!enabled)
+        return {};
+    const recommended = resolveInstanceAlarmDefinitions(instance, config, props);
+    const custom = customAlarms.map((b) => b.resolve(instance));
+    return (0, cloudwatch_1.createAlarms)(scope, id, [...recommended, ...custom]);
+}
+//# sourceMappingURL=instance-alarms.js.map

package/dist/commonjs/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/{instance-builder.d.ts → commonjs/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/commonjs/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/commonjs/instance-builder.js

@@ -0,0 +1,135 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createInstanceBuilder = createInstanceBuilder;
+const aws_ec2_1 = require("aws-cdk-lib/aws-ec2");
+const core_1 = require("@composurecdk/core");
+const cloudformation_1 = require("@composurecdk/cloudformation");
+const cloudwatch_1 = require("@composurecdk/cloudwatch");
+const instance_alarms_js_1 = require("./instance-alarms.js");
+const instance_defaults_js_1 = require("./instance-defaults.js");
+const instance_volume_attachments_js_1 = require("./instance-volume-attachments.js");
+class InstanceBuilder {
+    props = {};
+    #customAlarms = [];
+    #volumeAttachments = [];
+    #vpc;
+    /**
+     * 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) {
+        this.#vpc = vpc;
+        return 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, configure) {
+        this.#customAlarms.push(configure(new cloudwatch_1.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. */
+    [core_1.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 ? (0, core_1.resolve)(this.#vpc, context) : undefined;
+        if (!resolvedVpc) {
+            throw new Error(`InstanceBuilder "${id}" requires a VPC. Call .vpc() with an IVpc or a Ref to one.`);
+        }
+        const { recommendedAlarms: alarmConfig, role, keyPair, securityGroup, ...instanceProps } = this.props;
+        const mergedProps = {
+            ...instance_defaults_js_1.INSTANCE_DEFAULTS,
+            ...instanceProps,
+            vpc: resolvedVpc,
+            ...(role !== undefined ? { role: (0, core_1.resolve)(role, context) } : {}),
+            ...(keyPair !== undefined ? { keyPair: (0, core_1.resolve)(keyPair, context) } : {}),
+            ...(securityGroup !== undefined ? { securityGroup: (0, core_1.resolve)(securityGroup, context) } : {}),
+        };
+        const instance = new aws_ec2_1.Instance(scope, id, mergedProps);
+        const instanceAlarms = (0, instance_alarms_js_1.createInstanceAlarms)(scope, id, instance, alarmConfig, mergedProps, this.#customAlarms);
+        const { attachments, alarms: attachmentAlarms } = (0, instance_volume_attachments_js_1.createVolumeAttachments)(scope, id, instance, mergedProps, this.#volumeAttachments, context);
+        return {
+            instance,
+            alarms: { ...instanceAlarms, ...attachmentAlarms },
+            volumeAttachments: attachments,
+        };
+    }
+}
+/**
+ * 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"] },
+ * );
+ * ```
+ */
+function createInstanceBuilder() {
+    return (0, cloudformation_1.taggedBuilder)(InstanceBuilder);
+}
+//# sourceMappingURL=instance-builder.js.map