AWS Auto Scaling Group Provider¶
The ASG handler provisions capacity through an Auto Scaling Group. Each ORB request creates a dedicated ASG, sized to the requested count, which AWS then keeps at that size — replacing instances that fail EC2 health checks.
Use it when you want AWS to maintain capacity for you across availability zones. Use EC2 Fleet or Spot Fleet when you want fleet-style provisioning without a long-lived scaling group, or RunInstances for one-shot launches.
Quick start¶
1. Create a template¶
{
"template_id": "service-tier",
"name": "Service Tier ASG",
"description": "Long-running workers with health-checked replacement",
"provider_api": "ASG",
"image_id": "/aws/service/ami-amazon-linux-latest/al2023-ami-kernel-6.1-x86_64",
"machine_types": {"t3.medium": 2, "t3.xlarge": 4},
"subnet_ids": ["subnet-0f984e48e6e899311", "subnet-1a2b3c4d5e6f7a8b9"],
"security_group_ids": ["sg-0528dfedb6d763b16"],
"price_type": "ondemand",
"max_machines": 100,
"tags": {"Environment": "prod"}
}
2. Request capacity¶
With the weights above, six capacity units is satisfied by three t3.medium (2 each), or one t3.medium plus one t3.xlarge, or any other combination summing to 6 — see Weighted capacity.
3. Check status¶
4. Return capacity¶
Template configuration¶
The handler uses provider_api: "ASG". Each request creates a launch template, then calls create_auto_scaling_group with a name of the form <asg prefix><request-id>, where the prefix comes from resource.prefixes.asg and is empty unless you configure one.
Top-level fields¶
| Field | Required | Type | Description |
|---|---|---|---|
provider_api |
Yes | string |
Must be "ASG" |
image_id |
Yes | string |
AMI id or SSM parameter path. |
machine_types |
No | object |
Instance type → weighted capacity. Drives the MixedInstancesPolicy overrides. |
subnet_ids |
No | list[string] |
Becomes VPCZoneIdentifier (comma-joined). Supply subnets in several AZs for multi-AZ placement. |
security_group_ids |
No | list[string] |
Security groups, applied via the launch template. |
price_type |
No | string |
"ondemand" (default), "spot", or "heterogeneous". |
percent_on_demand |
No | integer |
0–100. On-demand share of capacity above the base. Forces a MixedInstancesPolicy. |
allocation_strategy |
No | string |
Spot allocation strategy. Converted to the ASG hyphenated form. |
max_price |
No | float |
Maximum spot price per hour. |
abis_instance_requirements |
No | object |
Attribute-based instance selection. Takes precedence over machine_types. |
max_machines |
No | integer |
Maximum capacity this template may provision. |
launch_template_id |
No | string |
Pin an existing launch template. |
context |
No | string |
Passed through as the ASG Context field. |
tags |
No | object |
Tags applied to the ASG with PropagateAtLaunch: true. |
provider_api_spec |
No | object |
Native CreateAutoScalingGroup parameters. See Native spec. |
Group sizing¶
ORB derives the group's bounds from the requested count rather than exposing them as template fields:
| ASG field | Value |
|---|---|
MinSize |
0 |
MaxSize |
requested_count * 2 |
DesiredCapacity |
requested_count |
DefaultCooldown |
300 |
HealthCheckType |
EC2 |
HealthCheckGracePeriod |
300 |
NewInstancesProtectedFromScaleIn |
true |
MinSize: 0 lets ORB scale the group to empty on return instead of fighting a floor. MaxSize is set to twice the request so AWS has headroom to replace unhealthy instances. Scale-in protection is on so AWS does not reclaim instances ORB has handed out to a scheduler.
Override any of these with a native spec if your workload needs different bounds, a different health check type, or ELB health checks.
Weighted capacity¶
Values in machine_types become WeightedCapacity on each MixedInstancesPolicy override. DesiredCapacity is then measured in those units, not in instances:
A request for 8 units can be satisfied by four t3.medium, two t3.xlarge, or one of each plus one more t3.medium. AWS picks the mix. This is why the fulfilment check sums weights rather than counting instances — see Fulfilment semantics.
Weights of 0 or omitted values leave WeightedCapacity unset, which AWS treats as 1.
Pricing and mixed instances¶
The shape of the generated config depends on pricing:
| Configuration | Generated config |
|---|---|
price_type: "ondemand", no percent_on_demand |
MixedInstancesPolicy with instance-type overrides (or a plain LaunchTemplate when neither machine_types nor ABIS is set). No InstancesDistribution. |
price_type: "spot" |
InstancesDistribution with OnDemandPercentageAboveBaseCapacity: 0 — all capacity above the base is spot. |
price_type: "heterogeneous" or any percent_on_demand |
InstancesDistribution with OnDemandPercentageAboveBaseCapacity: <percent_on_demand>. |
OnDemandBaseCapacity is always 0, so the percentage governs the whole group. When allocation_strategy is set it becomes SpotAllocationStrategy.
Example 30% on-demand, 70% spot:
{
"template_id": "mixed-tier",
"provider_api": "ASG",
"machine_types": {"t3.medium": 2, "t3.large": 2, "t3.xlarge": 4},
"price_type": "heterogeneous",
"percent_on_demand": 30,
"allocation_strategy": "lowestPrice"
}
Allocation strategies¶
ASG uses the hyphenated wire format. ORB accepts camelCase, hyphenated, or snake_case in templates and converts on the way out:
| Template value | Sent to AWS |
|---|---|
lowestPrice |
lowest-price |
capacityOptimized |
capacity-optimized |
capacityOptimizedPrioritized |
capacity-optimized-prioritized |
priceCapacityOptimized |
price-capacity-optimized |
diversified |
diversified |
When no strategy is set, spot and heterogeneous templates default to price-capacity-optimized and on-demand templates default to lowest-price. Note that prioritized has no ASG spot equivalent and falls back to lowest-price.
Attribute-based instance selection¶
Setting abis_instance_requirements replaces the instance-type overrides with a single InstanceRequirements override, letting AWS choose any matching type:
{
"provider_api": "ASG",
"abis_instance_requirements": {
"vcpu_count": {"min": 2, "max": 8},
"memory_mib": {"min": 4096, "max": 32768},
"cpu_manufacturers": ["intel", "amd"]
}
}
When ABIS is present, machine_types is ignored. The requirements are also injected into a native spec that omits them. See Attribute-Based Instance Selection.
Native spec¶
A provider_api_spec is rendered and merged over the generated config. ORB always enforces AutoScalingGroupName, defaults NewInstancesProtectedFromScaleIn to true, and patches the launch template id and version into either MixedInstancesPolicy.LaunchTemplate.LaunchTemplateSpecification or the top-level LaunchTemplate, whichever the spec uses. See the Native Spec Reference.
Machine data¶
Instances carry the ASG name as resource_id:
{
"instance_id": "i-0abc1234def567890",
"resource_id": "req-abc123def456",
"status": "running",
"private_ip": "10.0.1.42",
"instance_type": "t3.medium",
"provider_api": "ASG",
"provider_data": {
"cloud_host_id": "i-0abc1234def567890",
"vcpus": 2,
"availability_zone": "us-east-1a",
"region": "us-east-1"
}
}
Instances in Terminating, Terminated, Detaching, and Detached lifecycle states are excluded from the reported set.
Fulfilment semantics¶
The check is capacity-based, not instance-based: ORB sums WeightedCapacity across InService instances and compares that to DesiredCapacity.
| Condition | State |
|---|---|
In-service weighted capacity >= DesiredCapacity, nothing pending, nothing failed |
fulfilled |
| Instances in a failure state, none in service, none pending | failed |
| Anything else | in_progress |
Instances in Pending, Pending:Wait, and Pending:Proceed count as pending. Unweighted groups contribute 1 unit per in-service instance, so the same rule covers both cases.
Because ASG keeps reconciling toward DesiredCapacity, this handler has no terminal partial state — a shortfall stays in_progress while AWS keeps trying. requires_async_polling is true: the create call returns only the group name, and instances arrive later.
When one request spans several ASGs, all groups must be fulfilled for the request to be fulfilled; any failure makes it failed, any partial makes it partial, and otherwise it stays in progress.
Release behaviour¶
Returning instances from an ASG is more involved than terminating them, because AWS would otherwise replace them immediately.
- Group the instances. ORB maps each instance to its ASG, from the request's stored resource mapping when available, otherwise via
describe_auto_scaling_instances. Instances that belong to no ASG are terminated directly. - Filter to current members. Only instances in
InServiceorStandbyare processed. This is an idempotency guard: an instance already detached or terminated had its capacity decremented on the first call, and counting it again would double-decrement. - Terminate weight-aware. Each instance is terminated with
terminate_instance_in_auto_scaling_groupandShouldDecrementDesiredCapacity: true. This decrementsDesiredCapacityby the instance'sWeightedCapacityrather than by 1, which is symmetric with how weighted groups scale up.detach_instanceswould decrement by count and drift the group's capacity. - Clamp
MinSize. The group is re-described to read liveDesiredCapacity, andMinSizeis lowered if it now exceeds it. - Delete when empty.
DesiredCapacityof zero means the group is empty, so ORB deletes the ASG (ForceDelete: true) and cleans up the launch template.
Cancelling a request¶
Cancelling a request that is still being fulfilled scales the group to MinSize: 0 and DesiredCapacity: 0, which narrows the window in which an in-flight scale-out launches instances, and then force-deletes it. The scale-down is best effort because the force delete follows. A group that is absent or already Delete in progress counts as stopped and is not touched again. A group whose lifecycle hooks hold instances in Terminating:Wait stays in Delete in progress until the hook heartbeat times out, and those instances can keep billing until then. Instances still attached afterwards are found with the aws:autoscaling:groupName tag and returned with the recorded machines.
A later return of instances that belonged to a group that is being deleted or is gone terminates them directly and does not detach them from the group.
A separate pre-termination path (reduce_capacity) lowers DesiredCapacity and MinSize before instances are terminated by other means. Every failure in that path is warning-only, so a capacity-reduction hiccup never blocks a return.
IAM permissions¶
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"autoscaling:CreateAutoScalingGroup",
"autoscaling:UpdateAutoScalingGroup",
"autoscaling:DeleteAutoScalingGroup",
"autoscaling:DescribeAutoScalingGroups",
"autoscaling:DescribeAutoScalingInstances",
"autoscaling:CreateOrUpdateTags",
"autoscaling:SetDesiredCapacity",
"autoscaling:TerminateInstanceInAutoScalingGroup",
"ec2:DescribeInstances",
"ec2:TerminateInstances"
],
"Resource": "*"
}
]
}
ASG tagging uses autoscaling:CreateOrUpdateTags rather than ec2:CreateTags. Tag failures are non-fatal: the group is created and the request proceeds without orb: tags. Launch template and SSM permissions are shared with the other handlers — see the IAM Permissions Guide.
Limitations¶
- Group bounds are derived, not configured —
MinSize,MaxSize, cooldown, and health check settings come from the requested count unless you supply a native spec. - EC2 health checks only by default; ELB health checks need a native spec.
- No scaling policies or lifecycle hooks are created. ORB reads
instance_protectionandlifecycle_hooksattributes if a template carries them, but they are not part of the template schema. - No terminal partial state — an under-filled group reports
in_progresswhile AWS keeps reconciling, so a request for capacity that cannot be satisfied will not settle on its own. - One ASG per request — ORB does not reuse an existing group across requests.
Related¶
- EC2 Fleet — fleet provisioning with instant, request, and maintain modes
- Spot Fleet — spot-focused diversification
- EC2 Instances (RunInstances) — synchronous single-type launches
- Attribute-Based Instance Selection — describing requirements instead of instance types