zedcloud.yaml

zedcloud.yaml describes a workspace as code. Export what you drew, commit it, review changes in pull requests, and apply it to stage the differences.

zc export -o zedcloud.yaml        # the live workspace
zc apply -f zedcloud.yaml --dry-run
zc apply -f zedcloud.yaml         # stages the changes; then Deploy

Example

version: 1
groups:
  backend:
    color: "#0ea5e9"
    network: public
resources:
  db:
    kind: database
    subtype: postgres
    group: backend
  cache:
    kind: cache
    subtype: valkey
    group: backend
  api:
    kind: app
    subtype: docker
    group: backend
    repo: https://github.com/acme/api
    config:
      source: github
      branch: main
      containerPort: "8080"
      replicas: "2"
      healthPath: /healthz
      public: "true"
      public: "true"
    env:
      LOG_LEVEL: info
      STRIPE_KEY: {from_env: STRIPE_KEY}
      SESSION_SECRET: {secret: true}
links:
  - {from: api, to: db}
  - {from: api, to: cache}

Keys

Key	Meaning
version	Always 1
workspace	Optional {id, name}; a different id is refused
groups	Name → {color, network: public | isolated}
resources	Label → node. Labels are unique (ignoring case)
links	List of {from, to} by label
layout	Label → {x, y}, written by zc export --layout

Each resource has kind and subtype (apps use subtype: docker), and optional group, repo (a https://github.com/owner/repo URL), config and env. zc describe kind <subtype> lists the config keys. Use containerPort for the port your app listens on.

Secrets in the file

Never put secret values in the file. Instead:

Form	Meaning
KEY: value	A plain value
{secret: true}	Keep the value the node already has
{from_env: NAME}	Read from your shell’s environment when applying
{from_file: path}	Read from a file (relative to the manifest)
{from_stdin: true}	Read from stdin (once per file)

Values read from the environment, files or stdin are never printed. Exports always write {secret: true}.

How apply works

• The whole file is checked first. Every problem is listed as path: message and nothing is staged.
• Nodes are matched by label (or id). Applying the same file twice stages nothing the second time.
• Nodes in the workspace but not in the file are reported and left alone. --prune stages them for deletion (needs the resources:delete scope); nothing is removed until someone deploys.
• If applying stops part-way (for example on a quota), re-run with the same --idempotency-key to continue.
• A node’s kind can’t change: delete it and create a new one. Moving nodes in or out of isolated groups is done in the dashboard.

zc export --staged exports what the workspace will look like after the next Deploy. zc init writes a starter file.