DocuOps

Describe your infrastructure in Markdown. Keep it readable. Keep it maintainable.

DocuOps is a specification format for describing cloud infrastructure stacks as structured Markdown documents. Instead of scattering infrastructure knowledge across wikis, spreadsheets, IaC files, and architecture diagrams, DocuOps lets you capture everything — services, databases, networks, policies, migrations — in a single .do.md or .docuops file that is both machine-readable and human-friendly.

This extension gives you first-class editor support: syntax highlighting, real-time validation, IntelliSense completions, and snippets — so writing a DocuOps specification feels as natural as writing documentation.

---

Why Markdown?

Most infrastructure-as-code formats are designed to be parsed by machines first and read by humans second. DocuOps inverts that priority. Because a DocuOps spec is plain Markdown:

• It lives in your repo alongside the code it describes, and is versioned with it.
• You can write freely around the structure — add architecture diagrams with Mermaid, embed decision records, link to runbooks, explain context with full prose — all within the same file.
• It is immediately readable in GitHub, GitLab, Azure DevOps, or any Markdown renderer with no special tooling.
• Teams that don't run infrastructure — product managers, security reviewers, new joiners — can open the file and understand what is deployed without learning a DSL.
• The structure is enforced by convention through heading levels and attribute lists, not by a rigid schema, so it scales from a single microservice to a full platform specification.

---

File Associations

DocuOps files use the extension .do.md or .docuops. The extension activates automatically when you open either file type.

Both file types are treated as Markdown, so all standard VS Code Markdown features work — including the built-in preview (Cmd+Shift+V / Ctrl+Shift+V), Mermaid diagrams, and GitHub-flavoured rendering. DocuOps-specific syntax highlighting, validation, completions, and snippets layer on top automatically.

---

Document Structure

A DocuOps document has three levels of headings:

Level	Purpose	Example
#	Root — identifies the workspace or stack	# Stack: payments
##	Resource — a named infrastructure component	## Service: api
###	Section — a grouping of attributes for that resource	### Runtime

Attributes are written as a bulleted list inside each section:

- key: value

You can add any amount of prose, diagrams, or notes between the structured sections — the extension only validates the structured parts.

---

Frontmatter

Every DocuOps file must begin with a YAML frontmatter block. The following keys are required:

Key	Description
docuops	Spec version. Use 1.0.
workspace	Logical workspace or platform name.
stack	The stack or application name this file describes.
tenant	The tenant or business unit this belongs to.
environment	One of: production, staging, dev, test, qa.
provider	One of: azure, aws, gcp, kubernetes, other.
region	The primary deployment region (e.g. uksouth, us-east-1).
deployment_id	A unique identifier for this deployment.

Optional keys:

Key	Description
owner_team	Team responsible for this stack.
cost_center	Cost center or billing code.
classification	Data classification level.
managed_mode	One of: full, import, observe-only.
spec_version	Your own version string for this spec document.
tags	Array of strings or key/value object.

---
docuops: 1.0
workspace: platform
stack: payments
tenant: acme
environment: production
provider: azure
region: uksouth
deployment_id: payments-prod-uks
owner_team: platform-engineering
cost_center: CC-1042
---

---

Root Heading Types

The # heading identifies what the document describes. Allowed values:

• # Workspace: <name> — describes an entire workspace across stacks
• # Stack: <name> — describes a single application stack (most common)
• # System: <name> — describes a system boundary or bounded context
• # Migration Plan: <name> — describes a migration between systems or providers

---

Resource Types

Each ## heading declares an infrastructure resource. The format is always:

## <ResourceType>: <name>

The following resource types are supported:

