aws-prototyping-sdk.cdk-graph-plugin-diagram 0.12.21

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

Diagram Plugin - Cdk Graph

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

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		-	Graphviz
SVG		DOT	Graphviz
PNG		SVG	Graphviz

---

Diagram Providers

Provider	Status	Formats
Graphviz		DOT, SVG, PNG
Drawio		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 ❤️