Getting started

Welcome to multicloud-diagrams 👋 This section will walk you through the basic installation process and provide a quick example to get you started. If you’re looking for more advanced features and customization options, be sure to explore the subsequent sections in our comprehensive documentation.

Dependency details
On-line Documentation is Dynamic and generated from Tests
Installation
Usage
Open drawio editor and position nodes manually
Reuse coordinates from previous diagram version
Arrange Layout automatic positioning

Dependency details

python-3.11

python-3.10

python-3.9

python-3.8

python-3.7

The multicloud-diagrams package is a Python library that provides support for major Python versions, including 3.7, 3.8, 3.9, 3.10, and 3.11. The package ensures compatibility with these Python versions by running tests using a Git workflow. These tests are designed to verify that the library functions as expected across each mentioned Python version.

Compatibility tests are included for latest LTS Python versions that have Security Support.

Release	Released	Security Support	Latest
3.11	24 Oct 2022	24 Oct 2027	3.11.4
3.10	04 Oct 2021	04 Oct 2026	3.10.12
3.9	05 Oct 2020	05 Oct 2025	3.9.1
3.8	14 Oct 2019	14 Oct 2024	3.8.17
3.7	26 Jun 2018	27 Jun 2023	3.7.17

You can use multicloud-diagrams with Python versions <3.7 that do not have official Security Support with your own verification.
Since 27 Jun 2023 Python 3.7 has no security support, multicloud-diagrams are still support this version (pipeline with full features compatibility check), however on next Python LTS releases it will be deprecated. This evolution will enable us to seamlessly embrace the latest language features not accessible in the 3.7 release.

The package is readily accessible on PyPI: https://pypi.org/project/multicloud-diagrams/ for easy installation and usage. As an open-source project, it encourages community participation and welcomes contributions from developers https://github.com/tsypuk/multicloud-diagrams Whether you want to use the package’s functionalities or contribute to its improvement, it offers a user-friendly experience, backed by an active and engaged community.

On-line Documentation is Dynamic and generated from Tests

All the resources within this documentation, including code snippets, rendered images, and XML dumps, are compiled and generated through tests conducted during the publishing process.
This comprehensive testing not only ensures verification but also guarantees that the provided examples remain current, up-to-date, aligning seamlessly with the latest API updates and method signatures.
Furthermore, the rendering process showcases authentic images, presenting an accurate desired output.

Installation

You can install multicloud-diagrams using pip, the package manager for Python:

pip install multicloud-diagrams

If you are using poetry follow these instructions:

poetry add multicloud-diagrams

Edit your project.toml and add multicloud-diagrams as dependency:

[ tool.poetry.dependencies ]
  python = "^3.7"
  pyyaml = "^6.0"
  multicloud-diagrams = ^"0.3.41"

Usage

The minimum configuration requires importing MultiCloudDiagrams, adding vertices, connecting them with links and exporting to output file.

Let’s add 2 vertices IAM Role and Lambda function:

# given
# Create a new cloud diagram
mcd = MultiCloudDiagrams()

# when
func_arn = 'arn:aws:lambda:eu-west-1:123456789012:function:prod-lambda-name'
mcd.add_vertex(node_id=func_arn, node_name='prod-lambda-name', node_type='lambda_function')

role_arn = 'arn:aws:iam::123456789012:role/prod-lambda-name'
mcd.add_vertex(node_id=role_arn, node_name='role-lambda-name', node_type='iam_role')
mcd.add_link(src_node_id=f'lambda_function:{func_arn}', dst_node_id=f'iam_role:{role_arn}')

mcd.export_to_file('/tmp/diagram.drawio')

Open drawio editor and position nodes manually

Considering that we haven’t specified the coordinates or distribution algorithm yet (which will be detailed in the next instructions), by default, all elements will be placed in the left-top corner. We have the flexibility to move and position them according to our preferences.

IAM add Role and Lambda

Reuse coordinates from previous diagram version

New (v0.2.1)

When we provide the path to an existing drawio file, the current context framework will read the coordinates of all vertices from the previous diagram and reuse them. As a result, any new elements will be added to the top-left corner by default, while existing elements will retain their original coordinates. If certain vertices were removed from the framework, they will not be present in the resulting drawio file.

Now, we are adding 2 more vertices IAM Permissions to see how it works.

# given
# Create a new cloud diagram
mcd = MultiCloudDiagrams()

# when
output_file = '/tmp/diagram.drawio'
mcd.read_coords_from_file(output_file)

func_arn = 'arn:aws:lambda:eu-west-1:123456789012:function:prod-lambda-name'
mcd.add_vertex(node_id=func_arn, node_name='prod-lambda-name', node_type='lambda_function')

role_arn = 'arn:aws:iam::123456789012:role/prod-lambda-name'
mcd.add_vertex(node_id=role_arn, node_name='role-lambda-name', node_type='iam_role')

cw_policy_arn = "arn:aws:iam::123456789012:policy/prod-cloudwatch-policy"
mcd.add_vertex(node_id=cw_policy_arn, node_name='prod-cloudwatch-policy', node_type='iam_policy')

s3_policy_arn = "arn:aws:iam::123456789012:policy/prod-s3-policy"
mcd.add_vertex(node_id=s3_policy_arn, node_name='prod-s3-policy', node_type='iam_policy')

mcd.add_link(src_node_id=f'lambda_function:{func_arn}', dst_node_id=f'iam_role:{role_arn}')
mcd.add_link(f'iam_role:{role_arn}', f'iam_policy:{cw_policy_arn}')
mcd.add_link(f'iam_role:{role_arn}', f'iam_policy:{s3_policy_arn}')

# We can write to same Diagram
mcd.export_to_file(output_file)

# Or write to a new Diagram version
mcd.export_to_file('/tmp/diagram_v2.drawio')

This approach allows for efficient placement of new elements while preserving the layout of existing ones based on the previous diagram’s coordinates.

IAM add Permissions

By leveraging this feature, we can implement versioning effectively by consistently reading coordinates from the previous file, which includes a timestamp (e.g., datetime in the file name). Subsequently, we write the updated elements to a new file. This functionality proves invaluable for tracking historical records and facilitating a comprehensive comparison of infrastructure evolution over time.

Arrange Layout automatic positioning