billing

The platform's billing setup for compute: the meters and prices root keeps on the IAM root tenant, so root can bill its sub-tenants for what they use. Every method is decided as a compute:billing:* action on compute-fleet, which resolves only in the root tenant, so a tenant administrator is turned away before any IAM decision, however broad the tenant's own grants. A root member needs compute:billing:read or compute:billing:manage on compute-fleet.

These methods call the IAM root tenant's billing API as a root service account. The IAM port must be configured with one: bridge.embedded(iam, { rootTenantId, serviceCredential }) with iam:billing:manage and iam:billing:read on the root tenant (a remote bridge takes a serviceToken). Without it every method answers UNSUPPORTED and names that fix. Amounts are micros of the deployment's currency (1,000,000 micros = 1 unit).

The catalog these methods work from is the same one better-compute iam setup --meters and the IAM bridge sync: hosted and node GPU, CPU, memory and volume hours, provider VM meters, reservation-grant and managed-VM meters, the ancillary network, address, disk and snapshot meters, and the flavor.* meters root sets on flavors. vps({ billing: { gpuModels, gpuFamilies } }) names the GPU models whose VM meters exist; name the same models as the bridge so the two agree.

All 7 methods are served by @better-compute/server 0.3.0.

meters

POST /api/compute/billing/meters

Returns the catalog compute defines, catalog, and missing: the keys of the catalog the IAM root tenant has no meter for yet. Usage recorded on a missing meter is refused by IAM; syncMeters creates the missing ones.

An archived meter still exists on the root tenant, so it is not listed as missing. UNSUPPORTED when the IAM port cannot list meters.

• Kind: read
• Authorization: compute:billing:read @ compute-fleet
• Module: vps
• Phase: v1.0 (registered)

Input

Takes an empty object: {}.

syncMeters

POST /api/compute/billing/syncMeters

Creates the catalog's meters that the root tenant lacks, and returns { created, existing } (meter keys). A meter that exists is left as it is, whatever its name, unit or pricing mode; calling it again creates nothing.

Decided as compute:billing:manage on compute-fleet. The IAM call happens outside any compute transaction.

• Kind: mutation
• Authorization: compute:billing:manage @ compute-fleet
• Module: vps
• Phase: v1.0 (registered)

Input

Takes an empty object: {}.

prices

POST /api/compute/billing/prices

Returns the rate-card price entries of one meter, or of every rate-card meter, newest first, as { meter, targetTenantId, effectiveFrom, spec }. The list price is the entry whose targetTenantId is the root tenant; a negotiated price names the tenant (and its subtree) it applies to. targetTenantId filters.

meter and targetTenantId are optional. reported meters carry their cost on each usage event and have no prices.

• Kind: read
• Authorization: compute:billing:read @ compute-fleet
• Module: vps
• Phase: v1.0 (registered)

Input

setPrices

POST /api/compute/billing/setPrices

Sets up to 100 prices on the root tenant's rate card and returns { applied, failed }.

• Each price is { meter, targetTenantId?, effectiveFrom, spec }. Without targetTenantId it is the list price; with one it is a negotiated price for that tenant's subtree. effectiveFrom is a billing period (YYYY-MM), and spec is a better-iam price (per-unit, graduated, volume or package) in micros.
• Meters. Every meter must be in the catalog (meters) or be a flavor meter; one that is not refuses the whole request with INVALID_INPUT before any price is applied.
• Tenants. targetTenantId is not checked here: better-iam validates it, and a tenant it refuses lands in failed.
• Partial failure. A price better-iam refuses does not stop the others: applied lists the prices that took effect, in request order, and failed lists { index, meter, targetTenantId?, code, message } for the rest. Setting a price is idempotent, so a retry of the same request is safe.

Decided as compute:billing:manage on compute-fleet.

• Kind: mutation
• Authorization: compute:billing:manage @ compute-fleet
• Module: vps
• Phase: v1.0 (registered)

Input

proposePrices

POST /api/compute/billing/proposePrices

Reads the list prices of one of the platform's provider accounts, adds a margin and returns prices root can publish. It sets nothing: prices is the same before and after, and root publishes the proposals it wants through setPrices. Decided as compute:billing:read on compute-fleet. It needs no billing member on the IAM port, only the provider.

• Input. accountId is a provider account of the root tenant whose provider lists prices (Compute Engine reads the Cloud Billing Catalog): another tenant's account, or one that does not exist, is NOT_FOUND, and a provider without prices is UNSUPPORTED. marginPct (0 to 1000) is the percentage added. region limits the prices read to one region; without it the cheapest basis across the regions the provider lists is used. effectiveFrom (YYYY-MM) is the period root means to publish the proposals from; it is checked and left to setPrices.

• Result. { proposals, unpriced, currency }; currency is the deployment currency every proposal is in. A proposal is { meter, spec, basis }: spec is per-unit at round(unitPriceMicros x (1 + marginPct / 100)) micros, and basis lists the provider prices (sku, unitPriceMicros) it came from. A meter the provider's prices cover is proposed; the provider meters that remain are unpriced.

• vm.vcpu.hours and vm.memory.gib.hours take the cheapest general-purpose machine family (E2, N1, N2, N2D, N4, T2D, C3, C3D, C4, by one vCPU and four GiB of on-demand prices) in the region. Per-family accuracy is what flavor meters are for.

• GPU meters (vm.gpu.<model>.hours and the .spot meters) take the cheapest GPU SKU of that model, on demand or Spot. Ancillary meters (ip.public.hours, disk.<type>.gib.hours) take the matching SKU; monthly storage prices become GiB-hours at 730 hours a month.

