Config as Code

A config as code file is stackblaze.yaml at the repo root. It names a project and lists services and databases. Export a live environment from the dashboard or GET /api/iac/blueprint/export?pipeline=…&phase=…. Apply requires Infrastructure as Code on that project.

You can also import Compose, render.yaml, or fly.toml from + Service → Import on the canvas. That path compiles onto the canvas; it does not replace stackblaze.yaml.

Tip

Config as code is optional. Most teams compose on the canvas and deploy staged changes. Enable IaC when you want plan/apply and git-reviewed changes. Apply never deletes resources.

File format

The JSON Schema is GET /api/iac/blueprint/schema (no auth).

Top-level

stackblaze.yaml

pipeline: acme-app          # required — project name
domain: acme-app.stackblaze.app
previews:
  generation: automatic     # automatic | manual | off
  expireAfterDays: 7

services:
  - ...

databases:
  - ...

pipeline is the project name in the API.

Service

stackblaze.yaml

services:
  - name: api
    type: web                 # web | worker | cron
    runtime: node             # node|python|go|ruby|rust|elixir|docker|image
    plan: small
    rootDir: packages/api
    dockerfilePath: Dockerfile
    startCommand: node dist/server.js
    port: 8080
    healthCheckPath: /health
    numInstances: 2
    scaling:
      minInstances: 1
      maxInstances: 6
      targetCPUPercent: 70
    disk:
      name: data
      mountPath: /data
      sizeGB: 10
    autoDeploy: true
    envVars:
      - key: NODE_ENV
        value: production
      - key: JWT_SECRET
        sync: false           # prompted at apply; not stored in the file
      - key: DATABASE_URL
        fromDatabase:
          name: main-db
          property: connectionString

type: web is public HTTP. worker is always-on with no public domain. cron needs schedule.

Database

stackblaze.yaml

databases:
  - name: main-db
    type: postgres            # postgres | valkey | redis | mariadb | mysql
                              # kafka | clickhouse | rabbitmq | documentdb
                              # mongodb | rustfs | s3 | …
    databaseName: acme
    user: acme

Full example

stackblaze.yaml

pipeline: acme-app
domain: acme-app.stackblaze.app

databases:
  - name: postgres
    type: postgres
    databaseName: acme
  - name: cache
    type: valkey

services:
  - name: api
    type: web
    runtime: node
    rootDir: packages/api
    startCommand: node dist/index.js
    port: 3000
    plan: standard
    healthCheckPath: /health
    scaling:
      minInstances: 2
      maxInstances: 10
      targetCPUPercent: 70
    envVars:
      - key: NODE_ENV
        value: production
      - key: JWT_SECRET
        sync: false
      - key: DATABASE_URL
        fromDatabase: { name: postgres, property: connectionString }
      - key: REDIS_URL
        fromDatabase: { name: cache, property: connectionString }

  - name: worker
    type: worker
    runtime: node
    rootDir: packages/worker
    startCommand: node dist/worker.js
    envVars:
      - key: DATABASE_URL
        fromDatabase: { name: postgres, property: connectionString }
      - key: REDIS_URL
        fromDatabase: { name: cache, property: connectionString }

  - name: nightly-report
    type: cron
    runtime: node
    rootDir: packages/scripts
    startCommand: node dist/report.js
    schedule: "0 2 * * *"
    envVars:
      - key: DATABASE_URL
        fromDatabase: { name: postgres, property: connectionString }

Plan and apply

When IaC is enabled on the organization, stackblaze plan and stackblaze apply wrap the same API. You can also plan/apply from the dashboard or with a kbr_pat_ token. Apply never deletes.

terminal

# Validate (no live reads)
curl -sS -X POST https://api.stackblaze.cloud/api/iac/blueprint/validate \
  -H "Authorization: Bearer $STACKBLAZE_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"yaml\": $(jq -Rs . < stackblaze.yaml)}"

# Diff against live state
curl -sS -X POST https://api.stackblaze.cloud/api/iac/blueprint/plan \
  -H "Authorization: Bearer $STACKBLAZE_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"yaml\": $(jq -Rs . < stackblaze.yaml)}"

# Apply — upserts project + services + databases. Never deletes.
curl -sS -X POST https://api.stackblaze.cloud/api/iac/blueprint/apply \
  -H "Authorization: Bearer $STACKBLAZE_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"yaml\": $(jq -Rs . < stackblaze.yaml)}"

You can compile a file onto the canvas (POST /api/iac/blueprint/compile) and commit staged services from the dashboard. Compile is not gated on IaC.

Variable sync

sync: false declares a key without storing its value. Apply returns missingAnswers until you pass answers or set them in the dashboard. generateValue: true mints a stable random secret at compile time. fromGroup attaches a shared variable group defined in the file.

Caution

Never commit real secrets to stackblaze.yaml. Use sync: false or fromDatabase.

Schema reference

Field	Type	Required	Description
pipeline	string	Yes	Project name
domain	string	No	Default project domain
services	array	Yes	Service definitions
databases	array	No	Database definitions
services[].name	string	Yes	Service name in the environment
services[].type	string	No	web (default) | worker | cron
services[].runtime	string	No	Nixpacks language, docker, or image
services[].plan	string	No	Instance size name
services[].schedule	string	Cron only	Standard cron expression
services[].port	number	No	Container port (default 8080)

HTTP paths: API reference. OpenAPI: /api/docs.