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

Table of Contents

• Hands On
  • Requirements
  • AWS Services
  • Solution Overview
  • 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.

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): helps you securely create or connect your workforce identities and manage their access centrally across AWS accounts and applications.
• AWS Organizations: an account management service that enables you to consolidate multiple AWS accounts into an organization that you create and centrally manage.

Solution Overview

 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.

velez94 / reverse_diagrams

Reverse diagrams for cloud auditories and documentation as code.

Table of Contents

• Reverse Diagrams
• Requirement
• Install
• Use
  • Subcommands
    • watch
• Service supported
  • AWS Organizations
  • Identity and Access Manager Center (SSO)
• Additional Commands
  • watch
    • Options
    • Combine the options
  • Extras
    • Enable autocomplete

Reverse Diagrams

Continuous Documentation Tool - Documentation as Code Tool

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

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

…

View on GitHub

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

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 

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

$ ls
graph_org.py

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.

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

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!

Comments

[Monica Colangelo]

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

[Alejandro Velez]

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