You can utilize Amazon Q Developer in the CLI to create your AWS Diagram from your Terraform code.

This is how I made my first Diagrams with Code with the help of Amazon Q.

Just a quick note: This is not a “AI can create everything for me and I don’t need to know anything” blog. I used AI to help me create some diagrams and it was so convenient that I wanted to share the process.

The problem

The last part I always have to do after creating a Terraform module for AWS is to spend some time in draw.io to create a diagram of the AWS resources and their connections within the module for the documentation. Later, when I have to make a change to the module, I need to find the source document for the diagram to be able to update it. And this is not a good way to keep the documentation in the code.

I have read about Diagram as Code, but never looked into it. But during a drive to update the documentation of all my Terraform modules, I decided to look into it to see if it could help me not just quicken up the work but also make it more available and easier to update.

Since I often use Python, I decided to look into Diagrams ( https://diagrams.mingrammer.com) and was impressed by how easily the code was to understand. Started writing diagrams for my Terraform modules, and it worked well.

But as always, I wondered if I could speed it up some more with help from AI.

So I went to my “trusty” Sidekick ChatGPT to ask it to create the code for me (to be honest, it is not as trusty anymore). I explained the module and the resources in it, and it created the code for me. And when I ran the code, it failed with an import error (every Node (resource) you want to use in your diagram needs to be imported). Went back to ChatGPT with the error and got new code. And it failed again. After doing this back and forth a couple of times, my patience was spent.

But then I remembered that I had started testing Amazon Q Developer in my CLI and wondered if it would be a better option. And that is what this blog post is about.

Setting up the environment

First, let's install the programs and set up the environment. My guides will be for Mac.

Amazon Developer Q

You will need an AWS Builder ID (or IAM Identity Center user) to use Amazon Developer Q. The Builder ID is free. To create one, follow AWS instructions.

Follow AWS instructions to install Amazon Q Developer and give it access to the CLI.

Environment and Diagrams

Create a folder for your code and diagrams.

mkdir terraform_diagrams
cd terraform_diagrams

I suggest setting up a virtual environment with venv before installing dependencies.

python3 -m venv virtual_env
source virtual_env/bin/activate

Then we will install Diagrams and its dependencies. Diagrams require Graphviz to render the diagrams.

brew install graphviz

Then we will install Diagrams.

pip install diagrams

Now we are ready to create some diagrams. I would suggest reading the official documentation for Diagrams so you are avare on how it works since it will help with your understanding of the code.

Amazon Q Developer creates diagrams

This time, I started Q on the CLI and asked it to review a Terraform module and create the code for the diagram for me.

My prompt was: Can you check this Terraform module ${Path To Module} and create the code for me to create a AWS Diagram with Python diagrams package.

Q then started reading the files in the module and the README.md file to understand what the module was used for and how it worked.

Then it checked if Diagrams was installed and stated it would install it otherwise (not sure if it would try to install it, but I wouldn't suggest allowing AI to install packages on your computer). Since it was installed, it continued creating the code and running it to create the diagrams.

You will get prompted for allowing Q to do actions and I would suggest not allowing all actions being run without reviewing them. It will take some more time but give you more control.

And Q got the same import errors as ChatGPT got (importing the SNS node). But here is where I really got impressed with Q. It tried to fix the issues with the imports twice and failed both times. It then decided to check the Diagrams package for the available modules for AWS.

> Let's check the available modules in the diagrams package
> find virtual_env/lib/python3.12/site-packages/diagrams/aws -name "*.py" | grep -v "__" | sort

It then checked through all the modules and their classes, looking for the SNS nodes class, and found it in the integration module.

> Let's check the available classes in the engagement module
> grep -A 50 "class" virtual_env/lib/python3.12/site-packages/diagrams/aws/engagement.py
....
> Let's check the integration module for SNS
> grep -A 50 "class" virtual_env/lib/python3.12/site-packages/diagrams/aws/integration.py
....
> Great! Now I can see that SNS is in the integration module. Let's update our script

It then updated the code and tried to run it again. Now getting new errors as other imports were wrong. It then went through the modules again and found the correct node classes and updated the code until it worked.

It then ran the final code and created a diagram for my Terraform module, which creates an S3 bucket and DynamoDB to use as a Terraform backend.

Was the diagram perfect? No. But was it a great start. And if you then ask Q to fix the issues you have with the diagram, or you do it yourself, you can get it to the point where you want to add it to your documentation.

The diagram

Here is the diagram that Q created for me.

The code

Here is the code that Q created for this Diagram. Note that it imports classes that are not used. So not perfect but good enough.

from diagrams import Diagram, Cluster, Edge
from diagrams.aws.storage import S3
from diagrams.aws.database import DynamodbTable
from diagrams.aws.management import Config
from diagrams.aws.devtools import Codebuild
from diagrams.aws.compute import Lambda
from diagrams.onprem.client import User

# Create the diagram
with Diagram("AWS S3 Backend for Terraform State", show=True, direction="TB"):

    # Terraform users/clients
    with Cluster("Terraform Clients"):
        terraform_users = [\
            User("Developer 1"),\
            User("Developer 2"),\
            User("CI/CD Pipeline"),\
        ]

    # Terraform state management
    with Cluster("Terraform State Management"):
        terraform = Config("Terraform")

    # S3 Backend components
    with Cluster("S3 Backend Infrastructure"):
        # S3 bucket with versioning
        s3_bucket = S3("State Bucket\nwith Versioning")

        # DynamoDB for state locking
        dynamodb = DynamodbTable("DynamoDB\nState Lock Table")

    # Connect components
    for user in terraform_users:
        user >> Edge(label="terraform apply") >> terraform

    terraform >> Edge(label="read/write state") >> s3_bucket
    terraform >> Edge(label="acquire/release lock") >> dynamodb

Final thoughts

I was quite amazed that Q looked through the actual package for the classes we needed and found them. It worked much better than I predicted, and I didn't have to do the regular AI back-and-forth dance.

But don't just let the Q create the diagrams for you, learn the code as well, so you can polish the code for the diagram after Q creates the initial version.

Final note when using Amazon Q in the CLI. Remember to commit your changes between runs, as it can overwrite the files it’s working on, and you may lose some working code for broken code if you are not careful. But you can use Amazon Q to commit the files for you.