awslabs / diagram-as-code

Diagram-as-code for AWS architecture.

Diagram-as-code

This command line interface (CLI) tool enables drawing infrastructure diagrams for Amazon Web Services through YAML code. It facilitates diagram-as-code without relying on image libraries.

The CLI tool promotes code reuse, testing, integration, and automating the diagramming process. It allows managing diagrams with Git by writing human-readable YAML.

(generated from the example of PrivateLink)

Getting started

for Gopher (go 1.21 or higher)

$ go install github.com/awslabs/diagram-as-code/cmd/awsdac@latest

for macOS user

In preparing.

Usage

awsdac <input filename> [flags]

Flags:
      --cfn-template    [beta] Create diagram from CloudFormation template
  -h, --help            help for awsdac
  -o, --output string   Output file name (default "output.png")
  -v, --verbose         Enable verbose logging
      --yaml            [beta] Generate YAML file from CloudFormation template

Example

$ awsdac examples/alb-ec2.yaml

$ awsdac privatelink.yaml -o custom-output.png

Example templates are here.

[Beta] Create a diagram from CloudFormation template

--cfn-template option allows you to generate diagrams from CloudFormation templates, providing a visual representation of the resources. The tool can generate diagrams even if the CloudFormation template is not in a perfect format, enabling you to visualize the resources before actually creating the CloudFormation stack. This means you don't have to strictly adhere to the CloudFormation syntax constraints.

NOTE: The functionality of generating diagrams from CloudFormation templates is currently in beta. It sometimes works correctly, but we are aware of several known issues where the tool might not produce accurate results. We are actively working on improving the tool and fixing these issues.

$ awsdac examples/vpc-subnet-ec2-cfn.yaml --cfn-template

(generated from the example of VPC,Subnet,EC2)

There are some patterns where the tool may not work as expected. You can find a list of known issues and their status on the issue tracker. Your feedback and issue reports are appreciated, as they will help enhance the tool's performance and accuracy.

Use "--yaml" option

$ awsdac examples/vpc-subnet-ec2-cfn.yaml --cfn-template --yaml

CloudFormation templates have various dependencies, and there is no simple parent-child relationship between resources. As a result, generating the desired diagram directly from the existing CloudFormation template formats can be challenging at this stage. We considered utilizing Metadata or comments within the CloudFormation templates to include additional information. However, this approach would make the templates excessively long, and CloudFormation templates are primarily intended for resource creation and management rather than diagram generation. Additionally, combining different lifecycle components into a single CloudFormation template could make it difficult to manage and maintain.

Therefore, instead of directly generating diagrams from CloudFormation templates, you can create a separate YAML file from CloudFormation template and customize this YAML file. This customized YAML file can then be used as input for awsdac to generate the desired architecture diagrams. By decoupling the diagram generation process from the CloudFormation template structure, this approach offers greater flexibility and customization while leveraging the specialized strengths of awsdac.

CloudFormation template --[awsdac]--> yaml template --[user custom]--> your desired diagram :)

Features

• Compliant with AWS architecture guidelines
  Easily generate diagrams that follow AWS diagram guidelines.
• Flexible
  Automatically adjust the position and size of groups.
• Lightweight & CI/CD-friendly
  Start quickly on a container; no dependency on headless browser or GUI.
• Integrate with your Infrastructure as Code
  Generate diagrams to align with your IaC code without managing diagrams manually.
• As a drawing library
  Use as Golang Library and integrate with other IaC tools, AI, or drawing GUI tools.
• Extensible
  Add definition files to create non-AWS diagrams as well.

Resource types

See doc/resource-types.md.

Resource Link

See doc/links.md.

Security

See CONTRIBUTING for more information.

License

This project is licensed under the Apache-2.0 License.

diagram-as-code's Issues

[REQ] Arrow heads for connection lines

The standard followed in diagrams published by AWS over the years, shows the connection lines with arrowheads. Is this something that will be potentially supported in the future? The arrowheads really add context and meaning to the diagrams by indicating the direction of the flow.

thanks!

[Feature Request] Add automatic .png extension to output filename

Request

Add automatic .png extension to output filename.
For example,

• If the user enters example as the filename, the tool should save the file as example.png.
• If the user enters example.png as the filename, the tool should keep the filename as is.

Background

Currently, when specifying a filename for the output file, if the .png extension is not included, the tool does not automatically append it. This can lead to confusion and errors, especially for users who are not familiar with file extensions.
To improve the user experience and prevent potential issues, it would be beneficial to implement a feature that automatically adds the .png extension to the output filename if it is not already present.

Create mappings for CloudFormation resource types

Need to create a correspondence between CloudFormation resource types and architecture icons' labels (preset names).
Currently, We are using this file to list the corresponding resource types.

workaround

You can also use resource types that are not currently defined by utilizing a preset with the same name as the icon label.

Diagram:
  DefinitionFiles:
    - Type: URL
      Url: "https://raw.githubusercontent.com/awslabs/diagram-as-code/main/definitions/definition-for-aws-icons-light.yaml"
  Resources:
    Canvas:
      Type: AWS::Diagram::Canvas
      Direction: vertical
      Children:
        - StepFunction
    StepFunction:
      Type: AWS::Diagram::Resource
      Preset: "AWS Step Functions"

