disk-type

A disk type is a catalog resource that defines a persistent disk performance tier. Each environment can reference a disk type via its disk_type_ref field. This determines the storage tier and per-region cost for agent VMs. The platform provides built-in disk types for the tiers it manages. A built-in is immutable. You cannot edit one or delete it outright, but you can disable it: murmur rm disk-type <name> takes a built-in out of resolution so nothing can select it, and murmur set disk-type <name> with no payload re-enables it. A disabled built-in still appears in murmur get disk-type, marked as disabled, so you can see what you turned off. You can add your own with murmur set. A customer-managed placement in a region the built-ins do not price also needs a machine type of your own: a VM reads its compute rate from that entry and its storage rate from this one, so price every region your placements use in both. See Pricing for the current built-in disk rates and how disk storage contributes to a VM charge.

Fields

Name	Type	Required	Description
`name`	string	yes	Unique identifier. DNS label format: `[a-z][a-z0-9-]{0,62}`.
`description`	string	no	Human-readable description shown in the dashboard. Max 1024 bytes.
`substrate`	enum	yes	Cloud provider. Values: `SUBSTRATE_GCP`, `SUBSTRATE_AWS`. Must match the spec block (`gce` or `aws`).
`gce`	object	conditional	GCE disk type details. Exactly one of `gce` or `aws` is required.
`aws`	object	conditional	AWS EBS volume type details. Exactly one of `gce` or `aws` is required.

GCE spec fields

Set substrate: SUBSTRATE_GCP and provide gce:

Name	Type	Required	Description
`gce.disk_type`	string	yes	GCE disk type identifier (e.g. `pd-balanced`, `pd-ssd`, `pd-standard`, `hyperdisk-balanced`).
`gce.provisioned_iops`	int64	conditional	IOPS every disk of this type is created with. Required for `hyperdisk-balanced` and `pd-extreme`, rejected for every other disk type.
`gce.provisioned_throughput_mibps`	int64	conditional	Throughput in MiB/s every disk of this type is created with. Required for `hyperdisk-balanced`, rejected for every other disk type.
`gce.regions`	map	yes	Per-region pricing. Lists the regions this entry is priced in: include every region your placements use. Keyed by region string (e.g. `us-central1`). Each entry is a `DiskRegionConfig`.

Provisioned performance

Some GCE disk types let you choose IOPS and throughput when the disk is created; the rest work them out from the disk’s size. GCE rejects a request that sets a value its disk type works out for itself, so set exactly what the table says:

`gce.disk_type`	`provisioned_iops`	`provisioned_throughput_mibps`
`hyperdisk-balanced`	required	required
`pd-extreme`	required	rejected: derived from the provisioned IOPS
`pd-balanced`, `pd-ssd`, `pd-standard`	rejected: derived from capacity	rejected: derived from capacity

Disk types that aren’t in the table take neither value, and setting one is an error. On hyperdisk-balanced the two values also constrain each other. At P IOPS, throughput has to be between MAX(140, P/256) and MIN(2400, P/4) MiB/s: at 3,000 IOPS, that’s 140 to 750 MiB/s. A throughput outside that range can’t be built at any size, so murmur rejects the disk type. Performance belongs to the disk type, not to the environment that references it. An environment picks a disk type and a disk_size_gb; to offer a second performance level, add a second disk type. Disk types stored without these fields keep working, and their volumes get whatever performance GCE picks for the size. Fill the values in the next time you write one.

Disk types an agent VM cannot use

An agent VM has one disk and boots from it. GCE creates that disk together with the instance, from an image, in the instance’s zone. Four disk types can’t be used that way, so murmur rejects them whatever performance you give them.

`gce.disk_type`	Why
`hyperdisk-extreme`	GCE does not boot from a Hyperdisk Extreme volume.
`hyperdisk-throughput`	GCE does not boot from a Hyperdisk Throughput volume.
`hyperdisk-ml`	GCE does not boot from a Hyperdisk ML volume.
`hyperdisk-balanced-high-availability`	The volume is regional, and GCE creates a regional volume from a snapshot rather than from an image.

