recipe

A recipe is a catalog resource that defines how to build a custom image. Each recipe pairs one or more base images with a provisioning script that installs tools, languages, and dependencies. A single recipe can target multiple cloud substrates: reference an AWS base image, a GCE base image, or both. When you bake a recipe, Murmur runs the provisioning script on a scratch VM built from the base image, then snapshots the result as a new image.

Fields

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}`. Both segments match `[a-z][a-z0-9-]{0,62}`; a scoped name requires an existing workspace.
`base_image_aws_ref`	string	conditional	Base image name for AWS bakes. Must reference a catalog image with an AWS source. At least one of `base_image_aws_ref` or `base_image_gce_ref` is required.
`base_image_gce_ref`	string	conditional	Base image name for GCE bakes. Must reference a catalog image with a GCE source. At least one of `base_image_aws_ref` or `base_image_gce_ref` is required.
`provisioning_script`	string	yes	Script content that runs on the scratch VM during bake. Max 256 KiB.
`provisioning_timeout`	string	yes	Maximum execution time for the provisioning script. Go duration format (e.g. `10m`, `30m`). Max `1h`.
`secret_allowlist`	string[]	no	Names of catalog secrets the provisioning script may access during bake. Only these secrets are available on the scratch VM. Each name must match `[A-Z][A-Z0-9_]*` and must not start with `MURMUR_`.
`description`	string	no	Human-readable description shown in the dashboard. Max 1024 bytes.

When both base_image_aws_ref and base_image_gce_ref are set, the referenced images must have the same architecture. You cannot bake from an amd64 GCE base and an arm64 AWS base.

Examples

GCE-only recipe with a provisioning script

name: python-toolchain
base_image_gce_ref: murmur-gce-base
provisioning_script: |
  #!/bin/bash
  set -euo pipefail
  apt-get update -y
  apt-get install -y python3.12 python3.12-venv python3-pip
  pip3 install poetry==1.8.3 ruff==0.4.8
  python3.12 --version
  poetry --version
provisioning_timeout: "15m"
description: "Python 3.12 with Poetry and Ruff"

cat <<'EOF' | murmur set recipe python-toolchain
name: python-toolchain
base_image_gce_ref: murmur-gce-base
provisioning_script: |
  #!/bin/bash
  set -euo pipefail
  apt-get update -y
  apt-get install -y python3.12 python3.12-venv python3-pip
  pip3 install poetry==1.8.3 ruff==0.4.8
  python3.12 --version
  poetry --version
provisioning_timeout: "15m"
description: "Python 3.12 with Poetry and Ruff"
EOF

Multi-substrate recipe

name: go-service
base_image_aws_ref: murmur-aws-base
base_image_gce_ref: murmur-gce-base
provisioning_script: |
  #!/bin/bash
  set -euo pipefail
  curl -fsSL https://go.dev/dl/go1.22.4.linux-amd64.tar.gz | tar -C /usr/local -xz
  export PATH=$PATH:/usr/local/go/bin
  go install golang.org/x/tools/gopls@latest
  go version
provisioning_timeout: "20m"
secret_allowlist:
  - GITHUB_TOKEN
  - NPM_TOKEN
description: "Go 1.22 with gopls, cross-substrate"

Recipe with secret access

name: private-deps
base_image_gce_ref: murmur-gce-base
provisioning_script: |
  #!/bin/bash
  set -euo pipefail
  echo "//npm.pkg.github.com/:_authToken=${NPM_TOKEN}" >> ~/.npmrc
  npm install -g @acme/internal-cli@latest
provisioning_timeout: "10m"
secret_allowlist:
  - NPM_TOKEN
description: "Installs private npm packages"

Listing recipes

murmur get recipe

go-service
private-deps
python-toolchain

The list prints one name per line.

Reading a single recipe

murmur get recipe python-toolchain

Baking a recipe

After creating a recipe, run murmur bake to produce a runnable image:

murmur bake python-toolchain \
  --environment prod \
  --placement us-central1 \
  --service-profile infra-bot

See the custom images guide for a full walkthrough.

Errors

Code	Meaning	What to do
`INVALID_ARGUMENT`	`name is required`	Provide a `name` field.
`INVALID_ARGUMENT`	`recipe 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`	`at least one of base_image_aws_ref or base_image_gce_ref is required`	Set `base_image_aws_ref`, `base_image_gce_ref`, or both.
`INVALID_ARGUMENT`	`provisioning_script is required`	Provide the script content in `provisioning_script`.
`INVALID_ARGUMENT`	`provisioning_script exceeds 256 KiB limit (N bytes)`	Reduce the script size. Move large assets to a remote location and fetch them during provisioning.
`INVALID_ARGUMENT`	`provisioning_timeout is required`	Set `provisioning_timeout` to a Go duration string (e.g. `10m`).
`INVALID_ARGUMENT`	`provisioning_timeout: invalid duration "X"`	Use Go duration format: `10m`, `30m`, `1h`.
`INVALID_ARGUMENT`	`provisioning_timeout: duration must be positive, got "X"`	The duration must be greater than zero.
`INVALID_ARGUMENT`	`provisioning_timeout exceeds 1h maximum`	Reduce the timeout to 1 hour or less.
`INVALID_ARGUMENT`	`secret_allowlist[N]: secret name "X" must match [A-Z][A-Z0-9_]*`	Secret names use uppercase letters, digits, and underscores, starting with a letter.
`INVALID_ARGUMENT`	`secret_allowlist[N]: secret name "X" is reserved (MURMUR_* is internal)`	Names starting with `MURMUR_` are reserved. Choose a different name.
`INVALID_ARGUMENT`	`description exceeds 1024 byte limit (N bytes)`	Shorten the description to 1024 bytes or fewer.
`INVALID_ARGUMENT`	`base_image_aws_ref "X" does not exist`	The named image does not exist in the catalog. Create it first or fix the name.
`INVALID_ARGUMENT`	`base_image_aws_ref "X" is not an AWS image`	The referenced image exists but has a GCE source, not AWS. Use an image with an AWS source.
`INVALID_ARGUMENT`	`base_image_gce_ref "X" does not exist`	The named image does not exist in the catalog. Create it first or fix the name.
`INVALID_ARGUMENT`	`base_image_gce_ref "X" is not a GCE image`	The referenced image exists but has an AWS source, not GCE. Use an image with a GCE source.
`INVALID_ARGUMENT`	`architecture mismatch: base_image_aws_ref is X but base_image_gce_ref is Y`	Both base images must have the same architecture. Replace one so they match.
`FAILED_PRECONDITION`	`cannot delete recipe "X": referenced by image: Y`	Baked images reference this recipe. Delete the referencing images first.

Recipe: concept overview
Images: the artifacts produced by baking a recipe
Custom images guide: end-to-end walkthrough for building and using custom images
murmur set: CLI command for creating and updating catalog resources
murmur get: CLI command for reading catalog resources
murmur bake: bakes a recipe into an image

Getting Started

Core Concepts

Guides

Fields

Examples

GCE-only recipe with a provisioning script

Multi-substrate recipe

Recipe with secret access

Listing recipes

Reading a single recipe

Baking a recipe

Errors

​Fields

​Examples

​GCE-only recipe with a provisioning script

​Multi-substrate recipe

​Recipe with secret access

​Listing recipes

​Reading a single recipe

​Baking a recipe

​Errors

​Related

Fields

Examples

GCE-only recipe with a provisioning script

Multi-substrate recipe

Recipe with secret access

Listing recipes

Reading a single recipe

Baking a recipe

Errors

Related