You can check the preset name in the icon label of the pptx file or in the definition file.

Connection lines

Any plans to add connection lines between resources?

thanks!

[Feature Request] Allow optional control over vertical and horizontal display

Request

The current implementation defaults to horizontal, so only horizontal views are generated.

diagram-as-code/internal/types/group.go

Line 55 in 601056c

gr.direction = "horizontal"

It's better to be able to switch the display with an option.

Example

$ awsdac <input CloudFormation template> --cfn-template --vertical

Generate diagrams from CF templates

Would it be possible to generate diagrams from the templates?

Perhaps could use tags for things that CF does not support directly.

And then can use resource properties to infer some of the information for the diagrams (e.g. titles).

This would then be great for use with CDK, where resources can be defined and tagged in code, and then a template is generated and then a diagram is generated from that.

[Feature Request] Generate a diagram as a pptx file

Request

Currently, awsdac generates a diagram as a image file.
If you also get results in pptx format, you can manually rearrange the figures based on it.

Font path seems to have been hardcoded for Mac?

The code seems to do os.Open("/Library/Fonts/Arial Unicode.ttf"), which I think is only valid for a Mac

Overlapping group

Due to constraints in the drawing process, resources cannot support many-to-many dependencies between parents and children and support one-to-many, so it is not possible to draw Auto scaling groups that span groups such as the one below.

The dependencies in this architecture diagram are illustrated below.

Test and integrate with CI

• Add unit tests #43
• Add integration tests
• Automating tests with GitHub Actions

Deprecate AWS::Diagram::Group

Why

The main difference between groups and resources was whether they had children. However, I found that there are many icons that can be used as both groups and resources. (For example, AWS::ECS::Cluster etc.).

What

The difference between the group implementation and the resource implementation was not large, and similar implementations were wrapped in an interface. Since we found no concerns about migrating to the Resource type, we will abolish the Group type and adopt a method that changes the rendering method of the Resource type depending on the presence or absence of children.
This allows users to use CFn like types without worrying about group/resource differences.

Tasks

Beta Give feedback

1. 1. Migrate to AWS::Diagram::Resource
2. 2. Remove Node interface
3. 3. Deprecate AWS::Diagram::Group

Title string overflows image when Title is long

Issue

Expected

• The title string should be fully contained within the image boundaries.
• The title should wrap to a new line if it exceeds the image width to prevent horizontal overflow.

Add table resource

In architecture diagrams, tables are sometimes used to efficiently illustrate detailed information such as VPC route tables.

The content drawn may differ depending on the order of processing

Issue detail

For example, if there are multiple resources directly under the "AWS Cloud" resource, the results maybe obtained when executing the command will differ.

$ awsdac <input file name> --cfn-template

[Desired Outcome]

[Undesired Outcome]

Improve Readability of Execution and Debug Logs

Current Issues

Missing Debug Information

The current debug logs are missing some information, making it difficult to effectively debug and troubleshoot issues.

$ ./awsdac ../../examples/privatelink.yaml -o custom-output-test.png -v
...
INFO[0001]                                              
INFO[0001]                                              
INFO[0001] Link Drawing                                 
INFO[0001]                                              
INFO[0001]                                              
INFO[0001] Link Drawing                                 
INFO[0001]                                              
INFO[0001]                                              
INFO[0001] Save custom-output-test.png

Lack of Completion Messages

Currently, there are no clear completion messages displayed when a process or operation finishes. This makes it hard to determine whether the execution was successful or if there were any errors or failures.

$ ./awsdac ../../examples/privatelink.yaml -o custom-output-test.png 
$

Proposed Changes

Enhance Debug Logging

• Add [specific information] to the debug logs for better visibility and easier troubleshooting.
• Or delete blank messages for removing noise.

Implement Completion Messages

• Display a clear success message when a process or operation completes successfully.

Did not work on Windows

C:\Users\ugwis>awsdac -v vpc-natgw.yaml
time="2024-03-25T13:56:47+09:00" level=info msg="input file: vpc-natgw.yaml\n"
time="2024-03-25T13:56:47+09:00" level=info msg="Fetch definition file from URL: https://raw.githubusercontent.com/awslabs/diagram-as-code/main/definitions/definition-for-aws-icons-light.yaml\n"
time="2024-03-25T13:56:47+09:00" level=fatal msg="open C:\\Users\\ugwis\\.cache\\awsdac\\850960c5c172c277f880286d0349c39c-definition-for-aws-icons-light.yaml: The system cannot find the path specified."

Implement curves/dotted/arrows/orthogonal lines

Implement multiple types of connection lines.

• curves
• dotted
• arrows #27
• orthogonal

Improve definition file caching

Why

Currently, architecture icon and definition file caching is based on a hash of static values such as file names, and hash values do not change permanently, so changes to architecture icons and definition files are not reflected.
File caching is implemented as internal/cache.

What

• Use HTTP Etag caching for instant updates and reduce unnecessary data transfers.