Resource	Description
Service	A long-running web application, API, or background service.
Worker	A queue-consuming or event-driven background worker.
Job	A scheduled or one-off batch job.
Function	A serverless function.
Gateway	An API gateway, reverse proxy, or load balancer.
Database	A relational, document, or NoSQL database.
Cache	An in-memory cache (Redis, Memcached, etc.).
Queue	A message queue (SQS, Service Bus, etc.).
Topic	A pub/sub topic (SNS, Event Grid, Pub/Sub etc.).
Bucket	An object storage bucket.
FileShare	A network file share or managed file storage.
Network	A virtual network or VPC.
Subnet	A subnet within a network.
Firewall	A firewall, NSG, or security group.
DNSZone	A DNS zone.
Domain	A custom domain name mapping.
Certificate	A TLS/SSL certificate.
Secret	A secret or credential stored in a vault.
Config	A configuration store or config map.
Identity	A managed identity or service principal.
Policy	A governance or compliance policy.
Environment	Environment-level defaults applied to all resources.
Overlay	Conditional overrides applied to matching resources.
Monitoring	Observability configuration for a stack or resource.
Alert	An alerting rule.
Migration	A data or infrastructure migration plan.

---

Common Sections (available on all resource types)

These sections can appear on any resource:

Section	Key attributes
### Metadata	display_name, description, enabled, lifecycle, criticality, tier, version
### Ownership	team, owner, technical_owner, business_owner, cost_center, service_tier, support_group, data_classification, compliance_scope, approvers
### Tags	tags, tag.<name>
### Dependencies	uses, connects_to, depends_on, publishes, subscribes, reads_from, writes_to, mounts, exposes, protected_by
### Security	public_access, private_access, encryption_at_rest, encryption_in_transit, identity_required, waf_enabled, ddos_protection, audit_logging, allowed_cidrs, blocked_cidrs
### Extensions	azure.*, aws.*, gcp.*, k8s.* — provider-specific attributes
### Notes	Free-form notes (no attribute validation)
### Risks	Free-form risk notes
### Links	runbook, dashboard, repo, docs, adr, support_channel

---

Resource Reference

Service

Represents a long-running application: web app, API, or background service.

Required sections: ### Runtime

## Service: api

### Runtime
- runtime: webapp
- language: node
- language_version: 24
- framework: express
- framework_version: 4

### Compute
- instance_class: small
- min_instances: 2
- max_instances: 10
- autoscale: true
- scale_metric: cpu
- scale_target: 70

### Exposure
- exposure: public
- custom_domain: api.example.com
- redirect_http_to_https: true
- cors_enabled: true
- cors_origins: https://app.example.com

### Network
- protocol: https
- service_port: 443
- http2_enabled: true

### Environment
- env.NODE_ENV: production
- secret_env.DB_PASSWORD: db-password-secret
- config_ref: api-config

### Health
- readiness_path: /health/ready
- liveness_path: /health/live
- readiness_timeout: 5s

### Release
- deployment_strategy: blue-green
- rollback_enabled: true

Section attributes:

Section	Attributes
Runtime	runtime, language, language_version, framework, framework_version, hosting_model, os, architecture, image, command, args, working_dir, startup_timeout, shutdown_timeout
Compute	instance_class, cpu, memory, disk, gpu, min_instances, max_instances, desired_instances, autoscale, scale_metric, scale_target, scale_cooldown, availability_zone_spread
Network	protocol, service_port, internal_port, http2_enabled, websockets_enabled, session_affinity, outbound_access, vnet_integration, subnet_ref, private_endpoint, ip_allow_list, ip_deny_list
Exposure	exposure, ingress_enabled, ingress_class, public_endpoint, private_endpoint, custom_domain, custom_domains, certificate_ref, redirect_http_to_https, cors_enabled, cors_origins
Environment	env.<NAME>, secret_env.<NAME>, config_ref, secret_ref
Storage	mount_ref, mount_path, read_only_mount, ephemeral_storage, persistent_storage
Health	readiness_path, liveness_path, startup_path, health_port, health_protocol, readiness_timeout, liveness_timeout
Release	deployment_strategy, deployment_ring, blue_green, canary, canary_percent, rollback_enabled

---

Worker

