plantuml-stdlib / azure-plantuml

PlantUML sprites, macros, and other includes for Azure services

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
  • Prerequisites
  • List of all supported Azure Symbols
  • Hello World
• Usages
  • Basic usage
  • Raw sprite usage
  • Simplified mode
  • In combination with C4-PlantUML
• Advanced Samples
  • C4 Integration
  • Azure IoT Reference Architecture: Stateful stream processing
  • Azure Reference Architecture: Highly scalable web application
• 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

azure-plantuml's Issues

Add icon for Cloud Services

Include the icon for this https://azure.microsoft.com/en-us/services/cloud-services/ service.

Pull Request to follow shortly.

table.md icons broken due to extra "dist" in path

Azure-PlantUML/scripts/lib/MarkdownTable.cs

Line 38 in e38467c

sbTable.Append($" | ");

and second occurance below.

how to do similar plantuml support for Power Platform icons

Is it possible to use this project to also include these icons? separate repo? same approach?

https://docs.microsoft.com/en-us/power-platform/guidance/icons

Thanks & Regards,
Stefan

No Azure Blockchain Service

Hard Coded Paths In Build Scripts

Windows paths are hard-coded into the build scripts.
e.g.

var plantUmlPath = @"C:\ProgramData\chocolatey\lib\plantuml\tools\plantuml.jar";
var inkScapePath = @"C:\Program Files\Inkscape\inkscape.exe";
static string rsvgConvertPath = @"C:\ProgramData\chocolatey\bin\rsvg-convert.exe";

Even if you are on Windows you might have these installed in different locations.

It would be useful if these could be overridden with command line parameters.

For Ubuntu based distros rsvg-convert is installed with

sudo apt install librsvg2-bin

and is located at:

which rsvg-convert
/usr/bin/rsvg-convert

Can't use $link property

Hi, when trying to put the $link property in several components such as AzureServiceFabric, PlantUML diagram generation fails. Can't see in the documentation of this project if this property is supported or not.

Make build process more robust

The README in the scripts directory says:

 You also need to download the Microsoft Azure, Cloud and Enterprise Symbol / Icon Set and copy all files from Symbols\CnE_Cloud\SVG to source/official

The current file is Microsoft_Cloud_AI_Azure_Service_Icon_Set_2019_05_08_2.zip

This no longer has the Symbols\CnE_Cloud\SVG directory.

If you extract the zip as is the build fails.

If you extract the zip using the flat option, most but not all of the files are found.

Some of the files that are in the manual directory are now also in the official directory.
e.g. manual/Azure App Service - Web App (was Websites) is official/App Services

This means that the build is not reproducible.

You need a way to ensure consistency.
A few different ways you could do this is:

• check in all the files from the official version you used with a reference to the version number
• put a direct link to the version of the official zip file used (assuming that Microsoft keeps archives)
• Mirror the zips in another repo and link to the git hash (to save repo space in this repo)

etc

Missing Active Directory

Request inclusion for ActiveDirectory PUML please.

Add icons still missing after recent update

The recent update from #31 update (almost) all icons. Besides from some image corruption (being addressed in #32), it needs to be checked that none of the requested icon are missing.

From the overview of #29, the following icon might be missing:

• Azure App Configuration
• Azure Purview
• Generic "Internet" cloud that looks "azure-ish"

Also, the currently open MRs could also contain icons that are not in the current set:

• #26
• #17

Both need to be verified, and either marked as complete or have a linked issue or MR that adds them.

This issue is a follow-up to #29 and related MR(s).

Suggestion how to integrate Azure-PlantUML into PlantUML for Confluence

I need suggestion on how to make PlantUML for Confluence to work with Azure-PlantUML

Guidance on using the colored version of the symbols

Whenever I use this very cool library, it defaults to the monochrom version of the symbols.

How can I use the colored version of the symbols?

Future of Azure-PlantUML

Let's wait for upcoming changes at plantuml-stdlib/C4-PlantUML#81 and then proceed here.

Azure App Configuration missing

There doesn't seem to be resource icons, and associated puml file for Azure App Configuration.

How to use the colored version of icons?

I take advantage of the last activities on this repo to ask for this question : how to use the colored version of icons ?

Is this now possible ?

This prevents me to use PlantUML as it full potential ...

Originally posted by @ChrisProlls in #20 (comment)

Add standalone Azure icon

