diagrams-yaml 0.0.18

Diagrams as code: declarative configurations using YAML for drawing cloud system architectures.

Table of content:

• Introduction
• Roadmap
• Getting Started
  • How to Install
  • Examples
  • Syntax Highlighting
    • PyCharm
• Usage
  • Command Line Interface
• Disclaimer

Introduction

Diagrams as code is essentially the process of managing diagrams through code rather than interactively drawing them on specific web services such as draw.io. It lets you generate the cloud system architecture in a declarative way with widely used YAML syntax (which is de facto a standard for infrastructure and configurations).

Declarative method of describing things means that a user simply describes the solution they need, how it should look, and everything that would be in the state of the final solution, leaving the process for the software to decide.

Diagrams as code brings you the following benefits comparing to drawing architecture on your own, it:

• Does not require any knowledge about how to properly draw an architecture diagram. Basically, you just define a set of resources, compose them into groups and set relationships, the rest is done for you.
• Allows you to track an architecture diagram changes with a version control systems such as Git.
• Moves collaboration to the next level: updating an architecture diagram through a pull request with a code review instead of a video session and/or screen sharing.
• Reduces costs on further updating of an initial architecture diagram. Basically, when you create an image on a web service you have to eventually store two files: PNG-like to put into your documentation and XML to be able to adjust your image in the future. So, there is no need to care about XML anymore.
• Backups you in case of losing XML files as YAML files are always stored in a repository.
• Improves consistency as now a diagram is stored along the code in a repository, the place you visit and work on frequently, and it is easier to keep it up-to-date.

Currently, the following components are provided:

• Major cloud providers: AWS, Azure, GCP, IBM, Alibaba, Oracle, OpenStack, DigitalOcean and so on.
• On-Premise, Kubernetes, Firebase, Elastic, SaaS.
• Programming languages and frameworks.

Roadmap

• Add support of C4.
• Add support of Custom.
• Add IDEs plugins and/or web user interface for live editing.
• Research Confluence integration to update images from the CI-builds directly.
• Research ChatGRT integration.

Getting Started

How to install

As the project uses Graphviz to render the diagram, you need to install it:

• For Linux — https://graphviz.gitlab.io/download/#linux
• For Windows — https://graphviz.gitlab.io/download/#windows
• For macOS — https://graphviz.gitlab.io/download/#mac

After, you can install the project itself with the following command using pip3:

$ pip3 install diagrams-yaml

Examples

You can find examples of YAML configurations in the examples folder. Below are placed are few of them (click on the name to redirect to the configurations file).

Web Services on AWS	Web Services On-Premise	Exposed Pods on Kubernetes

Message Collecting on GCP	Events Processing on AWS	Workers on AWS

Syntax Highlighting

When you will be writing your own YAML files, you likely need a syntax highlighting. Currently, there is no mapping of the YAML files to a specific schema to enable the syntax highlighting automatically. So, there is a need for manual operation here.

PyCharm

For PyCharm, open the settings and proceed to Languages & Framworks, then to Scheams and DTDs, then to JSON Schema Mappings. After, create a new schema, name it Diagrams as code, choose JSON Schema version 7, paste https://raw.githubusercontent.com/dmytrostriletskyi/diagrams-yaml/main/json-schemas/0.0.1.json to the Schema file or URL field and click Apply:

Right after then, open a YAML file and click on No JSON schema at to bottom-right corner:

It will open a panel where you can choose the newly created schema with name Diagrams as code:

As the result, you will experience the syntax highlighting when typing:

Usage

Command Line Interface

To draw an architecture, call diagrams-yaml command line interface, providing a path to a YAML file with configurations. The drawing will be saved in the folder the command line interface was executed from.

$ diagrams-yaml examples/web-services-aws.yaml

Disclaimer

diagrams-yaml is a wrapper around original diagrams. The original diagrams lets you draw the cloud system architecture in Python code. It was born for prototyping a new system architecture design without any design tools. Under the hood, diagrams-yaml parse a YAML file and map to specific set of diagrams's functions and classes, and executes them in proper order.

But you don't have to worry about diagrams because diagrams-yaml is self-contained and encapsulates it well.