TutorialsTutorialInfrastructure

The complete guide to blueprint.yaml

One file defines your web services, databases, workers, cron jobs, and environment wiring. Here is every field and how teams use them in production.

Tom Walsh

Developer Advocate

May 10, 202613 min read

If you have deployed more than one service on StackBlaze, you have probably touched blueprint.yaml. It is the infrastructure-as-code file for your entire environment, not just your API, but Postgres, Redis, background workers, scheduled jobs, and how they connect to each other.

Minimal example

blueprint.yaml

name: my-app
region: us-east

services:
  web:
    type: web
    build: .
    port: 3000
    healthcheck:
      path: /healthz/ready
    env:
      NODE_ENV: production

  db:
    type: postgres
    version: "16"
    plan: standard

StackBlaze reads this file on every deploy. When you attach resources in the dashboard, we write the equivalent YAML back to your repo so the file stays the source of truth.

Service types

Type	Use case	Scaling
web	HTTP APIs, Next.js, Rails	Horizontal autoscaling
worker	Queue consumers, async jobs	Horizontal autoscaling
cron	Scheduled tasks	Single instance per schedule
postgres	Relational data	Vertical (plan tiers)
redis	Cache, sessions, pub/sub	Vertical

Linking services together

Use from_service to inject connection details without hardcoding hostnames. StackBlaze resolves .internal DNS and sets the right environment variables automatically.

blueprint.yaml

services:
  api:
    type: web
    build: ./api
    port: 8080
    env:
      DATABASE_URL:
        from_service: db
        property: connection_string
      REDIS_URL:
        from_service: cache
        property: connection_string

  db:
    type: postgres
    version: "16"

  cache:
    type: redis
    version: "7"

Secrets vs env

Use env for non-sensitive configuration. Use secrets for API keys and tokens, they are encrypted at rest and only exposed to the services you list under secret_refs.

Workers and cron jobs

blueprint.yaml

  worker:
    type: worker
    build: ./worker
    start: node dist/worker.js
    env:
      REDIS_URL:
        from_service: cache
        property: connection_string

  nightly-report:
    type: cron
    schedule: "0 6 * * *"
    build: ./jobs
    start: node dist/report.js
    env:
      DATABASE_URL:
        from_service: db
        property: connection_string

Deploy hooks and previews

Run migrations before traffic shifts to new code with a pre_deploy hook. Enable PR previews with a top-level previews block (see our PR previews announcement for details).

blueprint.yaml

services:
  web:
    type: web
    build: .
    hooks:
      pre_deploy: npm run db:migrate

previews:
  enabled: true
  seed_from: staging

Common mistakes

Forgetting healthcheck.path, deploys succeed but traffic never routes to new pods
Pointing build at the repo root when your Dockerfile lives in a subdirectory
Using the same service name in two environments without namespacing, names must be unique per blueprint
Setting max_instances without a spend_cap during your first traffic spike

blueprint.yaml is versioned with your code. Review changes in pull requests the same way you review application logic, your production topology is in that file.

Tom Walsh

Developer Advocate at StackBlaze

Member of the founding team at StackBlaze. Writes about infrastructure, engineering culture, and the systems that keep production running.

How Calico network policies isolate tenants on shared hosting

Shared Kubernetes does not have to mean shared trust boundaries. Calico enforces network isolation, Linkerd provides automatic mTLS between services, and Falco detects runtime threats, three layers that keep tenants separated on shared infrastructure.

Sarah Kim

Security16 min read

Shared platform vs dedicated clusters: control plane isolation and policy-as-code

Policy-as-code on a shared platform gives you guardrails without operational overhead. Dedicated clusters add an isolated control plane, single-tenant nodes, and customer-owned policy boundaries, here is how to choose and what changes under the hood.

Priya Patel

Security18 min read

Regulatory compliance and data governance on StackBlaze

SOC 2, GDPR, HIPAA-readiness, data residency, encryption, audit logs, and DPAs, a detailed map of how StackBlaze controls align with common regulatory frameworks and what you own vs what the platform certifies.

Nina Okoye