A queue-consuming or event-driven background process.

## Worker: order-processor

### Runtime
- runtime: container
- language: dotnet
- language_version: 8
- image: registry.example.com/order-processor:latest

### Queueing
- consumer_of: orders-queue
- max_concurrency: 5
- retry_policy: exponential
- dead_letter_enabled: true

### Compute
- instance_class: medium
- min_instances: 1
- max_instances: 5

Section	Attributes
Runtime	runtime, language, language_version, image, command, args, schedule, always_on
Compute	instance_class, cpu, memory, min_instances, max_instances, autoscale
Queueing	consumer_of, subscription_ref, max_concurrency, retry_policy, dead_letter_enabled, visibility_timeout, batch_size
Environment	env.<NAME>, secret_env.<NAME>

---

Job

A scheduled or one-off batch job.

## Job: nightly-report

### Runtime
- language: python
- language_version: 3.12
- image: registry.example.com/reporter:latest

### Schedule
- schedule: 0 2 * * *
- timezone: Europe/London
- concurrency_policy: forbid
- timeout: 30m

Section	Attributes
Runtime	runtime, language, language_version, image, command, args
Schedule	schedule, timezone, concurrency_policy, retry_policy, timeout, start_deadline, suspend
Compute	cpu, memory, disk, max_parallelism

---

Function

A serverless function.

## Function: send-notification

### Runtime
- language: node
- language_version: 24
- entrypoint: src/handler.ts
- timeout: 30s

### Trigger
- trigger_type: http
- http_methods: POST
- path: /notify

Section	Attributes
Runtime	runtime, language, language_version, entrypoint, handler, package_ref, timeout
Trigger	trigger_type, trigger_source, schedule, event_type, http_methods, path, queue_ref, topic_ref, bucket_ref
Compute	memory, cpu, max_instances, min_instances

---

Gateway

An API gateway, reverse proxy, or load balancer.

## Gateway: rest-api

### Platform
- gateway_type: apim
- sku: Standard
- zone_redundant: true

