Forum Discussion
Portable Azure topology and documentation snapshots with OSIRIS JSON
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
Ciao Jamony, really thank you so much for this feedback, this is exactly the kind of input I was hoping to receive.
Your suggestions are very aligned with the direction I had in mind, especially around VNets/subnets, peering visibility, route tables, NSGs, Private Endpoints, Private DNS, managed identities and application dependencies this will allow even to build a full end-to-end HUB-SPOKE topology which I'm already experimenting. I also agree that AKS, App Service, Gateways and private connectivity are very important because they are often where real enterprise topology becomes difficult to document clearly.
The idea of opinionated views on top of the same OSIRIS snapshot is a great point we can talk about that. My idea and direction is keeping the OSIRIS JSON document as the neutral source of truth which include resources, topology connection and grouping, then building with OSIRIS JSON consumer (in development) different outputs, for example:
- high quality markdown documentation
- automated topology
- audit and drift-oriented views
This would allow the same portable snapshot to support both clean architecture diagrams and deeper governance workflows without changing the underlying model.
I also appreciate your confirmation about the documentation vs audit split, my goal is exactly to avoid forcing one output to serve two very different audiences: architecture teams usually need readable, high-level views with high quality topology, while security/governance but also engineering teams need more complete evidence for end-to-end review.
Thanks again for taking the time to write such a useful reply, have you tried the latest release in your environment, if you have any real-world Azure edge cases that are usually painful to document or audit, I’d be very happy to entertain a conversation.
https://github.com/osirisjson/osiris-producers/releases