Service Configuration

The pilum.yaml file defines how your service is built and deployed. Pilum discovers these files automatically in your project.

Basic Structure

name: my-service
description: My awesome service
provider: gcp
project: my-gcp-project
region: us-central1

build:
  language: go
  version: "1.23"

env_vars:
  LOG_LEVEL: info

secrets:
  DATABASE_URL: projects/123/secrets/db-url:latest

Required Fields

These fields are validated by the recipe. Missing fields cause pilum check to fail.

Field	Description
`name`	Service identifier (used in commands and image names)
`provider`	Cloud provider (`gcp`, `aws`, `azure`, `homebrew`)

Additional required fields depend on the provider. See Providers for details.

Common Fields

Field	Type	Description
`name`	string	Service name
`description`	string	Human-readable description
`provider`	string	Cloud provider identifier
`project`	string	Project/account identifier
`region`	string	Deployment region
`regions`	list	Multiple regions for multi-region deploys
`template`	string	Recipe template to use (e.g., `gcp-cloud-run`)
`registry_name`	string	Container registry URL
`depends_on`	list	Services this depends on (for ordering)

Environment Variables

Define environment variables for your deployed service:

env_vars:
  LOG_LEVEL: info
  API_TIMEOUT: "30"
  FEATURE_FLAGS: "new-ui,dark-mode"

Secrets

Reference secrets from your cloud provider’s secret manager:

# GCP Secret Manager
secrets:
  DATABASE_URL: projects/123456/secrets/database-url:latest
  API_KEY: projects/123456/secrets/api-key:latest

Secrets are passed to the deployment command (e.g., --set-secrets for Cloud Run).

Multi-Region Deployments

Deploy to multiple regions with a single configuration:

name: my-api
provider: gcp
project: my-project
regions:
  - us-central1
  - europe-west1
  - asia-east1

Pilum expands this into three deployments, one per region.

Dependencies

Control deployment order with depends_on:

name: database
provider: gcp
# ...

# api/pilum.yaml
name: api
provider: gcp
depends_on:
  - database  # Deploy database first

Provider-Specific Configuration

Additional configuration varies by provider. Use nested maps:

# GCP Cloud Run specific
name: my-api
provider: gcp
project: my-project
region: us-central1

cloud_run:
  min_instances: 0
  max_instances: 10
  memory: "512Mi"
  cpu: "1"
  concurrency: 80
  timeout_seconds: 300
  cpu_throttling: true

# Homebrew specific
name: my-cli
provider: homebrew
project: my-org

homebrew:
  tap_url: https://github.com/my-org/homebrew-tap
  project_url: https://github.com/my-org/my-cli
  token_env: GH_TOKEN

Complete Example

name: payment-api
description: Payment processing API service
provider: gcp
project: acme-payments
region: us-central1
registry_name: us-central1-docker.pkg.dev/acme-payments/services

build:
  language: go
  version: "1.23"
  cmd: "go build -o ./dist/payment-api ./cmd/api"
  env_vars:
    CGO_ENABLED: "0"
    GOOS: linux
    GOARCH: amd64
  flags:
    ldflags:
      - "-s"
      - "-w"
      - "-X main.version=${TAG}"

env_vars:
  LOG_LEVEL: info
  ENVIRONMENT: production

secrets:
  STRIPE_KEY: projects/123456/secrets/stripe-key:latest
  DATABASE_URL: projects/123456/secrets/payment-db-url:latest

cloud_run:
  min_instances: 1
  max_instances: 50
  memory: "1Gi"
  cpu: "2"
  concurrency: 100
  timeout_seconds: 30

depends_on:
  - payment-db

Next Steps

Build Configuration — Detailed build settings
GCP Cloud Run — GCP-specific options
CLI Commands — All available commands