@Stability(Experimental)

Package software.aws.awsprototypingsdk.cdkgraphplugindiagram

Diagram Plugin - Cdk Graph

@aws-prototyping-skd/cdk-graph-plugin-diagram

experimental alpha \ API Documentation Source Code

This plugin generates diagrams utilizing the cdk-graph framework.

More comprehensive documentation to come as this package stabilizes.

Disclaimer: This is the first cdk graph plugin, it is highly experimental, and subject to major refactors as we gain feedback from the community.

| | | | --- | --- | | | |

Quick Start

 // bin/app.ts
 
 // Must wrap cdk app with async IIFE function to enable async cdk-graph report
 (async () => {
   const app = new App();
   // ... add stacks, etc
   const graph = new CdkGraph(app, {
     plugins: [new CdkGraphDiagramPlugin()],
   });
 
   app.synth();
 
   // async cdk-graph reporting hook
   await graph.report();
 })
 
 // => cdk.out/diagram.dot
 // => cdk.out/diagram.svg
 // => cdk.out/diagram.png

This plugin currently only supports async report() generation following the above example. Make sure to wrap the cdk app with async IIFE.

Supported Formats

| Format | Status | Extends | Provider | | --- | --- | --- | --- | | DOT | beta | - | Graphviz | SVG | beta | DOT | Graphviz | PNG | beta | SVG | Graphviz

Diagram Providers

| Provider | Status | Formats | | --- | --- | --- | | Graphviz | alpha | DOT, SVG, PNG | | Drawio | design | TBD: very early stage design and development |

Configuration

See API Documentation for details, and look in unit tests for more examples.

Example Configurations (expand below)

Presets

Preset: compact 

 {
   name: "compact",
   title: "Compact Diagram",
   filterPlan: {
     preset: FilterPreset.COMPACT,
   },
 },

Preset: verbose 

 {
   name: "verbose",
   title: "Verbose Diagram",
   format: DiagramFormat.PNG,
   ignoreDefaults: true,
 },

Focus

Focus: hoist 

 {
   name: "focus",
   title: "Focus Lambda Diagram (non-extraneous)",
   filterPlan: {
     focus: (store) =>
       store.getNode(getConstructUUID(app.stack.lambda)),
     preset: FilterPreset.NON_EXTRANEOUS,
   },
   ignoreDefaults: true,
 },

Focus: no hoist 

 {
   name: "focus-nohoist",
   title: "Focus WebServer Diagram (noHoist, verbose)",
   filterPlan: {
     focus: {
       node: (store) =>
         store.getNode(getConstructUUID(app.stack.webServer)),
       noHoist: true,
     },
   },
   ignoreDefaults: true,
 },

Filters

Filter: Include specific cfn resource types 

 {
   name: "includeCfnType",
   title: "Include CfnType Diagram (filter)",
   filterPlan: {
     filters: [
       Filters.includeCfnType([
         aws_arch.CfnSpec.ServiceResourceDictionary.EC2.Instance,
         /AWS::Lambda::Function.*/,
         "AWS::IAM::Role",
       ]),
       Filters.compact(),
     ],
   },
 },

Filter: Exclude specific cfn resource types 

 {
   name: "excludeCfnType",
   title: "Exclude CfnType Diagram (filter)",
   filterPlan: {
     filters: [
       Filters.excludeCfnType([
         /AWS::EC2::VPC.*/,
         aws_arch.CfnSpec.ServiceResourceDictionary.IAM.Role,
       ]),
       Filters.compact(),
     ],
   },
 },

Filter: Include specific graph node types 

 {
   name: "includeNodeType",
   title: "Include NodeType Diagram (filter)",
   filterPlan: {
     filters: [
       Filters.includeNodeType([
         NodeTypeEnum.STACK,
         NodeTypeEnum.RESOURCE,
       ]),
       Filters.compact(),
     ],
   },
 },

Filter: Include specific graph node types 

 {
   name: "includeNodeType",
   title: "Include NodeType Diagram (filter)",
   filterPlan: {
     filters: [
       Filters.includeNodeType([
         NodeTypeEnum.STACK,
         NodeTypeEnum.RESOURCE,
       ]),
       Filters.compact(),
     ],
   },
 },

Filter: Exclude specific graph node types 

 {
   name: "excludeNodeType",
   title: "Exclude NodeType Diagram (filter)",
   filterPlan: {
     filters: [
       Filters.excludeNodeType([
         NodeTypeEnum.NESTED_STACK,
         NodeTypeEnum.CFN_RESOURCE,
         NodeTypeEnum.OUTPUT,
         NodeTypeEnum.PARAMETER,
       ]),
       Filters.compact(),
     ],
   },
 },

Themes

Theme: Dark 

 {
   name: "Dark",
   title: "Dark Theme Diagram",
   theme: theme,
 },

Theme: Dark - render service icons 

 {
   name: "dark-services",
   title: "Dark Theme Custom Diagram",
   theme: {
     theme: theme,
     rendering: {
       resourceIconMin: GraphThemeRenderingIconTarget.SERVICE,
       resourceIconMax: GraphThemeRenderingIconTarget.CATEGORY,
       cfnResourceIconMin: GraphThemeRenderingIconTarget.DATA,
       cfnResourceIconMax: GraphThemeRenderingIconTarget.RESOURCE,
     },
   },
 },

Theme: Dark - verbose 

 {
   name: "dark-verbose",
   title: "Dark Theme Verbose Diagram",
   ignoreDefaults: true,
   theme: theme,
 },

---

Next Steps

  • [ ] Battle test in the wild and get community feedback
  • [ ] Improve image coverage and non-image node rendering
  • [ ] Add drawio support
  • [ ] Add common filter patterns and helpers
  • [ ] Enable generating diagrams outside of synthesis process (maybe CLI)
  • [ ] Implement interactive diagram, with potential for dynamic filtering and config generation
  • [ ] Support using interactive diagram as config generator for other plugins (or as separate plugin that depends on this)

Inspired by cdk-dia and cfn-dia with ❤️