Azure-PlantUML

PlantUML sprites, macros and stereotypes for creating PlantUML diagrams with Azure components.

Azure-PlantUML includes symbols and useful macros for all Azure services.
The official Microsoft Azure architecture icons are used as the primary source. On top the missing Azure services symbols have been extracted manually from Azure.com.

With Azure-PlantUML it is feasible to create visually appealing and memorable PlantUML diagrams for your Azure systems.

It is also possible to combine Azure-PlantUML with C4-PlantUML to create C4 models for Azure architectures.

See also Save the world from Powerpoint Cloud Solution Architects

Getting Started

To be able to use Azure-PlantUML it is necessary to use specific !includes.
After that the Azure service macros are available and can be used.
A list of all supported Azure services can be found in the Azure-PlantUML Azure Symbols Documentation.

Prerequisites

At the top of your Azure-PlantUML .puml file, you need to include the AzureCommon.puml file found in the dist folder of this repo.

To be independent of any internet connectivity, you can also download AzureCommon.puml and reference it locally with

!include path/to/AzureCommon.puml

If you want to use the always up-to-date version in this repo, use the following:

!includeurl https://raw.githubusercontent.com/plantuml-stdlib/Azure-PlantUML/release/2-2/dist/AzureCommon.puml

The next step is to include specific .puml files from Azure-PlantUML.
For each Azure service a specific .puml file exists, which contains sprite and macros definitions.
It is also possible to include Azure services category .puml files, which contain all Azure services from this category.

!define AzurePuml path/to
!include AzurePuml/AzureCommon.puml
!include AzurePuml/Databases/all.puml
!include AzurePuml/Compute/AzureFunction.puml

Or the always up-to-date version in this repo:

!define AzurePuml https://raw.githubusercontent.com/plantuml-stdlib/Azure-PlantUML/release/2-2/dist
!includeurl AzurePuml/AzureCommon.puml
!includeurl AzurePuml/Databases/all.puml
!includeurl AzurePuml/Compute/AzureFunction.puml

List of all supported Azure Symbols

All Azure services names, categories, colored and monochrom symbols, and their .puml files can be found in the Azure-PlantUML Azure Symbols Documentation.

Hello World

@startuml Hello World
!define AzurePuml https://raw.githubusercontent.com/plantuml-stdlib/Azure-PlantUML/release/2-2/dist
!includeurl AzurePuml/AzureCommon.puml
!includeurl AzurePuml/Databases/all.puml
!includeurl AzurePuml/Compute/AzureFunction.puml

actor "Person" as personAlias
AzureFunction(functionAlias, "Label", "Technology", "Optional Description")
AzureCosmosDb(cosmosDbAlias, "Label", "Technology", "Optional Description")

personAlias --> functionAlias
functionAlias --> cosmosDbAlias

@enduml

Usages

It is up to you how you want to use Azure-PlantUML.

It is possible to build very simple diagrams with it and leverage the Azure-PlantUML macros.
You can also decide that you just want to use the Azure-PlantUML sprites.
In addition it is also possible to use Azure-PlantUML in combination with C4-PlantUML for using the C4 model and creating diagrams for large systems.

Basic usage

Just import the necessary .puml files and you can use the macros in all your PlantUML diagrams.

@startuml Basic usage - Stream processing with Azure Stream Analytics

!define AzurePuml https://raw.githubusercontent.com/plantuml-stdlib/Azure-PlantUML/release/2-2/dist
!includeurl AzurePuml/AzureCommon.puml
!includeurl AzurePuml/Analytics/AzureEventHub.puml
!includeurl AzurePuml/Analytics/AzureStreamAnalyticsJob.puml
!includeurl AzurePuml/Databases/AzureCosmosDb.puml

left to right direction

agent "Device Simulator" as devices #fff

AzureEventHub(fareDataEventHub, "Fare Data", "PK: Medallion HackLicense VendorId; 3 TUs")
AzureEventHub(tripDataEventHub, "Trip Data", "PK: Medallion HackLicense VendorId; 3 TUs")
AzureStreamAnalyticsJob(streamAnalytics, "Stream Processing", "6 SUs")
AzureCosmosDb(outputCosmosDb, "Output Database", "1,000 RUs")

devices --> fareDataEventHub
devices --> tripDataEventHub
fareDataEventHub --> streamAnalytics
tripDataEventHub --> streamAnalytics
streamAnalytics --> outputCosmosDb

@enduml

Raw sprite usage

If you just want to use the PlantUML sprites inside your existing diagrams, this is also possible.

@startuml Raw usage - Sprites
!pragma revision 1

!define AzurePuml https://raw.githubusercontent.com/plantuml-stdlib/Azure-PlantUML/release/2-2/dist
!includeurl AzurePuml/AzureRaw.puml
!includeurl AzurePuml/Databases/AzureCosmosDb.puml
!includeurl AzurePuml/Compute/AzureFunction.puml


component "<color:red><$AzureFunction></color>" as myFunction

database "<color:#0072C6><$AzureCosmosDb></color>" as myCosmosDb

AzureFunction(mySecondFunction, "Stream Processing", "Consumption")

