DEV Community

Cover image for Documentation as Code- Reverse Diagram - Creating a diagram from AWS setup
Alejandro Velez for AWS Community Builders

Posted on • Updated on

Documentation as Code- Reverse Diagram - Creating a diagram from AWS setup

Table of Contents

Level 200

Usually, we need to create reference architectures, documents and maintain long papers about the configurations and current state of the architecture workloads for cloud and on-premises environments. As part of continuous collaboration practice you can create and find a document that somebody wrote for example in Atlassian, Google Docs, Sharepoint or Notion the hand-written architectural diagrams, API references, and other information written there are likely to be out of date when you find them. This is a great issue and limit the discoverability.

Discoverability is defined by how rapidly you can find information about a service, library, tool, team, or repository.

There are some practices to avoid this issue and unified and reliable information at scale through automation. First, adopt Documentation as Code from IaC abstractions, here tools as terraform graph, diagrams, terraform-docs, blast-radius, cdk-dia, rover, etc. Second, load diagrams from current state using tools as Lucid scale, cloudiscovery, reverse-diagrams, etc.

Continuous Documentation
Figure 1. Continuous Documentation

Providing automated Discoverability has become a significant enabler for improved collaboration at the organizations investing in developing an Inner Source culture.

In this blog you can find an example of second approach use a tool for take snapshots from your current setup in AWS environment.

Hands On

Requirements

  • AWS CLI >= 2.7.0
  • Python >= 3.10.4
  • reverse-diagrams >= 0.1.6
  • diagrams >= 0.22.0
  • boto3 >= 1.26.4

AWS Services

Solution Overview

![Continuous Documentation - Solution Overview](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/b28gta2r3rdm2nzkt9xg.png) Figure 2. Continuous Documentation - Solution Overview

The Figure 2 depicts an overview of the elements for this demonstration, basically use boto3 for getting information about the actual state and configuration of the services and diagrams library for convert this information to python file and png file.

Cloudiscovery helps you to analyze resources in your AWS account but not support Organizations nether Identity Center yet.

Step by Step

You must have a aws cli profile with read only access to your organizations manager account.

First install the reverse_diagrams package.

You can find the code here.

GitHub logo velez94 / reverse_diagrams

Reverse diagrams for cloud auditories and documentation as code.

Table of Contents

Reverse Diagrams

Continuous Documentation Tool - Documentation as Code Tool

This package create diagrams and help to audit your services from your shell.

Complete demo

Requirement

AWS programmatic access using AWS CLI. Configuring the AWS CLI

Install

pip install reverse-diagrams

Use

The following are the available options

$ reverse_diagrams  -h
usage: reverse_diagrams [-h] [-p PROFILE] [-od OUTPUT_DIR_PATH] [-r REGION] [-o] [-i] [-a] [-v] [-d] {watch}
Create architecture diagram, inspect and audit your AWS services from your current state.

options:
  -h, --help            show this help message and exit
  -p PROFILE, --profile PROFILE
                        AWS cli profile for AWS Apis
  -od OUTPUT_DIR_PATH, --output_dir_path OUTPUT_DIR_PATH
                        Name of folder to save the diagrams python code files
  -r REGION, --region REGION
                        AWS region
  -o, --graph_organization
                        Set if
…

This is my first open source project.

The following are the available options

$ reverse_diagrams -h 

usage: reverse_diagrams [-h] [-c CLOUD] [-p PROFILE] [-o] [-i] [-v]

options:
  -h, --help            show this help message and exit
  -c CLOUD, --cloud CLOUD
                        Cloud Provider, aws, gcp, azure
  -p PROFILE, --profile PROFILE
                        AWS cli profile for Access Analyzer Api
  -o, --graph_organization
                        Set if you want to create graph for your organization
  -i, --graph_identity  Set if you want to create graph for your IAM Center
  -v, --version         Show version

Enter fullscreen mode Exit fullscreen mode

Now run for your organization setup:

$ reverse_diagrams -c aws -p my-profile -o
Date: 2022-12-17 22:33:21.791819
πŸ”„ Getting Organization Info
πŸ”„ The Organizational Units list 
πŸ”„ Getting the Account list info
Run -> python3 graph_org.py 

Enter fullscreen mode Exit fullscreen mode

Now, you can find the diagrams code in .py files. For example for graph_org.py

$ ls
graph_org.py
Enter fullscreen mode Exit fullscreen mode

from diagrams import Diagram, Cluster

from diagrams.aws.management import Organizations, OrganizationsAccount, OrganizationsOrganizationalUnit
from diagrams.aws.general import Users, User

with Diagram("Organizations-State", show=False, direction="TB"):
    ou = OrganizationsOrganizationalUnit("OU")
    oa = OrganizationsAccount("Account")

    with Cluster('Organizations'):

        oo = Organizations('o-9tlhkjyoxx\n012345678901\nr-w3xx')

        ou_Sandbox= OrganizationsOrganizationalUnit("ou-w3ow-1sumtdxx\nSandbox")

        oo>> ou_Sandbox
...
Enter fullscreen mode Exit fullscreen mode

Finally, run python3 graph_org.py to create a png screenshot (organizations-state.png) for your current state.

Both files are saved into the current directory.

$ ls
graph_org.py organizations-state.png
Enter fullscreen mode Exit fullscreen mode

The Figure 3 shows the different diagrams, one creating in planning stage and other in the operating stage.

Continuous Documentation- Results
Figure 3. Continuous Documentation - Results

Use the option -i for getting a state of your AWS IAM Identity Center state.

Thanks for reading and sharing!

Top comments (2)

Collapse
 
monica_colangelo profile image
Monica Colangelo

This is nice! I'll give it a try. Thanks for sharing!

Collapse
 
avelez profile image
Alejandro Velez

Sure, IΒ΄m working in more services for the next version! Thanks for reading and support!