Disk size and provisioned IOPS

Size limits how much IOPS a hyperdisk-balanced volume can have, so a disk type and a disk_size_gb that are each fine on their own can still be a combination GCE won’t build. A volume of x GiB gets at least MIN(500x, 3000) IOPS and at most MIN(500x, 160000):

`disk_size_gb`	IOPS the volume takes
4	exactly 2,000
5	exactly 2,500
6 to 320	3,000 to `500 × disk_size_gb`
321 to 65,536	3,000 to 160,000

So a 3,000-IOPS disk type needs at least 6 GiB. Pair one with a smaller disk_size_gb and provisioning fails, with an error naming the environment, the size, and the IOPS GCE would have given the volume. The same happens for a size outside the 4 GiB to 64 TiB (65,536 GiB) range hyperdisk-balanced supports. An environment that leaves disk_size_gb unset uses the boot image’s size, which murmur doesn’t know when the environment is written and so can’t weigh against these bounds. That’s fine for a disk type that provisions nothing, but pair an unset size with one that provisions IOPS or throughput and the environment is rejected as soon as you write it: provisions performance, which needs the disk size stated.

AWS spec fields

Set substrate: SUBSTRATE_AWS and provide aws:

Name	Type	Required	Description
`aws.volume_type`	string	yes	EBS volume type identifier (e.g. `gp3`, `gp2`, `st1`). Provisioned-IOPS types (`io1`, `io2`) are refused: see below.
`aws.regions`	map	yes	Per-region pricing. Lists the regions this entry is priced in: include every region your placements use. Keyed by region string (e.g. `us-east-1`). Each entry is a `DiskRegionConfig`.

io1 and io2 are provisioned-IOPS volume types, and DiskRegionConfig has no field to carry an IOPS value, so a VM whose disk type names one is refused before launch. The built-in murmur-io2 is affected: use murmur-gp3 for AWS. An AWS agent VM is launched with two EBS volumes: a boot volume, and a volume sized to the instance’s RAM that holds the memory image EC2 writes when the agent sleeps. Both take the disk type the VM’s environment references, so that type’s rate for the placement’s region prices both. A machine type that does not preserve memory on sleep holds no memory image and is launched with its boot volume alone.

DiskRegionConfig

Each entry in the regions map contains:

Name	Type	Required	Description
`cost_per_gib_month`	double	yes	Storage cost per GiB per month in USD. Must be greater than 0 and at most 10. Murmur bills in centimills (0.00001 USD), so any rate under 0.000005 is rejected because it rounds to zero.
`performance_cost_per_month`	double	no	What the disk type’s provisioned IOPS and throughput cost per disk per month, in USD, on top of capacity. Must be `>= 0` and at most 1000000, and anything above `0` has to round to at least one centimill. Use `0` if the type provisions no performance, or if its performance is included in the per-GiB price.

A disk costs cost_per_gib_month × disk_size_gb + performance_cost_per_month per month. The performance charge doesn’t scale with size because provisioned performance doesn’t either: 3,000 IOPS costs the same on a 20 GiB disk as on a 2,000 GiB one. Rolling it into the per-GiB price would overcharge big disks and undercharge small ones. Only set performance_cost_per_month on a disk type that provisions performance. pd-* types get their IOPS and throughput from capacity, and murmur never sets IOPS or throughput on an AWS volume, so on those there’s no fixed performance to charge for. Use 0.

Examples

Listing disk types

murmur get disk-type

murmur-gp3
murmur-io2
murmur-pd-balanced
murmur-pd-ssd
murmur-pd-standard

