Prices and machine shapes
A design says where its prices come from:
"pricing": {"provider": "generic", "region": null, "purchaseOption": "on_demand", "families": [], "burstable": "auto"}
With a snapshot, a design normally also pins its date ("snapshotDate": "2026-10-28", see
Pinning a snapshot); the editor does that when you choose a snapshot.
Templates and new projects start with AWS us-east-1 prices, pinned to the newest AWS
snapshot ArchSim ships: {"provider": "aws", "region": "us-east-1", "snapshotDate": "2026-10-28"}.
The schema's default is still generic, so a document saved without pricing (every design
made before this) keeps its illustrative rates and its results; choose a snapshot under
Prices in Design to move it to real prices.
generic: ArchSim's illustrative rates, $0.037 per vCPU-hour, $0.0028 per GiB-hour and $0.08 per GiB-month of storage, roughly a large cloud's general-purpose VMs. There are no machine shapes, so auto-sizing rounds each part's CPU and memory up together to the cheapest standard shape of 2, 4 or 8 GiB per vCPU (the compute, general-purpose and memory-optimised ratios every large cloud sells): a part that needs 4 vCPU and 0.5 GiB gets 4 vCPU and 8 GiB. Cost lines say "from size", and every dollar figure says "illustrative rates".- Any other provider names a price snapshot: on-demand list prices of real instance types on a date, for a region. Auto-sizing then snaps each part to the cheapest instance type that covers the CPU and memory it needs (a value you set counts as the need), so parts run on shapes that exist; the inspector, the analysis and the report show the SKU, every cost line cites its SKU and the snapshot date, and every dollar figure names the snapshot ("AWS us-east-1 · Oct 2026").
Burstable types (AWS's t families: t3, t4g, db.t4g, cache.t4g, kafka.t3) run on CPU
credits: each vCPU can use its baseline (a t4g.micro 10%, a t4g.large 30%) all the time, earns
credits below it and spends them above it. Auto-sizing picks a t4g type for a light part
when it passes the credit check: its CPU at the workload's steady base load (the rate
outside a burst, the low end of a ramp, a trace's median) stays under 80% of the type's
baseline, so it earns credits all month, and its CPU at the peak stays under 60% of the type's
vCPUs, the target auto-sizing aims at; the engine then simulates every vCPU at full speed, as
the credits allow. The explanation says so ("burstable: 0.02 cores busy at the base load stay
under 80% of its baseline..."). EC2 and RDS run t types in unlimited mode, so the risk is a
charge, not throttling: when a part on a burstable type would keep more than its baseline busy
at the base load (a type named on the part, or a run busier than the estimate), its cost line
adds the surplus CPU credits (t4g $0.04, db.t4g $0.075 per vCPU-hour above the baseline);
ElastiCache's t types have no surplus credits and are throttled to their baseline instead,
which the cost line notes. pricing.burstable is auto (the default) or never (many teams
ban t types in production). Naming a burstable family in families (["t4g"]) allows it
wherever it is the cheapest fit, credit check or not, without restricting the other lists.
Pods on a Kubernetes cluster and serverless functions are not machines of their own (their machines are the cluster's nodes and the provider's), so they keep their computed size with or without a snapshot.
families limits snapping to some instance families (for example ["m7g", "c7g", "r7g"]). It
restricts a price list only when that list has one of the (non-burstable) families, so naming
compute families leaves the database and cache lists alone, and naming only t4g restricts
none (before engine 0.13 it forced every list onto t4g). A family the snapshot does not have restricts nothing
and gets a validation warning (pricing.unknown_family). purchaseOption is on-demand only:
savings plans and reserved terms are not modeled yet.
What snaps to what: services on VMs or Docker, self-hosted load balancers and Kubernetes node pools use compute instances; databases use the snapshot's managed database types for their engine (PostgreSQL, MySQL...), caches its cache types (Redis, Valkey, Memcached) and Kafka its broker types. An engine the snapshot has no managed type for (Cassandra, MongoDB...) runs on compute instances and the cost line says "self-managed". Services on Kubernetes are priced through their cluster's nodes; serverless services, managed queues (SQS-style, Pub/Sub-style) and managed load balancers (ALB-style) use the snapshot's per-request and per-hour rates where it has them. Managed services (ALB-, SQS-, Pub/Sub-, DynamoDB-style, CDN, API gateways) never snap to an instance type; the inspector shows no size price for them or for serverless functions, which are billed per use. Storage is priced at the snapshot's block storage rate, a managed database's at its own (RDS gp3). Not included: discounts, Multi-AZ, reserved instances and savings plans, data transfer and NAT, free tiers, licences (the cost panel says so).
Managed and per-request lines (with a snapshot that has the rate), each listing what it
prices with its unit price (items, shown in the cost panel as "394.20 M requests × $3.50/M"):
| Part | Priced as |
|---|---|
Application load balancer (aws_alb) |
hours, plus capacity units: requests/s at the base load × 10 KB processed each (assumed: request and response; new connections and rule evaluations are assumed to need fewer), 1 LCU per GB an hour |
| API gateway | requests at the base load × apiGatewayPerMillion |
| Serverless function | invocations × serverlessPerMillionRequests, plus GB-seconds: invocations × its duration at the base load (in flight ÷ arrivals over the run's base-load time buckets; before a run, the instant estimate's time in the part) × its memory |
| SQS-style queue | three requests per message (send, receive, delete) × queuePerMillionRequests |
| DynamoDB | provisioned: RCU and WCU × hours; on demand: read and write request units at the base load (a read is half a unit per 4 KB when eventually consistent, a write one per KB); plus storage (dataSizeGib, else keys × item size) |
| Services on Kubernetes without a cluster in the design | implied nodes: each pod's share of the cheapest general node type that fits it at 90% allocatable (not burstable, HPC or bare-metal types), plus one managed control plane (kubernetesControlPlaneHour). A cluster in the design also pays for its control plane. |
Per-request lines are priced at the workload's steady base load as if it lasted the whole month, unless the workload says how many hours a month it runs at its peak (below): after a run, each part's rate measured while the offered load was at the base, scaled to it exactly, so fan-out, cache misses and retries are kept but a burst's retries are not; before one, the static load estimate at the base rate, so a design is priced before it runs. When no time bucket of the run's window is at the base (a ramp that passes it during the warm-up), the rates are measured in the buckets nearest it, so the failures and timeouts at the peak do not move them; the peak's are too, when no bucket is at the peak.
What a month is#
A month is 730 hours: workload.peakHoursPerMonth of them at the pattern's peak (a burst's rate,
a ramp's high end, a trace's highest point), and the rest at the steady base load (a constant
pattern's rate, a burst's rate outside the burst, a ramp's low end, a trace's median)
(ADR-0074). The hours default to 0,
which bills the whole month at the base load, as before schema 1.8: say how long your peak lasts
(a sale day, an evening rush on every weekday) to bill it. A constant pattern has one rate, so the
hours change nothing there.
Each line is its base load's cost for the base's hours plus its peak's for the peak's: its
instances, its per-request items (their quantities are both loads' for their hours) and its
surplus CPU credits. Its instances stay the base's, beside peakInstances. Its basis says how
many run at the peak and for how long (3 pods at the base load (autoscaling 3–14) and 12 pods at the peak for 24 hours a month), or, for a line whose count is the same at both loads but whose
cost is not (a per-request part, a load balancer's capacity units), ends ; at the peak for 24 hours a month. A unit price that differs between the loads is the month's own: its cost over its
hours, or over its requests. The cost per million successful requests divides the month by both
loads' requests. cost.peakHours says how many hours the month billed at the peak (the
workload's, or 0 for a constant pattern, which has no peak), and cost.hourly has an hour at the
base load and an hour at the peak, whatever the hours.
An hour at the peak is priced as the base is: after a run, each part's rate measured while the offered load was at the peak, scaled to it; before one, the static load estimate at the peak rate; and a burstable type's surplus CPU credits for the cores it keeps busy at the peak, as if it had no credits saved.
A part that scales is billed at each load the count it settles at once that load holds:
- An autoscaled service: the replicas its autoscaler wants there, as a Kubernetes HPA computes
them, the work in busy replicas (the larger of its slots' and its CPU's utilization × its
replicas) ÷
targetUtilization, rounded up, withinminReplicas–maxReplicas. The busy replicas per request are what the run measured (before a run, what the instant estimate gives), times the part's requests at that load. A service that starts above its minimum is billed its minimum at a light base load, not the count it starts with. - A Kubernetes cluster with its autoscaler: the nodes its pods at that load need, packed first
fit, the largest first, as the cluster autoscaler packs them, within
minNodes–maxNodes. Without its autoscaler, itsnodes. - A serverless function: per invocation; with no rate for it, its average concurrency in the run, scaled to the load.
Black Friday on Kubernetes (examples/black-friday-kubernetes.json, 300 → 1,500 req/s) bills 24
peak hours a month, one sale day. After a run, the month at the base load is $824.80, the
checkout on its 3 pods. An hour at the peak costs $0.7844 more for the HPA design: 9 more checkout
pods (12 in all) and the database's surplus CPU credits, $0.1044. So its month is $824.80 +
24 × $0.7844 = $843.63. The fixed-pods scenario keeps 3 pods, so its peak hours add only the
credits: $824.80 + 24 × $0.1044 = $827.31. fixed-at-peak runs 14 pods, the HPA's maximum, all
month: $1,434.02, so the autoscaler saves $590 a month.
Checked by hand, the serverless template (150 req/s with a burst to 1,500): DynamoDB with
100 RCU and 60 WCU provisioned is 100 × $0.00013 × 730 + 60 × $0.00065 × 730 = $37.96 a month;
the function at 150 invocations/s, 1,769 MB (1 vCPU) and about 40 ms each at the base load is
394.2 M invocations × $0.20/M + 394.2 M × 0.04 s × 1.7275 GB × $0.0000166667 ≈ $530 a month, and
the cost line agrees within a few percent (it uses the measured duration and rate). The Python
engine's test_cost_managed.py kept it within 10% until stage 5 of the Java port deleted that
engine; the Java cost estimate gives that engine's figures on every golden entry
(parity/README.md).
Which price a part gets#
Each cost line has a priceSource; the first that applies wins:
set: a price you set on the part (costPerHour). A value counts as yours when it differs from the catalog default and from the illustrative price of every preset of the part's technology, or when its provenance (nodes/<id>/costPerHour) ismeasuredorassumed. It wins over everything, the snapshot's instance types and managed rates included.snapshot: with a snapshot, the instance type the part snaps to (withskuandsnapshotDate), or the snapshot's rate for a managed load balancer, queue or serverless function.preset: the illustrative price a technology preset put on the part (for example $0.17/h for Java/Spring). Presets' prices are illustrative, so a snapshot reprices them; with generic rates, or when the snapshot cannot price the part, they are used as they are. The inspector shows them as the preset's illustrative price, never as yours.size: the part's CPU, memory and storage at the generic illustrative rates. Whenever a line is priced this way the estimate's notes say so, also next to snapshot lines.default: the catalog default.
Snapshots#
A snapshot is a JSON file in archsim-model/src/main/resources/io/archsim/model/pricing/snapshots/
(shipped in the model's jar: its build lists every file of the folder) or in a directory named by
ARCHSIM_PRICES_DIR (several are separated by the path separator), in the
format archsim.prices/1:
{
"format": "archsim.prices/1",
"provider": "aws", "region": "us-east-1", "currency": "USD", "snapshotDate": "2026-10-01",
"sources": [{"name": "AWS Price List bulk API", "url": "https://pricing.us-east-1.amazonaws.com/..."}],
"compute": [{"sku": "m7g.large", "family": "m7g", "vcpu": 2, "memoryGib": 8, "hourly": {"on_demand": 0.0}},
{"sku": "t4g.small", "family": "t4g", "vcpu": 2, "memoryGib": 2, "hourly": {"on_demand": 0.0},
"burstable": true, "baselineCpu": 0.2}],
"databases": [{"sku": "db.r7g.large", "family": "r7g", "vcpu": 2, "memoryGib": 16, "hourly": {"on_demand": 0.0}, "engines": ["postgresql"]}],
"caches": [], "streams": [],
"rates": {"storageGibMonth": 0.0, "serverlessGbSecond": 0.0, "serverlessPerMillionRequests": 0.0,
"queuePerMillionRequests": 0.0, "loadBalancerHour": 0.0}
}
(The zeros above are placeholders, not prices.) A SKU may also carry "burstable": true and,
for a burstable type, baselineCpu: the share of each vCPU it can use all the time without
spending CPU credits (AWS publishes it in its instance tables, not in the price list), and
creditVcpuHour: the price of a vCPU-hour above the baseline when the type runs in unlimited
mode (EC2 t4g $0.04, RDS db.t4g $0.075). A burstable type without creditVcpuHour (ElastiCache's)
is throttled to its baseline once its credits run out.
Every rate is optional; older snapshots have fewer of them. The rates a snapshot can carry:
| Rate | Unit |
|---|---|
storageGibMonth |
block storage (EBS gp3), per GiB-month |
rdsStorageGibMonth |
managed database storage (RDS gp3, Single-AZ), per GiB-month |
serverlessGbSecond, serverlessPerMillionRequests |
functions (Lambda), per GB-second and per million invocations |
queuePerMillionRequests |
managed queues (SQS standard), per million requests |
loadBalancerHour, loadBalancerLcuHour |
an application load balancer per hour, and per capacity unit-hour (LCU) |
networkLoadBalancerHour, networkLoadBalancerLcuHour |
a network load balancer per hour, and per capacity unit-hour (NLCU) |
dynamodbReadPerMillion, dynamodbWritePerMillion |
DynamoDB on-demand, per million read and write request units |
dynamodbRcuHour, dynamodbWcuHour |
DynamoDB provisioned, per read and write capacity unit-hour |
dynamodbStorageGibMonth |
DynamoDB table storage, per GiB-month |
apiGatewayPerMillion |
an API gateway, per million requests (REST API, first tier) |
kubernetesControlPlaneHour |
a managed Kubernetes cluster's control plane (EKS), per hour |
Each per-request or per-unit rate is the first paid tier: not a free allowance, and not the cheaper tiers for very high volumes.
Every snapshot has a content hash, the SHA-256 of its canonical JSON (sorted keys, no
whitespace), so reformatting a file or changing its line endings does not change it.
GET /api/v1/pricing lists every snapshot on the machine with its date, hash and whether it is
the newest for its provider and region.
The AWS snapshots ArchSim ships#
| File | aws-us-east-1-2026-10-28.json (about 260 KB), the newest; templates and new projects pin it |
| Region | us-east-1 (US East, N. Virginia), USD, on-demand |
| Read on | 2026-10-28, by scripts/prices/aws.py |
| Source | AWS Price List bulk API (public, no account), offer files AmazonEC2 20261028180352, AmazonRDS 20261026214716, AmazonElastiCache 20261028192450, AmazonMSK 20261014170039, AWSLambda 20261022183959, AWSQueueService 20260911124607, AWSELB 20260911124544, AmazonDynamoDB 20260911124422, AmazonApiGateway 20261013003044, AmazonEKS 20261027191639 (the snapshot's note repeats them) |
| Contents | 1,107 EC2 types (Linux, shared tenancy), 315 RDS Single-AZ types (PostgreSQL, MySQL, MariaDB), 188 ElastiCache types (Redis, Valkey, Memcached), 16 MSK broker types; the t3, t3a and t4g types with their baseline CPU and, on EC2 and RDS, their surplus-credit price; every rate in the table above |
| Left out | Outposts, Local Zone and Wavelength prices, Capacity Blocks, previous-generation types (AWS's own flag), GPU, machine-learning, FPGA and media types, Express MSK brokers, reserved and savings-plan terms, free tiers, DynamoDB's Infrequent Access table class, API Gateway HTTP APIs and WebSockets |
aws-us-east-1-2026-10-27.json is the first snapshot, kept unchanged because stored runs pin
its content hash: the same instance types and prices (no price changed between the two dates),
without baselines and with only the first five rates.
Terms. These are AWS's published list prices, copied as facts (instance type, shape, price per hour) with their source and date. AWS's price list says of itself: "This pricing list is for informational purposes only. All prices are subject to the additional terms included in the pricing pages on http://aws.amazon.com." Use of AWS's sites is governed by the AWS Site Terms, and AWS changes prices from time to time, so a snapshot is a planning estimate for its date, not a quote: check aws.amazon.com/pricing before buying. ArchSim is not affiliated with or endorsed by Amazon Web Services.
Checked by hand against AWS's published on-demand prices for us-east-1: m7g.large $0.0816, c6g.xlarge $0.136, m5.large $0.096 per hour; db.m5.large $0.178 (PostgreSQL) and $0.171 (MySQL); cache.m7g.large $0.158 (Redis); kafka.m5.large $0.21; gp3 $0.08 per GiB-month; Lambda $0.20 per million requests and $0.0000166667 per GB-second; SQS standard $0.40 per million requests; an Application Load Balancer $0.0225 per hour and $0.008 per LCU-hour; DynamoDB $0.00013 per RCU-hour, $0.00065 per WCU-hour, $0.125 and $0.625 per million on-demand read and write request units and $0.25 per GiB-month; API Gateway REST APIs $3.50 per million requests; RDS gp3 $0.115 per GiB-month; the EKS control plane $0.10 per hour.
Pinning a snapshot#
Snapping changes the CPU and memory a part is simulated with, so which snapshot is used changes results, not just prices. A design therefore pins one:
snapshotDate(YYYY-MM-DD): exactly the snapshot of that date for the provider and region is used, never a newer one. The editor fills it in when you choose a snapshot; the inspector lists older snapshots only for designs pinned to them.snapshotSha256(optional, withsnapshotDate): the snapshot's content hash, so changed prices under the same date are not used either.- Unpinned (
snapshotDateempty): the newest snapshot for the provider (inregionwhen set) is used, as before.
Either way the engine resolves the snapshot once per analysis or run, and the run's input
records it: input.pricing carries the region, snapshotDate and snapshotSha256 actually
used (and cost.pricing.sha256 repeats the hash). A run's input is therefore a pinned document:
running it again, after newer snapshots were added, gives the same result digest. A pinned
snapshot this machine does not have (or whose content differs) is never swapped for another: the
design gets a validation warning (pricing.snapshot_missing, naming the snapshots it has) and is
priced at generic rates without snapping, and its run's input has no snapshotSha256. An
unpinned design whose provider has no snapshot here gets the same warning and generic rates.
Refreshing snapshots#
archsim-tools' price refresh (prices, run by Gradle from the repository's root) reads the
providers' public price lists and writes a snapshot. ArchSim never calls it, or any price API,
at runtime.
Monthly AWS refresh. .github/workflows/prices.yml rebuilds the us-east-1 snapshot among
the model's, runs the model's tests, and opens a pull request with the new file and a summary of
what changed (prices diff: types added, removed and repriced, largest changes first). When no
price changed it opens nothing. A person reviews and merges it. Older snapshots stay, so a
design pinned to one reproduces. Its monthly schedule (the 2nd) is off, and it runs
by hand only: the golden pricing entries and some sizing tests still expect 0.16.0's two
snapshots to be the only ones, so a new snapshot fails them until they stop assuming it
(ADR-0026).
After the merge, new projects pin the new snapshot (the API pins the newest AWS us-east-1
snapshot the model ships). Templates keep the date they name, because a new snapshot can
snap parts to other types and so change results. To move them: set pricing.snapshotDate in
examples/*.json to the new date, then regenerate what depends on their results (as for any
change to simulated results): copy examples/cache-aside-starter.json to
apps/web/src/test/fixtures/starter.json, run ./gradlew :archsim-engine:generate (which
analyzes that starter), and run the whole test suite.
By hand:
./gradlew :archsim-tools:run --args="prices aws --region us-east-1" # AWS Price List bulk API (CSV, streamed)
./gradlew :archsim-tools:run --args="prices diff archsim-model/src/main/resources/io/archsim/model/pricing/snapshots/aws-us-east-1-<date>.json"
./gradlew :archsim-tools:run --args="prices azure --region eastus" # Azure Retail Prices API
GOOGLE_API_KEY=... ./gradlew :archsim-tools:run --args="prices gcp --region us-central1" # Cloud Billing Catalog API
- AWS: EC2 (Linux, shared tenancy, on-demand), RDS Single-AZ (PostgreSQL, MySQL, MariaDB)
and its gp3 storage, ElastiCache (Redis, Valkey, Memcached), MSK standard brokers, EBS gp3
storage, Lambda, SQS standard, Application and Network Load Balancers (hours and capacity
units), DynamoDB (request units, capacity units, storage), API Gateway REST API requests and
the EKS control plane, each rate at its first paid tier. Burstable types get their baseline CPU
from a table in the refresh (AWS's instance tables; the price list does not have it). The EC2
file is about 300 MB; downloads are cached in
.cache/aws-pricesby AWS's file version. A region's file also lists Outposts and Local Zone prices, Capacity Blocks, unused capacity reservations and extended-support surcharges; only the region's own on-demand instance hours are kept, and the same type at two prices stops the refresh rather than letting snapping pick the wrong one. Types that differ only in engine are stored once (an ElastiCache type costs the same for Redis and Memcached). - Azure: virtual machines of the D v3-v6, E v3-v6 and F v2 series (Linux, pay-as-you-go). The API returns prices but not shapes, so memory comes from each series' published ratio.
- GCP: Compute Engine N2, N2D, E2 and C3 machine types, priced per vCPU-hour plus per
GiB-hour of their family. The API needs an API key, read from
GOOGLE_API_KEYand never written anywhere.
Their parsers are tested on small samples in each API's layout (archsim-tools' prices tests,
which compare them with what the Python scripts they port wrote); the AWS samples include the
rows that tripped the first run against the live price lists. The AWS refresh has been run
against the live lists (the snapshot above, by its Python version); the Azure and GCP
refreshes have not, so their first real refresh should be checked by hand (a few well-known
prices against the provider's pricing page) before the snapshot is committed.