Skip to main content
Welcome. This site supports keyboard navigation and screen readers. Press ? at any time for keyboard shortcuts. Press [ to focus the sidebar, ] to focus the content. High-contrast themes are available via the toolbar.
serard@dev00:~/cv

What Gets Generated — Real Outputs

"The Document DSL doesn't just generate Markdown. It generates Grafana dashboards, Prometheus alert rules, Kubernetes probes, Helm values — files your infrastructure consumes directly."

Beyond Markdown — Infrastructure as Generated Artifacts

Every attribute from the Ops sub-DSLs (Part IV) and the composed deployment (Part V) is a data source. The Document DSL's strategies don't just produce human-readable docs — they produce machine-consumable infrastructure artifacts.

One dotnet build generates:

docs/Order/deployment/
├── runbook.md                  ← Human-readable deployment guide
├── dag.mermaid                 ← Visual execution plan
├── grafana-dashboard.json      ← Import directly into Grafana
├── prometheus-alerts.yaml      ← Drop into Prometheus rules directory
├── k8s-probes.yaml             ← Kubernetes readiness/liveness probes
├── helm-values.yaml            ← Helm chart values per environment
├── rollback-playbook.md        ← Ordered reverse procedure
└── env-matrix.md               ← Config/secret requirements per environment

Generated Deployment DAG

From [MigrationStep] ordering + parallelism + [DeploymentDependency]:

Diagram

This diagram is generated from the attributes — no manual drawing. When a step changes, the DAG updates on next build.

Generated Runbook

From all Ops sub-DSLs combined, the DeploymentDocumentStrategy generates a step-by-step runbook:

# Deployment Runbook: Order Service v2.4.0

> Order service v2.4 — new payment flow
> Strategy: **Canary**
> Depends on: PaymentGatewayV3Deployment (must complete before)
> Environments: Staging, Production

## Pre-Flight Checklist

- [ ] PaymentGatewayV3Deployment completed successfully
- [ ] Secret `orders/payment-gateway-api-key` exists in Azure Key Vault
- [ ] Config section `PaymentGateway` prepared for Staging and Production
- [ ] OrdersDb and AuditDb accessible from migration host
- [ ] Grafana dashboard `order-v24-deployment` imported

## Step 1: Schema Migrations (Parallel)

