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

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.