The list prints one name per line, with no header. A disabled built-in prints as murmur-io2 (disabled — re-enable: murmur set disk-type murmur-io2). murmur-io2 is listed because the platform really does return it, but a VM that references it is refused before launch, as described under AWS spec fields. Use murmur-gp3 for AWS, and murmur rm disk-type murmur-io2 if you want it out of resolution entirely.

Reading a single disk type

murmur get disk-type murmur-pd-balanced

GCP disk type shape

This built-in shape shows its current production regions. The regions map lists where the entry is priced. A VM takes its storage rate from its disk type and its compute rate from its machine type, so price every region your placements use in both entries.

name: murmur-pd-balanced
description: "Balanced persistent disk"
substrate: SUBSTRATE_GCP
gce:
  disk_type: pd-balanced
  regions:
    us-central1:
      cost_per_gib_month: 0.10
    us-east1:
      cost_per_gib_month: 0.10
    us-west1:
      cost_per_gib_month: 0.10

GCP Hyperdisk disk type shape

name: murmur-hyperdisk-balanced
description: "GCE hyperdisk-balanced: SSD disk provisioned at 3,000 IOPS and 140 MiB/s."
substrate: SUBSTRATE_GCP
gce:
  disk_type: hyperdisk-balanced
  provisioned_iops: 3000
  provisioned_throughput_mibps: 140
  regions:
    us-central1:
      cost_per_gib_month: 0.08
      performance_cost_per_month: 0

AWS disk type shape

This built-in shape follows the same region-scoped pricing rule.

name: murmur-gp3
description: "General purpose SSD (gp3)"
substrate: SUBSTRATE_AWS
aws:
  volume_type: gp3
  regions:
    us-east-1:
      cost_per_gib_month: 0.08
    us-west-2:
      cost_per_gib_month: 0.08

Errors

