Forum Discussion
Portable Azure topology and documentation snapshots with OSIRIS JSON
Ciao everyone,
I’m working on https://github.com/osirisjson/osiris, a vendor-neutral specification for describing infrastructure resources and their relationships as portable point-in-time snapshots.
To proof that the specification could work in real-scenarios I already built an initial https://osirisjson.org/en/docs/producers/hyperscalers/microsoft-azure in Go. You run on-premise and it connects through the Azure CLI, reads Azure subscriptions and emits an OSIRIS JSON document that can be used for documentation, topology diagrams, audits, configuration drift analysis, CMDB/IPAM/DCIM workflows, or controlled AI/context workflows without giving those platforms/tools direct access to Azure.
The producer currently covers several Azure areas, including networking, compute, storage, identity, databases, containers, integration, observability, backup, automation, management groups, and cross-resource dependency edges such as Private Endpoint to PaaS targets, App Service to Application Insights / Log Analytics, AKS to subnets and node pools, and backup vault relationships.
It supports two output purposes:
- documentation: minimal high-level projection for diagrams, inventory dashboards, and architectural documentation
- audit: deeper projection with readable properties and extensions after sensitive-field redaction
This is not intended to replace Azure tooling, Azure Resource Graph, IaC, Azure Policy, or any existing governance/control-plane workflow. OSIRIS JSON is simply a read-only external producer that generates a vendor-neutral snapshot of the observed Azure environment.
I would really appreciate feedback from Azure architects, cloud engineers, and governance practitioners on the mapping model:
- Which Azure resources and relationships are the most important for documentation and topology generation?
- Are the current connection types useful for real-world architecture views?
- What should be prioritized in next releases?
- Would a documentation/audit split be useful in enterprise environments?
You find the current Azure producer documentation here:
https://osirisjson.org/en/docs/producers/hyperscalers/microsoft-azure
I would really appreciate any feedback, suggestions, edge cases, or ideas from people who operate, document, audit, or govern Azure environments and I also welcome anyone who want to participate on development.
Ciao from Italy,
Tia
1 Reply
Hi Tia, this is a really interesting idea, especially the read-only snapshot angle. For documentation and topology views, I’d personally prioritize VNets/subnets, peering, route tables, NSGs, private endpoints/private DNS zones, load balancers/App Gateways, AKS subnet/node pool links, Key Vault dependencies, managed identities, and App Service/Function dependencies.
The documentation vs audit split also makes sense to me. In enterprise environments, architecture teams usually want a clean high-level view, while security/governance teams need deeper properties for review and drift checks.
One useful next step could be adding opinionated “views” on top of the same snapshot, for example network topology, identity/access dependencies, internet exposure, and private connectivity. That would make the JSON easier to consume for diagrams, CMDB imports, and audit workflows.
Great work, and nice to see a vendor-neutral approach here