**Step 1a: AddPaymentMethodColumn** — OrdersDb · Schema · ~30s
```sql
ALTER TABLE Orders ADD PaymentMethod NVARCHAR(50);

Validation: SELECT COUNT(*) FROM information_schema.columns WHERE column_name = 'PaymentMethod' → expect 1 Rollback: RollbackPaymentColumn (Automatic, ~10s)

Step 1b: AddPaymentAuditTable — AuditDb · Schema · ~15s Rollback: RollbackAuditTable (Automatic)

Steps 1a and 1b run in parallel. Both must complete before Step 2.

Step 2: CreatePaymentMethodIndex — OrdersDb · Index · ~2m

Depends on: AddPaymentMethodColumn No rollback defined — index can be dropped manually.

Step 3: BackfillPaymentMethods — OrderMigrator · ~45m

Data migration: backfill payment methods from legacy PaymentType column Expected rows: ~2.4M Timeout: 45 minutes Input files: migration-scripts/backfill-payment-methods.sql Validation: SELECT COUNT(*) FROM Orders WHERE PaymentMethod IS NULL → expect 0 Rollback: RollbackPaymentBackfill (Manual, ~30m, requires approval) Pre-conditions for rollback: No orders created with new payment methods

⚠️ This step takes ~45 minutes. Monitor the migration-progress Grafana panel.

Step 4: Configuration Transforms

Staging: Replace section PaymentGateway Production: Replace section PaymentGateway (requires restart)

Secret: orders/payment-gateway-api-key from Azure Key Vault (rotation: 30d)

Step 5: Canary Deployment

Traffic: 5% for 15 minutes Success metric: order_payment_latency_ms.p99 < 300ms Auto-rollback if: error_rate > 0.5%

Step 6: Health Checks

App Endpoint Kind Timeout Retries Severity
OrderApi /health/payment HTTP 10s 5 × 3s Critical
OrderWorker /health/queue Queue 30s 3 × 5s Critical
OrdersDb — Database 5s 3 × 5s Critical

Post-Deployment

  • Monitor OrderPaymentErrorSpike alert (triggers if error rate > 1% for 3m)
  • Watch order_payment_latency_ms p99 on Grafana
  • Verify canary metrics stabilize after full rollout

Emergency Rollback

Execute in reverse order:

  1. Revert canary (restore previous deployment)
  2. Revert config transforms
  3. RollbackPaymentBackfill — Manual, requires approval (~30m)
  4. Drop index (manual)
  5. RollbackAuditTable — Automatic
  6. RollbackPaymentColumn — Automatic (~10s)

---

## Generated Grafana Dashboard JSON

From `[Dashboard]` + `[Metric]` + `[AlertRule]` attributes:

```json
{
  "dashboard": {
    "uid": "order-v24-deployment",
    "title": "Order Service v2.4 Deployment",
    "tags": ["deployment", "order-service", "v2.4.0"],
    "timezone": "utc",
    "refresh": "30s",
    "panels": [
      {
        "id": 1,
        "title": "Migration Progress",
        "type": "stat",
        "gridPos": { "h": 4, "w": 6, "x": 0, "y": 0 },
        "targets": [{
          "expr": "deployment_migration_step_status{deployment='order-v24'}",
          "legendFormat": "{{step}}"
        }]
      },
      {
        "id": 2,
        "title": "Payment Latency (p99)",
        "type": "timeseries",
        "gridPos": { "h": 8, "w": 12, "x": 0, "y": 4 },
        "targets": [{
          "expr": "histogram_quantile(0.99, rate(order_payment_latency_ms_bucket[5m]))",
          "legendFormat": "{{method}} {{status}}"
        }],
        "fieldConfig": {
          "defaults": {
            "unit": "ms",
            "thresholds": {
              "steps": [
                { "color": "green", "value": null },
                { "color": "yellow", "value": 300 },
                { "color": "red", "value": 500 }
              ]
            }
          }
        }
      },
      {
        "id": 3,
        "title": "Error Rate",
        "type": "timeseries",
        "gridPos": { "h": 8, "w": 12, "x": 12, "y": 4 },
        "targets": [{
          "expr": "rate(order_payment_errors_total[5m])",
          "legendFormat": "errors/s"
        }],
        "alert": {
          "name": "OrderPaymentErrorSpike",
          "conditions": [{
            "evaluator": { "type": "gt", "params": [0.01] },
            "query": { "params": ["A", "5m", "now"] },
            "reducer": { "type": "avg" }
          }],
          "for": "3m",
          "frequency": "1m",
          "notifications": [
            { "uid": "oncall-slack" },
            { "uid": "oncall-pager" }
          ]
        }
      },
      {
        "id": 4,
        "title": "Canary Traffic Split",
        "type": "piechart",
        "gridPos": { "h": 8, "w": 6, "x": 0, "y": 12 },
        "targets": [{
          "expr": "sum by (version) (rate(http_requests_total{service='order-api'}[5m]))",
          "legendFormat": "{{version}}"
        }]
      }
    ]
  }
}

This JSON is importable directly into Grafana. No manual dashboard creation. When you add a [Metric] attribute, the dashboard updates on next build.

Generated Prometheus Alert Rules

From [AlertRule] attributes:

# Generated by Ops.Observability.Generators — do not edit manually
# Source: OrderServiceV24Deployment
# Generated: 2026-03-29T10:30:00Z

groups:
  - name: order-service-v24
    rules:
      - alert: OrderPaymentErrorSpike
        expr: rate(order_payment_errors_total[5m]) > 0.01
        for: 3m
        labels:
          severity: critical
          service: order-service
          deployment: v2.4.0
        annotations:
          summary: "Payment error rate exceeds 1% threshold"
          description: "The payment error rate has been above 0.01/s for more than 3 minutes"
          runbook_url: "https://docs.internal/runbooks/order-payment-errors.md"
          dashboard_url: "https://grafana.internal/d/order-v24-deployment"

      - alert: OrderPaymentLatencyHigh
        expr: histogram_quantile(0.99, rate(order_payment_latency_ms_bucket[5m])) > 500
        for: 5m
        labels:
          severity: warning
          service: order-service
        annotations:
          summary: "Payment p99 latency exceeds 500ms"
          description: "order_payment_latency_ms p99 has been above 500ms for 5 minutes"

Drop this file into your Prometheus rules directory. No manual alert configuration.

Generated Kubernetes Probes

From [HealthCheck] attributes:

# Generated by Ops.Observability.Generators — do not edit manually
# Source: OrderServiceV24Deployment
# App: OrderApi

apiVersion: apps/v1
kind: Deployment
metadata:
  name: order-api
spec:
  replicas: 3
  template:
    spec:
      containers:
        - name: order-api
          readinessProbe:
            httpGet:
              path: /health/payment
              port: 8080
            initialDelaySeconds: 10
            periodSeconds: 5
            timeoutSeconds: 10
            failureThreshold: 5
          livenessProbe:
            httpGet:
              path: /health
              port: 8080
            initialDelaySeconds: 30
            periodSeconds: 10
            timeoutSeconds: 5
            failureThreshold: 3
