Visualize Stack

Within this tutorial we will automatically visualize the Stack during the deployment to AWS. By doing this we solve the problem of manual documentation. Instead we create up-to-date, accurate visualizations of complex infrastructure directly from code, which aids in collaboration, troubleshooting, and understanding resource relationships. By using this approach, teams can move from “diagrams as a manual task” to “diagrams as code,” saving time and ensuring visual representations match the live infrastructure.

Prerequisite

The starting point is the stack as we defined in Get started with CDK4J and some common understanding regarding maven.

Include diagram generation build

To generate the diagram we use the CDK4J diagram tooling within the maven build. For that we append the following snippet to our pom.xml

      <!-- Generate AWS infrastructure diagram -->
      <plugin>
        <groupId>com.github.eirslett</groupId>
        <artifactId>frontend-maven-plugin</artifactId>
        <version>2.0.0</version>
        <configuration>
          <installDirectory>target</installDirectory>
          <nodeVersion>v16.13.1</nodeVersion>
        </configuration>
        <executions>
          <execution>
            <id>install node and npm</id>
            <goals>
              <goal>install-node-and-npm</goal>
            </goals>
          </execution>
          <execution>
            <id>install cdk4j-diagram</id>
            <goals>
              <goal>npm</goal>
            </goals>
            <configuration>
              <arguments>install @datapith/cdk4j-diagram</arguments>
            </configuration>
          </execution>
          <execution>
            <id>generate infrastructure diagram</id>
            <goals>
              <goal>npx</goal>
            </goals>
            <!-- Make sure the generation of infrastructure diagram happens after synth -->
            <phase>package</phase>
            <configuration>
              <arguments>cdk4j-diagram html --ci-mode -t ${project.basedir}/target/cdk.out/GettingStartedStack.template.json -o ${project.basedir}/target/aws-diagram</arguments>
            </configuration>
          </execution>
        </executions>
      </plugin>

Within this snippet we assure the proper node.js version is used (install node and npm) and we automatically install cdk4j-diagram (install cdk4j-diagram).

With the execution part generate infrastructure diagram we tell cdk4j-diagram to generate a diagram based on the CloudFormation template GettingStartedStack.template.json and persist it at /target/aws-diagram.

Generate diagram

As CDK4J diagram is integrated within the maven build process, the diagram will be automatically generated when we deploy the stack by executing:

mvn deploy

Along with deploying the stack to AWS (as shown in Get started with CDK4J), a visualization of the stack is saved in the target/aws-diagram directory. Open the index.html file to view an interactive diagram similar to the image below:

The checkboxes in the blue sidebar allow you to hide specific resources, and clicking any resource reveals more detailed information.

Conclusion

Within this tutorial we have shown how we can automatically generate a diagram regarding the deployed stack. By this we

• Provide a clear and concise overview of resources, and their dependencies.
• Facilitate better communication among team members and external auditors by providing an easy-to-understand representation of the stack.
• Assure (new) employees or external contractors quickly understand the stack setup.