import * as autoscaling from "@distilled.cloud/aws/auto-scaling";
import { deepEqual, isResolved } from "alchemy/Diff";
import type { Input } from "alchemy/Input";
import { createPhysicalName } from "alchemy/PhysicalName";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import { createInternalTags, diffTags } from "alchemy/Tags";
import { toSeconds } from "alchemy/Util/Duration";
import * as Data from "effect/Data";
import type * as Duration from "effect/Duration";
import * as Effect from "effect/Effect";
import * as Schedule from "effect/Schedule";
import * as Stream from "effect/Stream";
import type { SubnetId } from "../EC2/Subnet.ts";
import type { Providers } from "../Providers.ts";
import type {
LaunchTemplateId,
LaunchTemplateName,
LaunchTemplate as LaunchTemplateResource,
} from "./LaunchTemplate.ts";
export class AutoScalingGroupUnexpectedResponse extends Data.TaggedError(
"AutoScalingGroupUnexpectedResponse",
)<{
readonly message: string;
readonly cause?: unknown;
}> {}
export class AutoScalingGroupNotReady extends Data.TaggedError("AutoScalingGroupNotReady")<{
readonly message: string;
readonly cause?: unknown;
}> {}
export type AutoScalingGroupName = string;
export interface LaunchTemplateReference {
/**
* ID of the launch template (`lt-...`). Provide either the ID or the name,
* not both.
*/
launchTemplateId?: Input<LaunchTemplateId>;
/**
* Name of the launch template. Provide either the ID or the name, not both.
*/
launchTemplateName?: Input<LaunchTemplateName>;
/**
* Template version to launch.
* @default "$Default"
*/
version?: Input<string | number>;
}
export interface AutoScalingGroupProps {
/**
* Auto Scaling Group name. If omitted, a deterministic name is generated.
*/
autoScalingGroupName?: string;
/**
* Launch template used for instances in the fleet.
*/
launchTemplate: Input<LaunchTemplateReference> | LaunchTemplateResource;
/**
* Subnets to place the fleet into.
*/
subnetIds: Input<SubnetId[]>;
/**
* Minimum number of instances.
*/
minSize: number;
/**
* Maximum number of instances.
*/
maxSize: number;
/**
* Desired number of instances. When omitted, updates leave the live value
* alone so external scalers (e.g. ECS managed scaling) keep control.
* @default minSize
*/
desiredCapacity?: number;
/**
* Target groups to attach to the fleet.
*/
targetGroupArns?: Input<string[]>;
/**
* Health check type.
* @default "ELB" when target groups are present, otherwise "EC2"
*/
healthCheckType?: "EC2" | "ELB";
/**
* Grace period before health checks start, e.g. `"5 minutes"` or
* `Duration.seconds(300)` (whole seconds on the wire).
*/
healthCheckGracePeriod?: Duration.Input;
/**
* Default cooldown between scaling activities, e.g. `"5 minutes"` or
* `Duration.seconds(300)` (whole seconds on the wire).
*/
defaultCooldown?: Duration.Input;
/**
* Termination policies for scale-in.
*/
terminationPolicies?: string[];
/**
* Instance attributes (vCPUs, memory, burstable, generations, …) to launch
* by instead of the launch template's instance type. Auto Scaling picks
* every instance type that matches.
*
* When set, the group is configured with a mixed instances policy whose
* single override carries these requirements; removing it switches the
* group back to the plain launch template.
*/
instanceRequirements?: autoscaling.InstanceRequirements;
/**
* How capacity is spread across Availability Zones. Removing it resets the
* group to the AWS default.
* @default { CapacityDistributionStrategy: "balanced-best-effort" }
*/
availabilityZoneDistribution?: autoscaling.AvailabilityZoneDistribution;
/**
* Tags to apply to the Auto Scaling Group itself.
*/
tags?: Record<string, string>;
}
export interface AutoScalingGroup extends Resource<
"AWS.AutoScaling.AutoScalingGroup",
AutoScalingGroupProps,
{
/**
* ARN of the Auto Scaling Group.
*/
autoScalingGroupArn: string;
/**
* Name of the Auto Scaling Group.
*/
autoScalingGroupName: AutoScalingGroupName;
/**
* ID of the launch template used by the fleet.
*/
launchTemplateId?: string;
/**
* Name of the launch template used by the fleet.
*/
launchTemplateName?: string;
/**
* Launch template version used by the fleet (e.g. `"$Default"` or a
* version number).
*/
launchTemplateVersion?: string;
/**
* Subnets the fleet is placed into.
*/
subnetIds: string[];
/**
* Minimum number of instances.
*/
minSize: number;
/**
* Maximum number of instances.
*/
maxSize: number;
/**
* Desired number of instances.
*/
desiredCapacity: number;
/**
* Load balancer target groups the fleet is registered with.
*/
targetGroupArns: string[];
/**
* Health check type (`EC2` or `ELB`).
*/
healthCheckType?: string;
/**
* Grace period in seconds before health checks start.
*/
healthCheckGracePeriod?: number;
/**
* Default cooldown in seconds between scaling activities.
*/
defaultCooldown?: number;
/**
* Termination policies applied on scale-in.
*/
terminationPolicies?: string[];
/**
* Instance requirements of the group's mixed instances policy, when it
* launches by attributes rather than a fixed instance type.
*/
instanceRequirements?: autoscaling.InstanceRequirements;
/**
* How capacity is spread across Availability Zones.
*/
availabilityZoneDistribution?: autoscaling.AvailabilityZoneDistribution;
/**
* Tags on the Auto Scaling Group.
*/
tags: Record<string, string>;
},
never,
Providers
> {}
/**
* An EC2 Auto Scaling Group that manages a fleet of instances from a launch
* template and can register that fleet with one or more load balancer target
* groups.
*
* Pair with {@link ScalingPolicy} for target-tracking scaling,
* {@link ScheduledAction} for time-based capacity changes, and
* {@link consumeLifecycleActions} to run a Lambda handler while instances
* pause during launch/terminate transitions.
* ### Creating an Auto Scaling Group
* **Example:** Fleet from a Launch Template
* ```typescript
* import { AutoScalingGroup, LaunchTemplate } from "@alchemy.run/aws/AutoScaling";
* import { Subnet, Vpc } from "@alchemy.run/aws/EC2";
*
* const vpc = yield* Vpc("Vpc", { cidrBlock: "10.0.0.0/16" });
* const subnet = yield* Subnet("Subnet", {
* vpcId: vpc.vpcId,
* cidrBlock: "10.0.1.0/24",
* });
*
* const template = yield* LaunchTemplate("Template", {
* imageId: "ami-0abcdef1234567890",
* instanceType: "t3.micro",
* });
*
* const group = yield* AutoScalingGroup("Fleet", {
* launchTemplate: template,
* subnetIds: [subnet.subnetId],
* minSize: 1,
* maxSize: 3,
* });
* ```
*
* **Example:** Reference an existing Launch Template by name
* ```typescript
* const group = yield* AutoScalingGroup("Fleet", {
* launchTemplate: { launchTemplateName: "my-template", version: 2 },
* subnetIds: [subnet.subnetId],
* minSize: 0,
* maxSize: 0,
* desiredCapacity: 0,
* });
* ```
*
* ### Load Balancing
* **Example:** Register the fleet with a target group
* ```typescript
* const group = yield* AutoScalingGroup("WebFleet", {
* launchTemplate: template,
* subnetIds: [subnetA.subnetId, subnetB.subnetId],
* minSize: 2,
* maxSize: 6,
* targetGroupArns: [targetGroup.targetGroupArn],
* // healthCheckType defaults to "ELB" when target groups are attached
* healthCheckGracePeriod: "5 minutes",
* });
* ```
*
* ### Choosing Instance Types by Attributes
* **Example:** Launch any burstable type with 2 vCPUs and 4–8 GiB
* ```typescript
* const group = yield* AutoScalingGroup("Fleet", {
* launchTemplate: template,
* subnetIds: [subnetA.subnetId, subnetB.subnetId],
* minSize: 1,
* maxSize: 4,
* instanceRequirements: {
* VCpuCount: { Min: 2, Max: 2 },
* MemoryMiB: { Min: 4096, Max: 8192 },
* BurstablePerformance: "required",
* },
* // keep zones strictly balanced instead of launching elsewhere
* availabilityZoneDistribution: {
* CapacityDistributionStrategy: "balanced-only",
* },
* });
* ```
*
* ### Scaling
* **Example:** Track average CPU utilization
* ```typescript
* import { ScalingPolicy } from "@alchemy.run/aws/AutoScaling";
*
* yield* ScalingPolicy("CpuPolicy", {
* autoScalingGroup: group,
* predefinedMetricType: "ASGAverageCPUUtilization",
* targetValue: 60,
* });
* ```
*
* @resource
*/
export const AutoScalingGroup = Resource<AutoScalingGroup>("AWS.AutoScaling.AutoScalingGroup");
const DEFAULT_CAPACITY_DISTRIBUTION_STRATEGY = "balanced-best-effort";
const sortStrings = (values: readonly string[] = []) =>
[...values].sort((a, b) => a.localeCompare(b));
/**
* A launch template naming a just-created instance profile is rejected until
* IAM propagates it; retry that rejection (bounded, ~1 minute).
*/
const retryInstanceProfilePropagation = <A, R>(
effect: Effect.Effect<
A,
autoscaling.CreateAutoScalingGroupError | autoscaling.UpdateAutoScalingGroupError,
R
>,
) =>
effect.pipe(
Effect.retry({
while: (error) => error._tag === "InvalidIamInstanceProfile",
schedule: Schedule.max([Schedule.recurs(10), Schedule.exponential("1 second")]),
}),
);
export const AutoScalingGroupProvider = () =>
Provider.effect(
AutoScalingGroup,
Effect.gen(function* () {
const toName = (id: string, props: { autoScalingGroupName?: string } = {}) =>
props.autoScalingGroupName
? Effect.succeed(props.autoScalingGroupName)
: createPhysicalName({ id, maxLength: 255, lowercase: true });
const toLaunchTemplateSpec = (input: AutoScalingGroupProps["launchTemplate"]) => {
// A whole-resource `launchTemplate: template` resolves to the
// LaunchTemplate's bare Attributes before reaching the provider —
// the resource `Type` marker does not survive resolution — so narrow
// on the attributes shape (`launchTemplateArn` exists only on
// attributes, never on a LaunchTemplateReference). Attributes carry
// BOTH id and name, and the API rejects a spec with both, so send
// the id alone.
const attrs = input as Partial<LaunchTemplateResource["Attributes"]> | undefined;
if (typeof attrs?.launchTemplateArn === "string") {
return {
LaunchTemplateId: attrs.launchTemplateId as string | undefined,
LaunchTemplateName: undefined,
Version:
attrs.defaultVersionNumber === undefined
? "$Default"
: String(attrs.defaultVersionNumber),
};
}
const spec = (input ?? {}) as LaunchTemplateReference;
return {
LaunchTemplateId: spec.launchTemplateId as string | undefined,
LaunchTemplateName: spec.launchTemplateName as string | undefined,
Version:
spec.version === undefined ? "$Default" : String(spec.version as string | number),
};
};
const describeGroup = (autoScalingGroupName: string) =>
autoscaling
.describeAutoScalingGroups({
AutoScalingGroupNames: [autoScalingGroupName],
})
.pipe(Effect.map((result) => result.AutoScalingGroups?.[0]));
const toTags = (name: string, tags: Record<string, string>) =>
Object.entries(tags).map(([Key, Value]) => ({
ResourceId: name,
ResourceType: "auto-scaling-group",
Key,
Value,
PropagateAtLaunch: false,
}));
const syncTargetGroups = Effect.fn(function* ({
autoScalingGroupName,
oldTargetGroupArns,
newTargetGroupArns,
}: {
autoScalingGroupName: string;
oldTargetGroupArns: string[];
newTargetGroupArns: string[];
}) {
const oldSet = new Set(oldTargetGroupArns);
const newSet = new Set(newTargetGroupArns);
const detached = oldTargetGroupArns.filter((arn) => !newSet.has(arn));
const attached = newTargetGroupArns.filter((arn) => !oldSet.has(arn));
if (detached.length > 0) {
yield* autoscaling.detachLoadBalancerTargetGroups({
AutoScalingGroupName: autoScalingGroupName,
TargetGroupARNs: detached,
} as any);
}
if (attached.length > 0) {
yield* autoscaling.attachLoadBalancerTargetGroups({
AutoScalingGroupName: autoScalingGroupName,
TargetGroupARNs: attached,
} as any);
}
});
const syncTags = Effect.fn(function* ({
autoScalingGroupName,
oldTags,
newTags,
}: {
autoScalingGroupName: string;
oldTags: Record<string, string>;
newTags: Record<string, string>;
}) {
const { removed, upsert } = diffTags(oldTags, newTags);
if (removed.length > 0) {
yield* autoscaling.deleteTags({
Tags: removed.map((Key) => ({
ResourceId: autoScalingGroupName,
ResourceType: "auto-scaling-group",
Key,
})),
} as any);
}
if (upsert.length > 0) {
yield* autoscaling.createOrUpdateTags({
Tags: upsert.map(({ Key, Value }) => ({
ResourceId: autoScalingGroupName,
ResourceType: "auto-scaling-group",
Key,
Value,
PropagateAtLaunch: false,
})),
} as any);
}
});
const toAttributes = (
group: autoscaling.AutoScalingGroup,
): AutoScalingGroup["Attributes"] => {
// A group launching by attributes carries its template inside the
// mixed instances policy instead of `LaunchTemplate`.
const mixed = group.MixedInstancesPolicy?.LaunchTemplate;
const launchTemplate = group.LaunchTemplate ?? mixed?.LaunchTemplateSpecification;
return {
autoScalingGroupArn: group.AutoScalingGroupARN!,
autoScalingGroupName: group.AutoScalingGroupName!,
launchTemplateId: launchTemplate?.LaunchTemplateId,
launchTemplateName: launchTemplate?.LaunchTemplateName,
launchTemplateVersion: launchTemplate?.Version,
subnetIds: String(group.VPCZoneIdentifier ?? "")
.split(",")
.filter(Boolean),
minSize: group.MinSize ?? 0,
maxSize: group.MaxSize ?? 0,
desiredCapacity: group.DesiredCapacity ?? 0,
targetGroupArns: sortStrings(group.TargetGroupARNs ?? []),
healthCheckType: group.HealthCheckType,
healthCheckGracePeriod: group.HealthCheckGracePeriod,
defaultCooldown: group.DefaultCooldown,
terminationPolicies: group.TerminationPolicies ?? [],
instanceRequirements: mixed?.Overrides?.find((o) => o.InstanceRequirements)
?.InstanceRequirements,
availabilityZoneDistribution: group.AvailabilityZoneDistribution,
tags: Object.fromEntries(
(group.Tags ?? [])
.filter((tag): tag is { Key: string; Value: string } =>
Boolean(tag.Key && tag.Value !== undefined),
)
.map((tag) => [tag.Key, tag.Value]),
),
};
};
return {
stables: ["autoScalingGroupArn", "autoScalingGroupName"],
list: () =>
// `describeAutoScalingGroups` is paginated; collect every page and
// flatten the `AutoScalingGroups` array into full `Attributes`.
autoscaling.describeAutoScalingGroups.pages({}).pipe(
Stream.runCollect,
Effect.map((chunk) =>
Array.from(chunk).flatMap((page) => (page.AutoScalingGroups ?? []).map(toAttributes)),
),
),
diff: Effect.fn(function* ({ id, olds, news: _news }) {
if (!isResolved(_news)) return undefined;
const news = _news as typeof olds;
const oldName = yield* toName(id, olds ?? {});
const newName = yield* toName(id, news ?? {});
if (oldName !== newName) {
return { action: "replace", deleteFirst: true } as const;
}
if (!deepEqual(olds, news)) {
return {
action: "update",
stables: ["autoScalingGroupArn", "autoScalingGroupName"],
} as const;
}
}),
read: Effect.fn(function* ({ id, olds, output }) {
const name = output?.autoScalingGroupName ?? (yield* toName(id, olds ?? {}));
const group = yield* describeGroup(name);
return group ? toAttributes(group) : undefined;
}),
reconcile: Effect.fn(function* ({ id, news, output, session }) {
const autoScalingGroupName = output?.autoScalingGroupName ?? (yield* toName(id, news));
const desiredTags = {
...(yield* createInternalTags(id)),
...news.tags,
};
const targetGroupArns = sortStrings((news.targetGroupArns ?? []) as string[]);
// With instance requirements the template goes inside a mixed
// instances policy; without, it is the plain `LaunchTemplate`.
// Either form replaces the other on `updateAutoScalingGroup`.
const launchTemplate = news.instanceRequirements
? {
MixedInstancesPolicy: {
LaunchTemplate: {
LaunchTemplateSpecification: toLaunchTemplateSpec(news.launchTemplate),
Overrides: [{ InstanceRequirements: news.instanceRequirements }],
},
},
}
: { LaunchTemplate: toLaunchTemplateSpec(news.launchTemplate) };
const capacityDistributionStrategy =
news.availabilityZoneDistribution?.CapacityDistributionStrategy ??
DEFAULT_CAPACITY_DISTRIBUTION_STRATEGY;
const healthCheckType =
news.healthCheckType ?? (targetGroupArns.length > 0 ? "ELB" : "EC2");
// Observe — fetch live state. `describeAutoScalingGroups` returns
// an empty list when the ASG is missing; we never trust `output`
// alone since the ASG may have been deleted out of band.
let existing = yield* describeGroup(autoScalingGroupName);
// Ensure — create the ASG if missing. `createAutoScalingGroup`
// raises `AlreadyExistsFault` on a race; we fall through to the
// sync path on that case.
if (!existing) {
yield* autoscaling
.createAutoScalingGroup({
AutoScalingGroupName: autoScalingGroupName,
MinSize: news.minSize,
MaxSize: news.maxSize,
DesiredCapacity: news.desiredCapacity ?? news.minSize,
...launchTemplate,
AvailabilityZoneDistribution: {
CapacityDistributionStrategy: capacityDistributionStrategy,
},
VPCZoneIdentifier: (news.subnetIds as string[]).join(","),
TargetGroupARNs: targetGroupArns,
HealthCheckType: healthCheckType,
HealthCheckGracePeriod: toSeconds(news.healthCheckGracePeriod),
DefaultCooldown: toSeconds(news.defaultCooldown),
TerminationPolicies: news.terminationPolicies,
Tags: toTags(autoScalingGroupName, desiredTags),
} as any)
.pipe(
retryInstanceProfilePropagation,
Effect.catchTag("AlreadyExistsFault", () => Effect.void),
);
existing = yield* describeGroup(autoScalingGroupName).pipe(
Effect.filterOrFail(
Boolean,
() =>
new AutoScalingGroupUnexpectedResponse({
message: `Auto Scaling Group '${autoScalingGroupName}' was not readable after create`,
}),
),
Effect.retry({
while: () => true,
schedule: Schedule.max([Schedule.recurs(8), Schedule.exponential("250 millis")]),
}),
);
}
// Sync core ASG configuration — `updateAutoScalingGroup`
// overwrites min/max/desired/template/subnets/health-check
// settings in one call, so we issue it unconditionally
// (idempotent for matching values). The zone distribution is
// diffed against the observed group (absent = the AWS default)
// and sent only when it differs.
const observedCapacityDistributionStrategy =
existing.AvailabilityZoneDistribution?.CapacityDistributionStrategy ??
DEFAULT_CAPACITY_DISTRIBUTION_STRATEGY;
yield* autoscaling
.updateAutoScalingGroup({
AutoScalingGroupName: autoScalingGroupName,
MinSize: news.minSize,
MaxSize: news.maxSize,
DesiredCapacity: news.desiredCapacity,
...launchTemplate,
AvailabilityZoneDistribution:
observedCapacityDistributionStrategy === capacityDistributionStrategy
? undefined
: { CapacityDistributionStrategy: capacityDistributionStrategy },
VPCZoneIdentifier: (news.subnetIds as string[]).join(","),
HealthCheckType: healthCheckType,
HealthCheckGracePeriod: toSeconds(news.healthCheckGracePeriod),
DefaultCooldown: toSeconds(news.defaultCooldown),
TerminationPolicies: news.terminationPolicies,
} as any)
.pipe(retryInstanceProfilePropagation);
// Sync target groups — observed cloud attachments vs desired.
const observedAttrs = toAttributes(existing);
yield* syncTargetGroups({
autoScalingGroupName,
oldTargetGroupArns: sortStrings(existing.TargetGroupARNs ?? []),
newTargetGroupArns: targetGroupArns,
});
// Sync tags — observed cloud tags vs desired. Adoption brings
// tags through `existing.Tags`; we converge regardless of what
// was there before.
yield* syncTags({
autoScalingGroupName,
oldTags: observedAttrs.tags,
newTags: desiredTags,
});
// Re-read final state so attributes reflect post-sync cloud
// state.
const group = yield* describeGroup(autoScalingGroupName).pipe(
Effect.filterOrFail(
Boolean,
() =>
new AutoScalingGroupUnexpectedResponse({
message: `Auto Scaling Group '${autoScalingGroupName}' was not readable after reconcile`,
}),
),
);
yield* session.note(autoScalingGroupName);
return toAttributes(group);
}),
delete: Effect.fn(function* ({ output }) {
const existing = yield* describeGroup(output.autoScalingGroupName);
if (!existing) {
return;
}
yield* autoscaling.deleteAutoScalingGroup({
AutoScalingGroupName: output.autoScalingGroupName,
ForceDelete: true,
} as any);
yield* describeGroup(output.autoScalingGroupName).pipe(
Effect.flatMap((group) =>
group
? Effect.fail(
new AutoScalingGroupNotReady({ message: "AutoScalingGroupStillExists" }),
)
: Effect.void,
),
Effect.retry({
while: (error) =>
error._tag === "AutoScalingGroupNotReady" &&
error.message === "AutoScalingGroupStillExists",
schedule: Schedule.max([Schedule.recurs(12), Schedule.exponential("250 millis")]),
}),
);
}),
};
}),
);