Forum Discussion

skhell's avatar
skhell
Copper Contributor
Jun 29, 2026

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

Architecture
audit
automation
azure
Documentation
governance
topology

2 Replies

  • Jamony's avatar
    Jamony
    MCT
    Jul 01, 2026

    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

    • skhell's avatar
      skhell
      Copper Contributor
      Jul 03, 2026

      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