@aws-prototyping-sdk/cdk-graph
Project description
CDK Graph (@aws-prototyping-sdk/cdk-graph
)
More comprehensive documentation to come as this package stabilizes
This package is the core framework for supporting additional cdk based automation and tooling, such as diagraming, cost modeling, security and compliance, in a holistic and comprehensive way.
This package provides the following functionality:
- Synthesizes a serialized graph (nodes and edges) from CDK source code.
- Provides runtime interface for interacting with the graph (in-memory database-like graph store).
- Provides plugin framework for additional tooling to utilize and extend the graph.
The goal of this framework is to enable bespoke tooling to be built without having to first traverse the CDK Tree and Metadata to build a graph. Projects like cdk-dia generate a bespoke in-memory graph that is then utilized to generate diagrams; while the diagram generation is the core value it must first have a graph to act upon and currently is required to generate this undifferentiated graph to provide its diagrams. By standardizing on the graph interface necessary to build complex tooling, we can more rapidly build new tooling that focuses on its core value.
Available Plugins
Name | Description | Screenshot | Links |
---|---|---|---|
Diagram | Generate cloud infrastructure diagrams from cdk graph |
Quick Start
Instrument CDK App with CdkGraph
#!/usr/bin/env node
import * as cdk from "aws-cdk-lib";
import { MyStack } from "../lib/my-stack";
import { CdkGraph } from "@aws-prototyping-sdk/cdk-graph";
const app = new cdk.App();
new MyStack(app, "MyStack");
// Add CdkGraph after other construct added to app
new CdkGraph(app);
Using Plugins
#!/usr/bin/env node
import * as cdk from "aws-cdk-lib";
import { MyStack } from "../lib/my-stack";
import { CdkGraph } from "@aws-prototyping-sdk/cdk-graph";
import { ExamplePlugin } from "@aws-prototyping-sdk/cdk-graph-plugin-example"; // does not exist, just example
const app = new cdk.App();
new MyStack(app, "MyStack");
// Add CdkGraph after other construct added to app
new CdkGraph(app, {
plugins: [new ExamplePlugin()],
});
Config
Configuration is supported through the .cdkgraphrc.js
and depending on the plugin, through passing config to the plugin instance.
Config precedence follows 1) defaults, 2) cdkgraphrc, 3) instance.
// .cdkgraphrc.js
module.exports = {
// Defaults to "<cdk.out>/cdkgraph"
outdir: "reports/graph",
// plugin configuration
example: {
verbose: true,
reportType: "csv",
},
};
#!/usr/bin/env node
import * as cdk from "aws-cdk-lib";
import { MyStack } from "../lib/my-stack";
import { CdkGraph } from "@aws-prototyping-sdk/cdk-graph";
import { ExamplePlugin } from "@aws-prototyping-sdk/cdk-graph-plugin-example"; // does not exist, just example
const app = new cdk.App();
new MyStack(app, "MyStack");
// Add CdkGraph after other construct added to app
new CdkGraph(app, {
plugins: [
new ExamplePlugin({
// Will override .cdkgraphrc.js value
verbose: false,
}),
],
});
Plugin Interface
/** CdkGraph **Plugin** interface */
export interface ICdkGraphPlugin {
/** Unique identifier for this plugin */
readonly id: string;
/** Plugin version */
readonly version: Version;
/** List of plugins this plugin depends on, including optional semver version (eg: ["foo", "bar@1.2"]) */
readonly dependencies?: string[];
/**
* Binds the plugin to the CdkGraph instance. Enables plugins to receive base configs.
*/
bind: IGraphPluginBindCallback;
/**
* Node visitor callback for construct tree traversal. This follows IAspect.visit pattern, but the order
* of visitor traversal in managed by the CdkGraph.
*/
inspect?: IGraphVisitorCallback;
/**
* Called during CDK synthesize to generate synchronous artifacts based on the in-memory graph passed
* to the plugin. This is called in fifo order of plugins.
*/
synthesize?: IGraphSynthesizeCallback;
/**
* Generate asynchronous reports based on the graph. This is not automatically called when synthesizing CDK.
* Developer must explicitly add `await graphInstance.report()` to the CDK bin or invoke this outside
* of the CDK synth. In either case, the plugin receives the in-memory graph interface when invoked, as the
* CdkGraph will deserialize the graph prior to invoking the plugin report.
*/
report?: IGraphReportCallback;
}
Plugin operations are automatically invoked by CdkGraph in the order they are defined in the plugins
property. The invocation flow of plugins follows: 1) bind
, 2) inspect
, 3) synthesize
, 4) async report
.
Asynchronous Plugins
Some plugins may requiring performing asynchronous requests, or may make expensive operations that are best left outside of the synthesis process.
CdkGraph support asynchronous operations through the async report()
method of plugins. However, since CDK does not support asynchronous operations during synthesis, this must be wired up a bit differently.
#!/usr/bin/env node
import * as cdk from "aws-cdk-lib";
import { MyStack } from "../lib/my-stack";
import { CdkGraph } from "@aws-prototyping-sdk/cdk-graph";
import { ExampleAsyncPlugin } from "@aws-prototyping-sdk/cdk-graph-plugin-async-example"; // does not exist, just example
(async () => {
const app = new cdk.App();
new MyStack(app, "MyStack");
// Add CdkGraph after other construct added to app
const graph = new CdkGraph(app, {
plugins: [new ExampleAsyncPlugin()],
});
// invokes all plugin `report()` operations asynchronously (in order they are defined in `plugins` property)
await graph.report();
})();
Example Plugin Implementation
Very basic example of implementing a plugin. Once the first actual plugins have been published this will be updated to reference those as examples.
import {
CdkGraph,
CdkGraphContext,
ICdkGraphPlugin,
} from "@aws-prototyping-sdk/cdk-graph";
export class CdkGraphExamplePlugin implements ICdkGraphPlugin {
static readonly ARTIFACT_NS = "EXAMPLE";
static readonly ID = "example";
static readonly VERSION = "0.0.0";
get id(): string {
return CdkGraphDiagramPlugin.ID;
}
get version(): string {
return CdkGraphDiagramPlugin.VERSION;
}
readonly dependencies?: string[] = [];
/** @internal */
private _graph?: CdkGraph;
bind(graph: CdkGraph): void {
this._graph = graph;
}
synthesize(context: CdkGraphContext): void {
const pluginConfig = this.config as Required<IPluginConfig>;
// Get counts of all resources
const cfnResourceCounts = context.store.counts.cfnResources;
// Write plugin artifact
context.writeArtifact(
this,
"EXAMPLE",
"example.json",
JSON.stringify(cfnResourceCounts, null, 2)
);
}
async report(context: CdkGraphContext): void {
// perform async operation here utilizing graph store
const cfnResourceCounts = context.store.counts.cfnResources;
const fetchedData = await fetch("https://example.com/data", {
method: "POST",
body: JSON.stringify(cfnResourceCounts),
});
// Write plugin artifact for fetched data
context.writeArtifact(
this,
"EXAMPLE:FETCHED",
"example-fetched.json",
JSON.stringify(fetchedData, null, 2)
);
}
}
Path to Stability
The below is a rough checklist of task necessary to elevate this from experimental to stable.
- Dynamic versioning and Semver enforcement (store, plugins, etc)
- Support running
async report()
method outside of CDK synthesis process - Find alternative synthesis solution that doesn't utilize CDK internals
- Support custom Nodes and Edges
- Improve logging, bookkeeping, and debugging
- Implement store upgrade solution
- Battle test the implementation against several plugins
- Battle test the implementation in all target languages (currently tested in Typescript, but vended in all PDK supported languages)
- Receive community feedback to validate approach
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for aws_prototyping_sdk.cdk_graph-0.19.66.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | a729a0127364961abcc1618bf81a2753393b1b51f832df800df62324f25788bd |
|
MD5 | 6a03372814a8be4f792e73e084c0edb8 |
|
BLAKE2b-256 | 3cf2e3208fa1e1d7dfce89db099df15472a131f6a19172c4755580bc1fb65d76 |
Hashes for aws_prototyping_sdk.cdk_graph-0.19.66-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | b00b2550e5aed8ee6992a57953d5cf6a9960d039baa7ba0271e06031f91fa387 |
|
MD5 | 9e7bc15d176aace7c749464ebae2ae74 |
|
BLAKE2b-256 | f4e8b361597510302630ea5d2a91edb9548f44284607ffeba619fc11a2cf8296 |