YAML reference

All authored resources live below .deliberate/. The directory-level project.yaml pins the Team, Project, and environment flow; every other YAML document begins with an explicit resource: discriminator.

Project pin

team: acme
project: chat
flow: default

Resources

Resource	Purpose
component	A long-running service, background worker, or scheduled job
database	Managed PostgreSQL or FerretDB
volume	Durable, automatically expanding filesystem storage
bucket	Elastic S3-compatible object storage
route	Explicit public or Private Net HTTP routing
domain	A customer-owned hostname attached to an environment
blueprint	A pinned instance of a published Blueprint
flow-pattern	A custom environment and promotion topology

Components

Components declare an image and only the behavior they need. Ports are internal unless they request visibility: public or private. No ports means a worker; schedule: means a scheduled job.

resource: component
name: app
image: ghcr.io/acme/app:1.4.2
cpu: 0.5
memory: 1Gi
ports:
  - port: 3000
    visibility: public
env:
  DATABASE_URL: "${{ postgres.url }}"
secrets:
  - SESSION_SECRET
needs:
  databases:
    - postgres
healthcheck:
  path: /health

Declaring needs authorizes the dependency; it injects nothing automatically. Wire the output to the environment-variable name your software expects with a ${{ name.output }} expression.

Complete example

This bundle describes a production application and its supporting resources. Put it in .deliberate/app.yaml, next to .deliberate/project.yaml.

# Managed PostgreSQL is addressed as `postgres` by the components below.
resource: database
name: postgres
engine: postgres
tier: prod
version: "17"
extensions:
  - vector

---
# Volumes grow automatically. `backup` selects the durability policy.
resource: volume
name: uploads
backup: offsite

---
# Buckets expose S3-compatible outputs such as endpoint and access_key.
resource: bucket
name: assets
expose: true
anonymousRead: false

---
resource: component
name: app
image: ghcr.io/acme/example-app:1.4.2
cpu: 0.5
memory: 1Gi
replicas: 1
class: standard
ports:
  - port: 3000
    protocol: http
env:
  NODE_ENV: production
  DATABASE_URL: "${{ postgres.url }}"
  DATABASE_POOL_URL: "${{ postgres.pooled_url }}"
  S3_ENDPOINT: "${{ assets.endpoint }}"
  S3_BUCKET: "${{ assets.bucket }}"
  S3_ACCESS_KEY: "${{ assets.access_key }}"
  S3_SECRET_KEY: "${{ assets.secret_key }}"
secrets:
  - SESSION_SECRET
needs:
  databases:
    - postgres
  buckets:
    - assets
  volumes:
    - name: uploads
      path: /app/uploads
healthcheck:
  path: /health
  port: 3000
  initialDelay: 15s
release:
  command: ["npm", "run", "migrate"]
  timeout: 10m
postDeploy:
  command: ["npm", "run", "warm-cache"]
  timeout: 5m
shutdown:
  gracePeriod: 60s
alerts:
  - name: elevated-error-rate
    type: http_error_rate
    threshold: 5
    window: 10m
    minRequests: 100
    recipients:
      - ops@example.com
overrides:
  preview-*:
    cpu: 0.125
    memory: 256Mi
    replicas: 1
    class: standard

---
# A worker is the same component primitive without a port.
resource: component
name: worker
image: ghcr.io/acme/example-app:1.4.2
command: ["npm", "run", "worker"]
cpu: 0.5
memory: 1Gi
env:
  DATABASE_URL: "${{ postgres.url }}"
needs:
  databases:
    - postgres

---
# Routes deliberately connect a hostname to a component.
resource: route
host: chat
visibility: public
rules:
  - path: /
    to: app
open:
  - label: Open Acme Chat
    path: /
    description: Open the customer-facing application.
  - label: Administration
    path: /admin
    description: Configure the application.

The needs declarations grant the app access to the named resources. The ${{ ... }} expressions then map their outputs to the environment-variable names this particular image expects. release runs before the new revision is made current; postDeploy runs after deployment. The preview-* override keeps every matching preview environment smaller without changing production.

The route is separate from the component on purpose: it makes public exposure explicit and lets the same component remain private in another declaration.

The parser rejects unknown fields. Internal projection and historical migration fields are not part of the authored vocabulary even if they appear in stored revision data.