{"id":13566013,"url":"https://github.com/milo-minderbinder/AWS-PlantUML","last_synced_at":"2025-04-03T23:31:04.710Z","repository":{"id":89708798,"uuid":"48261108","full_name":"milo-minderbinder/AWS-PlantUML","owner":"milo-minderbinder","description":"PlantUML sprites, macros, and other includes for AWS components.","archived":false,"fork":false,"pushed_at":"2019-05-07T22:04:23.000Z","size":37110,"stargazers_count":644,"open_issues_count":9,"forks_count":67,"subscribers_count":31,"default_branch":"master","last_synced_at":"2024-11-04T20:41:33.707Z","etag":null,"topics":["aws","diagram","graphviz","plantuml","uml"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/milo-minderbinder.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2015-12-18T23:30:06.000Z","updated_at":"2024-08-12T07:48:49.000Z","dependencies_parsed_at":null,"dependency_job_id":"33edc921-c36c-458b-9f7f-c42dacd2426e","html_url":"https://github.com/milo-minderbinder/AWS-PlantUML","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/milo-minderbinder%2FAWS-PlantUML","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/milo-minderbinder%2FAWS-PlantUML/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/milo-minderbinder%2FAWS-PlantUML/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/milo-minderbinder%2FAWS-PlantUML/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/milo-minderbinder","download_url":"https://codeload.github.com/milo-minderbinder/AWS-PlantUML/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247097662,"owners_count":20883122,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aws","diagram","graphviz","plantuml","uml"],"created_at":"2024-08-01T13:02:00.110Z","updated_at":"2025-04-03T23:30:59.700Z","avatar_url":"https://github.com/milo-minderbinder.png","language":"Python","funding_links":[],"categories":["Python","Documentation"],"sub_categories":[],"readme":"# AWS-PlantUML\nPlantUML sprites, macros, stereotypes, and other goodies for creating PlantUML diagrams with AWS components.\n\nAWS-PlantUML has high-quality sprites and convenient macros for AWS components and services for all of the AWS icons in the [AWS Simple Icons](https://aws.amazon.com/architecture/icons/) package, so that you can quickly and easily add stylized AWS elements to your PlantUML deployment diagrams.\n\n## Getting Started\nAt 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.\n\nIf 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:\n\n    !include path/to/common.puml\n\nOtherwise, you can link directly to the file in this repo with:\n\n    !includeurl https://raw.githubusercontent.com/milo-minderbinder/AWS-PlantUML/release/18-2-22/dist/common.puml\n\nAfter 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.\n\n    !define AWSPUML https://raw.githubusercontent.com/milo-minderbinder/AWS-PlantUML/release/18-2-22/dist\n    !includeurl AWSPUML/common.puml\n    !includeurl AWSPUML/Storage/AmazonS3/AmazonS3.puml\n    !includeurl AWSPUML/Storage/AmazonS3/bucket/bucket.puml\n    \nMacro definitions for components, like S3 and S3 Buckets, will take an alias as the first parameter, and a label as an optional second parameter:\n\n    AMAZONS3(s3_internal)\n    AMAZONS3(s3_partner,\"Vendor's S3\")\n    s3_internal \u003c-- s3_partner\n\n![simple example](examples/simple-s3.png)\n\nStarting 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:\n\n    ...\u003cSNIP\u003e...\n    !includeurl AWSPUML/Storage/AmazonS3/AmazonS3_LARGE.puml\n\n    skinparam nodeBackgroundColor White\n    skinparam storage\u003c\u003c**AmazonS3**\u003e\u003e {\n        backgroundColor #F9DFDC\n    }\n    AMAZONS3(s3_internal,\"Default S3\")\n    AMAZONS3(s3_internal2,\"S3 as node\",node)\n    AMAZONS3_LARGE(s3_partner,\"Large S3\")\n\n    s3_internal2 \u003c-r- s3_partner\n    s3_internal \u003c-l- s3_partner\n\n![customization example](examples/component-customization.png)\n\nYou can also nest components inside others using enclosures:\n\n    AMAZONS3(s3) {\n        BUCKET(site,www.insecurity.co)\n        BUCKET(logs,logs.insecurity.co)\n    }\n    site .r.\u003e logs : events\n\n![nesting example](examples/nested-components.png)\n\nBefore you know it, you'll be creating nice, clean diagrams for your AWS applications:\n\n    @startuml\n    !define AWSPUML https://raw.githubusercontent.com/milo-minderbinder/AWS-PlantUML/release/18-2-22/dist\n\n    !includeurl AWSPUML/common.puml\n    !includeurl AWSPUML/ApplicationServices/AmazonAPIGateway/AmazonAPIGateway.puml\n    !includeurl AWSPUML/Compute/AWSLambda/AWSLambda.puml\n    !includeurl AWSPUML/Compute/AWSLambda/LambdaFunction/LambdaFunction.puml\n    !includeurl AWSPUML/Database/AmazonDynamoDB/AmazonDynamoDB.puml\n    !includeurl AWSPUML/Database/AmazonDynamoDB/table/table.puml\n    !includeurl AWSPUML/General/AWScloud/AWScloud.puml\n    !includeurl AWSPUML/General/client/client.puml\n    !includeurl AWSPUML/General/user/user.puml\n    !includeurl AWSPUML/SDKs/JavaScript/JavaScript.puml\n    !includeurl AWSPUML/Storage/AmazonS3/AmazonS3.puml\n    !includeurl AWSPUML/Storage/AmazonS3/bucket/bucket.puml\n\n\n    skinparam componentArrowColor Black\n    skinparam componentBackgroundColor White\n    skinparam nodeBackgroundColor White\n    skinparam agentBackgroundColor White\n    skinparam artifactBackgroundColor White\n\n\n    USER(user)\n    CLIENT(browser)\n    JAVASCRIPT(js,SDK)\n\n    AWSCLOUD(aws) {\n\n        AMAZONS3(s3) {\n            BUCKET(site,www.insecurity.co)\n            BUCKET(logs,logs.insecurity.co)\n        }\n\n        AMAZONAPIGATEWAY(api)\n\n        AWSLAMBDA(lambda) {\n            LAMBDAFUNCTION(addComments,addComments)\n        }\n\n        AMAZONDYNAMODB(dynamo) {\n            TABLE(comments,Comments)\n        }\n    }\n\n    user - browser\n\n    browser -d-\u003e site :**1a**) get\\nstatic\\ncontent\n    site ~\u003e logs :1a\n    site .u.\u003e browser :**1b**\n    browser - js\n    js -r-\u003e comments :**2a**) get\\ncomments\n    comments ..\u003e js :**2b**\n\n    js -r-\u003e api :**3**) add\\ncomment\n\n    api -d-\u003e addComments :**4**\n\n    addComments -\u003e comments :**5**\n\n    comments ..\u003e js :**6**) new\\ncomments\n    @enduml\n\n\n![full example](examples/comments-architecture.png)\n\n\n## Customized Builds\nFor 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:\n\n    1. Download the [AWS Simple Icons set](https://aws.amazon.com/architecture/icons/) and extract them into a directory well refer to as `\u003cICONS_DIR\u003e`\n    2. Configure and/or add styles to the `puml.ini` configuration file, or create your own\n    3. Run the `puml.py` script against your downloaded `\u003cICONS_DIR\u003e` using your custom config\n\n#### 1. Download\nIf 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](https://www.python.org/downloads/release/python-360/).\n\nDownload the AWS Simple Icon set [here](https://aws.amazon.com/architecture/icons/) and extract the contents to a directory we'll refer to as `\u003cICONS_DIR\u003e`. This release was generated from version 17.10.18 of the AWS Simple Icons set release by Amazon.\n\n#### 2. Configure\nUsing 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:\u003cCOLOR_NAME\u003e` in a configuration option value, where \"`\u003cCOLOR_NAME\u003e`\" would be replaced by the desired option in the `[PUML.colors]` section.\n\nThe remaining sections designate generation options for the folders created from the icons in `\u003cICONS_DIR\u003e`. 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:\n\n    \u003cCATEGORY\u003e_\u003cSERVICE_NAME\u003e[_\u003cSERVICE_COMPONENT\u003e][_LARGE].\u003cFILE_EXTENSION\u003e\n\nOptions in the `awspuml.ini` can be set for an entire category\n\n    [InternetOfThings]\n    entity_type: artifact\n\nor for all subsections of a category\n\n    [InternetOfThings.AWSIoT.]\n    entity_type: component\n\nor just for a specific item in a category\n\n    [InternetOfThings.AWSIoT.action]\n    entity_type: usecase\n\nValid options are:\n\n    * `entity_type` - sets the PlantUML representation for the matching AWS-PlantUML components. Examples include `artifact`, `component`, `cloud`, etc.\n    * `color` - sets the foreground color for the matched entity's sprite\n    * `skinparam` - sets custom skinparam options for the stereotype generated for corresponding entities. An example value for this option would be `BackgroundColor Red`.\n\n#### 3. Run\nAfter configuring, simply run the `puml.py` module from the command line using Python 3, passing the configuration file and the `\u003cICONS_DIR\u003e` as command line options. If you need help, just call the script with the `-h` flag to print usage help to stdout:\n\n    \u003e python3 puml.py -h\n    usage: puml.py [-h] [-c CONFIG] [-g] [-o OUTPUT] icons_path\n\n    Generate PlantUML sprites and macros from images\n\n    positional arguments:\n      icons_path            Path to image icons directory\n\n    optional arguments:\n      -h, --help            show this help message and exit\n      -c CONFIG, --config CONFIG\n                            Config file for puml generation (default:\n                            /home/milo/AWS-PlantUML/puml.ini)\n      -g, --generate_config\n                            Write all sections to the INI file specified by the -c\n                            switch; if an INI file already exists, its sections\n                            and options will be preserved, but missing sections\n                            will be added and invalid sections will be deleted.\n                            (default: False)\n      -o OUTPUT, --output OUTPUT\n                            Output path for generated .puml files (default:\n                            /home/milo/AWS-PlantUML/dist)\n\nEnjoy!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmilo-minderbinder%2FAWS-PlantUML","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmilo-minderbinder%2FAWS-PlantUML","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmilo-minderbinder%2FAWS-PlantUML/lists"}