Overview
Configuring a diagram covers creating, editing, grouping, deleting, and downloading architecture diagrams — letting you build and maintain a visual representation of resources across your Azure subscriptions.
Business value
Being able to fully configure a diagram — not just view one — lets teams keep their architecture visuals current as resources and business orchestrations change, without needing to rebuild diagrams from scratch each time.
Prerequisites
Required permissions
| Role | Permission level | Access |
|---|---|---|
| Account owner, Owner, Contributor | Built-in | Full access to create, edit, delete, and download diagrams in the Diagrams tab. |
| Custom roles | Diagrams — Read | View existing diagrams and download them. Cannot create, edit, or delete them. |
| Custom roles | Diagrams — Manage | Full access to create, edit, and delete diagrams, in addition to Read access. |
How it works
A diagram is built from resources filtered out of one or more connected subscriptions, then visually connected and grouped to represent a business orchestration. Resource icons show connections you draw between them, and can be grouped to represent inner-level orchestrations within the overall architecture.
Steps
Use the following steps to create, edit, group, delete, or download a diagram. Go to Diagrams in Azure Documenter to get started.
Create a diagram
Creating a diagram lets you build a new architecture visualization from resources across one or more subscriptions.
- Click Add Diagram and provide a name for the diagram.
- Select the Service principals for the resources you want to display and connect.
- Optionally, filter resources by resource group, type, location, or tags to narrow down to the required subset.
- Click Create to start building the diagram.
- In the Resources pane, select the filtered resources you want to include.
- Click and drag from the edge of a resource icon to connect it to another resource.
- Click and drag a resource icon by its center to reposition it within the diagram.
- Click Update to finish creating the diagram.
Group and ungroup resources
Grouping resource icons lets you represent an inner-level orchestration within the broader architecture diagram.
- Select multiple resource icons and use the Group option to combine them into a single group.
- Use the Ungroup option on an existing group to separate the resource icons again when the grouping is no longer needed.
Edit a diagram
Editing a diagram lets you update its resources, connections, or the subscriptions it draws from, using one of two edit modes.
- Click the Edit option on the diagram.
- Choose one of the two edit modes:
- Modify diagram — change resource connections, add or remove resources, and rename the diagram.
- Configure subscriptions — change which subscriptions the diagram draws resources from, and adjust filters to refine which resources are available.
Delete a diagram
Deleting a diagram permanently removes it once it's no longer needed.
- Click the Delete icon on the diagram you want to remove.
Download a diagram
Downloading a diagram saves a copy as an SVG file for offline reference outside Azure Documenter.
- Click the Download option on the diagram.
Permission behavior
Users assigned Account owner, Owner, or Contributor can create, edit, delete, and download any diagram. Users on a custom role need the Diagrams feature permission enabled — Read to view and download diagrams, Manage to create, edit, or delete them. Custom role users without Diagrams access cannot open the Diagrams tab.
Example scenario
A team wants to document how their order-processing resources are orchestrated across two subscriptions. They click Add Diagram, name it, select the service principals for both subscriptions, filter to the relevant resource group, connect the resources to show their data flow, group the messaging resources together, and click Update to save the diagram.
Limitations
Diagrams are downloaded in SVG format only. Resources that are no longer available in the selected subscription, or whose service principal has been removed, appear with a red status icon rather than being removed automatically from the diagram.
Troubleshooting
-
Can't connect two resource icons
Cause: the connection must be drawn by clicking and dragging from the edge of a resource icon, not its center.
Fix: start the drag from the edge of the resource icon rather than the middle. -
Diagram changes aren't saved
Cause: changes made while building or editing a diagram must be confirmed with Update before they're saved.
Fix: click Update after making changes to the diagram. -
Can't edit or delete a diagram
Cause: the user's custom role has Diagrams — Read enabled, but not Manage.
Fix: enable Diagrams — Manage on the custom role to allow editing and deleting diagrams.
FAQs
-
What's the difference between Modify diagram and Configure subscriptions when editing?
Modify diagram changes resource connections, additions, removals, and the diagram name. Configure subscriptions changes which subscriptions and filters the diagram draws resources from. -
What format is a downloaded diagram saved in?
Diagrams are downloaded as SVG files for offline reference. -
Can I group resources after a diagram has already been created?
Yes. You can select existing resource icons on a diagram and use the Group option at any time, and Ungroup them later if needed.