Introduction
"Diagrams as Code" is an innovative approach to designing cloud system architectures using code instead of manually drawing them on platforms like draw.io. By utilizing YAML, a popular configuration and infrastructure language, users can create architectural diagrams declaratively. This means that instead of detailing each step, you simply outline what you need, and the system takes care of the rest.
This method offers several advantages over traditional manual diagramming. Users don't need prior knowledge of diagramming techniques; they define resources, group them, and set relationships — the software does the heavy lifting. Version control integration with systems like Git allows easy tracking of changes, enhancing collaboration through pull requests and code reviews instead of video calls or screen sharing. Updating diagrams is more cost-effective since there's no need for both PNG-type images and XML files; instead, everything is stored in version-controlled YAML files, ensuring consistency and reliability.
Supported components include major cloud providers (AWS, Azure, GCP, etc.), on-premise solutions, Kubernetes, and more.
Roadmap
The project's future plans include adding support for C4 model diagrams, custom nodes, IDE plugins, and web interfaces for live editing. Additionally, there are aspirations to integrate JSON Schema, explore Confluence, and ChatGPT integrations.
Getting Started
How to Install
To start using "Diagrams as Code," you need to install Graphviz, as it is essential for rendering diagrams. Here are specific instructions based on your operating system:
- Linux: Install Graphviz for Linux
- Windows: Install Graphviz for Windows
- macOS: Install Graphviz for macOS
Once Graphviz is installed, you can get "Diagrams as Code" through pip:
$ pip3 install diagrams-as-code
Examples
Visit the examples folder on the project's GitHub page to explore a variety of YAML configuration samples for different architectures.
Syntax Highlighting
For enhanced editing, syntax highlighting can be set up in IDEs like PyCharm and VSCode, helping you write and manage YAML files more effectively.
PyCharm
To enable syntax highlighting in PyCharm, navigate to Languages & Frameworks, then Schemas and DTDs, and create a new schema pointing to the correct JSON schema version.
VS Code
In VS Code, install the RedHat YAML extension and add a line to your YAML files to enable syntax highlighting.
Usage
Command Line Interface
Use the command line interface of "Diagrams as Code" by providing the path to your YAML configuration file:
$ diagrams-as-code examples/web-services-aws.yaml
This command generates and saves the diagram based on the configurations provided.
Guide
Refer to all-fields.yaml for a comprehensive example of configurations. The YAML files consist of generic settings like diagram name, file format, and layout, as well as resources and their relationships. Resources can be cloud services or elements like AWS and Kubernetes.
- Resources: Define individual components within your architecture.
- Groups: Aggregate multiple resources or other groups for collective identification.
- Clusters: Logical separation of multiple resource types, such as APIs, databases, or caches.
Disclaimer
"Diagrams as Code" is built upon the original diagrams project, which allows cloud architecture design using Python. While the original project serves for prototyping, "Diagrams as Code" enhances usability by providing a YAML interface to map and execute the necessary functions seamlessly, putting the power of diagramming into a more approachable and collaborative format.