Prevent circular references

why

There is no mechanism to detect circular references, so incorrect references will cause stack overflows.

$ cat rec.yaml               
Diagram:
  Resources:
    Canvas:
      Type: AWS::Diagram::Canvas
      Direction: vertical
      Children:
        - Resource1
    Resource1:
      Type: AWS::Diagram::Group
      Children:
        - Resource2
    Resource2:
      Type: AWS::Diagram::Group
      Children:
        - Resource1
$ awsdac rec.yaml -v
runtime: goroutine stack exceeds 1000000000-byte limit
runtime: sp=0xc0201e0390 stack=[0xc0201e0000, 0xc0401e0000]
fatal error: stack overflow

runtime stack:
runtime.throw({0xd4bf112?, 0x200000001?})
	/usr/local/Cellar/go/1.22.0/libexec/src/runtime/panic.go:1023 +0x5c fp=0x700009667d88 sp=0x700009667d58 pc=0xd23489c
runtime.newstack()
	/usr/local/Cellar/go/1.22.0/libexec/src/runtime/stack.go:1103 +0x5bd fp=0x700009667f38 sp=0x700009667d88 pc=0xd24fb5d
runtime.morestack()
	/usr/local/Cellar/go/1.22.0/libexec/src/runtime/asm_amd64.s:616 +0x7a fp=0x700009667f40 sp=0x700009667f38 pc=0xd2678fa

goroutine 1 gp=0xc000006380 m=4 mp=0xc000057b08 [running]:
runtime.convTstring({0x0?, 0x0?})
	/usr/local/Cellar/go/1.22.0/libexec/src/runtime/iface.go:388 +0x8c fp=0xc0201e03a0 sp=0xc0201e0398 pc=0xd20936c
github.com/awslabs/diagram-as-code/internal/types.(*Group).Scale(0xc0000ee500)

what

Detect and warn about circular resource references

Resource on the line of link and border

An architecture diagram may be drawn that places resources along links and boundaries. Examples: Internet gateways, VPN connections, etc.

On the line of link

On the line of border

Use the 16-wind rose to specify the location of the resource. See details of doc/links.md

Target resource is not drawn when related to resources in the same layer

Issue detail

Target resource is not drawn when related to resources in the same layer.

Reproduce process

Subnets are same layer in this template.
In this case, the ELB is a child resource of the two subnets, and then it is not rendered.

Yaml template

Resources:
  VPC1:
    Type: AWS::EC2::VPC
    Properties:
      CidrBlock: !Ref VPCCIDR    
      EnableDnsSupport: true
      EnableDnsHostnames: true
  Subnet1:
    Type: AWS::EC2::Subnet
    Properties:
      VpcId: !Ref VPC1
      MapPublicIpOnLaunch: false
  Subnet2:
    Type: AWS::EC2::Subnet
    Properties:
      VpcId: !Ref VPC1
      MapPublicIpOnLaunch: false
  NLB: 
    Type: AWS::ElasticLoadBalancingV2::LoadBalancer
    Properties: 
      Scheme: "internal"
      Subnets: 
        - !Ref Subnet1    ## <------- here
        - !Ref Subnet2    ## <------- here
      Type: network

Generate a yaml template (not CloudFormation template) for creating a diagram from CloudFormation template

Is your feature request related to a problem? Please describe.

Currently, awsdac creates a diagram from CloudFormation template without user customs.
Therefore, you cannot modify this diagram.
If you want to edit the diagram, you need to create a yaml template (not CloudFormation template).

Describe the solution you'd like

Generate a yaml template (not CloudFormation template) for creating a diagram from CloudFormation template.

Describe alternatives you've considered

Generate a yaml template from scratch.

Additional context

CloudFormation templates have various dependencies, and there is no simple parent-child relationship between resources. It seems difficult to generate the desired diagram using only existing CloudFormation template formats.

I considered utilizing Metadata or comments within the CloudFormation templates to include additional information, but this approach would make the templates excessively long, and CloudFormation templates are intended for resource creation and management rather than diagram generation.
Additionally, combining different lifecycle components into a single CloudFormation template would make it difficult to manage and maintain.

CloudFormation template --[awsdac]--> yaml template --[user custom]--> your desired diagram :)

Based on the challenges mentioned, instead of directly generating diagrams from CloudFormation templates, we propose an approach where we create a separate YAML file from the CloudFormation template. This YAML file can then be customized by users and used as input for awsdac to generate the desired architecture diagrams. This approach decouples the diagram generation process from the CloudFormation template structure, allowing for more flexibility and customization while leveraging the strengths of specialized awsdac.

Defualt arrow head with antialiasing

Since the argument of drawLine is image.Point (a structure with x,y as integers), the floating point number is cast to an integer.

diagram-as-code/internal/types/link.go

Lines 116 to 119 in cc6f6ce

	a := arrowPt.Mul(i)
	b := a.Add(at1.Mul(al - i)).Div(al)
	c := a.Add(at2.Mul(al - i)).Div(al)
	l.drawLine(img, b, c)

Considering extensibility, an option is to create a Point structure with x and y as floating point numbers.