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
`name`	string	yes	Unique identifier. DNS label format: `[a-z][a-z0-9-]{0,62}`.
`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

NAME               DESCRIPTION
python-toolchain   Python 3.12 with Poetry and Ruff
go-service         Go 1.22 with gopls, cross-substrate
private-deps       Installs private npm packages

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`	`name must match [a-z][a-z0-9-]{0,62}`	Use a lowercase DNS label — starts with a letter, only lowercase letters, digits, and hyphens, max 63 characters.
`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`	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`	Use Go duration format: `10m`, `30m`, `1h`.
`INVALID_ARGUMENT`	`provisioning_timeout: duration must be positive`	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 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 is reserved (MURMUR_*)`	Names starting with `MURMUR_` are reserved. Choose a different name.
`INVALID_ARGUMENT`	`description exceeds 1024 byte limit`	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 or Docker 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 or Docker 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