It would be very useful to have the base Microsoft Azure icon available in this library, to decorate shapes without necessarily having to provide a shape itself.

Add support for PlantUML themes

I'd like to propose adding PlantUML theme support for a future release. I believe this can be done without any breaking changes by adding a themes directory to the dist folder and referencing it as follows:

@startuml theme-DefaultMonospacedFontName

!define AzurePuml https://raw.githubusercontent.com/travisnielsen/Azure-PlantUML/themesupport/dist

' IMPORT THEME HERE 👇🏽
!includeurl AzurePuml/themes/blueprint.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

AzureEventHub(fareDataEventHub, "Fare Data", "PK: Medallion HackLicense VendorId; 3 TUs", "testing 1234")
note right: this is a note
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 : "test arrow"
devices --> tripDataEventHub
fareDataEventHub --> streamAnalytics
tripDataEventHub --> streamAnalytics
streamAnalytics --> outputCosmosDb

@enduml

I have a proof-of-concept branch here: https://github.com/travisnielsen/Azure-PlantUML/tree/themesupport

Examples:

Blueprint

crt-green

reddress-darkblue

cerulean

This is really cool. Thank-you

<3 - https://twitter.com/geoffreyhuntley

Microsoft Fabric Icons

Could I request adding https://learn.microsoft.com/en-us/fabric/get-started/icons to standard lib.
Thanks in advance

LAYOUT_WITH_LEGEND syntax error

Per plantuml-stdlib/C4-PlantUML#36 this it appears that this should be called as LAYOUT_WITH_LEGEND() in order for it to work.

As it is now it throws a syntax error. I think there's other places this should be updated so feel free to just discard my PR here

Missing Azure Lighthouse

Hi,
there is no Azure Lighthouse entity. Could you please provide it? 🙏

Thanks

Missing AzureSubnet

I don't know if there is an icon for an Azure Subnet upstream, but to complete my diagrams, I am currently missing out on an AzureSubnet entity.

Thanks for providing this.

🎉 Release v2.2 🎊

Full Changelog: v2.1...v2.2

This issue is a placeholder for all tasks that need to be completed to release a new version (2.2.0):

• Create a separate release/2-2 branch (as was done for previous releases).
  ^{So users can include a versioned file instead of requring main / HEAD}
• Update the versioned links in the README.md file (see fe13039)
  ^{So the documentation points to the latest available changes}
• Check if anything else that needs changing. Copyright year? Any contrib files? URLS? If so, add to the version branch.
  ^{Making everything is in order before the release, so we do not have to make minor releases afterwards}
• Open an MR to incorporate the changes needed for version release into the main branch.
  ^{So there is a fixed/traceable moment in time that marks the change}
• After review, merge the changes but DO NOT DELETE THE VERSION BRANCH. We want to keep that around.
  ^{So users can include a versioned file instead of requring main / HEAD}
• Create a new release of the latest changes (using "Generate Release Notes").
  ^{So there is a fixed/traceable moment in time that marks the change}
• Open an MR at plantuml/plantuml-stdlib
  ^{So the latest changes are available to all users}
• Mark the version branch as protected
  ^{So history cannot be falsified (whether by accident or on purpose).}

It also serves to be a first step in documenting how releases are made. Eventually a complete write-up should be added as part of a CONTRIBUTING.md

Use the new Azure "Fluent" logo

I love this repo as it is a good and helpful resource to get icons for diagram easily and without hassle. Great work!

Azure has a new logo: https://azure.microsoft.com/en-in/blog/a-fluent-new-look-for-the-azure-icon/, svg can be found here: https://en.wikipedia.org/wiki/File:Microsoft_Azure.svg

It would be great if that one could be added to the list.

I'm happy to submit a PR, just not sure where it all has to be changed (png and svg are easy enough to find, but not sure if there are any sprites that need updating)

Thanks!

ADT - Azure Digital Twin Icon Outdated

The icon for the Azure Digital Twin (ADT) is not up to date!

IS:

SHOULD:

In my code for the diagram I used this code snipped to include the icon

!define AzurePuml https://raw.githubusercontent.com/plantuml-stdlib/Azure-PlantUML/master/dist/
!includeurl AzurePuml/AzureCommon.puml
!includeurl AzurePuml/InternetOfThings/AzureDigitalTwins.puml

Would be super cool if you update the Azure Icons!

Separate styling from symbols?

