@composurecdk/ec2 0.5.0

package/README.md

@@ -0,0 +1,201 @@
+# @composurecdk/ec2
+
+EC2 and VPC builders for [ComposureCDK](../../README.md).
+
+This package provides fluent builders for AWS EC2 instances and VPCs with secure, AWS-recommended defaults. It wraps the CDK [Instance](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_ec2.Instance.html) and [Vpc](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_ec2.Vpc.html) constructs — refer to the CDK documentation for the full set of configurable properties.
+
+## Instance Builder
+
+```ts
+import { createInstanceBuilder } from "@composurecdk/ec2";
+import { InstanceClass, InstanceSize, InstanceType, MachineImage } from "aws-cdk-lib/aws-ec2";
+
+const server = createInstanceBuilder()
+  .vpc(vpc)
+  .instanceType(InstanceType.of(InstanceClass.T3, InstanceSize.MICRO))
+  .machineImage(MachineImage.latestAmazonLinux2023())
+  .build(stack, "MyInstance");
+```
+
+Every [InstanceProps](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_ec2.InstanceProps.html) property is available as a fluent setter on the builder, except `vpc` which is set via the dedicated `.vpc()` method to support cross-component wiring with `ref<T>(...)`.
+
+## Secure Defaults
+
+`createInstanceBuilder` applies the following defaults. Each can be overridden via the builder's fluent API.
+
+| Property                | Default                                         | Rationale                                                                                                 |
+| ----------------------- | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
+| `requireImdsv2`         | `true`                                          | IMDSv2 requires a session token, blocking the SSRF-based credential exfiltration common to IMDSv1.        |
+| `detailedMonitoring`    | `true`                                          | 1-minute CloudWatch metric granularity is required for short-window alarm evaluation.                     |
+| `ssmSessionPermissions` | `true`                                          | Attaches `AmazonSSMManagedInstanceCore` — Session Manager replaces SSH entirely (no key pairs, bastions). |
+| `ebsOptimized`          | `true`                                          | Dedicated EBS bandwidth. Free on current-generation instance types.                                       |
+| `blockDevices`          | 8 GiB GP3 root volume at `/dev/xvda`, encrypted | Encrypted at rest with the account's default EBS KMS key.                                                 |
+
+Three properties intentionally have no default — they are application-specific and must be supplied explicitly:
+
+- `vpc` (via the `.vpc()` method)
+- `instanceType`
+- `machineImage`
+
+The defaults are exported as `INSTANCE_DEFAULTS` for visibility and testing:
+
+```ts
+import { INSTANCE_DEFAULTS } from "@composurecdk/ec2";
+```
+
+## Recommended Alarms
+
+The builder creates [AWS-recommended CloudWatch alarms](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#EC2) by default. No alarm actions are configured — wire actions via `alarmActionsPolicy` from `@composurecdk/cloudwatch`, or by accessing alarms from the build result.
+
+| Alarm                          | Metric                                         | Default threshold   | Created when                                          |
+| ------------------------------ | ---------------------------------------------- | ------------------- | ----------------------------------------------------- |
+| `cpuUtilization`               | CPUUtilization (Average, 1 min)                | > 80% over 5 min    | Always                                                |
+| `statusCheckFailed`            | StatusCheckFailed (Sum, 1 min)                 | > 0 over 2 min      | Always                                                |
+| `attachedEbsStatusCheckFailed` | StatusCheckFailed_AttachedEBS (Maximum, 1 min) | >= 1 over 10 min    | Always                                                |
+| `cpuCreditBalance`             | CPUCreditBalance (Minimum, 5 min)              | < 50 over 3 x 5 min | `instanceType` is burstable (T2, T3, T3a, T4g family) |
+
+The defaults are exported as `INSTANCE_ALARM_DEFAULTS` for visibility and testing:
+
+```ts
+import { INSTANCE_ALARM_DEFAULTS } from "@composurecdk/ec2";
+```
+
+### Customizing thresholds
+
+Override individual alarm properties via `recommendedAlarms`. Unspecified fields keep their defaults.
+
+```ts
+const server = createInstanceBuilder()
+  .vpc(vpc)
+  .instanceType(InstanceType.of(InstanceClass.T3, InstanceSize.MICRO))
+  .machineImage(MachineImage.latestAmazonLinux2023())
+  .recommendedAlarms({
+    cpuUtilization: { threshold: 90, evaluationPeriods: 3, datapointsToAlarm: 3 },
+  });
+```
+
+### Disabling alarms
+
+Disable all recommended alarms:
+
+```ts
+builder.recommendedAlarms(false);
+// or
+builder.recommendedAlarms({ enabled: false });
+```
+
+Disable individual alarms:
+
+```ts
+builder.recommendedAlarms({ cpuCreditBalance: false });
+```
+
+### Custom alarms
+
+Add custom alarms alongside the recommended ones via `addAlarm`. The callback receives an `AlarmDefinitionBuilder` typed to the `Instance`.
+
+```ts
+import { Metric, Stats } from "aws-cdk-lib/aws-cloudwatch";
+import { Duration } from "aws-cdk-lib";
+
+const server = createInstanceBuilder()
+  .vpc(vpc)
+  .instanceType(InstanceType.of(InstanceClass.T3, InstanceSize.MICRO))
+  .machineImage(MachineImage.latestAmazonLinux2023())
+  .addAlarm("networkIn", (alarm) =>
+    alarm
+      .metric(
+        (instance) =>
+          new Metric({
+            namespace: "AWS/EC2",
+            metricName: "NetworkIn",
+            dimensionsMap: { InstanceId: instance.instanceId },
+            statistic: Stats.AVERAGE,
+            period: Duration.minutes(1),
+          }),
+      )
+      .threshold(1_000_000_000)
+      .greaterThanOrEqual()
+      .description("Inbound network traffic is unusually high"),
+  );
+```
+
+## VPC Builder
+
+```ts
+import { createVpcBuilder } from "@composurecdk/ec2";
+
+const network = createVpcBuilder().maxAzs(3).natGateways(3).build(stack, "Network");
+```
+
+Every [VpcProps](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_ec2.VpcProps.html) property is available as a fluent setter on the builder.
+
+### VPC Defaults
+
+| Property                       | Default                           | Rationale                                                                                          |
+| ------------------------------ | --------------------------------- | -------------------------------------------------------------------------------------------------- |
+| `maxAzs`                       | `2`                               | Meaningful HA without overspending. Override to 3+ for stricter production guarantees.             |
+| `natGateways`                  | `1`                               | Cost-conscious default. Production HA workloads should set `natGateways` to match `maxAzs`.        |
+| `enableDnsSupport`             | `true`                            | Required for most AWS managed services (ALB, RDS, VPC endpoints).                                  |
+| `enableDnsHostnames`           | `true`                            | Required for instances to receive public DNS hostnames.                                            |
+| `restrictDefaultSecurityGroup` | `true`                            | Strips rules from the default SG, forcing explicit SG design.                                      |
+| Flow logs                      | Auto-created CloudWatch log group | Network audit trail with well-architected retention and removal policies via `@composurecdk/logs`. |
+
+The defaults are exported as `VPC_DEFAULTS` for visibility and testing:
+
+```ts
+import { VPC_DEFAULTS } from "@composurecdk/ec2";
+```
+
+### Flow logs
+
+By default, the builder auto-creates a CloudWatch-Logs-backed flow log with a managed `LogGroup` from `@composurecdk/logs` (two-year retention, `RemovalPolicy.RETAIN`).
+
+Customize the auto-created LogGroup:
+
+```ts
+createVpcBuilder().flowLogs({
+  configure: (lg) => lg.retention(RetentionDays.NINETY_DAYS).removalPolicy(RemovalPolicy.DESTROY),
+});
+```
+
+Use a user-managed destination (e.g. an S3 bucket):
+
+```ts
+createVpcBuilder().flowLogs({
+  destination: FlowLogDestination.toS3(myBucket),
+});
+```
+
+Disable flow logs entirely:
+
+```ts
+createVpcBuilder().flowLogs(false);
+```
+
+For multiple flow logs against the same VPC, omit this config and create additional `FlowLog` constructs directly against the returned `vpc`.
+
+## Composing EC2 + VPC
+
+Compose the builders into a single system — the instance is wired to the VPC via `ref`:
+
+```ts
+import { compose, ref } from "@composurecdk/core";
+import { createInstanceBuilder, createVpcBuilder, type VpcBuilderResult } from "@composurecdk/ec2";
+import type { Vpc } from "aws-cdk-lib/aws-ec2";
+
+compose(
+  {
+    network: createVpcBuilder(),
+    server: createInstanceBuilder()
+      .vpc(ref<VpcBuilderResult>("network").map((r): Vpc => r.vpc))
+      .instanceType(InstanceType.of(InstanceClass.T3, InstanceSize.MICRO))
+      .machineImage(MachineImage.latestAmazonLinux2023()),
+  },
+  { network: [], server: ["network"] },
+).build(stack, "Ec2App");
+```
+
+## Examples
+
+- [Ec2Stack](../examples/src/ec2-app.ts) — VPC + EC2 instance with alarms wired to an SNS topic via `alarmActionsPolicy`.

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+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 { createVpcBuilder, type FlowLogsConfig, type IVpcBuilder, type VpcBuilderProps, type VpcBuilderResult, } from "./vpc-builder.js";
+export { VPC_DEFAULTS } from "./vpc-defaults.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -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;AAEvE,OAAO,EACL,gBAAgB,EAChB,KAAK,cAAc,EACnB,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,KAAK,gBAAgB,GACtB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/index.js

@@ -0,0 +1,6 @@
+export { createInstanceBuilder, } from "./instance-builder.js";
+export { INSTANCE_DEFAULTS } from "./instance-defaults.js";
+export { INSTANCE_ALARM_DEFAULTS } from "./instance-alarm-defaults.js";
+export { createVpcBuilder, } from "./vpc-builder.js";
+export { VPC_DEFAULTS } from "./vpc-defaults.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

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

@@ -0,0 +1,62 @@
+import type { AlarmConfig } from "@composurecdk/cloudwatch";
+/**
+ * Controls which recommended alarms are created for an EC2 instance.
+ * All 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#EC2
+ */
+export interface InstanceAlarmConfig {
+    /**
+     * 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 CPU utilization is sustained at a high level.
+     *
+     * Metric: `AWS/EC2 CPUUtilization`, statistic Average, period 1 minute.
+     * Default threshold: > 80% over 5 consecutive minutes.
+     *
+     * @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#EC2
+     */
+    cpuUtilization?: AlarmConfig | false;
+    /**
+     * Alarm when the instance fails its EC2 or system status checks.
+     *
+     * Metric: `AWS/EC2 StatusCheckFailed`, statistic Sum, period 1 minute.
+     * Default threshold: > 0 failures over 2 consecutive minutes.
+     *
+     * @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#EC2
+     */
+    statusCheckFailed?: AlarmConfig | false;
+    /**
+     * Alarm when the instance's attached EBS volumes are unreachable or
+     * unable to complete I/O — typically a host or storage-subsystem issue.
+     *
+     * Metric: `AWS/EC2 StatusCheckFailed_AttachedEBS`, statistic Maximum,
+     * period 1 minute. Default threshold: >= 1 over 10 consecutive minutes
+     * (the longer window reflects that EBS infrastructure usually self-heals
+     * within a few minutes).
+     *
+     * @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#EC2
+     */
+    attachedEbsStatusCheckFailed?: AlarmConfig | false;
+    /**
+     * Alarm when burstable (T-family) CPU credit balance falls low,
+     * indicating the instance is about to be throttled to baseline.
+     *
+     * Only created when the `instanceType` family is one of: t2, t3, t3a, t4g.
+     * For other instance types this alarm is skipped entirely.
+     *
+     * Metric: `AWS/EC2 CPUCreditBalance`, statistic Minimum, period 5 minutes.
+     * Default threshold: < 50 credits over 3 consecutive 5-minute windows.
+     *
+     * @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#EC2
+     * @see https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/burstable-credits-baseline-concepts.html
+     */
+    cpuCreditBalance?: AlarmConfig | false;
+}
+//# sourceMappingURL=instance-alarm-config.d.ts.map

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

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

package/dist/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/instance-alarm-defaults.d.ts

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

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

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

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

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

package/dist/instance-alarms.d.ts

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

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

@@ -0,0 +1,128 @@
+import { Duration } from "aws-cdk-lib";
+import { ComparisonOperator, Metric, Stats } from "aws-cdk-lib/aws-cloudwatch";
+import { createAlarms, resolveAlarmConfig } from "@composurecdk/cloudwatch";
+import { INSTANCE_ALARM_DEFAULTS } from "./instance-alarm-defaults.js";
+const METRIC_PERIOD = 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 = 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 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.
+ */
+export function resolveInstanceAlarmDefinitions(instance, config, props) {
+    if (config?.enabled === false)
+        return [];
+    const definitions = [];
+    if (config?.cpuUtilization !== false) {
+        const cfg = resolveAlarmConfig(config?.cpuUtilization, INSTANCE_ALARM_DEFAULTS.cpuUtilization);
+        definitions.push({
+            key: "cpuUtilization",
+            alarmName: cfg.alarmName,
+            metric: instanceMetric(instance, "CPUUtilization", Stats.AVERAGE),
+            threshold: cfg.threshold,
+            comparisonOperator: 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 = resolveAlarmConfig(config?.statusCheckFailed, INSTANCE_ALARM_DEFAULTS.statusCheckFailed);
+        definitions.push({
+            key: "statusCheckFailed",
+            alarmName: cfg.alarmName,
+            metric: instanceMetric(instance, "StatusCheckFailed", Stats.SUM),
+            threshold: cfg.threshold,
+            comparisonOperator: 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 = resolveAlarmConfig(config?.attachedEbsStatusCheckFailed, INSTANCE_ALARM_DEFAULTS.attachedEbsStatusCheckFailed);
+        definitions.push({
+            key: "attachedEbsStatusCheckFailed",
+            alarmName: cfg.alarmName,
+            metric: instanceMetric(instance, "StatusCheckFailed_AttachedEBS", Stats.MAXIMUM),
+            threshold: cfg.threshold,
+            comparisonOperator: 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 = resolveAlarmConfig(config?.cpuCreditBalance, INSTANCE_ALARM_DEFAULTS.cpuCreditBalance);
+        definitions.push({
+            key: "cpuCreditBalance",
+            alarmName: cfg.alarmName,
+            metric: instanceMetric(instance, "CPUCreditBalance", Stats.MINIMUM, CREDIT_METRIC_PERIOD),
+            threshold: cfg.threshold,
+            comparisonOperator: 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
+ */
+export function createInstanceAlarms(scope, id, instance, config, props, customAlarms = []) {
+    if (config === false)
+        return {};
+    const enabled = config?.enabled ?? INSTANCE_ALARM_DEFAULTS.enabled;
+    if (!enabled)
+        return {};
+    const recommended = resolveInstanceAlarmDefinitions(instance, config, props);
+    const custom = customAlarms.map((b) => b.resolve(instance));
+    return createAlarms(scope, id, [...recommended, ...custom]);
+}
+//# sourceMappingURL=instance-alarms.js.map

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

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

package/dist/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,QAAQ,EACR,KAAK,QAAQ,EACb,KAAK,cAAc,EACnB,KAAK,IAAI,EACT,KAAK,aAAa,EACnB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,KAAK,KAAK,EAAE,MAAM,qBAAqB,CAAC;AACjD,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EAEL,KAAK,QAAQ,EACb,KAAK,SAAS,EAEd,KAAK,UAAU,EAChB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAItE;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,oBAAqB,SAAQ,IAAI,CAChD,aAAa,EACb,KAAK,GAAG,MAAM,GAAG,SAAS,GAAG,eAAe,CAC7C;IACC;;;;;;;;;OASG;IACH,IAAI,CAAC,EAAE,UAAU,CAAC,KAAK,CAAC,CAAC;IAEzB;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE,UAAU,CAAC,QAAQ,CAAC,CAAC;IAE/B;;;;;;;;OAQG;IACH,aAAa,CAAC,EAAE,UAAU,CAAC,cAAc,CAAC,CAAC;IAE3C;;;;;;;;;;;;;;;;OAgBG;IACH,iBAAiB,CAAC,EAAE,mBAAmB,GAAG,KAAK,CAAC;CACjD;AAED;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,EAAE,QAAQ,CAAC;IAEnB;;;;;;;;;;;OAWG;IACH,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;CAC/B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,MAAM,gBAAgB,GAAG,QAAQ,CAAC,oBAAoB,EAAE,eAAe,CAAC,CAAC;AAE/E,cAAM,eAAgB,YAAW,SAAS,CAAC,qBAAqB,CAAC;;IAC/D,KAAK,EAAE,OAAO,CAAC,oBAAoB,CAAC,CAAM;IAI1C;;;;;;;;;OASG;IACH,GAAG,CAAC,GAAG,EAAE,UAAU,CAAC,IAAI,CAAC,GAAG,IAAI;IAKhC;;;;;;;;OAQG;IACH,QAAQ,CACN,GAAG,EAAE,MAAM,EACX,SAAS,EAAE,CAAC,KAAK,EAAE,sBAAsB,CAAC,QAAQ,CAAC,KAAK,sBAAsB,CAAC,QAAQ,CAAC,GACvF,IAAI;IAKP,KAAK,CAAC,KAAK,EAAE,UAAU,EAAE,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,qBAAqB;CAuC9F;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,qBAAqB,IAAI,gBAAgB,CAExD"}

package/dist/instance-builder.js

@@ -0,0 +1,87 @@
+import { Instance, } from "aws-cdk-lib/aws-ec2";
+import { Builder, resolve, } from "@composurecdk/core";
+import { AlarmDefinitionBuilder } from "@composurecdk/cloudwatch";
+import { createInstanceAlarms } from "./instance-alarms.js";
+import { INSTANCE_DEFAULTS } from "./instance-defaults.js";
+class InstanceBuilder {
+    props = {};
+    #customAlarms = [];
+    #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 AlarmDefinitionBuilder(key)));
+        return this;
+    }
+    build(scope, id, context) {
+        const resolvedVpc = this.#vpc ? 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,
+            ...instanceProps,
+            vpc: resolvedVpc,
+            ...(role !== undefined ? { role: resolve(role, context) } : {}),
+            ...(keyPair !== undefined ? { keyPair: resolve(keyPair, context) } : {}),
+            ...(securityGroup !== undefined ? { securityGroup: resolve(securityGroup, context) } : {}),
+        };
+        const instance = new Instance(scope, id, mergedProps);
+        const alarms = createInstanceAlarms(scope, id, instance, alarmConfig, mergedProps, this.#customAlarms);
+        return { instance, alarms };
+    }
+}
+/**
+ * Creates a new {@link IInstanceBuilder} for configuring an AWS EC2 instance.
+ *
+ * This is the entry point for defining an EC2 instance component. The
+ * returned builder exposes every {@link InstanceBuilderProps} property as a
+ * fluent setter/getter, plus {@link IInstanceBuilder.vpc | .vpc()} for
+ * cross-component VPC wiring with Ref support. It implements
+ * {@link Lifecycle} for use with {@link compose}.
+ *
+ * @returns A fluent builder for an AWS EC2 instance.
+ *
+ * @example
+ * ```ts
+ * const server = createInstanceBuilder()
+ *   .vpc(ref<VpcBuilderResult>("network").get("vpc"))
+ *   .instanceType(InstanceType.of(InstanceClass.T3, InstanceSize.MICRO))
+ *   .machineImage(MachineImage.latestAmazonLinux2023());
+ *
+ * // Use standalone:
+ * const result = server.build(stack, "MyInstance");
+ *
+ * // Or compose into a system:
+ * const system = compose(
+ *   { network: createVpcBuilder(), server },
+ *   { network: [], server: ["network"] },
+ * );
+ * ```
+ */
+export function createInstanceBuilder() {
+    return Builder(InstanceBuilder);
+}
+//# sourceMappingURL=instance-builder.js.map

package/dist/instance-builder.js.map

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

package/dist/instance-defaults.d.ts

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

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

@@ -0,0 +1,59 @@
+import { BlockDeviceVolume, EbsDeviceVolumeType } from "aws-cdk-lib/aws-ec2";
+/**
+ * Secure, AWS-recommended defaults applied to every EC2 instance built with
+ * {@link createInstanceBuilder}. Each property can be individually overridden
+ * via the builder's fluent API.
+ *
+ * Three required properties intentionally have no default — they are
+ * application-specific and must be supplied explicitly:
+ *   - `vpc` (via the builder's `.vpc()` method)
+ *   - `instanceType`
+ *   - `machineImage`
+ */
+export const 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: BlockDeviceVolume.ebs(8, {
+                encrypted: true,
+                volumeType: EbsDeviceVolumeType.GP3,
+            }),
+        },
+    ],
+};
+//# sourceMappingURL=instance-defaults.js.map

package/dist/instance-defaults.js.map

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

package/dist/vpc-builder.d.ts

@@ -0,0 +1,109 @@
+import { FlowLogDestination, Vpc, type VpcProps } from "aws-cdk-lib/aws-ec2";
+import { type LogGroup } from "aws-cdk-lib/aws-logs";
+import { type IConstruct } from "constructs";
+import { type IBuilder, type Lifecycle } from "@composurecdk/core";
+import { type ILogGroupBuilder } from "@composurecdk/logs";
+/**
+ * Configures how VPC flow logs are handled. Pass `false` to disable flow
+ * logs; pass an object to wire a destination or customize the auto-created
+ * LogGroup sub-builder.
+ *
+ * `configure` cannot be combined with `destination` — a user-managed
+ * destination is not built by this builder.
+ *
+ * For multiple flow logs against the same VPC, omit this config and create
+ * additional `FlowLog` constructs directly against the returned `vpc`.
+ *
+ * @see https://docs.aws.amazon.com/vpc/latest/userguide/flow-logs.html
+ */
+export type FlowLogsConfig = false | {
+    /** A user-managed flow log destination. Cannot be combined with `configure`. */
+    destination?: FlowLogDestination;
+    /**
+     * Customize the auto-created LogGroup sub-builder. Receives a builder
+     * pre-seeded with the well-architected log retention/removal defaults
+     * from {@link createLogGroupBuilder}.
+     */
+    configure?: (b: ILogGroupBuilder) => ILogGroupBuilder;
+};
+/**
+ * Configuration properties for the VPC builder.
+ *
+ * Hides the CDK `flowLogs` map field in favor of {@link flowLogs} — a
+ * discriminated config that supports an `false` opt-out, a user-managed
+ * destination, or a customizable auto-managed LogGroup.
+ */
+export interface VpcBuilderProps extends Omit<VpcProps, "flowLogs"> {
+    /** See {@link FlowLogsConfig}. Defaults to an auto-managed LogGroup-backed flow log. */
+    flowLogs?: FlowLogsConfig;
+}
+/**
+ * The build output of a {@link IVpcBuilder}. Contains the CDK constructs
+ * created during {@link Lifecycle.build}, keyed by role.
+ */
+export interface VpcBuilderResult {
+    vpc: Vpc;
+    /**
+     * The CloudWatch LogGroup created for the auto-managed flow log, or
+     * `undefined` when the user supplied their own `destination` or
+     * disabled flow logs entirely.
+     *
+     * @see https://docs.aws.amazon.com/vpc/latest/userguide/flow-logs.html
+     */
+    flowLogsLogGroup?: LogGroup;
+}
+/**
+ * A fluent builder for configuring and creating an AWS VPC.
+ *
+ * Each configuration property from the CDK {@link VpcProps} 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 builder implements {@link Lifecycle}, so it can be used directly as a
+ * component in a {@link compose | composed system}. When built, it creates
+ * a VPC with {@link VPC_DEFAULTS | well-architected defaults} and returns a
+ * {@link VpcBuilderResult}.
+ *
+ * By default the builder auto-creates a CloudWatch-Logs-backed flow log
+ * using a managed {@link LogGroup} so every VPC gets baseline network audit
+ * logging. Customize via {@link FlowLogsConfig} or disable with
+ * `flowLogs(false)`.
+ *
+ * @see https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_ec2.Vpc.html
+ *
+ * @example
+ * ```ts
+ * const network = createVpcBuilder().maxAzs(3).natGateways(3);
+ * ```
+ */
+export type IVpcBuilder = IBuilder<VpcBuilderProps, VpcBuilder>;
+declare class VpcBuilder implements Lifecycle<VpcBuilderResult> {
+    props: Partial<VpcBuilderProps>;
+    build(scope: IConstruct, id: string): VpcBuilderResult;
+}
+/**
+ * Creates a new {@link IVpcBuilder} for configuring an AWS VPC.
+ *
+ * This is the entry point for defining a VPC component. The returned builder
+ * exposes every {@link VpcBuilderProps} property as a fluent setter/getter
+ * and implements {@link Lifecycle} for use with {@link compose}.
+ *
+ * @returns A fluent builder for an AWS VPC.
+ *
+ * @example
+ * ```ts
+ * const network = createVpcBuilder().maxAzs(3).natGateways(3);
+ *
+ * // Use standalone:
+ * const result = network.build(stack, "Network");
+ *
+ * // Or compose into a system:
+ * const system = compose(
+ *   { network, server: createInstanceBuilder() },
+ *   { network: [], server: ["network"] },
+ * );
+ * ```
+ */
+export declare function createVpcBuilder(): IVpcBuilder;
+export {};
+//# sourceMappingURL=vpc-builder.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"vpc-builder.d.ts","sourceRoot":"","sources":["../src/vpc-builder.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,GAAG,EAAE,KAAK,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAC7E,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EAAW,KAAK,QAAQ,EAAE,KAAK,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAC5E,OAAO,EAAyB,KAAK,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAGlF;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,cAAc,GACtB,KAAK,GACL;IACE,gFAAgF;IAChF,WAAW,CAAC,EAAE,kBAAkB,CAAC;IACjC;;;;OAIG;IACH,SAAS,CAAC,EAAE,CAAC,CAAC,EAAE,gBAAgB,KAAK,gBAAgB,CAAC;CACvD,CAAC;AAEN;;;;;;GAMG;AACH,MAAM,WAAW,eAAgB,SAAQ,IAAI,CAAC,QAAQ,EAAE,UAAU,CAAC;IACjE,wFAAwF;IACxF,QAAQ,CAAC,EAAE,cAAc,CAAC;CAC3B;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,GAAG,CAAC;IAET;;;;;;OAMG;IACH,gBAAgB,CAAC,EAAE,QAAQ,CAAC;CAC7B;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,MAAM,WAAW,GAAG,QAAQ,CAAC,eAAe,EAAE,UAAU,CAAC,CAAC;AAIhE,cAAM,UAAW,YAAW,SAAS,CAAC,gBAAgB,CAAC;IACrD,KAAK,EAAE,OAAO,CAAC,eAAe,CAAC,CAAM;IAErC,KAAK,CAAC,KAAK,EAAE,UAAU,EAAE,EAAE,EAAE,MAAM,GAAG,gBAAgB;CAgBvD;AA2CD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,gBAAgB,IAAI,WAAW,CAE9C"}

package/dist/vpc-builder.js

@@ -0,0 +1,79 @@
+import { FlowLogDestination, Vpc } from "aws-cdk-lib/aws-ec2";
+import { Builder } from "@composurecdk/core";
+import { createLogGroupBuilder } from "@composurecdk/logs";
+import { VPC_DEFAULTS } from "./vpc-defaults.js";
+const DEFAULT_FLOW_LOG_KEY = "DefaultFlowLog";
+class VpcBuilder {
+    props = {};
+    build(scope, id) {
+        const { flowLogs: flowLogsConfig, ...vpcProps } = this.props;
+        const { flowLogsLogGroup, flowLogProps } = resolveFlowLogs(scope, id, flowLogsConfig);
+        const mergedProps = {
+            ...VPC_DEFAULTS,
+            ...flowLogProps,
+            ...vpcProps,
+        };
+        return {
+            vpc: new Vpc(scope, id, mergedProps),
+            flowLogsLogGroup,
+        };
+    }
+}
+function resolveFlowLogs(scope, id, cfg) {
+    if (cfg === false) {
+        return { flowLogProps: {} };
+    }
+    if (cfg?.destination !== undefined) {
+        if (cfg.configure !== undefined) {
+            throw new Error("flowLogs: 'configure' cannot be combined with 'destination' — " +
+                "the destination is user-managed and not built by this builder.");
+        }
+        return {
+            flowLogProps: {
+                flowLogs: { [DEFAULT_FLOW_LOG_KEY]: { destination: cfg.destination } },
+            },
+        };
+    }
+    let subBuilder = createLogGroupBuilder();
+    if (cfg?.configure) {
+        subBuilder = cfg.configure(subBuilder);
+    }
+    const flowLogsLogGroup = subBuilder.build(scope, `${id}FlowLogsLogGroup`).logGroup;
+    return {
+        flowLogsLogGroup,
+        flowLogProps: {
+            flowLogs: {
+                [DEFAULT_FLOW_LOG_KEY]: {
+                    destination: FlowLogDestination.toCloudWatchLogs(flowLogsLogGroup),
+                },
+            },
+        },
+    };
+}
+/**
+ * Creates a new {@link IVpcBuilder} for configuring an AWS VPC.
+ *
+ * This is the entry point for defining a VPC component. The returned builder
+ * exposes every {@link VpcBuilderProps} property as a fluent setter/getter
+ * and implements {@link Lifecycle} for use with {@link compose}.
+ *
+ * @returns A fluent builder for an AWS VPC.
+ *
+ * @example
+ * ```ts
+ * const network = createVpcBuilder().maxAzs(3).natGateways(3);
+ *
+ * // Use standalone:
+ * const result = network.build(stack, "Network");
+ *
+ * // Or compose into a system:
+ * const system = compose(
+ *   { network, server: createInstanceBuilder() },
+ *   { network: [], server: ["network"] },
+ * );
+ * ```
+ */
+export function createVpcBuilder() {
+    return Builder(VpcBuilder);
+}
+//# sourceMappingURL=vpc-builder.js.map

package/dist/vpc-builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vpc-builder.js","sourceRoot":"","sources":["../src/vpc-builder.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,GAAG,EAAiB,MAAM,qBAAqB,CAAC;AAG7E,OAAO,EAAE,OAAO,EAAiC,MAAM,oBAAoB,CAAC;AAC5E,OAAO,EAAE,qBAAqB,EAAyB,MAAM,oBAAoB,CAAC;AAClF,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAmFjD,MAAM,oBAAoB,GAAG,gBAAgB,CAAC;AAE9C,MAAM,UAAU;IACd,KAAK,GAA6B,EAAE,CAAC;IAErC,KAAK,CAAC,KAAiB,EAAE,EAAU;QACjC,MAAM,EAAE,QAAQ,EAAE,cAAc,EAAE,GAAG,QAAQ,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC;QAE7D,MAAM,EAAE,gBAAgB,EAAE,YAAY,EAAE,GAAG,eAAe,CAAC,KAAK,EAAE,EAAE,EAAE,cAAc,CAAC,CAAC;QAEtF,MAAM,WAAW,GAAG;YAClB,GAAG,YAAY;YACf,GAAG,YAAY;YACf,GAAG,QAAQ;SACZ,CAAC;QAEF,OAAO;YACL,GAAG,EAAE,IAAI,GAAG,CAAC,KAAK,EAAE,EAAE,EAAE,WAAW,CAAC;YACpC,gBAAgB;SACjB,CAAC;IACJ,CAAC;CACF;AAED,SAAS,eAAe,CACtB,KAAiB,EACjB,EAAU,EACV,GAA+B;IAE/B,IAAI,GAAG,KAAK,KAAK,EAAE,CAAC;QAClB,OAAO,EAAE,YAAY,EAAE,EAAE,EAAE,CAAC;IAC9B,CAAC;IAED,IAAI,GAAG,EAAE,WAAW,KAAK,SAAS,EAAE,CAAC;QACnC,IAAI,GAAG,CAAC,SAAS,KAAK,SAAS,EAAE,CAAC;YAChC,MAAM,IAAI,KAAK,CACb,gEAAgE;gBAC9D,gEAAgE,CACnE,CAAC;QACJ,CAAC;QACD,OAAO;YACL,YAAY,EAAE;gBACZ,QAAQ,EAAE,EAAE,CAAC,oBAAoB,CAAC,EAAE,EAAE,WAAW,EAAE,GAAG,CAAC,WAAW,EAAE,EAAE;aACvE;SACF,CAAC;IACJ,CAAC;IAED,IAAI,UAAU,GAAG,qBAAqB,EAAE,CAAC;IACzC,IAAI,GAAG,EAAE,SAAS,EAAE,CAAC;QACnB,UAAU,GAAG,GAAG,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC;IACzC,CAAC;IACD,MAAM,gBAAgB,GAAG,UAAU,CAAC,KAAK,CAAC,KAAK,EAAE,GAAG,EAAE,kBAAkB,CAAC,CAAC,QAAQ,CAAC;IAEnF,OAAO;QACL,gBAAgB;QAChB,YAAY,EAAE;YACZ,QAAQ,EAAE;gBACR,CAAC,oBAAoB,CAAC,EAAE;oBACtB,WAAW,EAAE,kBAAkB,CAAC,gBAAgB,CAAC,gBAAgB,CAAC;iBACnE;aACF;SACF;KACF,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,UAAU,gBAAgB;IAC9B,OAAO,OAAO,CAA8B,UAAU,CAAC,CAAC;AAC1D,CAAC"}

package/dist/vpc-defaults.d.ts

@@ -0,0 +1,15 @@
+import type { VpcProps } from "aws-cdk-lib/aws-ec2";
+/**
+ * Secure, cost-conscious defaults applied to every VPC built with
+ * {@link createVpcBuilder}. Each property can be individually overridden
+ * via the builder's fluent API.
+ *
+ * Subnet layout uses CDK defaults (one public + one private-with-egress
+ * subnet per AZ) — override `subnetConfiguration` for custom topologies.
+ *
+ * Flow logs are created separately by the builder (not via this defaults
+ * object) so the destination log group can be auto-managed with
+ * well-architected retention/removal policies.
+ */
+export declare const VPC_DEFAULTS: Partial<VpcProps>;
+//# sourceMappingURL=vpc-defaults.d.ts.map

package/dist/vpc-defaults.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vpc-defaults.d.ts","sourceRoot":"","sources":["../src/vpc-defaults.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAEpD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,YAAY,EAAE,OAAO,CAAC,QAAQ,CA6C1C,CAAC"}

package/dist/vpc-defaults.js

@@ -0,0 +1,55 @@
+/**
+ * Secure, cost-conscious defaults applied to every VPC built with
+ * {@link createVpcBuilder}. Each property can be individually overridden
+ * via the builder's fluent API.
+ *
+ * Subnet layout uses CDK defaults (one public + one private-with-egress
+ * subnet per AZ) — override `subnetConfiguration` for custom topologies.
+ *
+ * Flow logs are created separately by the builder (not via this defaults
+ * object) so the destination log group can be auto-managed with
+ * well-architected retention/removal policies.
+ */
+export const VPC_DEFAULTS = {
+    /**
+     * Two availability zones strike a balance between high availability
+     * and cost. Override to 3+ AZs for production workloads that need
+     * stricter HA guarantees.
+     * @see https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html
+     */
+    maxAzs: 2,
+    /**
+     * Single NAT gateway is a cost-conscious default. Production HA
+     * workloads should override this to match `maxAzs` so a single-AZ
+     * NAT failure does not partition private-subnet egress.
+     * @see https://docs.aws.amazon.com/vpc/latest/userguide/vpc-nat-gateway.html
+     */
+    natGateways: 1,
+    /**
+     * Required for internal DNS resolution for most AWS managed services
+     * (ALB, RDS, VPC endpoints). Default-on in AWS but set explicitly for
+     * safety across CDK feature-flag configurations.
+     * @see https://docs.aws.amazon.com/vpc/latest/userguide/vpc-dns.html
+     */
+    enableDnsSupport: true,
+    /**
+     * Required alongside DNS support for instances to receive public DNS
+     * hostnames. Needed for most hostname-based TLS and service discovery
+     * scenarios.
+     * @see https://docs.aws.amazon.com/vpc/latest/userguide/vpc-dns.html
+     */
+    enableDnsHostnames: true,
+    /**
+     * Strip all rules from the default security group. This prevents
+     * accidentally using the default SG (which allows all intra-SG
+     * traffic and no ingress) and forces explicit SG design — a
+     * foundational well-architected security practice.
+     *
+     * Also enabled by the `@aws-cdk/aws-ec2:restrictDefaultSecurityGroup`
+     * feature flag; we set it explicitly so the guarantee holds regardless
+     * of CDK context configuration.
+     * @see https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_ec2.Vpc.html#restrictdefaultsecuritygroup
+     */
+    restrictDefaultSecurityGroup: true,
+};
+//# sourceMappingURL=vpc-defaults.js.map

package/dist/vpc-defaults.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vpc-defaults.js","sourceRoot":"","sources":["../src/vpc-defaults.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,YAAY,GAAsB;IAC7C;;;;;OAKG;IACH,MAAM,EAAE,CAAC;IAET;;;;;OAKG;IACH,WAAW,EAAE,CAAC;IAEd;;;;;OAKG;IACH,gBAAgB,EAAE,IAAI;IAEtB;;;;;OAKG;IACH,kBAAkB,EAAE,IAAI;IAExB;;;;;;;;;;OAUG;IACH,4BAA4B,EAAE,IAAI;CACnC,CAAC"}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@composurecdk/ec2",
+  "version": "0.5.0",
+  "description": "Composable EC2 instance and VPC builders with well-architected defaults",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/laazyj/composureCDK",
+    "directory": "packages/ec2"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "clean": "rm -rf dist",
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests",
+    "test:watch": "vitest"
+  },
+  "keywords": [],
+  "author": "Jason Duffett (https://github.com/laazyj)",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "peerDependencies": {
+    "@composurecdk/cloudwatch": "^0.5.0",
+    "@composurecdk/core": "^0.5.0",
+    "@composurecdk/logs": "^0.5.0",
+    "aws-cdk-lib": "^2.0.0",
+    "constructs": "^10.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "aws-cdk-lib": "^2.245.0",
+    "constructs": "^10.6.0",
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.2"
+  }
+}