@fjall/components-infrastructure 6.0.0 → 7.0.0

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

@@ -1,6 +1,8 @@
 import { AmiHardwareType } from "aws-cdk-lib/aws-ecs";
 import { Token } from "aws-cdk-lib";
-import { DEFAULT_EC2_INSTANCE_TYPE, DEFAULT_EC2_MIN_CAPACITY, DEFAULT_EC2_MAX_CAPACITY, DEFAULT_EC2_INSTANCE_MONITORING, DEFAULT_WARM_POOL_MIN_SIZE, DEFAULT_WARM_POOL_REUSE_ON_SCALE_IN, inferAmiHardwareType } from "./ecsConstants.js";
+import { CAPACITY_ANCHOR_MAX_LENGTH, CAPACITY_ANCHOR_PATTERN, CAPACITY_SLOT_MAX_LENGTH, CAPACITY_SLOT_PATTERN, DEFAULT_CAPACITY_SLOT } from "@fjall/util";
+import { toPascalCase } from "../../../utils/capitaliseString.js";
+import { DEFAULT_EC2_INSTANCE_TYPE, DEFAULT_EC2_MIN_CAPACITY, DEFAULT_EC2_MAX_CAPACITY, DEFAULT_EC2_INSTANCE_MONITORING, DEFAULT_ROLLING_UPDATE_PAUSE_SECONDS, DEFAULT_WARM_POOL_MIN_SIZE, DEFAULT_WARM_POOL_REUSE_ON_SCALE_IN, INSTANCE_REFRESH_DEFAULT_MAX_HEALTHY, INSTANCE_REFRESH_DEFAULT_MIN_HEALTHY, INSTANCE_REFRESH_PDV_MAX_HEALTHY, INSTANCE_REFRESH_PDV_MIN_HEALTHY, inferAmiHardwareType } from "./ecsConstants.js";
 /**
  * Every `Ec2CapacityConfig` field, classified. The `Record<keyof …, …>`
  * satisfies-shape is a compile-time exhaustiveness guard in compiled `src/`
@@ -10,43 +12,116 @@ import { DEFAULT_EC2_INSTANCE_TYPE, DEFAULT_EC2_MIN_CAPACITY, DEFAULT_EC2_MAX_CA
  * silently discarded on a shared ASG" bucket.
  */
 const EC2_CONFIG_FIELD_ROLES = {
-    instanceType: "keyed",
-    amiHardwareType: "keyed",
-    warmPool: "keyed",
-    persistentDataVolume: "keyed",
-    availabilityZones: "keyed",
-    minCapacity: "scalar",
-    maxCapacity: "scalar",
-    desiredCapacity: "scalar",
-    instanceMonitoring: "scalar",
-    associatePublicIpAddress: "scalar",
-    machineImage: "opaque",
-    userData: "opaque",
-    blockDevices: "opaque",
-    tags: "tags",
-    memoryLimitMiB: "taskDefinition"
+    slot: "identity",
+    identityAnchor: "identity",
+    instanceType: "property:scalar",
+    amiHardwareType: "property:scalar",
+    minCapacity: "property:scalar",
+    maxCapacity: "property:scalar",
+    desiredCapacity: "property:scalar",
+    instanceMonitoring: "property:scalar",
+    associatePublicIpAddress: "property:scalar",
+    warmPool: "property:deep",
+    persistentDataVolume: "property:deep",
+    availabilityZones: "property:deep",
+    updatePolicy: "property:deep",
+    machineImage: "property:opaque",
+    userData: "property:opaque",
+    blockDevices: "property:opaque",
+    tags: "property:tags",
+    memoryLimitMiB: "validation"
 };
 function fieldsWithRole(role) {
     return Object.keys(EC2_CONFIG_FIELD_ROLES).filter((field) => EC2_CONFIG_FIELD_ROLES[field] === role);
 }
