Document your Azure environment
In this article I like to give you an overview about resources that helps you to visualize and document your Azure cloud solutions and environments.
Shapes and icon sets
Azure Design Visio VSSX
David Summers started an “Azure Icon Design project” to collect icons in Visio format (VSSX). You’ll find the icon set from his GitHub repo:
Azure-Stencils (VSSX und SVG)
There is just another GitHub repository by “azurekid” with many (categorized) icons in Visio format (VSSX) and SVG:
Microsoft Azure UX Patterns
Few hundreds icons in SVG format are also available from the “official” Microsoft Azure site:
Microsoft Integration Stencils Pack for Visio
Microsoft updates regular this Visio stencils package with many symbols of on-premises, hybrid and cloud services/products: https://gallery.technet.microsoft.com/Collection-of-Integration-e6a3f4d0#content
Microsoft Azure, Cloud and Enterprise Symbol / Icon Set
The most updated collection of cloud related icons by Microsoft is the following one. It includes (categorized) symbols in SVG format: https://www.microsoft.com/en-us/download/details.aspx?id=41937
Drawing your architecture (Samples)
Azure Solutions Architectures
Microsoft’s Azure solution architecture page shows some well-designed samples of reference architectures. This could be an inspiration to design your own architecture draws:
Microsoft 3D Visio Templates
You have probably already seen some beautiful Azure 3D blueprints from Microsoft (in the recent years). In this video you will get an introduction of using a Visio template that allows to create such isometric blueprints:
Microsoft 3D Blueprint Visio Training Video
Microsoft has moved to a flatter style in the current architecture draws.
The development of this template has stopped in 2017 but it’s still available from the Microsoft Download-Center:
Microsoft 3D Blueprint Visio Template Download
Online Diagram Tools
Visual Paradigm Online Diagram
This cross-platform diagram solution includes standard Azure icons and samples to start drawing your own Azure diagram:
The following diagram solution is a very popular free-to-license web app with integration in Atlassian products and other features (e.g. VSSX import, OneDrive-support).
Check out the various “Cloud” templates (including AWS, Azure and GCP) by clicking on “create new diagrams”.
I can strongly recommended to give them a try.
Represent Azure architectures accurately in Visio Online
You are using Vision Online? Take a look on the library which includes already Azure symbols, templates, and sample diagrams: https://techcommunity.microsoft.com/t5/Visio-Blog/Represent-Azure-architectures-accurately-in-Visio-Online/ba-p/274650
Visualizer and Automated Documentation
Azure Resource Visualizer
Using ARM parameter and template files are parts of Azure’s native “Infrastructure as Code” approach but are also one of the best ways to document your deployment. Visualizing your Azure resources based on your ARM files is (in my opinion) also a great option. Even in your draft phase this helps to visualize and review your planned solution.
That’s why ARMViz was my first choice over the past years - available as online tool or install package (to run it in your own environment): https://github.com/ytechie/AzureResourceVisualizer http://armviz.io/designer
Unfortunately it seems that ARMViz is outdated and have been abandoned. Ben Coleman started a project (“ARM Template Viewer”) and released a first version of a VSCode extension to displays a graphical view of an opened ARM template file. Great user experience and value for ARM authors! Strongly recommended to check out the extension: https://marketplace.visualstudio.com/items?itemName=bencoleman.armview
This tool allows you to generate documentation and diagrams for your Azure and other cloud service platforms (AWS, GCP, …) environment as well. Exportable as document type for Excel, Word, Visio and Draw.io.
Product details (subscription price) and trial version are available here:
Easy to use and popular architecture diagram generator.
Unfortunately (full) support only for AWS environment (status: 09/30/2019).
Advanced collaboration and editing/export features (e.g. Draw.io support) included.
Free version and pricing details are available:
General advice on writing design documentations
- Define an efficient documentation structure: Start with a short introduction of your key points such as scope, business/compliance requirements or technical background (initial situation). All your design documentations should follow a common schema.
- Describe the relation of your designed solution to the general (cloud) architecture: This is very important if your solution has dependency or strong references to other design decisions or guidelines.
- Start with a picture instead of using thousand words: Describe your solution based on a well-designed architecture draw (in formats that can be easily modified by design changes)
- Capture the decisions (including pros and cons): What were the reasons for the planned solutions? Review your design decision and the reasons to having cut off other variants?
- Design vs. implementation/operation guide: Move details about implementation or specification to the appendix or splitting the documentation between architecture (design) document and implementation guide.