AWS-PlantUML
PlantUML sprites, macros, stereotypes, and other goodies for creating PlantUML diagrams with AWS components.
AWS-PlantUML has high-quality sprites and convenient macros for AWS components and services for all of the AWS icons in the AWS Simple Icons package, so that you can quickly and easily add stylized AWS elements to your PlantUML deployment diagrams.
Getting Started
At the top of your PlantUML .puml file, first include the the common.puml file found in the dist folder at the root of this repo.
If you want to tweak the basic representation of AWS-PlantUML entities, or you don't want to rely on an internet connection, you can just download common.puml to your local machine and add it after the @startuml with:
!include path/to/common.puml
Otherwise, you can link directly to the file in this repo with:
!includeurl https://raw.githubusercontent.com/milo-minderbinder/AWS-PlantUML/release/18-2-22/dist/common.puml
After the common.puml is added, you can then add any additional .puml files from AWS-PlantUML to import the specific sprites, macros, and other definitions you need. Sometimes it's helpful to define a constant pointing to the dist folder of the AWS PlantUML version you're using, to make switching versions and hosts easier.
!define AWSPUML https://raw.githubusercontent.com/milo-minderbinder/AWS-PlantUML/release/18-2-22/dist
!includeurl AWSPUML/common.puml
!includeurl AWSPUML/Storage/AmazonS3/AmazonS3.puml
!includeurl AWSPUML/Storage/AmazonS3/bucket/bucket.puml
Macro definitions for components, like S3 and S3 Buckets, will take an alias as the first parameter, and a label as an optional second parameter:
AMAZONS3(s3_internal)
AMAZONS3(s3_partner,"Vendor's S3")
s3_internal <-- s3_partner
Starting from version 17.1.6, all icons now have a large version of sprites with accompanying macros and stereotypes. For additional customization, there is now a new six-parameter macro for all icons, which adds four new optional parameters in addition to the alias and label parameters, so that users can set the entity type, sprite color, stereotype, and sprite, respectively:
...<SNIP>...
!includeurl AWSPUML/Storage/AmazonS3/AmazonS3_LARGE.puml
skinparam nodeBackgroundColor White
skinparam storage<<**AmazonS3**>> {
backgroundColor #F9DFDC
}
AMAZONS3(s3_internal,"Default S3")
AMAZONS3(s3_internal2,"S3 as node",node)
AMAZONS3_LARGE(s3_partner,"Large S3")
s3_internal2 <-r- s3_partner
s3_internal <-l- s3_partner
You can also nest components inside others using enclosures:
AMAZONS3(s3) {
BUCKET(site,www.insecurity.co)
BUCKET(logs,logs.insecurity.co)
}
site .r.> logs : events
Before you know it, you'll be creating nice, clean diagrams for your AWS applications:
@startuml
!define AWSPUML https://raw.githubusercontent.com/milo-minderbinder/AWS-PlantUML/release/18-2-22/dist
!includeurl AWSPUML/common.puml
!includeurl AWSPUML/ApplicationServices/AmazonAPIGateway/AmazonAPIGateway.puml
!includeurl AWSPUML/Compute/AWSLambda/AWSLambda.puml
!includeurl AWSPUML/Compute/AWSLambda/LambdaFunction/LambdaFunction.puml
!includeurl AWSPUML/Database/AmazonDynamoDB/AmazonDynamoDB.puml
!includeurl AWSPUML/Database/AmazonDynamoDB/table/table.puml
!includeurl AWSPUML/General/AWScloud/AWScloud.puml
!includeurl AWSPUML/General/client/client.puml
!includeurl AWSPUML/General/user/user.puml
!includeurl AWSPUML/SDKs/JavaScript/JavaScript.puml
!includeurl AWSPUML/Storage/AmazonS3/AmazonS3.puml
!includeurl AWSPUML/Storage/AmazonS3/bucket/bucket.puml
skinparam componentArrowColor Black
skinparam componentBackgroundColor White
skinparam nodeBackgroundColor White
skinparam agentBackgroundColor White
skinparam artifactBackgroundColor White
USER(user)
CLIENT(browser)
JAVASCRIPT(js,SDK)
AWSCLOUD(aws) {
AMAZONS3(s3) {
BUCKET(site,www.insecurity.co)
BUCKET(logs,logs.insecurity.co)
}
AMAZONAPIGATEWAY(api)
AWSLAMBDA(lambda) {
LAMBDAFUNCTION(addComments,addComments)
}
AMAZONDYNAMODB(dynamo) {
TABLE(comments,Comments)
}
}
user - browser
browser -d-> site :**1a**) get\nstatic\ncontent
site ~> logs :1a
site .u.> browser :**1b**
browser - js
js -r-> comments :**2a**) get\ncomments
comments ..> js :**2b**
js -r-> api :**3**) add\ncomment
api -d-> addComments :**4**
addComments -> comments :**5**
comments ..> js :**6**) new\ncomments
@enduml
Customized Builds
For those so inclined, it is also simple to generate customized .puml files for your own personalized PlantUML diagrams with unique styles and colors. Building a custom set of PlantUML macros and sprites takes only three simple steps:
1. Download the [AWS Simple Icons set](https://aws.amazon.com/architecture/icons/) and extract them into a directory well refer to as `<ICONS_DIR>`
2. Configure and/or add styles to the `puml.ini` configuration file, or create your own
3. Run the `puml.py` script against your downloaded `<ICONS_DIR>` using your custom config
1. Download
If you haven't installed it already, you'll need Python 3 to run the puml.py module used to generate the AWS-PlantUML .puml files. You can get installation instructions and binaries for Python 3.6, which was used to generate the release version of AWS-PlantUML, on Python.org.
Download the AWS Simple Icon set here and extract the contents to a directory we'll refer to as <ICONS_DIR>. This release was generated from version 17.10.18 of the AWS Simple Icons set release by Amazon.
2. Configure
Using the release version of the awspuml.ini configuration file as a reference, you can specify custom styles for your own AWS-PlantUML build. The [PUML.colors] section maps color names to simple HTML color names (e.g. Red) or custom hex values (e.g. #AAFFCC). These custom color names can then be referenced elsewhere in the configuration by including ${PUML.colors:<COLOR_NAME> in a configuration option value, where "<COLOR_NAME>" would be replaced by the desired option in the [PUML.colors] section.
The remaining sections designate generation options for the folders created from the icons in <ICONS_DIR>. To make the generated folder structure of AWS-PlantUML URL-safe, the awspuml.py script relies on Amazon's file naming convention for the AWS Simple Icon set, which names files according to the pattern:
<CATEGORY>_<SERVICE_NAME>[_<SERVICE_COMPONENT>][_LARGE].<FILE_EXTENSION>
Options in the awspuml.ini can be set for an entire category
[InternetOfThings]
entity_type: artifact
or for all subsections of a category
[InternetOfThings.AWSIoT.]
entity_type: component
or just for a specific item in a category
[InternetOfThings.AWSIoT.action]
entity_type: usecase
Valid options are:
* `entity_type` - sets the PlantUML representation for the matching AWS-PlantUML components. Examples include `artifact`, `component`, `cloud`, etc.
* `color` - sets the foreground color for the matched entity's sprite
* `skinparam` - sets custom skinparam options for the stereotype generated for corresponding entities. An example value for this option would be `BackgroundColor Red`.
3. Run
After configuring, simply run the puml.py module from the command line using Python 3, passing the configuration file and the <ICONS_DIR> as command line options. If you need help, just call the script with the -h flag to print usage help to stdout:
> python3 puml.py -h
usage: puml.py [-h] [-c CONFIG] [-g] [-o OUTPUT] icons_path
Generate PlantUML sprites and macros from images
positional arguments:
icons_path Path to image icons directory
optional arguments:
-h, --help show this help message and exit
-c CONFIG, --config CONFIG
Config file for puml generation (default:
/home/milo/AWS-PlantUML/puml.ini)
-g, --generate_config
Write all sections to the INI file specified by the -c
switch; if an INI file already exists, its sections
and options will be preserved, but missing sections
will be added and invalid sections will be deleted.
(default: False)
-o OUTPUT, --output OUTPUT
Output path for generated .puml files (default:
/home/milo/AWS-PlantUML/dist)
Enjoy!