rectangle "<color:AZURE_SYMBOL_COLOR><$AzureCosmosDb></color>" as mySecondCosmosDb

myFunction --> myCosmosDb

mySecondFunction --> mySecondCosmosDb

@enduml

Simplified mode

Sometimes your architecture diagram includes to many information for your target audience. We need a management version if - something which can be used inside a presentation in front of the management round.

Please always include the technical one in the appendix and ensure that everybody knows, that this is only a simplified version.

To enable the simplified mode AzureSimplified.puml needs to be included or can just be commented in/out.

@startuml Two Mode Sample

!define AzurePuml https://raw.githubusercontent.com/plantuml-stdlib/Azure-PlantUML/release/2-2/dist
!includeurl AzurePuml/AzureCommon.puml

' !includeurl AzurePuml/AzureSimplified.puml

!includeurl AzurePuml/Analytics/AzureEventHub.puml
!includeurl AzurePuml/Compute/AzureFunction.puml
!includeurl AzurePuml/Databases/AzureCosmosDb.puml
!includeurl AzurePuml/Storage/AzureDataLakeStorage.puml
!includeurl AzurePuml/Analytics/AzureStreamAnalyticsJob.puml
!includeurl AzurePuml/InternetOfThings/AzureTimeSeriesInsights.puml
!includeurl AzurePuml/Identity/AzureActiveDirectoryB2C.puml
!includeurl AzurePuml/DevOps/AzureApplicationInsights.puml


LAYOUT_LEFT_RIGHT

AzureEventHub(rawEventsHubAlias, "Raw Event Hub", "PK: Medallion HackLicense VendorId; 3 TUs")
AzureDataLakeStorage(datalakeAlias, "Data Lake", "GRS")
AzureStreamAnalyticsJob(streamAnalyticsAlias, "Aggregate Events", "6 SUs")
AzureFunction(stateFunctionAlias, "State Processor", "C#, Consumption Plan")
AzureEventHub(aggregatedEventsHubAlias, "Aggregated Hub", "6 TUs")
AzureCosmosDb(stateDBAlias, "State Database", "SQL API, 1000 RUs")
AzureTimeSeriesInsights(timeSeriesAlias, "Time Series", "2 Data Processing Units")

rawEventsHubAlias ----> datalakeAlias
rawEventsHubAlias --> streamAnalyticsAlias
rawEventsHubAlias ---> stateFunctionAlias
streamAnalyticsAlias --> aggregatedEventsHubAlias
aggregatedEventsHubAlias --> timeSeriesAlias
stateFunctionAlias --> stateDBAlias

@enduml

In combination with C4-PlantUML

Our recommmendation is to use Azure-PlantUML in combination with C4-PlantUML.

Take a look into the Advanced Samples section to see the full power of Azure-PlantUML.

Advanced Samples

The following advanced samples are reproductions from the official Azure documentation and Azure architecture center.

All of them are created in combination with C4-PlantUML for using the C4 model:

"a way for software development teams to efficiently and effectively communicate their software architecture, at different levels of detail, telling different stories to different types of audience, when doing up front design or retrospectively documenting an existing codebase"

C4 Integration

For using Azure-PlantUML and C4-PlantUML together, you need to include AzureC4Integration.puml.

@startuml

!includeurl https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml

!define AzurePuml https://raw.githubusercontent.com/plantuml-stdlib/Azure-PlantUML/release/2-2/dist
!includeurl AzurePuml/AzureCommon.puml

!includeurl AzurePuml/AzureC4Integration.puml

!includeurl AzurePuml/Databases/AzureRedisCache.puml
!includeurl AzurePuml/Databases/AzureCosmosDb.puml

....

@enduml

Azure IoT Reference Architecture: Stateful stream processing

Original: Azure IoT Reference Architecture Guide

Source: C4 usage - IoT Reference Architecture - Stateful stream processing

Azure Reference Architecture: Highly scalable web application

Original: Azure Reference Architecture

Source: C4 usage - Highly scalable web application.puml

Snippets for Visual Studio Code

Because the PlantUML support inside of Visual Studio Code is excellend with the PlantUML extension, you can also find VS Code snippets for Azure-PlantUML at dist/.vscode/snippets/diagram.json.

It is possible to save them directly inside VS Code: Creating your own snippets.

Or you can use the Project Snippets extension.
Now it is possible to have workspace/project level code snippets.

Customized Builds

It is also possible to customize the Azure-PlantUML distro generation.
All details can be found in the Generating the Azure-PlantUML distro documentation.

Built With

.NET 6.0 / C# - The latest LTS version of .NET
YamlDotNet - .NET library for YAML config parsing
Json.NET - .NET library for JSON
Playwright - .NET library for the Playwright web testing and automation framework

Contributing

If you have any ideas, just open an issue and tell us what you think.

If you'd like to contribute, please fork the repository and use a feature branch.
Pull requests are warmly welcome.

License

This project is licensed under the MIT License - see the LICENSE.md file for details

Acknowledgments

AWS-PlantUML - for the base structure
plantuml-office - for the scripts idea
C4 Model - for the hope that it's possible to improve architecture documentations

naoyaikeda/Azure-PlantUML