Skip to content

Design versus as-built ​

Compare-RangerDesign answers "does what was built match what was designed?" from a Ranger manifest and a design record. It is read-only and works offline.

powershell
# Compare a finished run with the deploy automation environment file
Compare-RangerDesign -ManifestPath .\manifest\audit-manifest.json -DesignPath .\environment.azure-local.yml -OutputPath .\compare

# Trailwright's infrastructure.yml works the same way (the kind is detected)
Compare-RangerDesign -ManifestPath .\manifest\audit-manifest.json -DesignPath .\infrastructure.yml

# Add the comparison to the reports
Export-AzureLocalRangerReport -ManifestPath .\manifest\audit-manifest.json -DesignPath .\environment.azure-local.yml -Formats html,markdown,docx

# Export the snapshot that Azure Local Trailwright's As-built compare reads
Export-AzureLocalRangerReport -ManifestPath .\manifest\audit-manifest.json -Formats as-built-snapshot

-OutputPath writes design-comparison.json (design-comparison.v1) and design-comparison.html (a self-contained section). With -DesignPath, Export-AzureLocalRangerReport adds a Design vs as-built section to the technical reports.

Result ​

Each row has an area, an item, the design value, the as-built value, a status, a severity and, where Microsoft documents the item, a Learn link.

StatusMeaningSeverity
matchDesign and build agreeok
driftBoth have it and it differs, or the build has something the design does notwarning; error for release, identity model, witness type, node set, intent traffic, volume resiliency, subscription
missingThe design has it and the build does noterror
not-capturedThe snapshot has no data for it, so nothing is claimedinfo

The summary also reports coveragePercent, the share of design items the snapshot could actually be compared on, so a clean result with low coverage is visible.

Design record shapes ​

KindFileRead from
environmentThe deploy automation environment file (azure-local.environment schema)cluster_name, subscription_id, release.azure_local_version, release.sbe_version, identity.model, witness.type, nodes[], vlans{}, intents[], qos, ip_plan.dns_servers, storage.volumes[], sdn, logical_networks[]
infrastructureTrailwright infrastructure.yml (schema_version 4.0.0)_metadata.azure_local_release, azure_platform.*, identity.mode, compute.*, networking.*, infrastructure_network.dns_servers, storage.volumes[], sdn.*
snapshotAn as-built-snapshot.v1 file used as the design (for example a golden build)The snapshot fields below

Field-path mapping ​

The mapping was built from the collectors' code and the fixtures. Manifest paths on the left are where Ranger writes the value today; where a real run and the older synthetic fixture differ, both are listed.

