@composurecdk/ec2 0.6.0 → 0.8.0

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

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.INSTANCE_DEFAULTS = void 0;
+const aws_ec2_1 = require("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`
+ */
+exports.INSTANCE_DEFAULTS = {
+    /**
+     * Require IMDSv2. IMDSv1 is vulnerable to SSRF-based credential exfiltration;
+     * IMDSv2 requires a session token and blocks the common attack pattern.
+     * @see https://docs.aws.amazon.com/wellarchitected/latest/security-pillar/sec_detect_investigate_events_app_service_logging.html
+     * @see https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/configuring-instance-metadata-service.html
+     */
+    requireImdsv2: true,
+    /**
+     * Enable detailed (1-minute) CloudWatch metrics. Without this, instance
+     * metrics are emitted at 5-minute granularity, which makes short-window
+     * alarm evaluation unreliable.
+     * @see https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-cloudwatch-new.html
+     */
+    detailedMonitoring: true,
+    /**
+     * Attach the AmazonSSMManagedInstanceCore managed policy so Session Manager
+     * can be used in place of SSH. Removes the need for key pairs, bastion
+     * hosts, or inbound SSH access.
+     * @see https://docs.aws.amazon.com/systems-manager/latest/userguide/session-manager.html
+     */
+    ssmSessionPermissions: true,
+    /**
+     * EBS-optimized networking — dedicated bandwidth between the instance and
+     * its EBS volumes. Free and on-by-default for current-generation instance
+     * types; set explicitly for consistency.
+     * @see https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ebs-optimized.html
+     */
+    ebsOptimized: true,
+    /**
+     * Encrypt the root EBS volume at rest using the account's default EBS KMS
+     * key. GP3 is the current-generation general-purpose volume type — cheaper
+     * and faster than GP2 at equivalent sizes. Users override this to change
+     * volume size, IOPS, throughput, or to add additional block devices.
+     * @see https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EBSEncryption.html
+     */
+    blockDevices: [
+        {
+            deviceName: "/dev/xvda",
+            volume: aws_ec2_1.BlockDeviceVolume.ebs(8, {
+                encrypted: true,
+                volumeType: aws_ec2_1.EbsDeviceVolumeType.GP3,
+            }),
+        },
+    ],
+};
+//# sourceMappingURL=instance-defaults.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"instance-defaults.js","sourceRoot":"","sources":["../../src/instance-defaults.ts"],"names":[],"mappings":";;;AAAA,iDAAiG;AAEjG;;;;;;;;;;GAUG;AACU,QAAA,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,2BAAiB,CAAC,GAAG,CAAC,CAAC,EAAE;gBAC/B,SAAS,EAAE,IAAI;gBACf,UAAU,EAAE,6BAAmB,CAAC,GAAG;aACpC,CAAC;SACH;KACF;CACF,CAAC"}

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

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

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

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VOLUME_ATTACHMENT_ALARM_DEFAULTS = void 0;
+const aws_cloudwatch_1 = require("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
+ */
+exports.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: aws_cloudwatch_1.TreatMissingData.NOT_BREACHING,
+    },
+};
+//# sourceMappingURL=instance-volume-attachment-defaults.js.map

package/dist/commonjs/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,+DAA8D;AAQ9D;;;;;GAKG;AACU,QAAA,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,iCAAgB,CAAC,aAAa;KACjD;CACF,CAAC"}

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

