Skip to content

Diagrams

Diagrams are first-class Ranger outputs. They are not decorative extras.

They exist to make architecture, relationships, and operational boundaries visible faster than tables alone can do.

Diagram Rendering Rule

Diagrams render from the cached audit manifest. They do not perform live discovery.

If required data is missing, the diagram should be skipped or marked unavailable with a clear reason rather than rendered with guessed data.

Source and Export Format

When diagrams materially improve clarity, Ranger documentation should prefer draw.io source files exported to SVG.

Planned asset layout:

  • docs/assets/diagrams/*.drawio for editable source
  • docs/assets/diagrams/*.svg for published output and embedding

The operator journey flowchart is an operator-guide diagram rather than a discovered-environment output. It is embedded in the quickstart and runtime pages to explain the execution path from input to package generation.

Full Diagram Catalog

Baseline Set (Diagrams 1–6)

Baseline diagrams render on most successful runs. They do not require special trigger conditions.

# Name Purpose Audience
1 Physical Architecture Nodes, hardware summary, BMC, rack grouping, and physical adjacency Executive, Management, Technical
2 Logical Network Topology vSwitches, SET, intents, VLANs, subnets, SDN, and proxy path Management, Technical
3 Storage Architecture Pool, cache, virtual disks, CSVs, resiliency, and capacity posture Management, Technical
4 VM Placement Map VM-to-host placement, density, anti-affinity, and guest clusters Management, Technical
5 Azure Arc Integration Azure resource hierarchy, Arc Resource Bridge, custom location, extensions, and management flows Executive, Management, Technical
6 Workload and Services Map AVD, AKS, Arc VMs, monitoring stack, OEM tooling, backup, and DR relationships Management, Technical

Extended Set (Diagrams 7–18)

Extended diagrams render only when the trigger condition is met.

# Name Trigger Condition Audience
7 Topology and Deployment Variant Map Always in technical tier Management, Technical
8 Identity, Trust, and Secret Flow Local Key Vault identity mode detected Management, Technical
9 Monitoring, Telemetry, and Alerting Flow Monitoring domain collected Executive, Management, Technical
10 Connectivity, Firewall, and Dependency Map Always in technical tier Management, Technical
11 Identity and Access Surface Map Always in technical as-built Management, Technical
12 Monitoring and Health Heatmap Critical or warning findings present Executive, Management
13 OEM Hardware and Firmware Posture Hardware domain collected Management, Technical
14 Backup, Recovery, and Continuity Map Azure Backup or ASR detected Executive, Management, Technical
15 Management Plane and Tooling Map Always in technical tier Executive, Management, Technical
16 Workload Family Placement Map Multiple workload families detected Management, Technical
17 Multi-Rack or Rack-Aware Fabric Map Rack-aware deployment type detected Management, Technical
18 Disconnected Operations Control Plane Map Disconnected control plane mode detected Management, Technical

Selection Rules

Diagram generation should follow clear rules:

  1. baseline diagrams for most successful current-state and as-built runs
  2. extended diagrams only when the detected features justify them
  3. variant-specific diagrams only when the environment shape requires them
  4. skip diagrams whose required evidence is missing

Examples:

  • do not generate a multi-rack fabric map for a standard hyperconverged cluster
  • do not generate a Key Vault secret-flow diagram unless local identity with Key Vault is detected or explicitly documented
  • do not generate a detailed Azure integration diagram if Azure-side discovery was skipped

Audience Subsets

Executive Subset

Executive outputs usually need only a small subset such as:

  • Physical Architecture
  • Azure Arc Integration
  • Monitoring and Health Heatmap
  • Backup, Recovery, and Continuity Map

Technical Subset

Technical and as-built outputs can include most or all applicable diagrams.

Diagram Standards

All diagrams should include:

  • title
  • cluster or environment label
  • generation timestamp
  • Ranger version watermark

Diagram outputs should remain legible, consistent, and obviously product documentation rather than scratch engineering sketches.

When documenting the product itself, prefer draw.io source exported to SVG so the editable source and published artifact stay aligned.