Code	Meaning	What to do
`INVALID_ARGUMENT`	`name is required`	Provide a `name` field.
`INVALID_ARGUMENT`	`name must match [a-z][a-z0-9-]{0,62}`	Use a lowercase DNS label for `name`.
`INVALID_ARGUMENT`	`description exceeds 1024 byte limit`	Shorten the `description` to 1024 bytes or fewer.
`INVALID_ARGUMENT`	`substrate is required`	Set the `substrate` field to `SUBSTRATE_GCP` or `SUBSTRATE_AWS`.
`INVALID_ARGUMENT`	`spec is required (gce or aws)`	Provide a `gce` or `aws` spec block.
`INVALID_ARGUMENT`	`substrate must be GCP for gce spec, got <substrate>`	The `substrate` field does not match the spec block. Set `substrate: SUBSTRATE_GCP` when using `gce`.
`INVALID_ARGUMENT`	`substrate must be AWS for aws spec, got <substrate>`	The `substrate` field does not match the spec block. Set `substrate: SUBSTRATE_AWS` when using `aws`.
`INVALID_ARGUMENT`	`gce.disk_type is required`	The GCE spec is missing `disk_type`.
`INVALID_ARGUMENT`	`"<disk type>" cannot be a murmur VM's disk: <reason>, and a murmur VM boots from the one disk it is created with`	An agent VM boots from its only disk, and this type can’t be that disk. Pick one of the types listed above.
`INVALID_ARGUMENT`	`"<disk type>" takes its IOPS from the create request, so gce.provisioned_iops must be > 0, got 0`	This disk type takes its IOPS from you. Set `provisioned_iops`.
`INVALID_ARGUMENT`	`"<disk type>" takes its throughput from the create request, so gce.provisioned_throughput_mibps must be > 0, got 0`	This disk type takes its throughput from you. Set `provisioned_throughput_mibps`.
`INVALID_ARGUMENT`	`"<disk type>" derives its performance from its capacity, so GCE rejects the <field>=<value> it carries`	This disk type works out both values from the disk’s size. Remove the field.
`INVALID_ARGUMENT`	`"<disk type>" derives its <IOPS\|throughput> from <the other value it provisions>, so GCE rejects the <field>=<value> it carries`	This disk type takes one value from you and works out the other. Remove the one it works out.
`INVALID_ARGUMENT`	`"<disk type>" provisioned at <P> IOPS takes <lo> to <hi> MiB/s, not gce.provisioned_throughput_mibps=<value>`	The two values are incompatible. Move the throughput into the range the IOPS allows, or change the IOPS.
`INVALID_ARGUMENT`	`gce.regions must be non-empty`	Provide at least one region entry in the GCE spec.
`INVALID_ARGUMENT`	`gce.regions["<region>"].cost_per_gib_month must be > 0`	Every region entry needs a positive `cost_per_gib_month`.
`INVALID_ARGUMENT`	`<spec>.regions["<region>"].cost_per_gib_month <value> is above the maximum billable rate of 10 USD per GiB-month`	This rate is multiplied by both the disk’s size and how long it lives, so it adds up fast. Use 10 or less.
`INVALID_ARGUMENT`	`<spec>.regions["<region>"].cost_per_gib_month <value> is below one centimill (0.00001), the unit murmur bills in, and would round to unpriced`	A rate this small rounds to zero, and zero means unpriced rather than nearly free. Raise it to at least 0.000005.
`INVALID_ARGUMENT`	`<spec>.regions["<region>"].performance_cost_per_month must be >= 0`	A performance charge can’t be negative. Use `0` to charge nothing.
`INVALID_ARGUMENT`	`<spec>.regions["<region>"].performance_cost_per_month <value> is above the maximum billable rate of 1e+06 USD`	Use a rate of 1000000 or less.
`INVALID_ARGUMENT`	`<spec>.regions["<region>"].performance_cost_per_month <value> is below one centimill (0.00001), the unit murmur bills in, and would round to uncharged; state 0 to charge nothing`	Same rounding as above, except `0` is a real answer here. Raise the charge to at least 0.000005, or use `0`.
`INVALID_ARGUMENT`	`<spec>.regions["<region>"].performance_cost_per_month <value> charges for a provisioned performance this disk type does not fix; state 0`	This disk type doesn’t provision performance, so there’s nothing for the charge to cover. Use `0`, or put the cost in `cost_per_gib_month` if it scales with size.
`INVALID_ARGUMENT`	`aws.volume_type is required`	The AWS spec is missing `volume_type`.
`INVALID_ARGUMENT`	`aws.regions must be non-empty`	Provide at least one region entry in the AWS spec.
`INVALID_ARGUMENT`	`aws.regions["<region>"].cost_per_gib_month must be > 0`	Every region entry needs a positive `cost_per_gib_month`.
`INVALID_ARGUMENT`	`platform disk types are reserved for builtins and cannot be written via the catalog`	Do not set the `platform` field. Built-in disk types are managed by the platform.

Environments and placements: the resource that references a disk type via disk_type_ref
murmur get: CLI command for reading catalog resources
placement: catalog resource for cloud infrastructure targets

Getting Started

Core Concepts

Guides

Fields

GCE spec fields

Provisioned performance

Disk types an agent VM cannot use

Disk size and provisioned IOPS

AWS spec fields

DiskRegionConfig

Examples

Listing disk types

Reading a single disk type

GCP disk type shape

GCP Hyperdisk disk type shape

AWS disk type shape

Errors

​Fields

​GCE spec fields

​Provisioned performance

​Disk types an agent VM cannot use

​Disk size and provisioned IOPS

​AWS spec fields

​DiskRegionConfig

​Examples

​Listing disk types

​Reading a single disk type

​GCP disk type shape

​GCP Hyperdisk disk type shape

​AWS disk type shape

​Errors

​Related

Fields

GCE spec fields

Provisioned performance

Disk types an agent VM cannot use

Disk size and provisioned IOPS

AWS spec fields

DiskRegionConfig

Examples

Listing disk types

Reading a single disk type

GCP disk type shape

GCP Hyperdisk disk type shape

AWS disk type shape

Errors

Related