---
# App: OrderWorker
apiVersion: apps/v1
kind: Deployment
metadata:
  name: order-worker
spec:
  replicas: 2
  template:
    spec:
      containers:
        - name: order-worker
          readinessProbe:
            exec:
              command: ["/bin/health-check", "--queue"]
            initialDelaySeconds: 5
            periodSeconds: 10
            timeoutSeconds: 30
            failureThreshold: 3

The HealthCheckKind.Http generates an httpGet probe. HealthCheckKind.Queue generates an exec probe. The mapping is in the KubernetesDocumentStrategy.

Generated Helm Values

From [DeploymentApp] + [ConfigTransform] + [Secret] + [EnvironmentMatrix]:

# Generated by Ops.Configuration.Generators — do not edit manually
# Source: OrderServiceV24Deployment
# Environment: Production

orderApi:
  replicas: 3
  image:
    repository: registry.internal/order-service
    tag: v2.4.0
  config:
    paymentGateway:
      endpoint: "https://pay.example.com/v3"
      timeout: "30s"
  secrets:
    - name: payment-gateway-api-key
      vaultPath: orders/payment-gateway-api-key
      provider: azure-keyvault
      rotationPolicy: 30d
  probes:
    readiness:
      path: /health/payment
      port: 8080
      timeout: 10

orderWorker:
  replicas: 2
  image:
    repository: registry.internal/order-worker
    tag: v2.4.0
  probes:
    readiness:
      command: ["/bin/health-check", "--queue"]
      timeout: 30

auditWorker:
  replicas: 1
  image:
    repository: registry.internal/audit-worker
    tag: v2.4.0

migration:
  steps:
    - name: add-payment-method-column
      database: OrdersDb
      kind: schema
      order: 1
      parallel: true
      estimatedDuration: 30s
    - name: add-payment-audit-table
      database: AuditDb
      kind: schema
      order: 1
      parallel: true
      estimatedDuration: 15s
    - name: create-payment-method-index
      database: OrdersDb
      kind: index
      order: 2
      estimatedDuration: 2m
    - name: backfill-payment-methods
      kind: exe
      order: 3
      app: OrderMigrator
      timeout: 45m

canary:
  enabled: true
  trafficPercentage: 5
  duration: 15m
  successMetric: "order_payment_latency_ms.p99 < 300ms"
  rollbackThreshold: "error_rate > 0.5%"

Generated Environment Matrix

From [EnvironmentMatrix] + [ConfigTransform] + [Secret]:

# Environment Matrix — Order Service v2.4.0

## Required Configuration

| Config Section | Staging | Production | Requires Restart |
|---|---|---|---|
| PaymentGateway | ✓ Replace | ✓ Replace | Production only |

## Required Secrets

| Secret | Provider | Vault Path | Rotation | Staging | Production |
|---|---|---|---|---|---|
| PaymentGateway:ApiKey | Azure Key Vault | orders/payment-gateway-api-key | 30d | ✓ | ✓ |

## Database Access

| Database | Migrations | Validation | Estimated Duration |
|---|---|---|---|
| OrdersDb | Schema + Index + Data | SchemaCheck + DataIntegrity | ~48m total |
| AuditDb | Schema | — | ~15s |

## Applications

| App | Replicas | Health Check | Severity |
|---|---|---|---|
| OrderApi | 3 | HTTP /health/payment | Critical |
| OrderWorker | 2 | Queue /health/queue | Critical |
| AuditWorker | 1 | — | — |

Wiki vs. Generated — Side by Side

The Wiki Runbook (Real World)

# Order Service Deployment

1. Run OrdersDb migration
2. Run AuditDb migration
3. Deploy OrderApi
4. Deploy OrderWorker
5. Check health endpoints

Note: Talk to @dave about the payment gateway config.
Last updated: 2025-11-14 by @sarah

6 lines. Missing: parallel migrations, exe data migration, config transforms, canary strategy, rollback procedures, health check details, secret management, environment differences, Grafana dashboard, Prometheus alerts, Kubernetes probes. Last updated 4 months ago.

The Generated Runbook

120+ lines. Complete deployment DAG, step-by-step with estimated durations, pre-flight checklist, validation queries, rollback at each step with pre-conditions, canary rules, health check matrix, environment-specific configs, emergency rollback procedure. Always current — regenerated on every dotnet build.

The wiki runbook was written once and drifted. The generated runbook is rebuilt every time the typed deployment changes. It cannot drift because it does not exist separately from the types that produce it.

What's Next

These are the artifacts for one deployment. Part VII connects them to the dev-side documentation: the traceability matrix links requirements to deployment steps, the architecture diagram links aggregates to health checks, the release notes link code changes to runbook steps. DocumentSuite<T> ties it all together.