-const KEYED_ASG_FIELDS = fieldsWithRole("keyed");
-const SCALAR_ASG_FIELDS = fieldsWithRole("scalar");
-const OPAQUE_ASG_FIELDS = fieldsWithRole("opaque");
+const SCALAR_ASG_FIELDS = fieldsWithRole("property:scalar");
+const DEEP_ASG_FIELDS = fieldsWithRole("property:deep");
+const OPAQUE_ASG_FIELDS = fieldsWithRole("property:opaque");
+/** The `"ARM" | "STANDARD"` label the config key and drift compare share. */
+function resolvedAmiHardwareLabel(config) {
+    return (config.amiHardwareType ??
+        (inferAmiHardwareType(config.instanceType ?? DEFAULT_EC2_INSTANCE_TYPE) ===
+            AmiHardwareType.ARM
+            ? "ARM"
+            : "STANDARD"));
+}
 /**
- * Defaults resolved before a scalar field is compared — the SAME values the
- * ASG construction applies (`getOrCreateAsgCapacityProvider`), imported from
- * their `ecsConstants.ts` single source, so an explicit value equal to the
- * default compares equal to an omitted one instead of tripping the drift
+ * Per-field resolution before a scalar field is compared — the SAME values
+ * the ASG construction applies (`getOrCreateAsgCapacityProvider`), imported
+ * from their `ecsConstants.ts` single source, so an explicit value equal to
+ * the default compares equal to an omitted one instead of tripping the drift
  * throw on a pair that synthesises identically. Fields with no construction
  * default (`desiredCapacity`, `associatePublicIpAddress`) compare raw.
  */
