image

An image is a catalog resource that points to a runnable artifact on a specific substrate: an AWS AMI or a GCE disk image. Each workspace references one image via its image_ref field. Images are typically produced by the bake process. When you bake a recipe, the platform executes it against a base image and writes the resulting image back to the catalog with provenance metadata. Baked images are immutable: you cannot update them. Deleting a baked image with murmur rm image <name> also deletes its cloud artifact (the GCE image or the AMIs). Deleting a hand-authored image removes only the catalog record. You can also author images manually to reference existing AMIs or GCE images that you manage outside Murmur.

Fields

A new baked image inherits its recipe’s workspace_use policy. Reusing an existing baked image preserves its stored policy. Baked records are immutable to tenant callers, including their admission policy.

Name	Type	Required	Description
`workspace_use`	object	no	For tenant-level names, which workspaces may use this resource: `scope` is `WORKSPACE_USE_SCOPE_NONE` (default), `WORKSPACE_USE_SCOPE_ALL`, or `WORKSPACE_USE_SCOPE_SELECTED` with a `workspaces` list. Scoped names carry no policy and are usable only in their own workspace. See resource admission.
`name`	string	yes	A bare tenant-level DNS label or `{workspace}/{name}`, with both segments matching `[a-z][a-z0-9-]{0,62}`. A scoped name requires an existing workspace. Baking generates the name automatically.
`description`	string	no	Human-readable description shown in the dashboard. Maximum 1024 bytes.
`architecture`	string	yes	CPU architecture. Values: `ARCHITECTURE_AMD64`, `ARCHITECTURE_ARM64`.
`preinstalled`	string	no	Summary of preinstalled software on this image. Set on platform-managed images.
`aws`	object	one of	AWS AMI source. See AWS source fields.
`gce`	object	one of	GCE image source. See GCE source fields.

Exactly one of aws or gce must be set.

AWS source fields

Set aws to reference one or more AMIs:

Name	Type	Required	Description
`aws.ami_ids`	map<string, string>	yes	Region-to-AMI-ID map. Each key is an AWS region (e.g. `us-east-1`), each value is an AMI ID (e.g. `ami-0abc123def456789a`). Must have at least one entry.
`aws.provenance`	object	no	Bake provenance. Set automatically when the image is produced by a recipe bake. Cannot be set via `murmur set`.

AMIs are region-bound. A baked image has one entry in ami_ids: the region the bake ran in. If a workspace references this image and its placement targets a different region, spawn fails.

GCE source fields

Set gce to reference a GCE disk image or image family:

Name	Type	Required	Description
`gce.self_link`	string	yes	GCE image self-link. Format: `projects/<project>/global/images/<name>` or `projects/<project>/global/images/family/<family>`.
`gce.image_id`	uint64	no	GCE server-assigned immutable image id. Set at bake.
`gce.provenance`	object	no	Bake provenance. Set automatically when the image is produced by a recipe bake. Cannot be set via `murmur set`.

Provenance fields

Provenance is present on baked images and records what produced them. It is set automatically by the bake process and cannot be set via murmur set.

Name	Type	Required	Description
`provenance.recipe_ref`	string	yes	Name of the recipe that produced this image.
`provenance.image_hash`	string	yes	SHA-256 hex hash of bake inputs. 64 characters. Immutable.

Examples

Hand-authored GCE image

name: debian12-base
description: "Stock Debian 12 with our internal SDK"
architecture: ARCHITECTURE_AMD64
gce:
  self_link: "projects/acme-agents/global/images/family/debian-12-sdk"

cat <<'EOF' | murmur set image debian12-base
name: debian12-base
description: "Stock Debian 12 with our internal SDK"
architecture: ARCHITECTURE_AMD64
gce:
  self_link: "projects/acme-agents/global/images/family/debian-12-sdk"
EOF

Hand-authored AWS image

name: ubuntu22-ml
description: "Ubuntu 22.04 with CUDA and PyTorch"
architecture: ARCHITECTURE_AMD64
aws:
  ami_ids:
    us-east-1: "ami-0abc123def456789a"
    us-west-2: "ami-0def456789abc1234"

Baked image (generated by the platform)

Baked images appear in the catalog after a successful bake. Their names are generated and they carry provenance metadata:

name: go-python-a1b2c3d4e5f67890
architecture: ARCHITECTURE_AMD64
gce:
  self_link: "projects/acme-agents/global/images/go-python-a1b2c3d4e5f67890"
  provenance:
    recipe_ref: go-python
    image_hash: "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"

Listing images

murmur get image

Reading a single image

murmur get image debian12-base

Errors

Code	Meaning	What to do
`INVALID_ARGUMENT`	`name is required`	Provide a `name` field.
`INVALID_ARGUMENT`	`image name must be a DNS label or {workspace}/{name}`	Use a bare DNS label or a scoped name whose two segments are DNS labels.
`INVALID_ARGUMENT`	`description exceeds 1024 byte limit`	Shorten the `description` to 1024 bytes or fewer.
`INVALID_ARGUMENT`	`architecture is required`	Set `architecture` to `ARCHITECTURE_AMD64` or `ARCHITECTURE_ARM64`.
`INVALID_ARGUMENT`	`unknown architecture value <n>`	Use a valid architecture enum value.
`INVALID_ARGUMENT`	`source is required ...`	Provide exactly one of `aws` or `gce`.
`INVALID_ARGUMENT`	`aws.ami_ids must be non-empty`	Add at least one region-to-AMI entry in `aws.ami_ids`.
`INVALID_ARGUMENT`	`aws.ami_ids: region key must be non-empty`	Every key in `aws.ami_ids` must be a non-empty region string.
`INVALID_ARGUMENT`	`aws.ami_ids[<region>]: must match ami-[0-9a-f]{8,17}, got "<id>"`	Each AMI ID must be a valid AWS AMI identifier (e.g. `ami-0abc123def456789a`).
`INVALID_ARGUMENT`	`gce.self_link is required`	Provide a `gce.self_link` value.
`INVALID_ARGUMENT`	`gce.self_link: invalid GCE image reference`	Use the format `projects/<project>/global/images/<name>` or `projects/<project>/global/images/family/<family>`.
`INVALID_ARGUMENT`	`provenance cannot be set via SetResource`	Provenance is set by the bake process. Remove the `provenance` field from your input.
`FAILED_PRECONDITION`	`baked images are immutable`	Baked images cannot be updated. Bake a new image from the recipe instead.

Images: concept overview
Recipes: the provisioning template that produces baked images
Workspaces: the resource that references an image via image_ref
murmur set: CLI command for creating and updating catalog resources
murmur get: CLI command for reading catalog resources
murmur bake: bakes images from recipes

Getting Started

Core Concepts

Guides

Fields

AWS source fields

GCE source fields

Provenance fields

Examples

Hand-authored GCE image

Hand-authored AWS image

Baked image (generated by the platform)

Listing images

Reading a single image

Errors

​Fields

​AWS source fields

​GCE source fields

​Provenance fields

​Examples

​Hand-authored GCE image

​Hand-authored AWS image

​Baked image (generated by the platform)

​Listing images

​Reading a single image

​Errors

​Related

Fields

AWS source fields

GCE source fields

Provenance fields

Examples

Hand-authored GCE image

Hand-authored AWS image

Baked image (generated by the platform)

Listing images

Reading a single image

Errors

Related