@@ -0,0 +1,107 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createVolumeAttachments = createVolumeAttachments;
+const aws_cdk_lib_1 = require("aws-cdk-lib");
+const aws_cloudwatch_1 = require("aws-cdk-lib/aws-cloudwatch");
+const aws_ec2_1 = require("aws-cdk-lib/aws-ec2");
+const core_1 = require("@composurecdk/core");
+const cloudwatch_1 = require("@composurecdk/cloudwatch");
+const instance_volume_attachment_defaults_js_1 = require("./instance-volume-attachment-defaults.js");
+const STALLED_IO_PERIOD = aws_cdk_lib_1.Duration.minutes(1);
+const STALLED_IO_PERIOD_LABEL = `${String(STALLED_IO_PERIOD.toMinutes())} minute`;
+function resolveInstanceAz(instanceProps) {
+    if (instanceProps.availabilityZone && !aws_cdk_lib_1.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) => !aws_cdk_lib_1.Token.isUnresolved(az));
+}
+function unwrapVolume(resolved) {
+    if ("volumeId" in resolved) {
+        return resolved;
+    }
+    return resolved.volume;
+}
+function volumeAttachmentMetric(volume, instance, metricName, statistic, period) {
+    return new aws_cloudwatch_1.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 ?? instance_volume_attachment_defaults_js_1.VOLUME_ATTACHMENT_ALARM_DEFAULTS.enabled;
+    if (!enabled)
+        return [];
+    if (config?.volumeStalledIo === false)
+        return [];
+    const cfg = (0, cloudwatch_1.resolveAlarmConfig)(config?.volumeStalledIo, instance_volume_attachment_defaults_js_1.VOLUME_ATTACHMENT_ALARM_DEFAULTS.volumeStalledIo);
+    return [
+        {
+            key: `${attachmentKey}.volumeStalledIo`,
+            alarmName: cfg.alarmName,
+            metric: volumeAttachmentMetric(volume, instance, "VolumeStalledIOCheck", aws_cloudwatch_1.Stats.MAXIMUM, STALLED_IO_PERIOD),
+            threshold: cfg.threshold,
+            comparisonOperator: aws_cloudwatch_1.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.
+ */
+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 = (0, core_1.resolve)(pending.volumeRef, context);
+        const volume = unwrapVolume(resolved);
+        if (instanceAz !== undefined && !aws_cdk_lib_1.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 aws_ec2_1.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 ? (0, cloudwatch_1.createAlarms)(scope, id, alarmDefinitions) : {};
+    return { attachments: attachmentRecords, alarms };
+}
+//# sourceMappingURL=instance-volume-attachments.js.map

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

package/dist/commonjs/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}

package/dist/commonjs/volume-alarm-config.d.ts

@@ -0,0 +1,35 @@
+import type { AlarmConfig } from "@composurecdk/cloudwatch";
+/**
+ * Controls which recommended alarms are created for an EBS volume.
+ * All applicable alarms are enabled by default with AWS-recommended
+ * thresholds. Set 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 VolumeAlarmConfig {
+    /**
+     * Master switch: set to `false` to disable all recommended alarms.
+     * Individual alarms can also be disabled via their own entry.
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * Alarm when a burstable volume's I/O credit balance falls low,
+     * indicating the volume is about to be throttled to baseline IOPS or
+     * throughput.
+     *
+     * Only created when the configured `volumeType` is one of the burstable
+     * types: `gp2` (IOPS credits), `st1` and `sc1` (throughput credits).
+     * For non-burstable types (`gp3`, `io1`, `io2`, `standard`) the metric
+     * is not emitted, so the alarm is skipped entirely.
+     *
+     * Metric: `AWS/EBS BurstBalance`, statistic Average, period 5 minutes.
+     * Default threshold: < 20% over 3 consecutive 5-minute windows.
+     *
+     * @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#EBS
+     * @see https://docs.aws.amazon.com/ebs/latest/userguide/general-purpose.html#gp2-volume-performance
+     */
+    burstBalance?: AlarmConfig | false;
+}
+//# sourceMappingURL=volume-alarm-config.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"volume-alarm-config.d.ts","sourceRoot":"","sources":["../../src/volume-alarm-config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAE5D;;;;;;;GAOG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB;;;;;;;;;;;;;;;OAeG;IACH,YAAY,CAAC,EAAE,WAAW,GAAG,KAAK,CAAC;CACpC"}

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

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

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

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

package/dist/commonjs/volume-alarm-defaults.d.ts

@@ -0,0 +1,17 @@
+import type { AlarmConfigDefaults } from "@composurecdk/cloudwatch";
+interface VolumeAlarmDefaults {
+    enabled: true;
+    burstBalance: AlarmConfigDefaults;
+}
+/**
+ * AWS-recommended default alarm configuration for EBS volumes.
+ *
+ * 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#EBS
+ */
+export declare const VOLUME_ALARM_DEFAULTS: VolumeAlarmDefaults;
+export {};
+//# sourceMappingURL=volume-alarm-defaults.d.ts.map

package/dist/commonjs/volume-alarm-defaults.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"volume-alarm-defaults.d.ts","sourceRoot":"","sources":["../../src/volume-alarm-defaults.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAEpE,UAAU,mBAAmB;IAC3B,OAAO,EAAE,IAAI,CAAC;IACd,YAAY,EAAE,mBAAmB,CAAC;CACnC;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,qBAAqB,EAAE,mBAgBnC,CAAC"}

package/dist/commonjs/volume-alarm-defaults.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VOLUME_ALARM_DEFAULTS = void 0;
+const aws_cloudwatch_1 = require("aws-cdk-lib/aws-cloudwatch");
+/**
+ * AWS-recommended default alarm configuration for EBS volumes.
+ *
+ * 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#EBS
+ */
+exports.VOLUME_ALARM_DEFAULTS = {
+    enabled: true,
+    /**
+     * Burst credit balance is a percentage. Below 20% the volume is
+     * approaching throttling to baseline performance — early warning to
+     * upsize, switch to a non-burstable type (e.g. `gp3`), or investigate
+     * unexpectedly heavy I/O. The 3-of-3 evaluation at 5-minute granularity
+     * suppresses transient dips around backup windows.
+     */
+    burstBalance: {
+        threshold: 20,
+        evaluationPeriods: 3,
+        datapointsToAlarm: 3,
+        treatMissingData: aws_cloudwatch_1.TreatMissingData.NOT_BREACHING,
+    },
+};
+//# sourceMappingURL=volume-alarm-defaults.js.map

package/dist/commonjs/volume-alarm-defaults.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"volume-alarm-defaults.js","sourceRoot":"","sources":["../../src/volume-alarm-defaults.ts"],"names":[],"mappings":";;;AAAA,+DAA8D;AAQ9D;;;;;;;;GAQG;AACU,QAAA,qBAAqB,GAAwB;IACxD,OAAO,EAAE,IAAI;IAEb;;;;;;OAMG;IACH,YAAY,EAAE;QACZ,SAAS,EAAE,EAAE;QACb,iBAAiB,EAAE,CAAC;QACpB,iBAAiB,EAAE,CAAC;QACpB,gBAAgB,EAAE,iCAAgB,CAAC,aAAa;KACjD;CACF,CAAC"}

