Blueprints Reference

Blueprints are the "brain" of your MicroStax environments. They define what runs, how services talk to each other, and how your data is initialized. Think of it as a super-charged docker-compose.yml for Kubernetes.

Minimal Example

name: payments-dev
description: Payments API with Postgres

services:
  - name: api
    image: ghcr.io/example/payments-api:latest
    ports:
      - containerPort: 8080
    expose: true
    dependsOn: [db]
    env:
      DATABASE_URL: postgres://postgres:devpass@db:5432/payments

  - name: db
    image: postgres:16-alpine
    ports:
      - containerPort: 5432
    secrets:
      - name: db-password
        envKey: POSTGRES_PASSWORD
        value: auto-generated
    volumes:
      - name: db-data
        mountPath: /var/lib/postgresql/data
        type: pvc
        size: 5Gi

Top-Level Fields

Field	Type	Required	Notes
name	string	Yes	Environment name.
description	string	No	Human-readable context.
services	ServiceSpec[]	Yes	One or more services.
plans	object	No	Named deployment plans with per-service overrides.
routing	RoutingSpec	No	Environment mode and overlay controls.
autoShutdownEnabled	boolean	No	Idle control. Default: true.
autoShutdownDelayMinutes	number	No	Idle shutdown delay. Default: 30.

Deployment Plans

Use plans for named profiles such as production when a service needs different replicas or resource limits outside the base development Blueprint.

plans:
  production:
    services:
      db:
        replicas: 3
        resources:
          memory: 512Mi
          cpu: 500m

Service Fields

Field	Type	Required	Notes
name	string	Yes	DNS-safe service name.
image	string	Yes	OCI image reference.
ports	PortSpec[]	No	Container ports.
env	Record<string,string>	No	Runtime environment variables.
resources	ResourceSpec	No	CPU and memory requests and limits.
expose	boolean	No	Creates ingress when true.
dependsOn	string[]	No	Declares dependency order.
command	string[]	No	Overrides container command.
args	string[]	No	Overrides container args.
entrypoint	string[]	No	Overrides entrypoint.
replicas	number	No	Horizontal scaling count.
volumes	VolumeSpec[]	No	PVC or emptyDir mounts.
secrets	SecretSpec[]	No	Managed secret injection.
labels	Record<string,string>	No	Service-level Kubernetes labels.
annotations	Record<string,string>	No	Service-level annotations.
init	InitSpec	No	One-time initialization job.
snapshot	SnapshotSpec	No	Snapshot restore configuration.
mock	MockSpec	No	Stub or mirrored behavior.
livenessProbe	ProbeSpec	No	Liveness health check.
readinessProbe	ProbeSpec	No	Readiness health check.
startupProbe	StartupProbeSpec	No	Startup health check.
imagePullSecrets	{name:string}[]	No	Private registry auth.

Routing Modes

Routing controls how MicroStax provisions and resolves services.

Mode	Use when	Behavior
isolated	You need a fully independent environment.	All services are provisioned locally.
baseline	You want a shared provider environment.	Full environment intended to back overlays.
overlay	You want a sparse feature environment.	Changed services run locally; unchanged services bridge to the baseline/provider.

routing:
  mode: overlay
  baselineId: env_base_123
  overlayId: feat-checkout-refactor
  headerName: x-msx-env
  propagateHeader: true
  ttlHours: 24

Field notes:

• baselineId identifies the baseline environment for overlay routing.
• overlayId becomes the request routing value.
• headerName defaults to x-msx-env.
• propagateHeader controls downstream header propagation.
• ttlHours sets overlay expiry.

Resources

resources:
  memory: 256Mi
  cpu: 200m
  memoryLimit: 512Mi
  cpuLimit: 800m

• memory and cpu are requests.
• memoryLimit and cpuLimit cap usage.
• If limits are omitted, MicroStax derives them from requests.

Secrets

secrets:
  - name: stripe-secret
    envKey: STRIPE_SECRET_KEY
    value: auto-generated
    length: 48

Use secrets for credentials that should not be committed into plain environment variables.

Volumes

volumes:
  - name: cache-data
    mountPath: /data
    type: pvc
    size: 10Gi
    storageClass: standard-rwo

Supported volume types:

• pvc for persistent state
• emptyDir for ephemeral scratch storage

Init Data

Use init when you want a one-off script executed during provisioning.

init:
  script: ./seed/schema.sql
  mountPath: /seed
  timeout: 120
  type: sql

Use init for environment-local bootstrap that should be part of the validated Blueprint contract.

Snapshots

Use snapshot to restore sanitized production-like data at provision time.

snapshot:
  engine: postgres
  database: payments
  sourceSecretRef:
    name: prod-payments-url
    key: DATABASE_URL
    namespace: platform
  storage:
    provider: gcs
    bucket: microstax-snapshots
    region: us-central1
  excludeTables:
    - audit_logs
  sanitization:
    - field: users.email
      strategy: fake
    - field: users.ssn
      strategy: redact
  schedule: '0 */6 * * *'
  maxAgeHours: 12

Snapshot behavior:

