@composurecdk/ec2 0.6.0 → 0.8.0

package/dist/esm/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/esm/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/esm/package.json

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

package/dist/esm/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/esm/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/esm/volume-alarm-config.js

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

package/dist/esm/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/esm/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/esm/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/esm/volume-alarm-defaults.js

@@ -0,0 +1,27 @@
+import { TreatMissingData } from "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
+ */
+export const 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: TreatMissingData.NOT_BREACHING,
+    },
+};
+//# sourceMappingURL=volume-alarm-defaults.js.map

package/dist/esm/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,OAAO,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAQ9D;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,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,gBAAgB,CAAC,aAAa;KACjD;CACF,CAAC"}

package/dist/esm/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/esm/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/esm/volume-alarms.js

@@ -0,0 +1,88 @@
+import { Duration } from "aws-cdk-lib";
+import { ComparisonOperator, Metric, Stats } from "aws-cdk-lib/aws-cloudwatch";
+import { EbsDeviceVolumeType } from "aws-cdk-lib/aws-ec2";
+import { createAlarms, resolveAlarmConfig } from "@composurecdk/cloudwatch";
+import { VOLUME_ALARM_DEFAULTS } from "./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 = 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([
+    EbsDeviceVolumeType.GP2,
+    EbsDeviceVolumeType.ST1,
+    EbsDeviceVolumeType.SC1,
+]);
+function isBurstableVolumeType(volumeType) {
+    return volumeType !== undefined && BURSTABLE_VOLUME_TYPES.has(volumeType);
+}
+function volumeMetric(volume, metricName, statistic, period) {
+    return new 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.
+ */
+export function resolveVolumeAlarmDefinitions(volume, config, volumeType) {
+    if (config?.enabled === false)
+        return [];
+    const definitions = [];
+    if (config?.burstBalance !== false && isBurstableVolumeType(volumeType)) {
+        const cfg = resolveAlarmConfig(config?.burstBalance, VOLUME_ALARM_DEFAULTS.burstBalance);
+        definitions.push({
+            key: "burstBalance",
+            alarmName: cfg.alarmName,
+            metric: volumeMetric(volume, "BurstBalance", Stats.AVERAGE, BURST_METRIC_PERIOD),
+            threshold: cfg.threshold,
+            comparisonOperator: 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
+ */
+export function createVolumeAlarms(scope, id, volume, config, volumeType, customAlarms = []) {
+    if (config === false)
+        return {};
+    const enabled = config?.enabled ?? VOLUME_ALARM_DEFAULTS.enabled;
+    if (!enabled)
+        return {};
+    const recommended = resolveVolumeAlarmDefinitions(volume, config, volumeType);
+    const custom = customAlarms.map((b) => b.resolve(volume));
+    return createAlarms(scope, id, [...recommended, ...custom]);
+}
+//# sourceMappingURL=volume-alarms.js.map

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

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

@@ -0,0 +1,171 @@
+import { type Alarm } from "aws-cdk-lib/aws-cloudwatch";
+import { Volume, type VolumeProps } from "aws-cdk-lib/aws-ec2";
+import { type IKey } from "aws-cdk-lib/aws-kms";
+import { type IConstruct } from "constructs";
+import { COPY_STATE, type Lifecycle, type Resolvable } from "@composurecdk/core";
+import { type ITaggedBuilder } from "@composurecdk/cloudformation";
+import { AlarmDefinitionBuilder } from "@composurecdk/cloudwatch";
+import type { VolumeAlarmConfig } from "./volume-alarm-config.js";
+/**
+ * Configuration properties for the EBS volume builder.
+ *
+ * Extends the CDK {@link VolumeProps} but lifts the cross-component-wiring
+ * props to {@link Resolvable} so they can be supplied as either concrete
+ * values or {@link Ref}s to sibling components in a {@link compose}d system:
+ *
+ * - `availabilityZone` is supplied via the dedicated
+ *   {@link IVolumeBuilder.availabilityZone | .availabilityZone()} method
+ *   so it can be wired from a sibling `VpcBuilder`.
+ * - `encryptionKey` is exposed on the builder as a `Resolvable<IKey>`
+ *   setter so a sibling KMS key builder can supply a CMK.
+ *
+ * Other props (`size`, `volumeType`, `iops`, `throughput`, `enableMultiAttach`,
+ * `autoEnableIo`, `removalPolicy`, etc.) are passed through with their CDK
+ * types unchanged because they are almost always constructed inline rather
+ * than referenced from another component.
+ */
+export interface VolumeBuilderProps extends Omit<VolumeProps, "availabilityZone" | "encryptionKey"> {
+    /**
+     * Customer-managed KMS key (CMK) used to encrypt the volume.
+     *
+     * Accepts a concrete {@link IKey} or a {@link Ref} that resolves to one
+     * at build time (e.g. a sibling key builder in the same composed system).
+     *
+     * @default - the account's default EBS KMS key, applied because
+     *   `encrypted: true` is set in {@link VOLUME_DEFAULTS}.
+     *
+     * @see https://docs.aws.amazon.com/wellarchitected/latest/security-pillar/sec_protect_data_rest_encrypt.html
+     */
+    encryptionKey?: Resolvable<IKey>;
+    /**
+     * Configuration for AWS-recommended CloudWatch alarms.
+     *
+     * By default, the builder creates recommended alarms with sensible
+     * thresholds for every applicable metric. Individual alarms can be
+     * customized or disabled. Set to `false` to disable all alarms.
+     *
+     * No alarm actions are configured by default since notification methods
+     * are user-specific. Access alarms from the build result or use an
+     * `afterBuild` hook to apply actions.
+     *
+     * Contextual alarms (`burstBalance`) are only created when the
+     * corresponding volume configuration is present — e.g., a burstable
+     * `gp2`/`st1`/`sc1` volume type.
+     *
+     * @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#EBS
+     */
+    recommendedAlarms?: VolumeAlarmConfig | false;
+}
+/**
+ * The build output of a {@link IVolumeBuilder}. Contains the CDK constructs
+ * created during {@link Lifecycle.build}, keyed by role.
+ */
+export interface VolumeBuilderResult {
+    volume: Volume;
+    /**
+     * CloudWatch alarms created for the volume, keyed by alarm name.
+     *
+     * Includes both AWS-recommended alarms and any custom alarms added
+     * via {@link IVolumeBuilder.addAlarm}. Access individual alarms by
+     * key (e.g., `result.alarms.burstBalance`).
+     *
+     * No alarm actions are configured — apply them via the result or an
+     * `afterBuild` hook.
+     *
+     * @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#EBS
+     */
+    alarms: Record<string, Alarm>;
+}
+/**
+ * A fluent builder for configuring and creating an AWS EBS volume.
+ *
+ * Each configuration property from the CDK {@link VolumeProps} is exposed
+ * as an overloaded method: call with a value to set it (returns the builder
+ * for chaining), or call with no arguments to read the current value.
+ *
+ * The `availabilityZone` is set via the dedicated
+ * {@link IVolumeBuilder.availabilityZone | .availabilityZone()} method that
+ * accepts a {@link Resolvable} value for cross-component wiring (e.g., to
+ * a sibling {@link IVpcBuilder}). The `encryptionKey` setter likewise
+ * accepts a {@link Resolvable} value so a sibling KMS-key builder's output
+ * can be supplied via {@link ref}.
+ *
+ * The builder implements {@link Lifecycle}, so it can be used directly as a
+ * component in a {@link compose | composed system}. When built, it creates
+ * an EBS volume with the configured properties and returns a
+ * {@link VolumeBuilderResult}.
+ *
+ * AWS-recommended CloudWatch alarms are created by default. Alarms can be
+ * customized or disabled via the `recommendedAlarms` property. Custom
+ * alarms can be added via the {@link addAlarm} method.
+ *
+ * @see https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_ec2.Volume.html
+ *
+ * @example
+ * ```ts
+ * const data = createVolumeBuilder()
+ *   .availabilityZone(ref<VpcBuilderResult>("network").map(r => r.vpc.availabilityZones[0]))
+ *   .size(Size.gibibytes(50));
+ * ```
+ */
+export type IVolumeBuilder = ITaggedBuilder<VolumeBuilderProps, VolumeBuilder>;
+declare class VolumeBuilder implements Lifecycle<VolumeBuilderResult> {
+    #private;
+    props: Partial<VolumeBuilderProps>;
+    /**
+     * Sets the Availability Zone the volume will be created in.
+     *
+     * Accepts a concrete AZ string 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} via
+     * `ref<VpcBuilderResult>("network").map(r => r.vpc.availabilityZones[0])`.
+     *
+     * @param availabilityZone - The AZ string or a Ref to one.
+     * @returns This builder for chaining.
+     */
+    availabilityZone(availabilityZone: Resolvable<string>): 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 Volume}; configure it fluently and return it.
+     *
+     * @param key - A unique key for the alarm (used to generate the alarm id).
+     * @param configure - Callback that configures the alarm definition.
+     * @returns This builder for chaining.
+     */
+    addAlarm(key: string, configure: (alarm: AlarmDefinitionBuilder<Volume>) => AlarmDefinitionBuilder<Volume>): this;
+    /** @internal — see ADR-0005. */
+    [COPY_STATE](target: VolumeBuilder): void;
+    build(scope: IConstruct, id: string, context?: Record<string, object>): VolumeBuilderResult;
+}
+/**
+ * Creates a new {@link IVolumeBuilder} for configuring an AWS EBS volume.
+ *
+ * This is the entry point for defining an EBS volume component. The
+ * returned builder exposes every {@link VolumeBuilderProps} property as a
+ * fluent setter/getter, plus
+ * {@link IVolumeBuilder.availabilityZone | .availabilityZone()} for
+ * cross-component AZ wiring with Ref support. It implements
+ * {@link Lifecycle} for use with {@link compose}.
+ *
+ * @returns A fluent builder for an AWS EBS volume.
+ *
+ * @example
+ * ```ts
+ * const data = createVolumeBuilder()
+ *   .availabilityZone(ref<VpcBuilderResult>("network").map(r => r.vpc.availabilityZones[0]))
+ *   .size(Size.gibibytes(50));
+ *
+ * // Use standalone:
+ * const result = data.build(stack, "Data", { network });
+ *
+ * // Or compose into a system:
+ * const system = compose(
+ *   { network: createVpcBuilder(), data },
+ *   { network: [], data: ["network"] },
+ * );
+ * ```
+ */
+export declare function createVolumeBuilder(): IVolumeBuilder;
+export {};
+//# sourceMappingURL=volume-builder.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"volume-builder.d.ts","sourceRoot":"","sources":["../../src/volume-builder.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,KAAK,EAAE,MAAM,4BAA4B,CAAC;AACxD,OAAO,EAAE,MAAM,EAAE,KAAK,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAC/D,OAAO,EAAE,KAAK,IAAI,EAAE,MAAM,qBAAqB,CAAC;AAChD,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,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAIlE;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,kBAAmB,SAAQ,IAAI,CAC9C,WAAW,EACX,kBAAkB,GAAG,eAAe,CACrC;IACC;;;;;;;;;;OAUG;IACH,aAAa,CAAC,EAAE,UAAU,CAAC,IAAI,CAAC,CAAC;IAEjC;;;;;;;;;;;;;;;;OAgBG;IACH,iBAAiB,CAAC,EAAE,iBAAiB,GAAG,KAAK,CAAC;CAC/C;AAED;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,CAAC;IAEf;;;;;;;;;;;OAWG;IACH,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;CAC/B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,MAAM,cAAc,GAAG,cAAc,CAAC,kBAAkB,EAAE,aAAa,CAAC,CAAC;AAE/E,cAAM,aAAc,YAAW,SAAS,CAAC,mBAAmB,CAAC;;IAC3D,KAAK,EAAE,OAAO,CAAC,kBAAkB,CAAC,CAAM;IAIxC;;;;;;;;;;OAUG;IACH,gBAAgB,CAAC,gBAAgB,EAAE,UAAU,CAAC,MAAM,CAAC,GAAG,IAAI;IAK5D;;;;;;;;OAQG;IACH,QAAQ,CACN,GAAG,EAAE,MAAM,EACX,SAAS,EAAE,CAAC,KAAK,EAAE,sBAAsB,CAAC,MAAM,CAAC,KAAK,sBAAsB,CAAC,MAAM,CAAC,GACnF,IAAI;IAKP,gCAAgC;IAChC,CAAC,UAAU,CAAC,CAAC,MAAM,EAAE,aAAa,GAAG,IAAI;IAKzC,KAAK,CAAC,KAAK,EAAE,UAAU,EAAE,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,mBAAmB;CAkC5F;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,mBAAmB,IAAI,cAAc,CAEpD"}

package/dist/esm/volume-builder.js

@@ -0,0 +1,95 @@
+import { Volume } from "aws-cdk-lib/aws-ec2";
+import { COPY_STATE, resolve } from "@composurecdk/core";
+import { taggedBuilder } from "@composurecdk/cloudformation";
+import { AlarmDefinitionBuilder } from "@composurecdk/cloudwatch";
+import { createVolumeAlarms } from "./volume-alarms.js";
+import { VOLUME_DEFAULTS } from "./volume-defaults.js";
+class VolumeBuilder {
+    props = {};
+    #customAlarms = [];
+    #availabilityZone;
+    /**
+     * Sets the Availability Zone the volume will be created in.
+     *
+     * Accepts a concrete AZ string 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} via
+     * `ref<VpcBuilderResult>("network").map(r => r.vpc.availabilityZones[0])`.
+     *
+     * @param availabilityZone - The AZ string or a Ref to one.
+     * @returns This builder for chaining.
+     */
+    availabilityZone(availabilityZone) {
+        this.#availabilityZone = availabilityZone;
+        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 Volume}; 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 AlarmDefinitionBuilder(key)));
+        return this;
+    }
+    /** @internal — see ADR-0005. */
+    [COPY_STATE](target) {
+        target.#availabilityZone = this.#availabilityZone;
+        target.#customAlarms.push(...this.#customAlarms);
+    }
+    build(scope, id, context) {
+        const resolvedAz = this.#availabilityZone
+            ? resolve(this.#availabilityZone, context)
+            : undefined;
+        if (resolvedAz === undefined) {
+            throw new Error(`VolumeBuilder "${id}" requires an availability zone. ` +
+                `Call .availabilityZone() with a string or a Ref to one.`);
+        }
+        const { recommendedAlarms: alarmConfig, encryptionKey, ...volumeProps } = this.props;
+        const mergedProps = {
+            ...VOLUME_DEFAULTS,
+            ...volumeProps,
+            availabilityZone: resolvedAz,
+            ...(encryptionKey !== undefined ? { encryptionKey: resolve(encryptionKey, context) } : {}),
+        };
+        const volume = new Volume(scope, id, mergedProps);
+        const alarms = createVolumeAlarms(scope, id, volume, alarmConfig, mergedProps.volumeType, this.#customAlarms);
+        return { volume, alarms };
+    }
+}
+/**
+ * Creates a new {@link IVolumeBuilder} for configuring an AWS EBS volume.
+ *
+ * This is the entry point for defining an EBS volume component. The
+ * returned builder exposes every {@link VolumeBuilderProps} property as a
+ * fluent setter/getter, plus
+ * {@link IVolumeBuilder.availabilityZone | .availabilityZone()} for
+ * cross-component AZ wiring with Ref support. It implements
+ * {@link Lifecycle} for use with {@link compose}.
+ *
+ * @returns A fluent builder for an AWS EBS volume.
+ *
+ * @example
+ * ```ts
+ * const data = createVolumeBuilder()
+ *   .availabilityZone(ref<VpcBuilderResult>("network").map(r => r.vpc.availabilityZones[0]))
+ *   .size(Size.gibibytes(50));
+ *
+ * // Use standalone:
+ * const result = data.build(stack, "Data", { network });
+ *
+ * // Or compose into a system:
+ * const system = compose(
+ *   { network: createVpcBuilder(), data },
+ *   { network: [], data: ["network"] },
+ * );
+ * ```
+ */
+export function createVolumeBuilder() {
+    return taggedBuilder(VolumeBuilder);
+}
+//# sourceMappingURL=volume-builder.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"volume-builder.js","sourceRoot":"","sources":["../../src/volume-builder.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAoB,MAAM,qBAAqB,CAAC;AAG/D,OAAO,EAAE,UAAU,EAAkB,OAAO,EAAmB,MAAM,oBAAoB,CAAC;AAC1F,OAAO,EAAuB,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAClF,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAElE,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAiHvD,MAAM,aAAa;IACjB,KAAK,GAAgC,EAAE,CAAC;IAC/B,aAAa,GAAqC,EAAE,CAAC;IAC9D,iBAAiB,CAAsB;IAEvC;;;;;;;;;;OAUG;IACH,gBAAgB,CAAC,gBAAoC;QACnD,IAAI,CAAC,iBAAiB,GAAG,gBAAgB,CAAC;QAC1C,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;;;;;OAQG;IACH,QAAQ,CACN,GAAW,EACX,SAAoF;QAEpF,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,sBAAsB,CAAS,GAAG,CAAC,CAAC,CAAC,CAAC;QAC5E,OAAO,IAAI,CAAC;IACd,CAAC;IAED,gCAAgC;IAChC,CAAC,UAAU,CAAC,CAAC,MAAqB;QAChC,MAAM,CAAC,iBAAiB,GAAG,IAAI,CAAC,iBAAiB,CAAC;QAClD,MAAM,CAAC,aAAa,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,aAAa,CAAC,CAAC;IACnD,CAAC;IAED,KAAK,CAAC,KAAiB,EAAE,EAAU,EAAE,OAAgC;QACnE,MAAM,UAAU,GAAG,IAAI,CAAC,iBAAiB;YACvC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,iBAAiB,EAAE,OAAO,CAAC;YAC1C,CAAC,CAAC,SAAS,CAAC;QAEd,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;YAC7B,MAAM,IAAI,KAAK,CACb,kBAAkB,EAAE,mCAAmC;gBACrD,yDAAyD,CAC5D,CAAC;QACJ,CAAC;QAED,MAAM,EAAE,iBAAiB,EAAE,WAAW,EAAE,aAAa,EAAE,GAAG,WAAW,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC;QAErF,MAAM,WAAW,GAAG;YAClB,GAAG,eAAe;YAClB,GAAG,WAAW;YACd,gBAAgB,EAAE,UAAU;YAC5B,GAAG,CAAC,aAAa,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,OAAO,CAAC,aAAa,EAAE,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC5E,CAAC;QAEjB,MAAM,MAAM,GAAG,IAAI,MAAM,CAAC,KAAK,EAAE,EAAE,EAAE,WAAW,CAAC,CAAC;QAElD,MAAM,MAAM,GAAG,kBAAkB,CAC/B,KAAK,EACL,EAAE,EACF,MAAM,EACN,WAAW,EACX,WAAW,CAAC,UAAU,EACtB,IAAI,CAAC,aAAa,CACnB,CAAC;QAEF,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;IAC5B,CAAC;CACF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,UAAU,mBAAmB;IACjC,OAAO,aAAa,CAAoC,aAAa,CAAC,CAAC;AACzE,CAAC"}

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

@@ -0,0 +1,15 @@
+import { type VolumeProps } from "aws-cdk-lib/aws-ec2";
+/**
+ * Secure, AWS-recommended defaults applied to every EBS volume built with
+ * {@link createVolumeBuilder}. Each property can be individually overridden
+ * via the builder's fluent API.
+ *
+ * Three properties intentionally have no default — they are application-
+ * specific and must be supplied explicitly:
+ *   - `availabilityZone` (via the builder's `.availabilityZone()` method)
+ *   - `size`
+ *   - `iops` / `throughput` (only when opting into a volume type that
+ *     requires them, e.g. `io1`/`io2`)
+ */
+export declare const VOLUME_DEFAULTS: Partial<VolumeProps>;
+//# sourceMappingURL=volume-defaults.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"volume-defaults.d.ts","sourceRoot":"","sources":["../../src/volume-defaults.ts"],"names":[],"mappings":"AACA,OAAO,EAAuB,KAAK,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAE5E;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,eAAe,EAAE,OAAO,CAAC,WAAW,CAkChD,CAAC"}