Run dev / staging / prod environments

Three separation strategies

• Name prefix — soft isolation, zero overhead. Tiny teams, single org, dev- + prod- naming.
• Compute Zones — hard isolation across zones, low overhead. Compliance / latency separation, multi-region.
• Separate organizations — hardest isolation, full tenant boundary. Strict prod isolation, separate budgets, separate teams.

Pick the smallest one that solves your problem. Most customers start with name prefix, graduate to Compute Zones once they hit ~50 VSs, and only split into separate orgs when finance demands separate invoices.

Strategy 1 — Name prefix

The simplest pattern. Every VS has a name field; pick a convention: prod-checkout-api-01, staging-checkout-api-01, dev-hadar-checkout-api.

In the dashboard, the search box filters by name substring. From the API, paginate /api/v1/virtual-servers. [VERIFY: confirm name-filter query param vs client-side only at launch — list endpoint accepts status and device_id filters today]

Pros: zero setup. Cons: no enforcement — anyone with deploy rights can hit prod. Audit log helps after the fact (Chapter 4), but there's no permission gate.

Strategy 2 — Compute Zones

Zones are the recommended middle ground. The /api/v1/zones router exposes per-zone allocation of Compute Nodes. Common layouts:

• Zone A = "production" — most reliable Compute Nodes; SLAs pinned here; higher auto-scaling caps.
• Zone B = "staging" — second tier of hardware; relaxed SLAs.
• Zone C = "development" — lab / on-desk Compute Nodes; lowest priority.

When you deploy a VS, Zyra's placement engine picks a Compute Node inside the target zone. Pros: real isolation, separate capacity, separate failure domains. Cons: you need enough hardware in each zone.

Strategy 3 — Separate organizations

The strictest split. Create two Zyra organizations (Acme Prod, Acme Staging), each with its own Org Admins, billing, audit log, and webhook subscribers. Single sign-on can span both if your IdP maps the same user into both (Chapter 3).

Use when: regulated industries, full separation of duties, fully separate budgets. Avoid when: small team — two orgs doubles your admin overhead.

Environment-specific secrets

Whichever strategy you pick, never share secrets across environments. Staging gets staging keys; prod gets prod keys.

• API keys are per-user. Create one labelled ci-prod and another ci-staging. Revoke them independently.
• Webhook endpoints are per-org. With strategy 1 or 2 you can register two endpoints (/zyra/prod, /zyra/staging) and dispatch the right events to each.
• Container registry creds are per-org. With strategy 3 they're hard-separated by definition.

Promoting a workload dev → staging → prod

1. Build once. A single Docker image, tagged with the commit SHA. Same artifact promoted across environments — never "rebuild for prod".
2. Deploy with environment-specific spec. Different name, vcpus, memory_mb, enable_ssh, env-var bundle.
3. Verify with smoke test. Hit a /health endpoint inside the VS, wait for running plus e2e_validated=true.
4. Cut over. Update DNS / load balancer / SLA agreement to point at the new VS.
5. Decommission the old one. DELETE /api/v1/virtual-servers/{id}.

Cost allocation by environment

The cost_per_hour and total_cost columns on virtual_servers are per-VS, in Numeric(10, 6) dollars. To attribute cost:

• Strategy 1. Filter the invoice line items by name LIKE 'prod-%' from the dashboard's CSV export.
• Strategy 2. Use /api/v1/analytics/costs — it groups by zone natively. [VERIFY: confirm cost-by-zone aggregation endpoint signature]
• Strategy 3. Each org gets its own invoice — no allocation needed.

What just happened

You picked one of three separation strategies, kept secrets isolated, learned the promotion pattern (build once, redeploy with different specs), and saw how to split cost by environment. There is no magic "environment" field on the VS model today — that's the honest answer.

[VERIFY: a typed environment label field on the VS model is in the backlog — current model exposes name and target_device_id plus zone membership via Compute Node assignment]

Troubleshooting

• A dev VS pulls work meant for prod. Job queues are scoped per-org; check your routing in Chapter 5.
• SSO members can see all environments. Yes — same org, same access. Use strategy 3 if you need stricter separation.
• Invoices don't split cleanly. Strategy 3 is the only one that yields separate invoices.

What comes next

You've finished Stage 4. Stage 5 covers architecture patterns for distributed workloads, capacity planning, and contributing back to the community. Look for it in the Organization Guide index once it lands.