• supported engines: postgres, mongo, mysql
• supported storage providers: gcs, s3, local
• supports inclusion/exclusion filters and sanitization rules
• cached artifacts may be reused until maxAgeHours expires

Mocking And Shadow Validation

Mocks can fully replace a dependency, run as a sidecar, or receive mirrored traffic.

mock:
  enabled: true
  mode: ai-stateful
  openapi: ./specs/payments-openapi.yaml
  deployment:
    mode: mirror
    istio:
      mirrorPercent: 25
  validation:
    mode: warn
    coercion: true

Important distinctions:

• mode controls mock behavior: static or ai-stateful
• deployment.mode controls runtime placement: replace, sidecar, or mirror
• mirror is intended for traffic shadowing and behavioral diffing

Probes

readinessProbe:
  path: /ready
  port: 8080

Use:

• startupProbe for slow boots
• readinessProbe for routing eligibility
• livenessProbe for restart detection

Example: Baseline Blueprint

name: storefront-base
routing:
  mode: baseline

services:
  - name: web
    image: ghcr.io/example/storefront-web:stable
    ports:
      - containerPort: 3000
    expose: true

  - name: catalog
    image: ghcr.io/example/catalog-api:stable
    ports:
      - containerPort: 8080

Example: Overlay Blueprint

name: storefront-checkout
routing:
  mode: overlay
  baselineId: env_base_123
  overlayId: feat-checkout
  ttlHours: 8

services:
  - name: checkout
    image: ghcr.io/example/checkout-api:feat-checkout
    ports:
      - containerPort: 8080

Admission Sanitizer

MicroStax runs every blueprint you submit through an admission-time sanitizer before the orchestrator touches Kubernetes. The goal is simple: your blueprint should just work on the cluster we're targeting, even if the blueprint was authored somewhere else. The sanitizer applies seven passes and records every change on the environment record so you can review exactly what it did.

The seven passes

• image — Resolves every image: against the configured registry. If an image can't be pulled, the sanitizer substitutes the platform stub-proxy image and tags the service with microstax.io/sanitizer-substituted-image. Your env still boots.
• node-selector — Reads microstax.io/node-selector and drops any key=value pair that no node in the cluster actually has. If nothing matches, the selector is removed entirely — otherwise the pod would be Pending forever.
• secret-fallback — If a service requires a paid credential (e.g. LOCALSTACK_AUTH_TOKEN) and no matching secret is bound, the sanitizer substitutes a compatible OSS/mock variant. LocalStack Pro → LocalStack community is the canonical example.
• probe — Services with ports but no readinessProbe get a TCP probe on the first port. Stops the orchestrator from flipping a still-starting pod to error.
• limits — Missing resources.cpu/memory requests and limits are filled with platform defaults (100m/128Mi requests, 500m/512Mi limits). Keeps the scheduler's behavior predictable across clusters.
• pin — Mutable tags (:latest, :main, :dev, or no tag) are resolved to an immutable @sha256:... digest, so a redeploy two months from now lands on the same bytes you tested today.
• context-agent — Opts services into the mesh-free overlay context-agent sidecar only when the image is actually published for the current platform version. Otherwise the annotation is set to false so the pod can reach Ready.

Where to see the fixes

Every rewrite is attached to the environment record as autoFixes[]. Open the environment in the dashboard and look for the "Platform auto-fixed N issues in your blueprint" panel above the tabs. Each row explains what changed and why.

Strict mode

If you want byte-for-byte determinism — for example because you're promoting an overlay to a signed baseline — set the top-level field:

strictSanitizer: true

In strict mode every would-be rewrite becomes a BLUEPRINT_REJECTED error. You get the full list of objections and can fix them yourself. The original blueprint is never mutated.

Pre-flight dry-run

After the sanitizer, MicroStax renders every Kubernetes manifest the orchestrator would apply and asks the API server to validate them (dryRun=All) without actually creating anything. If the dry-run finds blocking errors the env is rejected with a PREFLIGHT_FAILED code and the structured report is attached to the response. Non-blocking warnings (e.g. "preflight runner unavailable in this deployment mode") appear in the dashboard's auto-fixes panel under "Pre-flight warnings".

Auto-heal

Environments default to autoHealEnabled: true. When POST /environments/:id/diagnose runs, any high-confidence suggestion that includes a safe JSON patch (confidence >= 0.95, blueprintPatch present, autoApplyIfConfidenceAbove set) is applied silently — no dashboard click required. The diagnose response includes autoHealApplied: [suggestionId, ...] so you can audit what happened. Turn this off per-env by setting autoHealEnabled: false before promotion.

Best Practices

• Keep service names stable across baseline and overlay Blueprints.
• Use overlays only for services you are actively changing.
• Put realistic data policy in snapshot, not ad hoc shell scripts.
• Keep public exposure limited to services that actually need ingress.
• Add probes for every stateful or externally exposed service.
• Trust the sanitizer — write the blueprint you want for production; the platform will degrade gracefully on dev/test clusters.
• For baselines and signed blueprints, set strictSanitizer: true so the rewrite rules never silently change what you promoted.