🎡 CDK-Dia - Automated diagrams for CDK infrastructure

Cdk-dia diagrams your CDK provisioned infrastructure using the Graphviz dot language.

Example

This Diagram was automatically generated from an AWS CDK stack

Getting started - Typescript / Javascript

Add cdk-dia to your CDK project

npm install cdk-dia

Install Graphviz

brew install graphviz

• If you don't use brew: Graphviz installation in many environments is well documented.
• make sure Graphviz's dot binary is available in your PATH.

Synthesize your CDK application

cdk synth

Generate a CDK-DIA diagram PNG

npx cdk-dia

Generate a CDK-DIA diagram as an interactive HTML (experimental)

npx cdk-dia --rendering cytoscape-html

Getting started - any other CDK language

Globally install cdk-dia

npm install cdk-dia -g

Install Graphviz

brew install graphviz

• If you don't use brew: Graphviz installation in many environments is well documented.
• make sure Graphviz's dot binary is available in your PATH.

Synthesize your CDK application

cdk synth

Generate a CDK-DIA diagram

cdk-dia

Customize diagrams

In some cases it is useful to be able to tweak a diagram. For this purpose CDK-DIA includes customizers/decorators you can use with your CDK constructs in order to tweak the diagram.

Limitations:

• Customization and decorators are currently only support for Typescript/Javascript CDK projects.
• In order to customize you have to add cdk-dia as a npm project dependency (globally installing it using npm i -g won't allow you to use the CdkDiaDecorator class)

Example:

Consider the following diagram of a 3-Tier CDK Stack:

In this diagram CDK-DIA collapsed the DBTier (done automatically to any CDK Level 2 (L2) construct) in order to create a diagram which contains the most important details.

One can use a decorator in order to customize the diagram and prevent CDK-DIA from collapsing the Construct.

This is done by implementing CDK's IInpectable's interface and using CDK-DIA's decorator. example:

This results in a Diagram where the DB-Tier was not collapsed providing more details:

• a full example or the above can be found at examples/decoration-example

Ignoring Resources

You can exclude specific resources from the diagram using the ignore option. This is useful when certain constructs add noise to your diagram without providing meaningful architectural insight.

Using the @DiagramOptions class decorator (experimental):

import { DiagramOptions } from "cdk-dia"

@DiagramOptions({ ignore: true })
export class InternalBucket extends s3.Bucket {
    constructor(scope: Construct, id: string) {
        super(scope, id);
    }
}

Using CdkDiaDecorator directly (implementing IInspectable):

import { CdkDia, CdkDiaDecorator } from "cdk-dia"
import * as cdk from "aws-cdk-lib"

export class InternalBucket extends s3.Bucket implements cdk.IInspectable {
    constructor(scope: Construct, id: string) {
        super(scope, id);
    }

    inspect(inspector: cdk.TreeInspector): void {
        const decorator = new CdkDiaDecorator().ignore()
        CdkDia.decorate(inspector, decorator)
    }
}

When a resource is ignored, it and all its children are removed from the diagram entirely.

CLI arguments

• npx cdk-dia --help - Get possible arguments
• npx cdk-dia --include stackOne stackFour - only diagram chosen aws-cdk stacks
• npx cdk-dia --include pipelinestack/prod/database - choose stacks by path (nested stacks, pipeline stacks)
• npx cdk-dia --exclude stackOne - exclude chosen aws-cdk stacks from the diagram

🙏🏽 Contributing

Contribution is covered in the CONTRIBUTING.md markdown.