A look at the cdk-notifier tool
In this article, I want to talk about a small CLI tool cdk-notifier that helps you to improve the review process on GitHub pull requests and gives more confidence for changed resources of your AWS CDK stacks. AWS Cloud Development Kit is a tool to provide your AWS infrastructure as Code.
In the past, we have been using TFNotify to preview changes in Terraform projects and it really improved our workflows.
On the one hand, the reviewer has easier access to the terraform plan output to verify the code changes matching the preview.
And on the other hand, it makes sure that you are not accidentally changing resources on production without noticing.
Sometimes the code changes can be complex and difficult to review. It’s good to have a second anchor before approving the PR in these cases.
In our company, we migrated to CDK last year. However, there was no comparable tool available like TFNotify. So I decided to start our own tool in Golang inspired by TFNotify. It has been used now for over 5 months successfully. Since we started the project with good test coverage, there was less need for us to introduce manual approval steps on production rollouts. However, having the additional layer in the workflow to visualize production changes was a must.
CDK-notifier will use the output of
cdk diff command. It will read in the output from the file and run several processing steps and finally post the CDK diff to pull request as a comment.
CDK-notifier will remove ASCII color to have a clean output. Then it will convert CDK addition and deletion symbols to a markdown diff compatible text
[+].. -> + .. so that we can highlight additions or deletion in GitHub’s native markdown diff. More examples can be found in tests.
Also, we want to make sure that the message does not exceed the text limit for comments.
The main purpose of this tool is to run in CI systems, however, testing from CLI can be a start.
cdk-notifier was built for CircleCI as this is our main CI system. Environment Variables that are provided by CirlceCi are automatically assigned to required arguments. In other CI systems, you need to map manually, however, I’m open-minded to support other CI’s just let me know by creating an issue.
The provided GitHub token should have
read:discussion. First generate the log file
cdk-notifier will post the processed log of CDK diff to PR if there are changes.
If a diff comment for
tag-idexists and no changes are detected then the comment will be deleted.
tag-id is used to identify your CDK stack. If you have multiple CDK stacks in your pipeline, the parameter is necessary to distinguish the stacks. Additionally, it’s used to identify comments that require an update or delete. If there is no CDK diff within one stack, no comment will be sent and the existing comment will be removed.
This is an example of how the diff would like on GitHub if it’s running with provided environment variables of CircleCI
I created a CircleCI Orb signavio/cdk-orb which is used to deploy our stacks. This might be another article to explain fully. However, the cdk-notifier is integrated there as well.
Whenever we run
cdk diffin the pipeline, we also post the diff to the pull request, so that reviewers can validate changes that are going to production.
We have a multi-stack cross-region and cross-account deployment. So far cdk-notifier has increased transparency and confidence for reviewers. This is especially important if you have complex CDK stacks.
I hope I could spread some inspiration. Thanks for reading.