• Flavor meters (flavor.<name>.hours) are composed for the flavors of the account's pools that carry them: the flavor's vCPUs, memory and GPUs at the prices of its offer's machine family in the offer's region (an offer id spelled zone/machine-type). Archived flavors are ignored. A flavor's GPU model is its pool's gpuModel as the deployment's GPU models name it (vps({ billing: { gpuModels } }), as metering does), so a model the deployment does not name is other and has no price. Flavors that share a meter must share a shape, else the meter is unpriced.

• Left unpriced: instance, reserved, reservation-grant and managed-VM meters, network and snapshot meters, GPU models the provider has no price for, and any meter whose price is in another currency than the deployment's (vps({ billing: { currency } }), default USD). Hosted, node and sandbox meters are the platform's own and are not listed.

• Kind: read

• Authorization: compute:billing:read @ compute-fleet

• Module: vps

• Phase: v1.0 (registered)

Input

margins

POST /api/compute/billing/margins

Returns the platform's margin over a range: revenue (what better-iam billed) minus provider cost (what the providers billed the platform, D12), grouped by tenant, pool, account (provider account) or meter, as { rows, unattributedCostMicros, currency, from, to }.

• Input. from and to are epoch milliseconds (to after from, at most 400 days apart); groupBy is required.
• Revenue comes from the IAM port's spend report on the root tenant (IamPort.spend, by tenant, by meter, or by the pool tag). better-iam sums whole billing periods, so the answer covers every period the range touches, and costs are summed over exactly that range: from and to in the answer are the range both cover. Without spend, revenueMicros, marginMicros and marginPct are null and costs cover the query's range. better-iam has no provider-account dimension, so groupBy: 'account' always has null revenue.
• Revenue is before contract terms. It is better-iam's spend: usage rated at list or negotiated prices (setPrices), before the contract discounts of setTerms, which better-iam applies when it closes the period into a statement. Margins of a discounted tenant are overstated by its discount.
• Root's own usage is not revenue. better-iam never invoices the platform. By tenant, the root tenant's row keeps its provider cost and has revenueMicros: 0, so its margin is minus that cost. By pool or meter, the spend report cannot be scoped to the root tenant without the tenants below it, so pool and meter revenue include root's internal usage at its rated price.
• Cost is the sum of cost plus credits of the vps.costs worker's rows (provider_costs) of the platform's own provider accounts (the root tenant's; a tenant's own account is that tenant's cost, not the platform's) whose usage started in the range, in the deployment currency (vps({ billing: { currency } }), default USD; rows in another currency are excluded). Rows attributed to no tenant are not in rows but in unattributedCostMicros. By pool, a row counts toward its instance's pool; by meter, toward the reported meter it was passed through on. Attributed cost with no such pool or meter is grouped under the key (none), whose revenue is null. Provider compute cost has no meter dimension (a provider bills a VM's cores and memory, not compute's meters), so with groupBy: 'meter' all compute cost is under (none) while its revenue is under the vm.* meters: read the meter view for pass-through margins, and the tenant or pool view for compute. Pass-through usage carries the instance's pool tag, so revenue by pool includes it.
• Rows. One per key that has revenue or cost, sorted by key with (none) last: { key, revenueMicros, costMicros, marginMicros, marginPct }. marginPct is the margin over revenue in percent (2 decimals), null when revenue is not positive.

Decided as compute:billing:read on compute-fleet, so a tenant cannot read it. The IAM call happens outside any compute transaction.

Leak detection (reported as events, listed by leaks) — at the end of every vps.costs pass over a platform provider account, each instance's provider-billed compute is compared with what compute metered for it, per UTC day. The provider hours of an instance-day are the distinct hour slots the provider billed compute for it (regular rows of the provider's compute SKUs attributed to the instance, quantity above 0), not the sum of the rows' quantities: a provider bills a VM's cores and memory as separate rows in vCPU-hours and GiB-hours, so summed quantities are no count of hours. The metered hours are how many of those slots a running usage interval of the instance overlaps. When the provider hours exceed the metered ones by more than vps({ costs: { leakToleranceHours } }) (default 1), billing.leak is published, at most once per instance and day. Instances with billing: none and tenants' own accounts are not checked.

A provider whose cost rows are period aggregates (billing.periodRows: a DigitalOcean invoice item is a Droplet's month so far) is compared differently: the row's billed hours against the instance's metered hours over the row's span, with a gap over max(leakToleranceHours, 5%) of the billed hours, raised once per instance and period; a provider that bills stopped machines (billing.billsStopped) has the instance's stopped hours counted as metered.

• Kind: read
• Authorization: compute:billing:read @ compute-fleet
• Module: vps
• Phase: v1.0 (registered)

Input

leaks

POST /api/compute/billing/leaks

Lists the leaks raised on the platform's (root's) provider accounts whose day is in [from, to), newest day first, at most 500: { items }.

• Input. from and to are epoch milliseconds; a leak's day is its UTC day (for a period row, the period's first day).

• Items. { accountId, accountName, provider, instanceId, tenantId, day, providerHours, meteredHours, raisedAt }: tenantId is the instance's tenant, null once the instance is gone; providerHours is what the provider billed and meteredHours what compute metered. A tenant's own accounts are never checked, so they have no leaks; without a root tenant the list is empty.

• IAM. Decided as compute:billing:read on compute-fleet, so a tenant cannot read it. A read of the database: no provider is called.

• Kind: read

• Authorization: compute:billing:read @ compute-fleet

• Module: vps

• Phase: v1.0 (registered)

Input