-const SCALAR_ASG_FIELD_DEFAULTS = {
-    minCapacity: DEFAULT_EC2_MIN_CAPACITY,
-    maxCapacity: DEFAULT_EC2_MAX_CAPACITY,
-    instanceMonitoring: DEFAULT_EC2_INSTANCE_MONITORING
+const SCALAR_ASG_FIELD_RESOLVERS = {
+    instanceType: (c) => c.instanceType ?? DEFAULT_EC2_INSTANCE_TYPE,
+    amiHardwareType: resolvedAmiHardwareLabel,
+    minCapacity: (c) => c.minCapacity ?? DEFAULT_EC2_MIN_CAPACITY,
+    maxCapacity: (c) => c.maxCapacity ?? DEFAULT_EC2_MAX_CAPACITY,
+    instanceMonitoring: (c) => c.instanceMonitoring ?? DEFAULT_EC2_INSTANCE_MONITORING
 };
 function resolvedScalar(config, field) {
-    return config[field] ?? SCALAR_ASG_FIELD_DEFAULTS[field];
+    const resolver = SCALAR_ASG_FIELD_RESOLVERS[field];
+    return resolver !== undefined ? resolver(config) : config[field];
+}
+/**
+ * JSON-stable projections for the plain-data config objects, defaults
+ * resolved. `persistentDataVolume.alarmTopic` is a CDK `ITopic` — projected
+ * to defined-vs-undefined like the opaque fields. `updatePolicy.pauseTime`
+ * is a literal `Duration` — projected to seconds.
+ */
+const DEEP_ASG_FIELD_PROJECTIONS = {
+    warmPool: (c) => c.warmPool === undefined
+        ? undefined
+        : {
+            minSize: c.warmPool.minSize ?? DEFAULT_WARM_POOL_MIN_SIZE,
+            reuseOnScaleIn: c.warmPool.reuseOnScaleIn ?? DEFAULT_WARM_POOL_REUSE_ON_SCALE_IN
+        },
+    persistentDataVolume: (c) => c.persistentDataVolume === undefined
+        ? undefined
+        : {
+            sizeGb: c.persistentDataVolume.sizeGb,
+            deviceName: c.persistentDataVolume.deviceName,
+            availabilityZone: stableAzSegment(c.persistentDataVolume.availabilityZone),
+            volumeType: c.persistentDataVolume.volumeType,
+            iops: c.persistentDataVolume.iops,
+            throughputMbps: c.persistentDataVolume.throughputMbps,
+            alarmTopicDefined: c.persistentDataVolume.alarmTopic !== undefined
+        },
+    availabilityZones: (c) => c.availabilityZones === undefined
+        ? undefined
+        : [...c.availabilityZones].map(stableAzSegment).sort(),
+    updatePolicy: (c) => {
+        // Mirrors resolveUpdatePolicy (ec2.ts): explicit-equal-to-default ≠ drift.
+        const policy = c.updatePolicy ?? { type: "instanceRefresh" };
+        const hasPdv = c.persistentDataVolume !== undefined;
+        switch (policy.type) {
+            case "rollingUpdate":
+                return {
+                    type: policy.type,
+                    pauseTimeSeconds: policy.pauseTime?.toSeconds() ??
+                        DEFAULT_ROLLING_UPDATE_PAUSE_SECONDS
+                };
+            case "instanceRefresh":
+                return {
+                    type: policy.type,
+                    minHealthyPercentage: policy.minHealthyPercentage ??
+                        (hasPdv
+                            ? INSTANCE_REFRESH_PDV_MIN_HEALTHY
+                            : INSTANCE_REFRESH_DEFAULT_MIN_HEALTHY),
+                    maxHealthyPercentage: policy.maxHealthyPercentage ??
+                        (hasPdv
+                            ? INSTANCE_REFRESH_PDV_MAX_HEALTHY
+                            : INSTANCE_REFRESH_DEFAULT_MAX_HEALTHY)
+                };
+            default:
+                return { type: policy.type };
+        }
+    }
+};
+function projectedDeep(config, field) {
+    const projection = DEEP_ASG_FIELD_PROJECTIONS[field];
+    return JSON.stringify(projection !== undefined ? projection(config) : config[field]);
 }
 /** Deep tag-record equality, treating `{}` and absent as the same ASG shape. */
 function tagRecordsEqual(a, b) {
@@ -60,6 +135,11 @@ function tagRecordsEqual(a, b) {
 }
 function findDifferingAsgFields(ec2Config, origin) {
     const differing = SCALAR_ASG_FIELDS.filter((field) => !Object.is(resolvedScalar(ec2Config, field), resolvedScalar(origin, field)));
+    for (const field of DEEP_ASG_FIELDS) {
+        if (projectedDeep(ec2Config, field) !== projectedDeep(origin, field)) {
+            differing.push(field);
+        }
+    }
     if (!tagRecordsEqual(ec2Config.tags, origin.tags))
         differing.push("tags");
     for (const field of OPAQUE_ASG_FIELDS) {
@@ -69,59 +149,123 @@ function findDifferingAsgFields(ec2Config, origin) {
     }
     return differing;
 }
+/** The slot this ec2Config binds to (`"primary"` when undeclared). */
+export function resolveCapacitySlot(ec2Config) {
+    return ec2Config.slot ?? DEFAULT_CAPACITY_SLOT;
+}
+/** Rejects at synth a slot name outside the kebab grammar. */
+export function assertValidCapacitySlot(slot) {
+    if (slot.length > CAPACITY_SLOT_MAX_LENGTH ||
+        !CAPACITY_SLOT_PATTERN.test(slot)) {
+        throw new Error(`EC2 capacity slot '${slot}' is invalid — slot names are lowercase kebab ` +
+            `(letter first, e.g. 'primary', 'clickhouse-data'), max ` +
+            `${CAPACITY_SLOT_MAX_LENGTH} characters.`);
+    }
+}
+/**
+ * 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 function resolveCapacityAnchor(ec2Config, pin) {
+    const anchor = ec2Config.identityAnchor ??
+        pin?.legacyAnchor ??
+        toPascalCase(resolveCapacitySlot(ec2Config));
+    if (anchor.length > CAPACITY_ANCHOR_MAX_LENGTH ||
+        !CAPACITY_ANCHOR_PATTERN.test(anchor)) {
+        throw new Error(`EC2 capacity identity anchor '${anchor}' is invalid — anchors are ` +
+            `alphanumeric, start with a letter, max ${CAPACITY_ANCHOR_MAX_LENGTH} ` +
+            `characters.`);
+    }
+    return anchor;
+}
+/**
+ * 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 function assertAnchorUnique(slot, anchor, anchorsBySlot) {
+    for (const [otherSlot, otherAnchor] of anchorsBySlot) {
+        if (otherSlot !== slot && otherAnchor === anchor) {
+            throw new Error(`EC2 capacity slots '${otherSlot}' and '${slot}' both resolve to ` +
+                `identity anchor '${anchor}' — their CloudFormation logical IDs ` +
+                `would collide. Rename one slot (or adjust its identityAnchor).`);
+        }
+    }
+}
 /**
  * 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 function assertSharedAsgConfigMatches(serviceName, ec2Config, key, origin) {
+export function assertSharedAsgConfigMatches(serviceName, ec2Config, slot, origin) {
+    if (ec2Config.identityAnchor !== origin.ec2Config.identityAnchor) {
+        const describe = (anchor) => anchor === undefined ? "unset" : `'${anchor}'`;
+        throw new Error(`Service '${serviceName}': ec2Config.identityAnchor ` +
+            `(${describe(ec2Config.identityAnchor)}) disagrees with service ` +
+            `'${origin.serviceName}' (${describe(origin.ec2Config.identityAnchor)}) ` +
+            `for capacity slot '${slot}' — a slot has exactly one identity. ` +
+            `Align the pin, or declare a second slot.`);
+    }
     // Cross-service only: the construction path legitimately re-resolves the
     // SAME service's provider (e.g. a second task definition riding its ASG),
     // and that re-entry must not trip the singleton throw.
     if (origin.ec2Config.persistentDataVolume !== undefined &&
         serviceName !== origin.serviceName) {
-        throw new Error(`Service '${serviceName}': its ec2Config resolves to the same EC2 capacity key ('${key}') ` +
-            `as service '${origin.serviceName}', whose persistentDataVolume pairs that auto scaling ` +
-            `group with a single EBS data volume. A persistent-data-volume service is a singleton — ` +
-            `two services sharing its ASG would race to attach the same volume. Change a keyed field ` +
-            `(${KEYED_ASG_FIELDS.map((f) => `'${f}'`).join(", ")}) so this service gets its own ASG.`);
+        throw new Error(`Service '${serviceName}': it declares the same capacity slot ` +
+            `('${slot}') as service '${origin.serviceName}', whose ` +
+            `persistentDataVolume pairs that auto scaling group with a single ` +
+            `EBS data volume. A persistent-data-volume slot is a singleton — ` +
+            `two services sharing its ASG would race to attach the same volume. ` +
+            `Declare a separate slot for this service.`);
     }
     const differing = findDifferingAsgFields(ec2Config, origin.ec2Config);
     if (differing.length === 0)
         return;
     throw new Error(`Service '${serviceName}': ec2Config ${differing.map((f) => `'${f}'`).join(", ")} ` +
-        `${differing.length === 1 ? "is" : "are"} ignored — it shares an auto scaling group with ` +
-        `service '${origin.serviceName}' (both resolve to EC2 capacity key '${key}'), and that ASG ` +
-        `is built from the first service's ec2Config. Either give the two services the same value ` +
-        `for ${differing.map((f) => `'${f}'`).join(", ")}, or give this service its own ASG by ` +
-        `changing a keyed field (${KEYED_ASG_FIELDS.map((f) => `'${f}'`).join(", ")}).`);
+        `${differing.length === 1 ? "is" : "are"} ignored — it shares capacity ` +
+        `slot '${slot}' with service '${origin.serviceName}', and that slot's ` +
+        `ASG is built from the first service's ec2Config. Align the two ` +
+        `services' values for ${differing.map((f) => `'${f}'`).join(", ")}, or ` +
+        `declare a second slot to give this service its own ASG.`);
 }
 /**
- * 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 const LEGACY_KEY_FIELDS = [
+    "instanceType",
+    "amiHardwareType",
+    "warmPool",
+    "persistentDataVolume",
+    "availabilityZones"
+];
+/**
+ * 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 function getEc2ConfigKey(ec2Config) {
     const instanceType = ec2Config.instanceType ?? DEFAULT_EC2_INSTANCE_TYPE;
-    const amiHardwareType = ec2Config.amiHardwareType ??
-        (inferAmiHardwareType(instanceType) === AmiHardwareType.ARM
-            ? "ARM"
-            : "STANDARD");
+    const amiHardwareType = resolvedAmiHardwareLabel(ec2Config);
     const warmPoolKey = ec2Config.warmPool
         ? `wp${ec2Config.warmPool.minSize ?? DEFAULT_WARM_POOL_MIN_SIZE}-${ec2Config.warmPool.reuseOnScaleIn ?? DEFAULT_WARM_POOL_REUSE_ON_SCALE_IN}`
         : "nowp";
     const baseKey = `${instanceType}-${amiHardwareType}-${warmPoolKey}`;
-    // PDV services are implicit singletons — two identical PDV configs still
-    // collide on this key, so sharing is rejected in assertSharedAsgConfigMatches.
     const pdv = ec2Config.persistentDataVolume;
     const extras = [];
     if (pdv !== undefined) {
         extras.push(`pdv-${pdv.deviceName}-${pdv.sizeGb}-${stableAzSegment(pdv.availabilityZone)}`);
     }
     // Serialise actual AZ names — `az${length}` would let services pinned to different AZs collide on `az1`.
-    // CDK Tokens (env-agnostic stacks) substitute a stable sentinel to keep logical IDs deterministic.
+    // CDK Tokens (env-agnostic stacks) substitute a stable sentinel to keep the checksum deterministic.
     if (ec2Config.availabilityZones !== undefined) {
         const azKey = [...ec2Config.availabilityZones]
             .map(stableAzSegment)
@@ -131,31 +275,49 @@ export function getEc2ConfigKey(ec2Config) {
     }
     return extras.length === 0 ? baseKey : `${baseKey}-${extras.join("-")}`;
 }
+/**
+ * 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 function legacyAnchorFromKey(key) {
+    return key.replace(/[^a-zA-Z0-9]/g, "");
+}
 function stableAzSegment(az) {
     return Token.isUnresolved(az) ? "synthAz" : az;
 }
 /**
- * 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 function validateSharedEc2CapacityConfig(services) {
     const origins = new Map();
+    const anchorsBySlot = new Map();
     for (const service of services) {
         if (service.capacityProvider !== "EC2")
             continue;
         const ec2Config = service.ec2Config ?? {};
-        const key = getEc2ConfigKey(ec2Config);
-        const origin = origins.get(key);
+        const slot = resolveCapacitySlot(ec2Config);
+        assertValidCapacitySlot(slot);
+        const origin = origins.get(slot);
         if (origin === undefined) {
-            origins.set(key, { serviceName: service.name, ec2Config });
+            const anchor = resolveCapacityAnchor(ec2Config);
+            assertAnchorUnique(slot, anchor, anchorsBySlot);
+            anchorsBySlot.set(slot, anchor);
+            origins.set(slot, { serviceName: service.name, ec2Config, anchor });
             continue;
         }
-        assertSharedAsgConfigMatches(service.name, ec2Config, key, origin);
+        assertSharedAsgConfigMatches(service.name, ec2Config, slot, origin);
     }
 }

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

@@ -12,6 +12,21 @@ export declare const DEFAULT_EC2_CONTAINER_MEMORY_MIB = 1024;
 export declare const DEFAULT_EC2_MIN_CAPACITY = 2;
 export declare const DEFAULT_EC2_MAX_CAPACITY = 3;
 export declare const DEFAULT_EC2_INSTANCE_MONITORING = Monitoring.BASIC;
+/**
+ * `updatePolicy` construction defaults, read at the same two must-agree sites
+ * as the capacity defaults above: `resolveUpdatePolicy` (ec2.ts) applies them
+ * at construction; the shared-ASG drift compare (`ecsCapacityConfig.ts`
+ * DEEP_ASG_FIELD_PROJECTIONS) resolves them so an explicit value equal to the
+ * default never reads as drift. A `persistentDataVolume` ASG cannot surge
+ * (its single-attach EBS volume can only follow one instance), so it
+ * terminates-then-launches (0/100); every other ASG surges-then-shrinks
+ * (100/200) so capacity never dips.
+ */
+export declare const INSTANCE_REFRESH_PDV_MIN_HEALTHY = 0;
+export declare const INSTANCE_REFRESH_PDV_MAX_HEALTHY = 100;
+export declare const INSTANCE_REFRESH_DEFAULT_MIN_HEALTHY = 100;
+export declare const INSTANCE_REFRESH_DEFAULT_MAX_HEALTHY = 200;
+export declare const DEFAULT_ROLLING_UPDATE_PAUSE_SECONDS = 300;
 /**
  * The container hard memory limit for an EC2-capacity ECS service.
  *

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

@@ -25,6 +25,21 @@ export const DEFAULT_EC2_CONTAINER_MEMORY_MIB = 1024;
 export const DEFAULT_EC2_MIN_CAPACITY = 2;
 export const DEFAULT_EC2_MAX_CAPACITY = 3;
 export const DEFAULT_EC2_INSTANCE_MONITORING = Monitoring.BASIC;
+/**
+ * `updatePolicy` construction defaults, read at the same two must-agree sites
+ * as the capacity defaults above: `resolveUpdatePolicy` (ec2.ts) applies them
+ * at construction; the shared-ASG drift compare (`ecsCapacityConfig.ts`
+ * DEEP_ASG_FIELD_PROJECTIONS) resolves them so an explicit value equal to the
+ * default never reads as drift. A `persistentDataVolume` ASG cannot surge
+ * (its single-attach EBS volume can only follow one instance), so it
+ * terminates-then-launches (0/100); every other ASG surges-then-shrinks
+ * (100/200) so capacity never dips.
+ */
+export const INSTANCE_REFRESH_PDV_MIN_HEALTHY = 0;
+export const INSTANCE_REFRESH_PDV_MAX_HEALTHY = 100;
+export const INSTANCE_REFRESH_DEFAULT_MIN_HEALTHY = 100;
+export const INSTANCE_REFRESH_DEFAULT_MAX_HEALTHY = 200;
+export const DEFAULT_ROLLING_UPDATE_PAUSE_SECONDS = 300;
 /**
  * The container hard memory limit for an EC2-capacity ECS service.
  *

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

@@ -15,13 +15,14 @@ import type { EcsConstructContext } from "./ecsContext.js";
 export declare function resolveCircuitBreaker(config: false | {
     rollback?: boolean;
 } | undefined): DeploymentCircuitBreaker | undefined;
-/** Mutable state for ASG capacity provider deduplication. */
+/** Mutable state for ASG capacity provider deduplication, keyed by SLOT. */
 export interface AsgCapacityState {
     providers: Map<string, AsgCapacityProvider>;
     /**
-     * The service + ec2Config that first created each keyed ASG, so a later
-     * service sharing the key can be checked against it
-     * ({@link assertSharedAsgConfigMatches}).
+     * The service + ec2Config + anchor that first claimed each capacity slot,
+     * so a later service declaring the slot can be checked against it
+     * ({@link assertSharedAsgConfigMatches}) and anchor collisions across
+     * slots rejected ({@link assertAnchorUnique}).
      */
     asgOrigins: Map<string, Ec2AsgOrigin>;
     autoScalingGroup?: AutoScalingGroup;
@@ -30,9 +31,18 @@ export interface AsgCapacityState {
 export { getEc2ConfigKey, validateSharedEc2CapacityConfig, type Ec2AsgOrigin, type SharedEc2CapacityServiceInput } from "./ecsCapacityConfig.js";
 /**
  * Gets or creates an ASG capacity provider for an EC2-backed service.
- * Services with matching EC2 configs share the same ASG.
+ * Services declaring the same capacity SLOT share the same ASG.
  *
- * Mutates `state` to track the provider and first ASG/security group.
+ * Every CloudFormation identity surface (the four construct-ID prefixes,
+ * the physical service name and everything `Ec2Instance` derives from it)
+ * comes from the slot's identity ANCHOR — `identityAnchor` pin, else the
+ * deploy-injected `fjall:capacityIdentity` context pin, else
+ * `toPascalCase(slot)` — never from the hardware config, so a config change
+ * updates the deployed ASG in place instead of renaming (replacing) it.
+ *
+ * Mutates `state` to track the provider and first ASG/security group, and
+ * records the slot's identity alias on the manifest collector (rename
+ * detection and the pin writer consume it).
  */
 export declare function getOrCreateAsgCapacityProvider(ctx: EcsConstructContext, serviceProps: EcsServiceProps, state: AsgCapacityState): AsgCapacityProvider;
 /**

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

@@ -2,7 +2,7 @@ import { FargateService, Ec2Service, PropagatedTagSource, PlacementStrategy, Asg
 import { Peer, Port, SubnetType, UserData } from "aws-cdk-lib/aws-ec2";
 import { ServicePrincipal } from "aws-cdk-lib/aws-iam";
 import { Role } from "../iam/role.js";
-import { CfnOutput, Duration } from "aws-cdk-lib";
+import { Aws, CfnOutput, Duration } from "aws-cdk-lib";
 import { AdjustmentType, PredefinedMetric, ScalableTarget, ServiceNamespace, StepScalingAction, TargetTrackingScalingPolicy } from "aws-cdk-lib/aws-applicationautoscaling";
 import { Alarm, ComparisonOperator, MathExpression } from "aws-cdk-lib/aws-cloudwatch";
 import { ApplicationScalingAction } from "aws-cdk-lib/aws-cloudwatch-actions";
@@ -11,7 +11,9 @@ import { Ec2Instance } from "./ec2.js";
 import { vpcHasNatGateways } from "../../../utils/vpcUtils.js";
 import { toPascalCase } from "../../../utils/capitaliseString.js";
 import { DEFAULT_EC2_INSTANCE_TYPE, DEFAULT_EC2_MIN_CAPACITY, DEFAULT_EC2_MAX_CAPACITY, DEFAULT_EC2_INSTANCE_MONITORING, DEFAULT_WARM_POOL_MIN_SIZE, DEFAULT_WARM_POOL_REUSE_ON_SCALE_IN, DEFAULT_HEALTH_CHECK_GRACE_SECONDS, DEFAULT_MIN_HEALTHY_PERCENT, DEFAULT_MAX_HEALTHY_PERCENT, DEFAULT_DESIRED_COUNT, inferAmiHardwareType } from "./ecsConstants.js";
-import { assertSharedAsgConfigMatches, getEc2ConfigKey } from "./ecsCapacityConfig.js";
+import { assertAnchorUnique, assertSharedAsgConfigMatches, assertValidCapacitySlot, getEc2ConfigKey, legacyAnchorFromKey, LEGACY_KEY_FIELDS, resolveCapacityAnchor, resolveCapacitySlot } from "./ecsCapacityConfig.js";
+import { lookupCapacityIdentityPin } from "../../../utils/capacityIdentityContext.js";
+import { getCurrentCollector } from "../../../utils/manifestWriter.js";
 import { ScalingType } from "./ecsTypes.js";
 import { isServiceFargate, isServiceEc2 } from "./ecsTaskDefinition.js";
 /**
@@ -29,23 +31,60 @@ export function resolveCircuitBreaker(config) {
 export { getEc2ConfigKey, validateSharedEc2CapacityConfig } from "./ecsCapacityConfig.js";
 /**
  * Gets or creates an ASG capacity provider for an EC2-backed service.
- * Services with matching EC2 configs share the same ASG.
+ * Services declaring the same capacity SLOT share the same ASG.
  *
- * Mutates `state` to track the provider and first ASG/security group.
+ * Every CloudFormation identity surface (the four construct-ID prefixes,
+ * the physical service name and everything `Ec2Instance` derives from it)
+ * comes from the slot's identity ANCHOR — `identityAnchor` pin, else the
+ * deploy-injected `fjall:capacityIdentity` context pin, else
+ * `toPascalCase(slot)` — never from the hardware config, so a config change
+ * updates the deployed ASG in place instead of renaming (replacing) it.
+ *
+ * Mutates `state` to track the provider and first ASG/security group, and
+ * records the slot's identity alias on the manifest collector (rename
+ * detection and the pin writer consume it).
  */
 export function getOrCreateAsgCapacityProvider(ctx, serviceProps, state) {
     const ec2Config = serviceProps.ec2Config ?? {};
-    const key = getEc2ConfigKey(ec2Config);
-    const existing = state.providers.get(key);
+    const slot = resolveCapacitySlot(ec2Config);
+    assertValidCapacitySlot(slot);
+    const existing = state.providers.get(slot);
     if (existing) {
-        const origin = state.asgOrigins.get(key);
+        const origin = state.asgOrigins.get(slot);
         if (origin !== undefined) {
-            assertSharedAsgConfigMatches(serviceProps.name, ec2Config, key, origin);
+            assertSharedAsgConfigMatches(serviceProps.name, ec2Config, slot, origin);
         }
         return existing;
     }
-    state.asgOrigins.set(key, { serviceName: serviceProps.name, ec2Config });
-    const safeKey = key.replace(/[^a-zA-Z0-9]/g, "");
+    const collector = getCurrentCollector();
+    const appName = collector?.getAppName();
+    const pin = appName !== undefined
+        ? lookupCapacityIdentityPin(ctx.scope, appName, slot)
+        : undefined;
+    const anchor = resolveCapacityAnchor(ec2Config, pin);
+    assertAnchorUnique(slot, anchor, new Map([...state.asgOrigins].map(([s, o]) => [s, o.anchor])));
+    state.asgOrigins.set(slot, {
+        serviceName: serviceProps.name,
+        ec2Config,
+        anchor
+    });
+    const physicalServiceName = `${ctx.props.clusterName}${anchor}`;
+    if (collector !== null) {
+        const legacyKey = getEc2ConfigKey(ec2Config);
+        const legacyAnchor = legacyAnchorFromKey(legacyKey);
+        collector.addCapacityIdentityAlias({
+            appName: collector.getAppName(),
+            slot,
+            clusterName: ctx.props.clusterName,
+            anchor,
+            pinned: pin !== undefined || ec2Config.identityAnchor !== undefined,
+            currentServiceName: physicalServiceName,
+            legacyKey,
+            legacyAnchor,
+            legacyServiceName: `${ctx.props.clusterName}${legacyAnchor}`,
+            legacyKeyFields: [...LEGACY_KEY_FIELDS]
+        });
+    }
     const instanceType = ec2Config.instanceType ?? DEFAULT_EC2_INSTANCE_TYPE;
     const amiHardwareType = ec2Config.amiHardwareType
         ? ec2Config.amiHardwareType === "STANDARD"
@@ -54,10 +93,14 @@ export function getOrCreateAsgCapacityProvider(ctx, serviceProps, state) {
         : inferAmiHardwareType(instanceType);
     const minCapacity = ec2Config.minCapacity ?? DEFAULT_EC2_MIN_CAPACITY;
     const maxCapacity = ec2Config.maxCapacity ?? DEFAULT_EC2_MAX_CAPACITY;
+    // GroupDescription is CFN create-only: a pinned slot must reproduce the
+    // deployed string verbatim or the SG is replaced. New stacks derive it
+    // from the anchor-based physical service name, stable by construction.
     const asgSecurityGroup = ctx.props.cluster?.securityGroup ??
-        new SecurityGroup(ctx.scope, `${safeKey}AsgSecurityGroup`, {
+        new SecurityGroup(ctx.scope, `${anchor}AsgSecurityGroup`, {
             vpc: ctx.cluster.vpc,
-            description: `Security group for ${key} auto scaling group`
+            description: pin?.legacySgDescription ??
+                `Security group for the ${physicalServiceName} auto scaling group`
         });
     if (ctx.directAccessEnabled) {
         for (const service of ctx.props.services) {
@@ -80,12 +123,12 @@ export function getOrCreateAsgCapacityProvider(ctx, serviceProps, state) {
         : undefined;
     // userData + role must be set on the LaunchTemplate or AsgCapacityProvider
     // throws at synth (ProvidedLaunchTemplateExposeUser/ExposeDefine).
-    const instanceRole = new Role(ctx.scope, `${safeKey}InstanceRole`, {
+    const instanceRole = new Role(ctx.scope, `${anchor}InstanceRole`, {
         assumedBy: new ServicePrincipal("ec2.amazonaws.com"),
-        description: `EC2 instance role for ${key} ECS capacity`
+        description: `EC2 instance role for the ${slot} ECS capacity slot`
     });
-    const ec2Instance = new Ec2Instance(ctx.scope, `${safeKey}Ec2Instance`, {
-        serviceName: `${ctx.props.clusterName}${safeKey}`,
+    const ec2Instance = new Ec2Instance(ctx.scope, `${anchor}Ec2Instance`, {
+        serviceName: physicalServiceName,
         vpc: ctx.cluster.vpc,
         vpcSubnets: {
             subnetType: hasNat ? SubnetType.PRIVATE_WITH_EGRESS : SubnetType.PUBLIC,
@@ -114,6 +157,9 @@ export function getOrCreateAsgCapacityProvider(ctx, serviceProps, state) {
             associatePublicIpAddress: ec2Config.associatePublicIpAddress
         }),
         ...(resolvedWarmPool !== undefined && { warmPool: resolvedWarmPool }),
+        ...(ec2Config.updatePolicy !== undefined && {
+            updatePolicy: ec2Config.updatePolicy
+        }),
         ...(ec2Config.persistentDataVolume !== undefined && {
             persistentDataVolume: {
                 ...ec2Config.persistentDataVolume,
@@ -121,12 +167,15 @@ export function getOrCreateAsgCapacityProvider(ctx, serviceProps, state) {
                     ctx.props.alertsTopic !== undefined && {
                     alarmTopic: ctx.props.alertsTopic
                 })
-            }
+            },
+            // Pinned slots reproduce the deployed fjall:OwnerLogicalId verbatim —
+            // the re-attach Lambdas filter on it, so a drift strands the volume.
+            dataVolumeStableOwnerId: pin?.legacyOwnerId ?? `${Aws.STACK_NAME}/${anchor}/PersistentDataVolume`
         }),
         ...(ec2Config.tags !== undefined && { tags: ec2Config.tags })
     });
     const asg = ec2Instance.getAutoScalingGroup();
-    const provider = new AsgCapacityProvider(ctx.scope, `${safeKey}AsgCapacityProvider`, {
+    const provider = new AsgCapacityProvider(ctx.scope, `${anchor}AsgCapacityProvider`, {
         autoScalingGroup: asg,
         enableManagedDraining: true,
         // MTP's ProtectedFromScaleIn flag does NOT clear on CP deletion, so
@@ -139,7 +188,7 @@ export function getOrCreateAsgCapacityProvider(ctx, serviceProps, state) {
         enableManagedScaling: minCapacity !== maxCapacity
     });
     ctx.cluster.addAsgCapacityProvider(provider);
-    state.providers.set(key, provider);
+    state.providers.set(slot, provider);
     if (!state.autoScalingGroup) {
         state.autoScalingGroup = asg;
     }