package/dist/commonjs/volume-alarms.d.ts

@@ -0,0 +1,29 @@
+import { type Alarm } from "aws-cdk-lib/aws-cloudwatch";
+import { EbsDeviceVolumeType, type Volume } from "aws-cdk-lib/aws-ec2";
+import type { IConstruct } from "constructs";
+import type { AlarmDefinition } from "@composurecdk/cloudwatch";
+import { AlarmDefinitionBuilder } from "@composurecdk/cloudwatch";
+import type { VolumeAlarmConfig } from "./volume-alarm-config.js";
+/**
+ * Resolves the recommended alarm configuration into fully-resolved
+ * {@link AlarmDefinition}s, applying contextual logic for the
+ * burstable-only credit alarm.
+ */
+export declare function resolveVolumeAlarmDefinitions(volume: Volume, config: VolumeAlarmConfig | undefined, volumeType: EbsDeviceVolumeType | undefined): AlarmDefinition[];
+/**
+ * Creates AWS-recommended CloudWatch alarms for an EBS volume,
+ * 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 volume - The EBS volume to create alarms for.
+ * @param config - User-provided alarm configuration, or `false` to disable all.
+ * @param volumeType - Resolved volume type, used to gate the contextual
+ *   burst-balance alarm.
+ * @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#EBS
+ */
+export declare function createVolumeAlarms(scope: IConstruct, id: string, volume: Volume, config: VolumeAlarmConfig | false | undefined, volumeType: EbsDeviceVolumeType | undefined, customAlarms?: AlarmDefinitionBuilder<Volume>[]): Record<string, Alarm>;
+//# sourceMappingURL=volume-alarms.d.ts.map

package/dist/commonjs/volume-alarms.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"volume-alarms.d.ts","sourceRoot":"","sources":["../../src/volume-alarms.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,KAAK,EAAqC,MAAM,4BAA4B,CAAC;AAC3F,OAAO,EAAE,mBAAmB,EAAgB,KAAK,MAAM,EAAE,MAAM,qBAAqB,CAAC;AACrF,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,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AA4ClE;;;;GAIG;AACH,wBAAgB,6BAA6B,CAC3C,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,iBAAiB,GAAG,SAAS,EACrC,UAAU,EAAE,mBAAmB,GAAG,SAAS,GAC1C,eAAe,EAAE,CAqBnB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,UAAU,EACjB,EAAE,EAAE,MAAM,EACV,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,iBAAiB,GAAG,KAAK,GAAG,SAAS,EAC7C,UAAU,EAAE,mBAAmB,GAAG,SAAS,EAC3C,YAAY,GAAE,sBAAsB,CAAC,MAAM,CAAC,EAAO,GAClD,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAUvB"}

package/dist/commonjs/volume-alarms.js

