AMIs with a contract: anatomy of EC2's new instance-type block

Every platform team that publishes golden AMIs has lived this scene. The hardened image was built for x86_64, with a statically compiled EDR agent and a kernel that only loads its network driver on a Nitro host. Someone creates an Auto Scaling group with attribute-based instance type selection asking for 4 vCPUs and 16 GiB, leaves Spot diversification wide — which is the correct recommendation for filling capacity — and EC2 picks a Graviton family because it matches the attributes and is the cheapest right now.

The instance comes up. That detail is what makes the failure mode hurt. It doesn't die at RunInstances; it dies later, with no console, no network, nothing but a health check running out. The ASG waits the default 300-second grace period, marks the instance unhealthy, terminates it and tries again — and since the allocation decision hasn't changed, it picks the same pool. You get a launch/terminate loop billed at a 60-second minimum per instance created, an alarm firing at 2 AM, and a graph that looks exactly like a capacity shortage.

Every defense available lived on the caller side: an ec2:InstanceType condition in an IAM policy, an SCP at the Organization, ExcludedInstanceTypes inside a fleet's InstanceRequirements. All correct, all sharing one structural defect — they describe what that principal may launch, not what that image can survive. Share the AMI with 40 accounts and you replicate the rule 40 times, in 40 places that drift apart.

The attribute is InstanceTypeSpecification and it carries SupportedInstanceTypes and UnsupportedInstanceTypes. The logic is short enough to fit in an ADR: with no specification, everything passes (that's the default, and that's why nothing broke on the 4th); with only the unsupported list, everything passes except what matches; with the supported list set, the type must match the supported list and must not match the unsupported one. Denial always wins.

You write it with aws ec2 replace-image-instance-type-specification --image-id ami-... --instance-type-specification '{"SupportedInstanceTypes": ["t3.","a2."], "UnsupportedInstanceTypes": ["t3.micro"]}'. Omitting the parameter removes the restriction. You read it back through describe-images, which returns the InstanceTypeSpecification field with the patterns as stored. A blocked launch returns InvalidParameterCombination from RunInstances, with a message pointing at DescribeImages as the place to look.

Four properties change the design, and none of them are in the announcement:

Replace, not Modify: the operation swaps the whole specification. There is no add or remove — it's read-modify-write with no conditional version. Two pipelines patching the same image in parallel produce last-writer-wins silently, and the loser only finds out when a legitimate launch gets blocked.

Only the owner writes. An account that received the shared AMI consumes the contract and does not negotiate it.

CopyImage preserves the specification. That's what makes the pattern worth it in a multi-Region topology: you declare once and the sa-east-1 replica is born with the contract.

Marketplace is mutually exclusive. You can't set a specification on an AMI listed in AWS Marketplace, and you can't list an AMI that already has one. If you're an ISV shipping an appliance, this feature does not exist for you.

Both lists accept . The docs give the examples: t3. matches the whole t3 family, g5. matches g5, .12xlarge matches any 12xlarge in any family, *xlarge matches any type xlarge or larger. It looks expressive. This is where I'd stop and ask the question that matters: are you describing hardware, or are you describing names?

What the AMI actually requires is a capability — arm64 versus x86_64, Nitro versus Xen hypervisor, presence of a GPU, presence of local NVMe. What the specification evaluates is a pattern over the instance type's string. The two coincide today because AWS names Graviton families with a g and local-storage families with a d. They coincide by convention, and a naming convention is not a contract: c6gn, c7gd, m7i-flex, u7in-32tb and mac2-m2pro already show a scheme full of exceptions, suffixes and infixes that no simple glob covers. A g. written to exclude Graviton is a heuristic — and a hand-written heuristic, in a file nobody revisits, is debt that accrues interest.

The second trap is temporal, and it's the expensive one. An explicit allow-list blocks every future generation by construction. New families reach new Regions constantly; the day the next generation shows up in your Spot pool, the fleet you deliberately left wide — because wide diversification is the correct practice for Spot capacity — will skip exactly the cheapest, most available family. You get no error: the ASG simply doesn't choose it, price creeps up, interruption rate creeps up, and nobody connects that to a JSON written eight months ago. It's the same tension behind OnDemandMaxPricePercentageOverLowestPrice, which ships with a 20% default headroom precisely so it doesn't narrow your pool without telling you.

The documentation is explicit: EC2 enforces the specification as a hard block, and launch templates and Auto Scaling groups that reference the AMI can fail if the configured instance type isn't allowed. That isn't an implementation detail — it's the pattern's central trade. You converted a slow, expensive failure (zombie instance, health check, loop) into a fast, cheap one (InvalidParameterCombination at RunInstances). Fast and cheap wins on 95% of days. On the other 5%, you're in the middle of a zonal capacity event, price-capacity-optimized has finally found a pool with room, and your contract says no.

In financial systems that has a name: you traded correctness risk for availability risk, and you did it on purpose. When the AMI genuinely won't boot on that hardware, the trade is trivially good — the instance was never going to serve traffic. When the list is merely stale, you invented an unavailability mode that didn't exist before, in exactly the window where elasticity matters. That's why a generated allow-list and a minimal deny-list aren't aesthetic preferences: one errs toward letting through, the other errs toward blocking.

The hole is observability. The specification doesn't affect running instances, emits no metric of its own, and shows up on no dashboard by default. The auditable signal is the RunInstances event in CloudTrail carrying an errorCode — build a metric filter grouped by requestParameters.imageId and alarm on any block, because in steady state the expected rate is zero. A recurring block isn't the control working; it's a launch template pointing at an AMI whose contract changed underneath it. And add the read side to the runbook: describe-images with its InstanceTypeSpecification field is the first thing to check when a launch fails on a parameter — the error message itself sends you there, and whoever is on call at 2 AM needs to know that before opening a support case.