ankon/explain-cloudformation-changeset

Tool to process a (possibly nested) CloudFormation changeset, and represent the changes in a human-understandable way.

explain-cloudformation-changeset

Tool to process a (possibly nested) CloudFormation changeset, and represent the changes in a human-understandable way. The main goal:

Make it possible to review a complex changeset and reason about the potential impacts of executing it.

Building

go build

Using

$ id=$(aws cloudformation create-change-set ... --output text --query Id)
$ ./explain-cloudformation-changeset --change-set-name=${id} --graph-output=graph.svg

The tool will download (nested) changeset descriptions and save them by default in the current working directory as JSON files. This can be changed by using the --cache-dir argument. If a changeset specified on the command-line already is cached, the cached version will be used.

The examples can be used by setting the cache directory accordingly:

./explain-cloudformation-changeset --cache-dir=aws-examples --change-set-name=SampleChangeSet-direct --graph-output=SampleChangeSet-direct.svg

TODO & Ideas

• Table: Build a simple CSV with all planned changes
• Augment information from changeset with information from template(s) (should point to S3 location of packaged template, so we can find nested stack templates automatically)

License

See LICENSE for the license of the code.

The files in aws-examples have been taken from https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-updating-stacks-changesets-samples.html and are licensed under a modified MIT license.

explain-cloudformation-changeset's Issues

Use named ports for change in/out edges

This should basically deduplicate the points where edges attach, and make things more readable.

Implement support for visualizing `beforeContext`/`afterContext` changes

Handle removal of substacks correctly

Right now removing a substack crashes the tool:

INFO[0010] processing nested stack XXXXXXXX
FATA[0010] unable to build graph, failed to get changeset, operation error CloudFormation: DescribeChangeSet, 1 validation error(s) found.
- missing required field, DescribeChangeSetInput.ChangeSetName. 

The fix should be trivial

1. Check whether ResourceChange.Action is Modify/Remove/Add
2. Depending on whether there is a changeset: Recurse
3. Depending on the operation itself color the stack subgraph border (if possible?)

Should find and connect all causing changes

It is possible that multiple parameters cause a change in the same resource. These should all be linked, as when reviewing these are very likely also the ones the reviewer looks for.

Add GitHub action to process aws-examples on commit/PRs

Publish releases

README should mention to use the changeset ARN, or specify region/stack

Use a more canonical project structure

Go tools seem to have a "cmd/" directory for commands ("graph" in our case, more to come), and then other directories for library-ish code.

Follow the best practices, and prepare for adding the "table" command.

Move license into separate file

Seems GitHub only checks license files, but not markdown blocks :)

Remove cached files unless requested to keep them

Over the last weeks of usage I never once needed to look at the cache, and rarely ever had to re-do a graph either that would be sped up by the cache. So, let's remove them after a run, but keep a flag (--keep) to explicitly keep the cached files.