@@ -0,0 +1,92 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveVolumeAlarmDefinitions = resolveVolumeAlarmDefinitions;
+exports.createVolumeAlarms = createVolumeAlarms;
+const aws_cdk_lib_1 = require("aws-cdk-lib");
+const aws_cloudwatch_1 = require("aws-cdk-lib/aws-cloudwatch");
+const aws_ec2_1 = require("aws-cdk-lib/aws-ec2");
+const cloudwatch_1 = require("@composurecdk/cloudwatch");
+const volume_alarm_defaults_js_1 = require("./volume-alarm-defaults.js");
+/**
+ * BurstBalance is published at 5-minute granularity for burstable volume
+ * types. A shorter period yields missing data rather than higher resolution.
+ *
+ * @see https://docs.aws.amazon.com/ebs/latest/userguide/using_cloudwatch_ebs.html
+ */
+const BURST_METRIC_PERIOD = aws_cdk_lib_1.Duration.minutes(5);
+const BURST_METRIC_PERIOD_LABEL = `${String(BURST_METRIC_PERIOD.toMinutes())} minute`;
+/**
+ * EBS volume types that publish a `BurstBalance` metric. `gp2` accrues IOPS
+ * credits; `st1` and `sc1` accrue throughput credits. Other types
+ * (`gp3`, `io1`, `io2`, `standard`) have no burst credit model.
+ *
+ * @see https://docs.aws.amazon.com/ebs/latest/userguide/using_cloudwatch_ebs.html
+ */
+const BURSTABLE_VOLUME_TYPES = new Set([
+    aws_ec2_1.EbsDeviceVolumeType.GP2,
+    aws_ec2_1.EbsDeviceVolumeType.ST1,
+    aws_ec2_1.EbsDeviceVolumeType.SC1,
+]);
+function isBurstableVolumeType(volumeType) {
+    return volumeType !== undefined && BURSTABLE_VOLUME_TYPES.has(volumeType);
+}
+function volumeMetric(volume, metricName, statistic, period) {
+    return new aws_cloudwatch_1.Metric({
+        namespace: "AWS/EBS",
+        metricName,
+        dimensionsMap: { VolumeId: volume.volumeId },
+        statistic,
+        period,
+    });
+}
+/**
+ * Resolves the recommended alarm configuration into fully-resolved
+ * {@link AlarmDefinition}s, applying contextual logic for the
+ * burstable-only credit alarm.
+ */
+function resolveVolumeAlarmDefinitions(volume, config, volumeType) {
+    if (config?.enabled === false)
+        return [];
+    const definitions = [];
+    if (config?.burstBalance !== false && isBurstableVolumeType(volumeType)) {
+        const cfg = (0, cloudwatch_1.resolveAlarmConfig)(config?.burstBalance, volume_alarm_defaults_js_1.VOLUME_ALARM_DEFAULTS.burstBalance);
+        definitions.push({
+            key: "burstBalance",
+            alarmName: cfg.alarmName,
+            metric: volumeMetric(volume, "BurstBalance", aws_cloudwatch_1.Stats.AVERAGE, BURST_METRIC_PERIOD),
+            threshold: cfg.threshold,
+            comparisonOperator: aws_cloudwatch_1.ComparisonOperator.LESS_THAN_THRESHOLD,
+            evaluationPeriods: cfg.evaluationPeriods,
+            datapointsToAlarm: cfg.datapointsToAlarm,
+            treatMissingData: cfg.treatMissingData,
+            description: `EBS burstable volume burst credit balance is low — baseline-IOPS throttling is imminent. Threshold: < ${String(cfg.threshold)}% (average) over ${String(cfg.evaluationPeriods)} x ${BURST_METRIC_PERIOD_LABEL}.`,
+        });
+    }
+    return definitions;
+}
+/**
+ * Creates AWS-recommended CloudWatch alarms for an EBS volume,
+ * 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 volume - The EBS volume to create alarms for.
+ * @param config - User-provided alarm configuration, or `false` to disable all.
+ * @param volumeType - Resolved volume type, used to gate the contextual
+ *   burst-balance alarm.
+ * @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#EBS
+ */
+function createVolumeAlarms(scope, id, volume, config, volumeType, customAlarms = []) {
+    if (config === false)
+        return {};
+    const enabled = config?.enabled ?? volume_alarm_defaults_js_1.VOLUME_ALARM_DEFAULTS.enabled;
+    if (!enabled)
+        return {};
+    const recommended = resolveVolumeAlarmDefinitions(volume, config, volumeType);
+    const custom = customAlarms.map((b) => b.resolve(volume));
+    return (0, cloudwatch_1.createAlarms)(scope, id, [...recommended, ...custom]);
+}
+//# sourceMappingURL=volume-alarms.js.map

package/dist/commonjs/volume-alarms.js.map

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