Press CTRL+K to open search

Managing diagram configurations

  • 13 minute(s) read
Prev Next

Overview

Diagram configurations define how Azure Documenter generates auto-diagrams for the Azure resources in a document group. Each configuration specifies the diagram type, the subscriptions and scope to draw from, an optional schedule, and notification channels. Configurations are created through the New diagram wizard and managed from the Diagrams tab of the document group.

Clicking a diagram name opens the interactive canvas directly, where you can inspect resources, filter the view, compare versions, and export the diagram.

Business value

Diagram configurations give your team automatically generated, up-to-date visual maps of your Azure infrastructure without switching to the Azure portal or maintaining diagrams manually. Scheduled configurations keep diagrams current as your environment changes. Generation history tracks every run with notification delivery status per channel, giving you full visibility into what was generated and when.

Prerequisites

Required permissions

Diagrams access is controlled by the Diagrams feature permission in your role configuration.

Role Access
Account Owner, Owner, Contributor Full access: create, edit, generate, view canvas, view generation history, delete diagram configurations
Custom role: Diagrams Read View existing diagram configurations, open the canvas, download diagrams
Custom role: Diagrams Manage Full access: create, edit, generate, view canvas, view generation history, delete diagram configurations

Custom role users without Diagrams access cannot open the Diagrams tab.

Dependencies

A service principal with Reader access to the target Azure subscriptions is required before you can create a diagram configuration. See Managing service principals.

How it works

Each diagram configuration is created through the New diagram wizard and saved to the Diagrams tab of the document group. A configuration stores everything needed to generate a diagram: the diagram name, type, Azure subscription scope, optional schedule, and notification channels. Once saved, a configuration can be generated on demand, edited, or deleted from the Diagrams tab.

Diagram types. Three diagram types are available, each suited to a different use case:

  • Network: maps virtual network topology including VNets, subnets, NICs, VMs, NSGs, and public IPs. Use this for network architecture reviews, incident response, and infrastructure documentation.
  • Workload: maps an application stack per resource group, including App Services, SQL databases, and Storage. Use this to document application-level dependencies and workload architecture.
  • Resource visualizer: generates an ARG-query-based dependency map across subscriptions, including external dependencies. Use this for a broad, cross-subscription view of how resources connect, with optional enrichment from App Insights, Log Analytics, App settings, and external dependency data.

Generation pipeline. Each run consumes one document license. When a diagram is generated, Azure Documenter queries Azure using the configured service principal and subscriptions, builds the diagram, and delivers notifications to configured channels. The completed diagram is stored as a versioned snapshot accessible from the canvas.

Schedule column. The Diagrams tab list shows the schedule for each configuration. Configurations without a schedule show Manual. Scheduled configurations show the frequency and the next scheduled run datetime, for example "Weekly / Next run 14/09/2026 02:00:00".

Version history. Every generation creates a new version. You can switch between versions using the version picker on the canvas to compare how your infrastructure has changed over time.

Interactive canvas. Opening a diagram configuration launches the canvas, which shows the generated diagram with tools for navigating and inspecting it. The canvas supports:

  • Group by: change how resources are clustered, for example by VNet or subnet
  • Fit / Focus: zoom to fit the full diagram or focus on a selected node
  • Show isolated: toggle visibility of resources with no connections
  • Search: find specific resources by name
  • Filters: narrow the view by Resource Types, Subscriptions, or Resource groups
  • Connection view: switch between Direct connections, All connected, External dependencies, or Show all
  • Node inspection: click any node to see its resource type, resource group, location, SKU, subscription, and full resource ID, with an option to open the resource directly in the Azure portal or copy the resource ID
  • Export: download the diagram as draw.io, PNG, or SVG

Steps

The following operations are available from the Diagrams tab of a document group. Navigate to the document group in Azure Documenter and select the Diagrams tab to get started.

Create a diagram configuration

