OrchStep for solutions architects

As a solutions architect you ship the same reference stack into a dozen different shapes: a one-replica dev sandbox for the POC, a six-replica production estate for the rollout, different regions per customer. The architecture is identical; only the knobs change. Yet the artifact you usually hand over is a runbook — prose that drifts from reality the moment someone edits the cluster by hand.

A runbook describes the stack. A workflow is the stack. When the environment-specific values live in declarative blocks and the steps stay environment-agnostic, "deploy to prod" and "deploy to dev" are the same command with a different --env.

One workflow, many targets

defaults: holds the baseline. env_groups: and environments: describe how each target differs — here, just the replica count. The provision steps never mention an environment by name.

name: reference-stack
# One workflow, many target environments - the architect's reference deploy.
defaults:
  region: us-east-1
  replicas: "2"

env_groups:
  app:
    vars:
      region: "us-east-1"
      replicas: "2"

environments:
  dev:
    group: app
    vars:
      replicas: "1"
  prod:
    group: app
    vars:
      replicas: "6"

tasks:
  # `orchstep run provision --env prod`
  provision:
    steps:
      - name: network
        func: shell
        do: echo "provisioning network in {{ vars.region }}"
      - name: data
        func: shell
        do: echo "provisioning managed datastore"
      - name: app
        func: shell
        do: echo "deploying app with {{ vars.replicas }} replicas in {{ vars.region }}"
      - name: verify
        func: shell
        do: echo "smoke check against the reference stack"

The architecture is in one place; the per-target deltas are in another. A customer who needs eu-west-1 and ten replicas adds an environment block — they don't fork your steps.

Select the target, don't edit the stack

orchstep run provision --env dev    # 1 replica
orchstep run provision --env prod   # 6 replicas

Same steps, different resolved values. And --var always beats --env, so a one-off tweak never means editing the file:

orchstep run provision --env prod --var replicas=10

Prove coverage before you hand it over

The failure mode of multi-environment configs is a variable that's set for one target and silently empty for another. orchstep validate catches it statically — it scans every vars.X the task references and shows which environments would leave it unresolved, as a coverage matrix:

orchstep validate provision --strict

With --strict it fails CI when a referenced variable is supplied by no environment. That's the difference between "the runbook says set the region" and a machine-checked guarantee that every target resolves cleanly before a customer ever runs it.

What you gained

This isn't infrastructure-as-code — Terraform and Pulumi still describe the resources. OrchStep is the orchestration on top: the ordered, environment-aware procedure that ties those tools together and travels with the customer. If you only ever target one environment, inline values are simpler and you don't need this. The second target is where it pays off.

Where to go next

• Environments & Variable Files — inline and externalized styles
• Variables & Outputs — the full precedence ladder
• orchstep validate — the coverage matrix
• HTTP & APIs — wiring integration checks into the stack

Take your most-deployed reference architecture, lift the per-environment knobs into environments:, and hand customers a command instead of a chapter.