Generate diagrams from CF templates

[moltar]

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.

[ugwis]

Thank you for creating issue!

Currently, it is not supported, but it is within our scope. There are a few challenges we will need to overcome in order to achieve this:

• 20: We are currently using this file to create a list of resource types that correspond to the icon titles in the pptx file.

• Resolve resource dependency of templates: To generate diagrams, dependencies should be resolved by parsing the DependsOn, Ref, and Sub functions as shown in this. However, resolving conditions that depend on parameters is difficult. Resolve conditions only to the extent possible, or use an interactive shell and let the user specify it.
• Must be customizable and consider for non-CloudFormation users. Resources have several attributes to customize the diagram layout/decoration. https://github.com/awslabs/diagram-as-code/blob/0fb7005ca7d1fd3e27b9bd16f302e2862902239b/cmd/awsdac/main.go#L45-L54 For example, CloudFormation users may be easier to use the following notation:

  Resources:
   Instance:
     Type: AWS::EC2::Instance
     Properties:
       KeyPair: 
       ...
     Metadata:
       Diagram:
         Title: Instance 1
  Metadata:
   Diagram:
     DefinitionFiles:
       ...

  However, for non-CloudFormation users, unnecessary Metadata will be required to utilize custom attributes, as demonstrated in the following example.

  Resources:
   Instance:
     Type: AWS::EC2::Instance
     Metadata:
       Diagram:
         Title: Instance 1
  Metadata:
   Diagram:
     DefinitionFiles:
       ...

  One possible solution is to make the current notation coexist with the CloudFormation notation. I'm not sure if this method would be supported by the community. Please let me know if you have any other good ideas.

To give some background, I have dozens of CloudFormation templates and created this tool to generate diagrams for these templates. It seems that many users are looking forward to generation from CloudFormation templates, so I would be happy if I could contribute with this tool.

[ugwis]

First, we have taken a step towards solving this issue. Added the --cfn-template flag to the awsdac command. If you specify the flag, awsdac reads the YAML file as a CloudFormation template and generates an architecture diagram. Thanks, @a2ush, for your hard work on this issue. Please refer example diagram generated from CloudFormation template. README.md#beta-create-a-diagram-from-cloudformation-template

However, not all CloudFormation templates can generate diagrams. The three issues mentioned above are not fully resolved and are only partial resolutions. We also confirmed that since CloudFormation templates are not a notation designed for generating diagrams, there are patterns that cannot be generated, depending on the template. Furthermore, the kind of diagrams a user prefers depends on the user’s purpose. We will continue to improve the way we generate diagrams from CloudFormation templates, but it is not a tool that will meet the needs of all users (we have yet to see the potential of Generative AI). Also, please note that we will not be able to maintain backward compatibility for diagrams generated from CloudFormation templates as we work toward better drawing.

Therefore, we recommend using the --dac-file flag to convert the CloudFormation template to the DaC syntax and generate the diagram from DaC syntax, especially if you want to keep backward compatibility with diagrams generated on CI/CD. We will keep backward compatibility with the DaC syntax (starts with Diagram:) as much as possible.

# Convert CFn template to DaC syntax(output.yaml)
$ awsdac cloudformation.yaml --cfn-template --dac-file
[Done] DAC (diagram as code) data has been written to the output.yaml
[Done] The AWS infrastructure diagram has been generated: output.png

# Rearrange resources from your diagram or remove unnecessary resources.
$ edit output.yaml

# Regenerate diagrams
$ awsdac output.yaml -o output.png

Please note that the implementation task in the metadata section of DaC attributes in a CloudFormation template is currently a low priority, as the feature will not be backward compatible for some time. However, we are actively working on improving drawings and will provide updates as soon as we can. In the meantime, we recommend that you customize them by outputting them in the --dac-file format. This will allow you to keep compatibility with your existing diagrams. For more information, please refer to CFn related issues for additional issues related to generating from CloudFormation templates.