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
Content
- Content
- Getting Started
- Usages
- Advanced Samples
- Snippets for Visual Studio Code
- Customized Builds
- Built With
- Contributing
- License
- Acknowledgments
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