The Common file includes several declarations that modify the theme/skinparams for things like arrows. This has the result that if I include an Azure symbol in my Sequence diagram all of the arrows are changed and I have to override the skinparams in each of my diagrams to return them back to their default. Could you place the the skinparam modifications into a separate puml file (CommonStyles) so that those of us that would like to include just the symbols can do so without changing the style(s) of our existing diagrams?

I can fork & submit a pull request if desired.

Azure Firewall Not Included

Looks to me like Azure Firewall isn't included in the set of icons. Would be nice to have.

Update URL for Azure icons to latest

The current set of icons is available here rather than the one pointed to on the project's readme

Corrupted icons

The latest merge corrupted some of the icons, and I don't know enough about svg to diagnose what is going on see https://github.com/plantuml-stdlib/Azure-PlantUML/blob/master/AzureSymbols.md

• AzurePowerBIEmbedded
• AzureServiceEndpoint
• AzureSubnet
• AzureVirtualNetworkPeering

It's probably systemic or down to the original icons but as I said I can't really help much.

FEATURE: Management Structures

It would be great if we could model the hierarchical constructs withing azure. Something like:

Unfortunately, I neither possess the time nor skills to offer any help on this one.

C4 examples return Error Fetching Resource

The picture links for the C4 examples seem to be broken.

Missing Azure static web App icon

I'd like to be able to use https://iconduck.com/icons/158807/azure-staticwebapp

Thank you in advance for your response

Missing Azure OpenAI sprites and icons

I'm not sure where they live or I'd try to help

AzureTableStorage missing?

I am missing the Service 'AzureTableStorage'

Did I miuss something? Or is a there a way to emulate this?

https://learn.microsoft.com/en-us/azure/cosmos-db/table/support?toc=https%3A%2F%2Flearn.microsoft.com%2Fen-us%2Fazure%2Fstorage%2Ftables%2Ftoc.json&bc=https%3A%2F%2Flearn.microsoft.com%2Fen-us%2Fazure%2Fbread%2Ftoc.json

Update all icons to more recent versions

This issue is a catch-all for updating ALL the icons in this repo, rather than the individual MR/issues that are open(ed) now.

Individual issues will all be closed in favor of this issue, which takes the highest priority.

(It is assumed that all requests for missing icons will be resolved by using newer sources. If this turns out to be incorrect, those issues should be opened individually.)

Overview of requested (missing) icons:

• Azure App Configuration

• Azure Purview

• generic "Internet" cloud that looks "azure-ish"

• Azure Firewall

  - Source: Firewalls
    Target: AzureFirewall
  - Source: Azure Firewall Manager
    Target: AzureFirewallManager
  

• Azure Blockchain Service

  - Name: Blockchain
  Services:
  - Source: Azure Blockchain Service
    Target: AzurBlockchainService
  - Source: Azure Token Service
    Target: AzurBlockchainTokenService
  - Source: ABS Member
    Target: AzurBlockchainMember
  - Source: Consortium
    Target: AzureBlockchainConsortium
  - Source: Outbound Connection
    Target: AzureBlockchainConnection
  

• Azure Subnet

  - Source: VNet Subnets
    Target: AzureSubnet
  

• Active Directory

  - Source: Azure Active Directory
    Target: AzureActiveDirectory
  - Source: Azure AD Domain Services
    Target: AzureActiveDirectoryDomainServices
  - Source: Azure AD B2C
    Target: AzureActiveDirectoryB2C
  - Source: Active Directory Connect Health
    Target: AzureActiveDirectoryConnectHealth
  - Source: Azure AD Identity Protection
    Target: AzureActiveDirectoryIdentityProtection
  - Source: Azure AD Roles and Administrators
    Target: AzureActiveDirectoryRolesAndAdministrators
  - Source: Groups
    Target: AzureActiveDirectoryGroup
  - Source: Users
    Target: AzureActiveDirectoryUser
  - Source: Identity Governance
    Target: AzureIdentityGovernance
  - Source: Managed Identities
    Target: AzureManagedIdentity
  - Source: Enterprise Applications
    Target: AzureEnterpriseApplication
  - Source: App Registrations
    Target: AzureAppRegistration
  

• Azure Synapse

  - Source: Azure Synapse Analytics
    Target: AzureSynapseAnalytics  
  

• Device Provisioning Service

  - Source: Device Provisioning Services
    Target: AzureDeviceProvisioningService  
  

• PowerBI

  - Source: Power BI Embedded
    Target: AzurePowerBIEmbedded