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.
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
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
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 ifThis 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!
Top comments (2)
This is nice! I'll give it a try. Thanks for sharing!
Sure, I´m working in more services for the next version! Thanks for reading and support!