Skip to content

Cdk Graph Diagram Plugin

stable API Documentation Source Code

This plugin generates diagrams utilizing the cdk-graph framework.

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 stable DOT, SVG, PNG
Drawio design TBD: very early stage design and development

Configuration

See IPluginConfig interface for details, and look in unit tests for additional examples.

By default the diagram plugin will generate a single "compact" preset diagram. It is capable of creating multiple diagrams each with different configurations, as well as defining the defaults to use.

Defaults Option

Changing the defaults option will modify default options for all diagrams, including the default diagram.

See IDiagramConfigBase interface for plugin.defaults options.

new CdkGraphDiagramPlugin({
  defaults: {
    theme: "dark",
    filterPlan: {
      preset: FilterPreset.NONE,
    },
  },
});

// => results in a single diagram that is "verbose" and "dark", since no resources are filtered

Diagrams Option

By modifying the diagrams option of the plugin you have full control over the rendering of diagrams, and can render multiple diagrams.

See IDiagramConfig interface for diagram config options.

new CdkGraphDiagramPlugin({
  diagrams: [
    {
      name: "diagram-1",
      title: "Diagram 1 (dark + compact)",
      theme: "dark",
      // the default `filterPlan: { preset: FilterPreset.COMPACT }` will still apply
    },
    {
      name: "diagram-2",
      title: "Diagram 2 (dark + verbose)",
      theme: "dark",
      filterPlan: {
        preset: FilterPreset.NONE,
      },
    },
    {
      name: "diagram-3",
      title: "Diagram 3 (no defaults)",
      ignoreDefaults: true, // default options will not be applied (theme, filterPlan, etc)
    },
  ],
});

Example Diagram Configs (expand below)

The below examples define individual diagram configs in the diagrams options of the plugin as described above.

new CdkGraphDiagramPlugin({
  diagrams: [
    // ... insert diagram  config(s) here - see below for examples
  ],
});
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: {
        filter: {
            filter: (store) =>
                store.getNode(getConstructUUID(app.stack.lambda)),
            },
        },
    preset: FilterPreset.NON_EXTRANEOUS,
  },
  ignoreDefaults: true,
},
Focus: no hoist
{
  name: "focus",
  title: "Focus Lambda Diagram (non-extraneous)",
  filterPlan: {
    focus: {
        filter: {
            filter: (store) =>
                store.getNode(getConstructUUID(app.stack.lambda)),
        },
        noHoist: true,
    },
    preset: FilterPreset.NON_EXTRANEOUS,
  },
  ignoreDefaults: true,
},
Filters
Filter: Include specific cfn resource types
{
  name: "includeCfnType",
  title: "Include CfnType Diagram (filter)",
  filterPlan: {
    filters: [
      {
        graph: Filters.includeCfnType([
          aws_arch.CfnSpec.ServiceResourceDictionary.EC2.Instance,
          /AWS::Lambda::Function.*/,
          "AWS::IAM::Role",
        ]),
      },
      { store: Filters.compact() },
    ],
  },
},
Filter: Exclude specific cfn resource types
{
  name: "excludeCfnType",
  title: "Exclude CfnType Diagram (filter)",
  filterPlan: {
    filters: [
      {
        graph: Filters.excludeCfnType([
          /AWS::EC2::VPC.*/,
          aws_arch.CfnSpec.ServiceResourceDictionary.IAM.Role,
        ]),
      },
      { store: Filters.compact() },
    ],
  },
},
Filter: Include specific graph node types
{
  name: "includeNodeType",
  title: "Include NodeType Diagram (filter)",
  filterPlan: {
    filters: [
      {
        graph: Filters.includeNodeType([
          NodeTypeEnum.STACK,
          NodeTypeEnum.RESOURCE,
        ]),
      },
      { store: Filters.compact() },
    ],
  },
},
Filter: Exclude specific graph node types
{
  name: "excludeNodeType",
  title: "Exclude NodeType Diagram (filter)",
  filterPlan: {
    filters: [
      {
        graph: Filters.excludeNodeType([
          NodeTypeEnum.NESTED_STACK,
          NodeTypeEnum.CFN_RESOURCE,
          NodeTypeEnum.OUTPUT,
          NodeTypeEnum.PARAMETER,
        ])
      },
      { store: 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,
},
Node Positions
Fixed y-coordinate for a node
{
  nodePositions: {
    WebServer: { x: 0, y: 10 },
  },
},

Future Enhancements

  • [ ] 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 ❤️


Last update: 2024-12-09