### Routing
- path: /api/v1/*
- backend_ref: api
- rewrite_path: /*
- timeout: 30s

### Security
- subscription_required: true
- rate_limit: 1000
- jwt_validation: true

Section	Attributes
Platform	gateway_type, sku, capacity, zone_redundant, managed_identity, developer_portal
Routing	route, routes, path, methods, backend_ref, rewrite_path, strip_prefix, timeout, backend_protocol
Domains	custom_domain, custom_domains, certificate_ref, tls_mode
Security	subscription_required, auth_required, auth_scheme, oauth_provider, rate_limit, quota, ip_filter, jwt_validation
Policies	policy_ref, request_transform, response_transform, caching_enabled, cors_enabled, cors_origins

---

Database

A relational, document, analytical, time-series, or graph database.

## Database: orders-db

### Engine
- engine: postgres
- engine_version: 16
- edition: Standard

### Capacity
- instance_class: db.t3.medium
- storage: 100Gi
- iops: 3000
- serverless: false

### Availability
- multi_az: true
- read_replicas: 1
- geo_replication: false

### Access
- private_access: true
- subnet_ref: data-subnet
- identity_auth: true
- sql_auth_enabled: false

### Backups
- backup_enabled: true
- backup_retention_days: 30
- point_in_time_restore: true

### Connection
- database_name: orders
- connection_secret_ref: orders-db-connection

Section	Attributes
Engine	engine, engine_version, engine_mode, database_model, edition, sku, compatibility_level
Capacity	instance_class, compute, cpu, memory, storage, iops, throughput, max_size, serverless, auto_pause
Availability	multi_az, zone_redundant, read_replicas, failover_group, geo_replication, high_availability
Access	public_access, private_access, subnet_ref, private_endpoint, firewall_rules, allowed_cidrs, identity_auth, sql_auth_enabled
Backups	backup_enabled, backup_retention_days, point_in_time_restore, geo_backup, long_term_retention
Security	encryption_at_rest, customer_managed_key, audit_logging, threat_detection, data_masking, transparent_data_encryption
Connection	database_name, admin_username_ref, admin_password_ref, connection_secret_ref, port

Supported engine values: postgres, mysql, mariadb, sqlserver, oracle, sqlite, cockroachdb, aurora, mongodb, cosmosdb, dynamodb, cassandra, couchdb, firestore, elasticsearch, opensearch, redis, memcached, snowflake, bigquery, redshift, duckdb, clickhouse, databricks, influxdb, timescaledb, neo4j, neptune

---

Cache

## Cache: session-cache

### Engine
- engine: redis
- engine_version: 7
- cluster_mode: true

### Capacity
- instance_class: cache.t3.medium
- memory: 2Gi
- replica_count: 2

### Access
- private_access: true
- tls_enabled: true

Section	Attributes
Engine	engine, engine_version, sku, cluster_mode
Capacity	instance_class, memory, replica_count, shard_count
Access	public_access, private_access, subnet_ref, port, tls_enabled
Security	auth_required, auth_secret_ref, encryption_at_rest, encryption_in_transit

---

Queue

## Queue: order-events

### Delivery
- queue_type: standard
- fifo: false
- message_retention: 7d
- max_message_size: 256Kb

### Reliability
- dead_letter_enabled: true
- max_receive_count: 3

Section	Attributes
Delivery	queue_type, fifo, visibility_timeout, message_retention, max_message_size, duplicate_detection
Reliability	dead_letter_enabled, dead_letter_ref, max_receive_count, poison_handling
Access	public_access, private_access, auth_required, identity_ref

---

Topic

## Topic: payment-events

### Delivery
- topic_type: standard
- message_retention: 7d

### Subscriptions
- subscription_ref: payment-processor-sub
- dead_letter_ref: payment-events-dlq

Section	Attributes
Delivery	topic_type, ordering_enabled, message_retention, schema_ref
Subscriptions	subscription_ref, push_endpoint, pull_enabled, filter, dead_letter_ref

---

Bucket

## Bucket: uploads

### Storage
- storage_class: standard
- versioning: true
- encryption_at_rest: true

### Access
- public_access: false
- cdn_enabled: true

Section	Attributes
Storage	storage_class, versioning, replication, retention_policy, lifecycle_policy, encryption_at_rest
Access	public_access, private_access, cdn_enabled, static_website_enabled, cors_enabled, cors_origins
Security	customer_managed_key, access_logging, object_lock, malware_scanning

---

FileShare

## FileShare: shared-assets

### Storage
- protocol: nfs
- capacity: 500Gi
- snapshot_enabled: true

### Access
- identity_auth: true
- subnet_ref: app-subnet

Section	Attributes
Storage	protocol, capacity, throughput, snapshot_enabled, backup_enabled
Access	network_access, subnet_ref, mount_options, identity_auth

---

Network

## Network: platform-vnet

### Topology
- address_space: 10.0.0.0/16
- dns_servers: 168.63.129.16
- peering_refs: hub-vnet

### Access
- internet_egress: true
- nat_enabled: true

Section	Attributes
Topology	address_space, cidr, cidrs, dns_servers, peering_refs, transit_enabled
Access	internet_egress, nat_enabled, private_service_access, flow_logs_enabled
Security	segmentation_model, waf_enabled, ddos_protection

---

Subnet

## Subnet: app-subnet

### Topology
- cidr: 10.0.1.0/24
- network_ref: platform-vnet
- delegation: Microsoft.Web/serverFarms

### Access
- private_subnet: true
- service_endpoints: Microsoft.Storage

Section	Attributes
Topology	cidr, availability_zone, delegation, route_table_ref, network_ref
Access	public_subnet, private_subnet, nat_required, service_endpoints, private_link_enabled

---

Firewall

## Firewall: app-nsg

### Rules
- rule_name: allow-https
- priority: 100
- direction: inbound
- action: allow
- protocol: tcp
- destination_port: 443

### Policy
- default_inbound_action: deny
- default_outbound_action: allow

Section	Attributes
Rules	rule_name, priority, direction, action, protocol, source, destination, source_port, destination_port
Policy	default_inbound_action, default_outbound_action, managed_ruleset, threat_intel_mode

---

DNSZone

## DNSZone: example.com

### Zone
- domain: example.com
- zone_type: public

### Records
- record_type: A
- host: api
- ttl: 300
- target_ref: rest-api

Section	Attributes
Zone	domain, zone_type, dns_provider, private_zone
Records	record_type, host, ttl, value, values, target_ref, alias, priority, weight, port

---

Domain

## Domain: api.example.com

### Mapping
- hostname: api.example.com
- target_ref: rest-api
- dns_zone_ref: example.com

### TLS
- tls_enabled: true
- certificate_ref: api-cert
- minimum_tls_version: "1.2"
- redirect_http_to_https: true

Section	Attributes
Mapping	hostname, target_ref, dns_zone_ref, redirect_to, canonical
TLS	tls_enabled, certificate_ref, certificate_mode, minimum_tls_version, redirect_http_to_https

---

Certificate

## Certificate: api-cert

### Issuance
- certificate_mode: managed
- subject: api.example.com
- auto_renew: true

### Storage
- key_vault_ref: platform-keyvault

Section	Attributes
Issuance	certificate_mode, subject, sans, issuer, auto_renew, validation_method, dns_zone_ref
Storage	secret_ref, key_vault_ref, certificate_store

---

Secret

## Secret: api-db-password

### Source
- secret_provider: azure-keyvault
- external_ref: api-db-password
- rotation_enabled: true
- rotation_period: 90d

### Access
- identity_ref: api-identity
- allowed_consumers: api

Section	Attributes
Source	secret_provider, external_ref, version, rotation_enabled, rotation_period
Access	identity_ref, allowed_consumers, exportable

---

Config

## Config: api-config

### Data
- config.LOG_LEVEL: info
- config.MAX_CONNECTIONS: 100
- format: env
- reload_on_change: true

Section	Attributes
Data	config.<NAME>, format, versioned, reload_on_change

---

Identity

## Identity: api-identity

### Principal
- identity_type: managed
- federation_enabled: false

### Permissions
- role_refs: Storage Blob Data Reader
- scope_refs: uploads-bucket
- least_privilege: true

Section	Attributes
Principal	identity_type, federation_enabled, subject, audience, issuer
Permissions	role_refs, scope_refs, least_privilege, secret_access, storage_access, database_access

---

Policy

## Policy: production-baseline

### Scope
- applies_to: all
- environment: production

### Rules
- require_tls: true
- require_private_networking: true
- require_backup: true
- block_public_database: true

### Enforcement
- mode: enforce
- severity: critical

Section	Attributes
Scope	applies_to, environment, resource_types, tenant, workspace
Rules	require_tls, require_private_networking, require_backup, require_tags, require_owner, block_public_database, block_unencrypted_storage
Enforcement	mode, severity, waiver_process, exception_ref

---

Environment

Defines default values applied across all resources in a given environment.

## Environment: production

### Defaults
- provider: azure
- region: uksouth
- instance_class: standard
- backup_enabled: true
- public_access: false
- logging_level: warn

### Governance
- approval_required: true
- change_window: Sat 22:00-Sun 06:00

Section	Attributes
Defaults	provider, region, regions, instance_class, backup_enabled, public_access, private_access, logging_level, observability_profile
Governance	policy_refs, approval_required, change_window, freeze_window

---

Overlay

Conditionally overrides attributes on matching resources.

## Overlay: prod-upsize

### Matching
- match_environment: production
- match_provider: azure

### Overrides
- set.instance_class: large
- set.min_instances: 3

Section	Attributes
Matching	match_provider, match_region, match_environment, match_tenant, match_workspace
Overrides	set.<path>, append.<path>, remove.<path>

---

Monitoring

## Monitoring: platform-observability

### Signals
- metrics_enabled: true
- logs_enabled: true
- traces_enabled: true

### Destinations
- workspace_ref: log-analytics
- trace_sink_ref: application-insights

### Retention
- metrics_retention: 90d
- logs_retention: 365d

Section	Attributes
Signals	metrics_enabled, logs_enabled, traces_enabled, profiling_enabled
Destinations	dashboard_ref, workspace_ref, log_sink_ref, trace_sink_ref
Retention	metrics_retention, logs_retention, traces_retention

---

Alert

## Alert: high-error-rate

### Condition
- signal_type: metric
- metric_name: http_5xx_rate
- operator: gt
- threshold: 1
- window: 5m

### Routing
- severity: critical
- notification_channel: pagerduty-platform
- runbook: https://wiki.example.com/runbooks/high-error-rate
- auto_mitigate: false

Section	Attributes
Condition	signal_type, metric_name, operator, threshold, window, evaluation_frequency
Routing	severity, notification_channel, runbook, auto_mitigate

---

Migration

## Migration Plan: monolith-decomposition

### Source
- source_system: orders-monolith
- source_provider: aws
- source_region: us-east-1

### Target
- target_system: orders-service
- target_provider: azure
- target_region: uksouth

### Data Mapping
- entity: orders
- source: orders_table
- target: Order
- mode: copy
- key: id

### Steps
- action: provision-target
- target_ref: orders-service
- approval_required: true

### Validation
- check_type: row-count
- expected_result: match
- tolerance: 0

### Rollback
- rollback_action: restore-snapshot
- rollback_trigger: validation-failure

Section	Attributes
Source	source_system, source_region, source_provider, source_ref
Target	target_system, target_region, target_provider, target_ref
Data Mapping	entity, source, target, mode, key, transform, validation
Steps	action, target_ref, workflow_ref, approval_required, timeout, retry_policy, on_failure, notes
Validation	check_type, expected_result, tolerance, query_ref, dashboard_ref
Rollback	rollback_action, rollback_target_ref, rollback_trigger, rollback_timeout

---

Mixing Structure and Prose

One of DocuOps' core strengths is that the structured attribute lists and free-form documentation coexist in the same file. You can write context, link to decisions, and embed diagrams anywhere:

## Service: api

> This service replaced the legacy monolith in Q2 2025.

### Runtime
- language: node
- language_version: 24

Architecture overview:

```mermaid
graph LR
  Gateway --> API --> Database
  API --> Cache
```

### Dependencies
- depends_on: orders-db
- depends_on: session-cache

The extension only validates headings and attribute lists — everything else is treated as documentation.

---

Snippets

Type a snippet prefix and press Tab to expand:

Prefix	Inserts
dotemplate	A minimal DocuOps document with frontmatter, a Stack heading, and one Service block
doservice	A Service block with Runtime, Compute, and Exposure sections
dodatabase	A Database block with Engine, Capacity, and Access sections

---

Validation

The extension validates your document as you type and shows diagnostics inline:

• Unknown root heading type — the # heading must be Workspace, Stack, System, or Migration Plan
• Unknown resource type — the ## heading resource type must be one of the supported types
• Unknown section — the ### heading must be a valid section for that resource type
• Missing required section — Service requires a ### Runtime section
• Unknown attribute — the - key: value key must be valid for that resource and section
• Invalid enum value — exposure, runtime, language, engine, managed_mode, and deployment_strategy have validated value sets
• Frontmatter errors — missing required keys or invalid values

---

Settings

Setting	Default	Description
docuops.validation.enabled	true	Enable or disable all validation diagnostics
docuops.validation.severity.unknownResource	warning	Severity for unknown resource heading types. One of error, warning, information, hint.

---

Learn More

• Vibgrate Platform
• DocuOps Specification