Operational Workflows

Step-by-step guides for common environment operations. Each section covers one task from start to finish.

1. Create A Stable Baseline

Set up a shared environment that your whole team can build on top of.

Use a baseline when multiple developers need a shared provider environment.

microstax env validate --file ./baseline.yaml
microstax baseline create --file ./baseline.yaml
microstax baseline list

Guidance:

• put stable shared services in the baseline
• keep image tags explicit
• verify health before allowing overlays to depend on it

2. Create A Lightweight Overlay

Deploy only the services you changed — inherit everything else from the baseline.

Use an overlay when you only need to run the services you are actively changing.

microstax overlay create --baseline <baseline-id> --file ./overlay.yaml
microstax overlay list --baseline <baseline-id>

Overlay best practices:

• only include changed services in the overlay Blueprint
• keep service names identical to the baseline
• use overlayId values that map cleanly to branch or feature names

3. Route Requests Into The Overlay

Send traffic to your overlay instead of the baseline using a request header.

Most overlay workflows rely on the routing header.

curl -H "x-msx-env: feat-checkout" https://your-service-url

If downstream services should stay inside the same derived context, keep propagateHeader: true.

4. Restore Realistic Data

Populate your environment with production-like data using snapshots and seeds.

For production-like testing, configure snapshot in the Blueprint or create snapshots from a running environment.

microstax env snapshot create <env-id>
microstax env snapshot list <env-id>

Then combine that with seeds if needed:

microstax seed search payments
microstax seed run payments-core <env-id>

5. Run Shadow And Diff Workflows

Mirror traffic to a test environment and compare its responses to the baseline.

Use shadowing when you want to compare runtime behavior without replacing the primary response path.

Recommended sequence:

1. create or identify the baseline
2. configure mock.deployment.mode: mirror or create a shadow workflow
3. drive traffic through the baseline path
4. inspect diffs

microstax env diffs <env-id>
microstax env traces <env-id>

6. Diagnose A Failing Environment

Troubleshoot issues using MicroStax's built-in tools before reaching for kubectl.

Start with platform-native tools before dropping into raw Kubernetes.

microstax env get <env-id>
microstax env logs <env-id>
microstax env diagnose <env-id>
microstax env traces <env-id>

Use kubectl only when platform outputs are insufficient.

7. Promote With Governance

Make an environment the new shared baseline, with policy enforcement and audit logging.

Promotion is a control point, not just a rename.

microstax env promote <env-id>
microstax governance logs
microstax org compliance

If promotion is blocked:

• inspect governance logs
• confirm the environment is healthy and policy-compliant
• use force only if your role and process allow it

8. Share Environments Safely

Generate a secure link so teammates, QA, or reviewers can access your environment.

microstax env share <env-id>

When sharing outside the core engineering team:

• prefer expiring links
• use PIN-protected sharing where available
• avoid exposing internal-only services through ingress unless required

9. Replay Environment State

Re-run an environment's setup from a saved state to verify it comes up the same way.

Use replay when you need to verify determinism or reproduce a known environment execution flow.

microstax env replay <env-id>
microstax env replay <env-id> <snapshot-id>

Use cases:

• reproduce regressions
• validate snapshot restore behavior
• compare execution behavior across platform changes