@fjall/components-infrastructure 6.0.0 → 7.0.1

package/dist/lib/patterns/aws/clickhouseDatabase.js

@@ -389,6 +389,10 @@ export class ClickHouseDatabase extends Construct {
                     securityGroups: [securityGroup],
                     deployment: { minHealthyPercent: 0, maxHealthyPercent: 100 },
                     ec2Config: {
+                        // Pattern-chosen stable slot: the composed cluster must never
+                        // collide with the app's own EC2 compute defaulting "primary"
+                        // (slots are app-scoped; collision is a hard synth error).
+                        slot: "clickhouse",
                         instanceType,
                         machineImage: EcsOptimizedImage.amazonLinux2023(amiHardwareType),
                         instanceMonitoring: Monitoring.BASIC,

package/dist/lib/resources/aws/compute/ec2.d.ts

@@ -4,28 +4,37 @@ import { Duration, Stack, type StackProps } from "aws-cdk-lib";
 import { type Role } from "aws-cdk-lib/aws-iam";
 import { AutoScalingGroup, Monitoring, type WarmPoolOptions } from "aws-cdk-lib/aws-autoscaling";
 import { type PersistentDataVolumeProps } from "./persistentDataVolume.js";
-export type Ec2InstancePersistentDataVolumeConfig = Omit<PersistentDataVolumeProps, "autoScalingGroup">;
+export type Ec2InstancePersistentDataVolumeConfig = Omit<PersistentDataVolumeProps, "autoScalingGroup" | "stableOwnerId">;
 /**
  * Caller-supplied ASG `UpdatePolicy` resolution. Default (`undefined`) →
- * `rollingUpdate({ minInstancesInService: 0, maxBatchSize: 1, pauseTime:
- * Duration.minutes(5) })`. The rolling shape propagates userdata mutations
- * to running instances on every `LaunchTemplateVersion` change; data
- * continuity for stateful patterns is preserved by `persistentDataVolume`.
+ * `instanceRefresh` with `minHealthyPercentage 0 / maxHealthyPercentage 100`
+ * when `persistentDataVolume` is set (single-attach EBS forbids a surge
+ * instance), `100 / 200` otherwise (surge-then-shrink, no capacity dip).
+ * Either shape propagates userdata/launch-template mutations to running
+ * instances on every `LaunchTemplateVersion` change; data continuity for
+ * stateful patterns is preserved by `persistentDataVolume`.
  *
  * Variants:
- * - `rollingUpdate` — single-instance roll; `pauseTime` overridable.
- *   `minInstancesInService` and `maxBatchSize` are fixed at `0` and `1`.
+ * - `instanceRefresh` — ASG-native rolling replacement via CFN
+ *   `UpdatePolicy.InstanceRefresh`; percentages overridable.
+ * - `rollingUpdate` — legacy CFN-driven single-instance roll; `pauseTime`
+ *   overridable. `minInstancesInService` and `maxBatchSize` are fixed at
+ *   `0` and `1`.
  * - `replacingUpdate` — explicit opt-in to the legacy full-replacement shape.
  *   No Fjall consumer uses this today; retained for future bare-EC2 patterns.
- * - `none` — no caller-driven `UpdatePolicy` (omits both
- *   `AutoScalingRollingUpdate` and `AutoScalingReplacingUpdate`). CDK still
- *   auto-emits `AutoScalingScheduledAction.IgnoreUnmodifiedGroupSizeProperties`
+ * - `none` — no caller-driven `UpdatePolicy` (omits the rolling, replacing
+ *   AND refresh blocks). CDK still auto-emits
+ *   `AutoScalingScheduledAction.IgnoreUnmodifiedGroupSizeProperties`
  *   regardless. For callers owning rollout externally.
  *
  * See `aiDocs/troubleshooting/clickhouse-rolling-update-window.md` for the
  * ClickHouse-specific downtime expectations.
  */
 export type Ec2InstanceUpdatePolicyConfig = {
+    type: "instanceRefresh";
+    minHealthyPercentage?: number;
+    maxHealthyPercentage?: number;
+} | {
     type: "rollingUpdate";
     pauseTime?: Duration;
 } | {
@@ -105,10 +114,18 @@ export interface Ec2InstanceProps extends StackProps {
      */
     persistentDataVolume?: Ec2InstancePersistentDataVolumeConfig;
     /**
-     * ASG `UpdatePolicy` resolution. Absent →
-     * `UpdatePolicy.rollingUpdate({ minInstancesInService: 0, maxBatchSize: 1,
-     * pauseTime: Duration.minutes(5) })`. Userdata mutations propagate to
-     * running instances via a single-batch rolling roll. See
+     * Stable owner identifier for the persistent data volume — becomes the
+     * volume's `fjall:OwnerLogicalId` tag and the re-attach Lambdas'
+     * `OWNER_LOGICAL_ID`. REQUIRED whenever `persistentDataVolume` is set
+     * (rejected at synth otherwise) so the re-attach identity is an explicit
+     * caller decision, never an accident of construct-tree position. Must
+     * remain byte-stable for the stack's whole life — changing it strands the
+     * deployed volume (the Lambda filter stops matching).
+     */
+    dataVolumeStableOwnerId?: string;
+    /**
+     * ASG `UpdatePolicy` resolution. Absent → `UpdatePolicy.instanceRefresh`
+     * (0/100 with `persistentDataVolume`, 100/200 otherwise). See
      * `Ec2InstanceUpdatePolicyConfig` for the variant menu and
      * `aiDocs/troubleshooting/clickhouse-rolling-update-window.md` for the
      * downtime-window runbook.

package/dist/lib/resources/aws/compute/ec2.js

@@ -3,7 +3,8 @@ import { Construct } from "constructs";
 import { resolvePrivateSubnetType } from "../../../utils/vpcUtils.js";
 import { safeEbs } from "./blockDeviceVolume.js";
 import { Duration, Stack, Tags } from "aws-cdk-lib";
-import { AutoScalingGroup, GroupMetrics, Monitoring, TerminationPolicy, UpdatePolicy, OnDemandAllocationStrategy, SpotAllocationStrategy } from "aws-cdk-lib/aws-autoscaling";
+import { AutoScalingGroup, GroupMetrics, InstanceRefreshStrategy, Monitoring, TerminationPolicy, UpdatePolicy, OnDemandAllocationStrategy, SpotAllocationStrategy } from "aws-cdk-lib/aws-autoscaling";
+import { DEFAULT_ROLLING_UPDATE_PAUSE_SECONDS, INSTANCE_REFRESH_DEFAULT_MAX_HEALTHY, INSTANCE_REFRESH_DEFAULT_MIN_HEALTHY, INSTANCE_REFRESH_PDV_MAX_HEALTHY, INSTANCE_REFRESH_PDV_MIN_HEALTHY } from "./ecsConstants.js";
 import { AwsCustomResource } from "../utilities/awsCustomResource.js";
 import { PhysicalResourceId } from "aws-cdk-lib/custom-resources";
 import { Vpc } from "../networking/vpc.js";
@@ -22,17 +23,17 @@ const DEFAULT_ROOT_DEVICE_NAME = "/dev/xvda";
 const DEFAULT_ROOT_VOLUME_SIZE_GIB = 30;
 /**
  * Resolve the caller's `updatePolicy` prop to a CDK `UpdatePolicy`. Default
- * (`config` absent) → single-instance rolling roll on every
- * `LaunchTemplateVersion` change. The `none` branch returns `undefined` so
- * `addAutoScalingGroup` can conditionally spread the field — passing
- * `updatePolicy: undefined` directly emits an empty `UpdatePolicy: {}` block
- * on some CDK versions.
+ * (`config` absent) → instance refresh, percentages keyed on
+ * `hasPersistentDataVolume` (see the constants above). The `none` branch
+ * returns `undefined` so `addAutoScalingGroup` can conditionally spread the
+ * field — passing `updatePolicy: undefined` directly emits an empty
+ * `UpdatePolicy: {}` block on some CDK versions.
  *
  * Free function rather than a private method: `this` state is not read, and
  * a free function is easier to reach from focused tests.
  */
-function resolveUpdatePolicy(config) {
-    const resolved = config ?? { type: "rollingUpdate" };
+function resolveUpdatePolicy(config, hasPersistentDataVolume) {
+    const resolved = config ?? { type: "instanceRefresh" };
     switch (resolved.type) {
         case "none":
             return undefined;
@@ -42,7 +43,20 @@ function resolveUpdatePolicy(config) {
             return UpdatePolicy.rollingUpdate({
                 minInstancesInService: 0,
                 maxBatchSize: 1,
-                pauseTime: resolved.pauseTime ?? Duration.minutes(5)
+                pauseTime: resolved.pauseTime ??
+                    Duration.seconds(DEFAULT_ROLLING_UPDATE_PAUSE_SECONDS)
+            });
+        case "instanceRefresh":
+            return UpdatePolicy.instanceRefresh({
+                strategy: InstanceRefreshStrategy.ROLLING,
+                minHealthyPercentage: resolved.minHealthyPercentage ??
+                    (hasPersistentDataVolume
+                        ? INSTANCE_REFRESH_PDV_MIN_HEALTHY
+                        : INSTANCE_REFRESH_DEFAULT_MIN_HEALTHY),
+                maxHealthyPercentage: resolved.maxHealthyPercentage ??
+                    (hasPersistentDataVolume
+                        ? INSTANCE_REFRESH_PDV_MAX_HEALTHY
+                        : INSTANCE_REFRESH_DEFAULT_MAX_HEALTHY)
             });
         default:
             return assertNever(resolved);
@@ -139,7 +153,7 @@ export class Ec2Instance extends Construct {
                 ? SubnetType.PUBLIC
                 : resolvePrivateSubnetType(this.vpc)
         };
-        const resolvedUpdatePolicy = resolveUpdatePolicy(props.updatePolicy);
+        const resolvedUpdatePolicy = resolveUpdatePolicy(props.updatePolicy, props.persistentDataVolume !== undefined);
         const baseAsgProps = {
             vpc: this.vpc,
             vpcSubnets,
@@ -242,8 +256,11 @@ export class Ec2Instance extends Construct {
     addPersistentDataVolume(props) {
         if (props.persistentDataVolume === undefined)
             return;
+        if (props.dataVolumeStableOwnerId === undefined)
+            return; // unreachable: validateEc2InstanceProps rejects the pair
         this.persistentDataVolume = new PersistentDataVolume(this, `${props.serviceName}PersistentDataVolume`, {
             autoScalingGroup: this.autoScalingGroup,
+            stableOwnerId: props.dataVolumeStableOwnerId,
             ...props.persistentDataVolume
         });
     }
@@ -282,6 +299,13 @@ function validateEc2InstanceProps(props) {
         throw new Error(`Ec2Instance.maxCapacity (${props.maxCapacity}) must be >= minCapacity (${props.minCapacity})`);
     }
     if (props.persistentDataVolume !== undefined) {
+        if (props.dataVolumeStableOwnerId === undefined ||
+            props.dataVolumeStableOwnerId === "") {
+            throw new Error("Ec2Instance.persistentDataVolume requires dataVolumeStableOwnerId — " +
+                "the volume's re-attach identity must be an explicit, stable " +
+                "caller decision (it becomes the fjall:OwnerLogicalId tag the " +
+                "lifecycle Lambdas filter on)");
+        }
         const azs = props.vpcSubnets?.availabilityZones;
         if (azs === undefined || azs.length !== 1) {
             throw new Error(`Ec2Instance.persistentDataVolume requires vpcSubnets.availabilityZones to be exactly 1 entry; got ${azs?.length ?? 0}`);

package/dist/lib/resources/aws/compute/ecsCapacityConfig.d.ts

@@ -1,23 +1,58 @@
+import { type CapacityIdentityPin } from "@fjall/util";
 import type { Ec2CapacityConfig, EcsCapacityProvider } from "./ecsTypes.js";
-/** The service + ec2Config that first claimed an EC2 capacity key. */
+/** The service + ec2Config that first claimed a capacity slot. */
 export interface Ec2AsgOrigin {
     serviceName: string;
     ec2Config: Ec2CapacityConfig;
+    /** Identity anchor the slot's ASG was built with (pin-frozen or slot-derived). */
+    anchor: string;
 }
+/** The slot this ec2Config binds to (`"primary"` when undeclared). */
+export declare function resolveCapacitySlot(ec2Config: Ec2CapacityConfig): string;
+/** Rejects at synth a slot name outside the kebab grammar. */
+export declare function assertValidCapacitySlot(slot: string): void;
+/**
+ * The identity anchor every CloudFormation identity surface derives from.
+ * Precedence: explicit `identityAnchor` config pin, then the deploy-injected
+ * context pin's `legacyAnchor`, then `toPascalCase(slot)`. The anchor grammar
+ * is validated whichever source wins — a bad anchor corrupts every logical
+ * ID and physical name downstream.
+ */
+export declare function resolveCapacityAnchor(ec2Config: Ec2CapacityConfig, pin?: CapacityIdentityPin): string;
+/**
+ * Rejects at synth two slots whose anchors collide (`web-1` and `web1` both
+ * normalise to `Web1`) — colliding anchors mean colliding logical IDs.
+ * `anchorsBySlot` carries every anchor already resolved for the cluster.
+ */
+export declare function assertAnchorUnique(slot: string, anchor: string, anchorsBySlot: ReadonlyMap<string, string>): void;
 /**
  * Rejects at synth when a service reusing a shared ASG is incompatible with
- * it: either the origin's `persistentDataVolume` makes the ASG a singleton
- * (two tasks would race to attach the same EBS volume), or the reusing
- * service asks for ASG settings that differ from the ones the ASG was built
- * with — those settings would be silently ignored (same silent-ignore class
- * as `validateEc2ServiceSizing`).
+ * it: the slot's identity is contested (`identityAnchor` disagreement), the
+ * origin's `persistentDataVolume` makes the slot a singleton (two tasks
+ * would race to attach the same EBS volume), or the reusing service asks for
+ * ASG settings that differ from the ones the ASG was built with — those
+ * settings would be silently ignored (same silent-ignore class as
+ * `validateEc2ServiceSizing`).
  */
-export declare function assertSharedAsgConfigMatches(serviceName: string, ec2Config: Ec2CapacityConfig, key: string, origin: Ec2AsgOrigin): void;
+export declare function assertSharedAsgConfigMatches(serviceName: string, ec2Config: Ec2CapacityConfig, slot: string, origin: Ec2AsgOrigin): void;
 /**
- * Generates a unique key for EC2 config so services with matching
- * configurations share an ASG.
+ * Config fields that fed the pre-6.0 (config-keyed) identity derivation —
+ * the "identity derives from …" causes named in manifest identity aliases.
+ */
+export declare const LEGACY_KEY_FIELDS: readonly string[];
+/**
+ * The pre-6.0 config-derived identity key. SURVIVES ONLY as the legacy
+ * checksum behind manifest identity-alias hints (`legacyKey`/`legacyAnchor`)
+ * — it feeds no construct IDs, no physical names and no template properties.
+ * ASG sharing keys on the capacity SLOT.
  */
 export declare function getEc2ConfigKey(ec2Config: Ec2CapacityConfig): string;
+/**
+ * The anchor a pre-6.0 synth derived from a config key — the exact `safeKey`
+ * strip the factory used (`key.replace(/[^a-zA-Z0-9]/g, "")`). Feeds the
+ * manifest alias hints and pin capture; never a live identity surface.
+ */
+export declare function legacyAnchorFromKey(key: string): string;
 /**
  * Minimal structural input for {@link validateSharedEc2CapacityConfig} —
  * exactly the fields the check reads. Both the resources-layer
@@ -31,13 +66,18 @@ export interface SharedEc2CapacityServiceInput {
     ec2Config?: Ec2CapacityConfig;
 }
 /**
- * Cross-service shared-ASG compatibility: groups EC2 services by their
- * capacity key and rejects a reuse that is incompatible with the ASG's origin
- * — config drift the shared ASG would silently discard, or a
- * `persistentDataVolume` singleton being shared. Pure; called from BOTH
- * validation layers — resources `validateEcsClusterProps` and patterns
- * `validateEcsProps` (generator-standards § "Validate at the Lowest Layer the
- * Field Belongs To") — with the same check at the construction site
+ * Cross-service capacity-slot compatibility: validates slot grammar, rejects
+ * anchor collisions across slots, and rejects a slot reuse that is
+ * incompatible with the slot's origin — config drift the shared ASG would
+ * silently discard, a contested identity, or a `persistentDataVolume`
+ * singleton being shared. Pure; called from BOTH validation layers —
+ * resources `validateEcsClusterProps` and patterns `validateEcsProps`
+ * (generator-standards § "Validate at the Lowest Layer the Field Belongs To")
+ * — with the same checks at the construction site
  * (`getOrCreateAsgCapacityProvider`) as defence-in-depth.
+ *
+ * Anchor collisions are checked on the PIN-BLIND anchor (`identityAnchor` or
+ * slot derivation) — this layer is pure and cannot read the deploy-injected
+ * context pins. The factory re-checks with pins applied.
  */
 export declare function validateSharedEc2CapacityConfig(services: readonly SharedEc2CapacityServiceInput[]): void;