How Recipes Work

Recipes are the heart of Pilum. They define deployment workflows as ordered steps, along with validation rules for service configuration.

What is a Recipe?

A recipe is a YAML file that defines:

Required fields — What a pilum.yaml must contain
Optional fields — Additional configuration with defaults
Steps — Ordered commands to execute

name: gcp-cloud-run
description: Deploy to GCP Cloud Run
provider: gcp
service: cloud-run

required_fields:
  - name: project
    description: GCP project ID
    type: string
  - name: region
    description: GCP region
    type: string

optional_fields:
  - name: min_instances
    description: Minimum number of instances
    type: int
    default: "0"

steps:
  - name: build binary
    execution_mode: service_dir
    timeout: 300

  - name: build docker image
    execution_mode: service_dir
    timeout: 300

  - name: push to registry
    execution_mode: root
    timeout: 180

  - name: deploy to cloud run
    execution_mode: root
    timeout: 300
    tags:
      - deploy

Recipe-Driven Validation

When you run pilum check, Pilum:

Finds all pilum.yaml files
Looks up the recipe for each service’s provider
Validates that all required fields (without defaults) are present

This means no Go code per provider — just add a YAML file.

$ pilum check
✓ api-gateway: validated against gcp-cloud-run
✓ worker-service: validated against gcp-cloud-run
✗ payment-api: missing required field 'region'

Required vs Optional Fields

Required Fields

Fields that must be in pilum.yaml:

required_fields:
  - name: project
    description: GCP project ID
    type: string

  - name: region
    description: GCP region (e.g., us-central1)
    type: string

If a required field has a default, it becomes optional:

required_fields:
  - name: stack_name
    description: CloudFormation stack name
    type: string
    default: ${name}-stack  # Uses service name if not specified

Optional Fields

Additional configuration shown during pilum init:

optional_fields:
  - name: min_instances
    description: Minimum number of instances
    type: int
    default: "0"

  - name: memory
    description: Memory allocation
    type: string
    default: "512Mi"

Optional fields are not validated — they provide suggestions during setup.

Field Types

Type	Description	Example
`string`	Text value	`"us-central1"`
`int`	Integer value	`10`
`bool`	true/false	`true`
`list`	Array of values	`["a", "b"]`

Steps

Steps define the deployment workflow:

steps:
  - name: build binary
    execution_mode: service_dir
    timeout: 300
    env_vars:
      CGO_ENABLED: "0"

  - name: deploy
    command: ["gcloud", "run", "deploy", "${name}"]
    execution_mode: root
    timeout: 300
    retries: 2
    tags:
      - deploy

Step Options

Field	Type	Description
`name`	string	Step name (used for handler lookup)
`command`	string/list	Explicit command (overrides handler)
`execution_mode`	string	`root` or `service_dir`
`timeout`	int	Max seconds to wait
`retries`	int	Retry count on failure
`env_vars`	map	Environment variables
`tags`	list	Labels for filtering

Execution Mode

root — Run from project root directory
service_dir — Run from the service’s directory

Handler vs Explicit Commands

Steps can use:

Handlers — Auto-generated commands based on step name
Explicit commands — Shell commands defined in the recipe

Using Handlers

When no command is specified, Pilum looks up a registered handler:

steps:
  - name: build binary
    execution_mode: service_dir
    # Handler generates: go build -o ./dist ...

Using Explicit Commands

Define the exact command to run:

steps:
  - name: sync to s3
    command: aws s3 sync ./dist s3://${project}-bucket
    execution_mode: service_dir

Available variables: ${name}, ${tag}, ${provider}, ${region}, ${project}

Built-in Recipes

Pilum includes recipes for:

Recipe	Provider	Service
`gcp-cloud-run`	`gcp`	`cloud-run`
`aws-lambda`	`aws`	`lambda`
`homebrew`	`homebrew`	`package`

Next Steps

Adding a Provider — Add new provider support to Pilum
CLI Commands — Using step tags and filtering