Creating a configuration saves the diagram type, subscription scope, schedule, and notification settings that Azure Documenter reuses each time the diagram is generated.

  1. Select + New diagram.
  2. Complete the New diagram wizard:

    • Basics: enter a Name (required) and optional Description. Under Diagram type, select Network, Workload, or Resource visualizer.

    • Azure scope & filters: select the subscriptions to include. Each subscription listed belongs to a service principal already configured in Azure Documenter. Select + Add service principal to add a new one if the required subscriptions are not listed. For the Resource visualizer type, select a Resource Graph query template to define which Azure resources the diagram covers. Four preset templates are available:

      • Complete architecture: returns all resources across the selected subscriptions. Use this for a full-coverage infrastructure map with no resource type filtering.
      • Infrastructure / IaaS: focuses on classic infrastructure resources: virtual machines, disks, NICs, network security groups, and related compute and storage components. Use this when your documentation scope is traditional IaaS workloads.
      • Container / AKS: returns all AKS managed clusters and all resources deployed into the associated node resource groups. Use this when your environment is primarily Kubernetes-based.
      • Per-resource-group: scopes the query to individual resource groups rather than the full subscription. Use this to generate a focused view of a single workload or team boundary without cross-group noise.

      All four templates expose the same query editor below the selector, so you can refine any preset before proceeding. A Custom option does not appear when creating a new configuration. It becomes available as a fifth option in the Resource Graph query selector only after you modify a preset query and save the configuration. When you return to edit the configuration later, the saved query appears under Custom.

      After selecting or editing a template, configure Runtime link enrichment options as needed (App Insights dependencies, Log Analytics, App settings / connection strings, Include external dependencies). Select Test query to validate the query and confirm the resource count before proceeding.

    • Schedule: optionally enable a recurring schedule. Each run consumes one document license, so frequent schedules spend the monthly allowance faster. Set the Frequency (Weekly or Monthly), days, and time. Select + Add schedule to add multiple schedules, for example one weekly and one monthly.

    • Notifications: optionally enable Download diagram from notifications (open link) to include a draw.io file download link in notifications. Enter a Recipient email address and select an Email template. Under Configure notification channels, select any additional channels to notify when a generation completes.

    • Review: confirm all settings, then select Generate to save the configuration and generate the diagram immediately.

Download the latest diagram

The download icon on the Diagrams tab list lets you download the most recently generated version of a diagram as a draw.io file, without opening the canvas.

  1. On the Diagrams tab, locate the diagram configuration you want to download.
  2. Select the download icon in the Last generation column.

The latest generated version downloads as a draw.io file. To download a specific historical version, use the download icon in the Generation history dialog instead.

Open and navigate the canvas

Opening a diagram configuration launches the interactive canvas where you can inspect resources and navigate the generated diagram.

  1. On the Diagrams tab, select the diagram name to open the canvas.
  2. If no generation has run yet, the canvas displays a prompt to generate a new version. Select Generate now to run the first generation.
  3. Use the toolbar controls to navigate:
    • Select Group by to change the clustering of resources.
    • Select Fit to zoom to the full diagram, or Focus to zoom to a selected node.
    • Toggle Show isolated to show or hide resources with no connections.
  4. Use the Search resources field and the Resource Types, Subscriptions, and Resource groups filters to narrow the visible resources.
  5. Use the connection view tabs at the top right (Direct connections, All connected, External dependencies, Show all) to change which connections are displayed.
  6. Click any node on the canvas to inspect its details in the right panel, including resource type, resource group, location, SKU, subscription, and resource ID. Select Open in Azure portal to navigate directly to the resource, or Copy resource ID to copy it to the clipboard.
  7. Select the Latest version dropdown to open the version history picker and switch to a previous generation snapshot.
  8. Select Export to download the diagram as Download draw.io, Download PNG, or Download SVG.

Generate a diagram now

Generating on demand produces an updated diagram immediately using the current state of your Azure subscriptions.

  1. On the Diagrams tab, select the Actions menu (...) next to the diagram configuration.
  2. Select Generate now.
  3. Review the configuration summary shown in the dialog, then select Generate.

Azure Documenter begins generation. When complete, the new version appears in the canvas version history.

Edit a diagram configuration

Editing lets you update any setting on an existing configuration, including the diagram type, without recreating it.

  1. On the Diagrams tab, select the Actions menu next to the configuration you want to edit.
  2. Select Edit.
  3. Update any settings across the wizard steps: name, description, diagram type, subscriptions, scope filters, schedule, or notification channels.
  4. Select Save changes on the Review step.

View generation history

Generation history shows every generation run for a configuration, with status and notification delivery details per channel.

  1. On the Diagrams tab, select the Actions menu next to the configuration.
  2. Select Generation history.
  3. The Generation history dialog lists each run with its timestamp, status (Success or failure), and a View details link.
  4. Select View details on a run to see notification details: the configured recipients and diagram link option, and the transmission result per channel including whether the notification was transmitted, the timestamp, and any exception or issue reported.
  5. Select the download icon next to a run to download that specific version of the diagram as a draw.io file.

Delete a diagram configuration

Deleting a configuration permanently removes it and all its settings. Previously generated versions are not recoverable after deletion.

  1. On the Diagrams tab, select the Actions menu next to the configuration you want to delete.
  2. Select Delete.
  3. Confirm the deletion.

Permission behavior