Snapshot fieldManifest pathEnvironment file keyinfrastructure.yml keyRule
cluster.namedomains.clusterNode.cluster.name, else target.clusterNamecluster_nameazure_platform.instance_name, else _metadata.environment_namecase-insensitive equal
cluster.releasedomains.clusterNode.updatePosture.solutionUpdateEnv.CurrentVersion or .Version; -Release overridesrelease.azure_local_version_metadata.azure_local_release (2609)full version equal; a four-digit train matches 12.<train>.*
cluster.sbeVersiondomains.clusterNode.solutionUpdateDetail.currentSbeVersion, else solutionUpdateEnv.CurrentSbeVersion / SbeVersionrelease.sbe_version, else sbe.versionnoneequal
azure.subscriptionIdtarget.subscriptionIdsubscription_idazure_platform.subscriptions.sub_azure_local_idequal (error on drift)
azure.resourceGrouptarget.resourceGroupnoneazure_platform.resource_groups.rg_azurelocal_clusterequal
identity.modeltopology.identityMode (ad, local-key-vault)identity.model (ad-joined, hybrid -> active-directory; local-identity-keyvault -> local-identity-key-vault)identity.modeequal
identity.domaindomains.clusterNode.cluster.domain (AD only)nonenonenot compared
witness.typedomains.clusterNode.quorum.witnessDetail.type, else quorum.quorumType (CloudWitness -> cloud, FileShareWitness -> file-share)witness.type (fileshare -> file-share)compute.cluster.witness_typeequal
nodes[].namedomains.clusterNode.nodes[].namenodes[].namecompute.nodes[].nameshort name, case-insensitive; set compared both ways
nodes[].serialdomains.hardware.nodes[].serialNumber, else serviceTagnodes[].service_tagcompute.nodes[].serialequal
nodes[].managementIpdomains.networking.nodes[].hostVirtualNics[] where isManagementNic (flat hostVirtualNics / ipAddresses only when they carry a node)nodes[].management_ipcompute.nodes[].ipequal
nodes[].storageIpshost vNICs named *smb* or *storage*nodes[].storage_ips{smb1,smb2}noneset equal
nodes[].bmcIpdomains.oemIntegration.endpoints[].ip, else hardware.nodes[].ipmiAddressnodes[].bmc_ipnoneequal
nodes[].bmcTypedomains.oemIntegration.managementPosture[].managerModel (iDRAC, iLO, XClarity), else the manufacturernonenoneinformational
vlans[].iddomains.networking.nodes[].vlan[].AccessVlanId (management OS adapters), else host vNIC vlanIdvlans{}.idnetworking.vlans[].idby id; extras are warnings
intents[].namedomains.networking.nodes[].intents[].Nameintents[].namenetworking.intents[].nameby name, then by traffic set
intents[].trafficIs*Intent flags and intentOverrides[].isManagementIntent; older shape trafficType[]intents[].traffic_typesnetworking.intents[].trafficset equal (error on drift)
intents[].adaptersdomains.networking.nodes[].intentOverrides[].adaptersintents[].adaptersnetworking.intents[].adaptersset equal (warning; design port labels can differ from OS names)
intents[].jumbosmallest mtuSize of the intent's adaptersintents[].overrides.jumbo_packet, else qos.jumbo_frame_size (storage)noneequal
intents[].rdmardmaCapable / rdmaEnabled on the intent's adaptersintents[].overrides.rdma_enabled or rdma_protocol setnoneequal; capability is not configuration, so treat a match as indicative
intents[].qosdomains.networking.nodes[].dcb.trafficClasses[] named SMB / storage / clusterqos.storage_priority, qos.storage_bandwidth_percentnoneequal
volumes[].namedomains.storage.virtualDisks[].friendlyNamestorage.volumes[].namestorage.volumes[].nameby name; platform volumes in the build are info
volumes[].sizeGiBvirtualDisks[].sizeGiB (older shape: size bytes / 1 GiB)storage.volumes[].size_gb (read as GiB)storage.volumes[].size_gibwithin 1 percent or 1 GiB
volumes[].resiliencyresiliencySettingName plus numberOfDataCopies (Mirror 2 -> two-way, 3 -> three-way, 4 -> nested-two-way on two nodes else four-way; Parity -> parity)two-way-mirror -> two-way ...resiliencyequal (error on drift)
dnsServersdomains.networking.dns[].ServerAddressesip_plan.dns_serversinfrastructure_network.dns_serversset equal
sdn.enableddomains.networking.sdn[].sdn.deployed (any node)sdn.enabledsdn.enabledequal
sdn.prefixnot capturedsdn.prefixsdn.prefixnot-captured unless supplied
sdn.logicalNetworks[]domains.networking.logicalNetworks[] (name, first subnet vlan and addressPrefix)logical_networks[]sdn.logical_networks[]by name, then VLAN and subnet

Known limits ​

  • The flattened networking collections (domains.networking.adapters, intents, dns, vlan) lose the node name in real runs; Ranger reads the per-node domains.networking.nodes[] and only falls back to the flat lists when a list carries a node field.
  • Intent adapters are compared as sets of names. A design that uses port labels (Port1) and an OS that reports Embedded NIC 1 shows a warning, not an error.
  • nested-two-way is inferred from four data copies on a two-node cluster. A cluster with a different layout reports the raw copy count as four-way.
  • A jumbo or RDMA match uses the adapters' reported capability and MTU, not the Network ATC override setting.
  • hybrid identity is compared as Active Directory; hybrid-specific requirements are not checked.
  • The witness type is compared, not the witness storage account or share.

as-built-snapshot.v1 ​

ConvertTo-RangerAsBuiltSnapshot (and -Formats as-built-snapshot) writes the document that Azure Local Trailwright's As-built compare reads. The core fields (schema, capturedAt, source, cluster.name, cluster.release, identity, witness, nodes, vlans, intents, volumes, dnsServers) follow Trailwright's contract. The extras (cluster.sbeVersion, cluster.osBuild, azure, nodes[].bmcType, nodes[].bmcIp, intents[].jumbo/rdma/qos, sdn) are optional and ignored by readers that do not know them. The JSON Schema is as-built-snapshot.v1.schema.json.

json
{
  "schema": "as-built-snapshot.v1",
  "capturedAt": "2026-10-15T09:20:00.0000000Z",
  "source": { "tool": "ranger", "version": "2.7.0", "note": "manifest schema 1.1.0-draft" },
  "cluster": { "name": "example-azl-01", "release": "12.2609.1003.7", "sbeVersion": "4.1.2312.5" },
  "identity": { "model": "active-directory", "domain": "lab.example.com" },
  "witness": { "type": "cloud" },
  "nodes": [ { "name": "node1", "serial": "EXAMPLE-0001", "managementIp": "192.0.2.11", "bmcType": "idrac" } ],
  "vlans": [ { "id": 100 } ],
  "intents": [ { "name": "Management_Compute", "traffic": ["management", "compute"], "adapters": ["pNIC01", "pNIC02"] } ],
  "volumes": [ { "name": "workloads", "sizeGiB": 1024, "resiliency": "three-way" } ],
  "dnsServers": ["192.0.2.10"]
}

Released under the MIT License.