Documentation as Code- Reverse Diagram - Creating a diagram from AWS setup
Tags: devops, devsecops, aws, opensource
Published: 2022-12-28 13:52:07

**Table of Contents**  

- [Hands On](#hands-on)
  - [Requirements](#requirements)
  - [AWS Services](#aws-services)
  - [Solution Overview](#solution-overview)
  - [Step by Step](#step-by-step)


**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](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/v41rq96ipossx516ywmr.png)
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

- [AWS IAM Identity Center (Successor to AWS Single Sign-On)](https://aws.amazon.com/iam/identity-center/?nc2=h_ql_prod_se_sso): helps you securely create or connect your workforce identities and manage their access centrally across AWS accounts and applications.
- [AWS Organizations](https://aws.amazon.com/organizations/?nc2=h_ql_prod_mg_org): an account management service that enables you to consolidate multiple AWS accounts into an organization that you create and centrally manage.

## Solution Overview

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

</center>

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. 

{% embed https://github.com/velez94/reverse_diagrams %}

> This is my first open source project.

The following are the available options


```commandline
$ 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

```

Now run for your organization setup: 

```commandline
$ 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 

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

```commandline
$ ls
graph_org.py
```

```python

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
...
```

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.

```commandline
$ ls
graph_org.py organizations-state.png
```

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



![Continuous Documentation- Results](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/esguniv70gmoh9gusqbh.png)
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!