Users assigned Account Owner, Owner, or Contributor have full access to all diagram configuration operations by default.

Users on a custom role require the Diagrams feature permission. Read permission allows viewing existing configurations, opening the canvas, and downloading diagrams. Manage permission adds the ability to create, edit, generate, and delete configurations.

Custom role users without Diagrams permission cannot open the Diagrams tab.

Example scenario

A platform team maintains documentation for their production Azure environment. They create a Resource visualizer diagram configuration scoped to five production subscriptions, using the Complete architecture ARG query template with App Insights dependencies and Log Analytics enrichment enabled. They set a weekly schedule every Monday at 02:00 and configure Teams and email notifications so the team is alerted when the new version is ready.

Each Monday, Azure Documenter generates an updated diagram. The Schedule column shows the next scheduled run datetime so the team always knows when to expect the next version. A team member opens the canvas, uses the Subscriptions filter to focus on a single subscription, and clicks a Kubernetes Service node to inspect its resource details and open it directly in the Azure portal. When a resource shows unexpected external dependencies, they switch to the External dependencies connection view to investigate. They export the diagram as PNG to share in a team review, and download the draw.io file directly from the list for a colleague who wants to edit it offline.

Limitations

  • Each diagram generation consumes one document license. Frequent schedules spend the monthly allowance faster.
  • The download icon on the Diagrams tab list downloads the latest generated version as draw.io only. To download PNG or SVG, open the canvas and use the Export menu.
  • The Resource visualizer type requires a valid ARG query. Use Test query to verify the query returns results before saving the configuration.
  • Notification channel delivery failures are recorded in generation history and do not prevent the diagram from being generated.
  • Version history retains all previous generation snapshots. There is no automatic pruning of old versions.

Troubleshooting

  1. Subscriptions do not appear in the Azure scope & filters step
    Cause: no service principal is configured in Azure Documenter, or the configured service principal does not have access to the required subscriptions.
    Fix: verify that a service principal is configured and has Reader access to the target subscriptions. Select + Add service principal to add one if needed. See Managing service principals.

  2. Resource visualizer query returns no resources
    Cause: the selected subscriptions have no resources matching the ARG query template, or the service principal lacks Reader access to those subscriptions.
    Fix: select Test query on the Azure scope & filters step to confirm the query returns resources. Verify the service principal has Reader access on all selected subscriptions.

  3. Generation fails or shows an error in generation history
    Cause: the service principal has lost access to one or more selected subscriptions, or the subscription scope has changed since the configuration was saved.
    Fix: open the configuration for editing, navigate to the Azure scope & filters step, and verify the subscriptions and service principal. Re-save and regenerate.

  4. Notification channel does not receive the generation alert
    Cause: the notification channel is misconfigured, or the recipient email address is missing.
    Fix: open the configuration for editing, navigate to the Notifications step, and verify the recipient email address and channel configuration. Check generation history under View details for the specific transmission error.

  5. Canvas shows no resources after opening a diagram
    Cause: the diagram has not been generated yet, or the diagram version opened from history predates the interactive viewer.
    Fix: if no generation has run, select Generate now directly from the canvas prompt to create the first version. If you opened an older version from the version history picker and the canvas displays a message that the version predates the viewer, select Load latest version to switch to the most recent interactive snapshot. If the latest version also shows no resources, toggle Show isolated to on and check the Subscriptions and Resource Types filters to confirm the expected resources are in scope.

FAQs

  1. Can I add multiple schedules to a single diagram configuration?
    Yes. In the Schedule step, select + Add schedule to add more than one recurring schedule. For example, you can configure a weekly schedule for operational reviews and a monthly schedule for reporting, each with different days and times.

  2. Can I use the same service principal in multiple diagram configurations?
    Yes. A service principal can be selected across multiple configurations. This is useful when several diagrams cover overlapping subscription scopes that the same service principal can access.

  3. What is the difference between the Network, Workload, and Resource visualizer diagram types?
    Network maps VNet topology including subnets, NICs, VMs, NSGs, and public IPs. Workload maps application stacks per resource group including App Services, SQL, and Storage. Resource visualizer uses an ARG query to generate a cross-subscription dependency map with optional external dependency enrichment.

  4. Can I change the diagram type of an existing configuration?
    Yes. The diagram type can be changed when editing an existing configuration. Open the Actions menu next to the configuration, select Edit, and update the diagram type in the Basics step.

  5. What export formats are available for a generated diagram?
    The download icon on the Diagrams tab list downloads the latest version as draw.io only. From the canvas Export menu, you can download draw.io, PNG, or SVG. Specific historical versions can be downloaded as draw.io from the Generation history dialog.

Related articles