@flit/cdk-pipeline 1.0.1 → 1.0.3

package/README.md

@@ -1,18 +1,184 @@
-# @flit/cdk
+# @flit/cdk-pipeline
 
-This package exposes some useful CDK constructs to improve deployment workflows.
+This library exposes a highly customizable and extensible L3 pipeline construct intended as an alternative to the CDK native L3 [CodePipeline](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.pipelines.CodePipeline.html) construct which has some inherent limitations in capability and extensibility.
+
+This library provides the tools and documentation to get your own pipeline up and running and build your own custom segments.
 
 _**Warning:** This package is EXPERIMENTAL and might undergo breaking changes_
 
+## Table of contents
+
+- [Table of contents](#table-of-contents)
+- [Homepage](https://p-mercury.github.io/jumper-de/modules/_flit_cdk_pipeline)
+- [Usage](#usage)
+  - [1. Installation](#1-installation)
+  - [2. Basics](#1-basics)
+  - [3. Multiple stacks](#3-multiple-stacks)
+  - [4. Passing assets](#4-passing-assets)
+  - [4. Build your own segment](#3-build-your-own-segment)
+
 ## Usage
 
-### Installation
+### 1. Installation
 
 ```bash
-npm i -g @flit/cdk
+npm i -g @flit/cdk-pipeline
+```
+
+### 2. Basics
+
+The snippet bellow is a basic example of a pipeline which will run whenever a change is detected in a GitHub repository and which will update itself and deploy and update a user defined stack. This example demonstrates the three basic elements that make up a pipeline:
+
+#### - Pipeline
+
+The Pipeline construct will create a CloudFormation Stack which contains the pipeline and all of the required peripheral resources to make it work.
+
+#### - Segment
+
+A Segment is simply a pre-configured set of pipeline actions which together represent a commonly used CI/CD pattern, like for example building and deploying a stack.
+
+To build properly, a Pipeline requires at least one SourceSegment, exactly one PipelineSegment and at least one other segment.
+
+#### - Artifact
+
+An Artifact represents a pipeline artifact which can be used to pass information between stages. Every asset needs to be the output of a Segment and can be consumed by any segments that need that output.
+
+```typescript
+import { App, SecretValue, Stack } from "aws-cdk-lib";
+import {
+  Pipeline,
+  GitHubSourceSegment,
+  PipelineSegment,
+  StackSegment,
+  Artifact,
+} from "@flit/cdk-pipeline";
+
+const APP = new App();
+
+const sourceArtifact = new Artifact();
+
+new Pipeline(APP, "Pipeline", {
+  rootDir: "./",
+  segments: [
+    new GitHubSourceSegment({
+      oauthToken: SecretValue.secretsManager("github-access-token"),
+      output: sourceArtifact,
+      owner: "owner-name",
+      repo: "repo-name",
+      branch: "branch-name",
+    }),
+    new PipelineSegment({
+      input: sourceArtifact,
+      command: "cdk synth Pipeline --strict --exclusively",
+    }),
+    new StackSegment({
+      stack: new Stack(APP, "Stack1"),
+      input: sourceArtifact,
+      command: "cdk synth Stack1 --strict --exclusively",
+    }),
+  ],
+});
+```
+
+The above code will produce the following pipeline
+
+<div style="width: 300px; height: 340px; overflow-x: hidden; overflow-y: scroll;"><img src="media://pipeline-ouput-example.png" alt="alt text" width="100%"></div>
+
+### 3. Multiple stacks
+
+To add another stack to the pipeline you simply add another StackSegment with a new stack instance and the pipeline will handle the rest.
+
+```typescript
+import { App, SecretValue, Stack } from "aws-cdk-lib";
+import {
+  Pipeline,
+  GitHubSourceSegment,
+  PipelineSegment,
+  StackSegment,
+  Artifact,
+} from "@flit/cdk-pipeline";
+
+const APP = new App();
+
+const sourceArtifact = new Artifact();
+
+new Pipeline(APP, "Pipeline", {
+  rootDir: "./",
+  segments: [
+    new GitHubSourceSegment({
+      oauthToken: SecretValue.secretsManager("github-access-token"),
+      output: sourceArtifact,
+      owner: "owner-name",
+      repo: "repo-name",
+      branch: "branch-name",
+    }),
+    new PipelineSegment({
+      input: sourceArtifact,
+      command: "cdk synth Pipeline --strict --exclusively",
+    }),
+    new StackSegment({
+      stack: new Stack(APP, "Stack1"),
+      input: sourceArtifact,
+      command: "cdk synth Stack1 --strict --exclusively",
+    }),
+    new StackSegment({
+      stack: new Stack(APP, "Stack2"),
+      input: sourceArtifact,
+      command: "cdk synth Stack2 --strict --exclusively",
+    }),
+  ],
+});
+```
+
+### 3. Passing assets
+
+If a segment requires the output artifact of a previous segment it you can simply add an output artifact to the previous stage and pass it as additional input to another segment
+
+```typescript
+import { App, SecretValue, Stack } from "aws-cdk-lib";
+import {
+  Pipeline,
+  GitHubSourceSegment,
+  PipelineSegment,
+  StackSegment,
+  Artifact,
+} from "@flit/cdk-pipeline";
+
+const APP = new App();
+
+const sourceArtifact = new Artifact();
+const stack1Artifact = new Artifact();
+
+new Pipeline(APP, "Pipeline", {
+  rootDir: "./",
+  segments: [
+    new GitHubSourceSegment({
+      oauthToken: SecretValue.secretsManager("jumper-de-github-access-tokens"),
+      output: sourceArtifact,
+      owner: "p-mercury",
+      repo: "jumper-de",
+      branch: "main",
+    }),
+    new PipelineSegment({
+      input: sourceArtifact,
+      command: "cdk synth Pipeline --strict --exclusively",
+    }),
+    new StackSegment({
+      stack: new Stack(APP, "Stack1"),
+      input: sourceArtifact,
+      output: stack1Artifact,
+      command: "cdk synth Stack1 --strict --exclusively",
+    }),
+    new StackSegment({
+      stack: new Stack(APP, "Stack2"),
+      input: [sourceArtifact, stack1Artifact],
+      command: "cdk synth Stack2 --strict --exclusively",
+    }),
+  ],
+});
 ```
 
-### Pipeline
+### 4. Build your own segment
 
 An alternative L3 construct which fixes some inherit limitations of the CDK native CodePipeline L3 construct.
 

package/package.json

@@ -1,14 +1,18 @@
 {
   "name": "@flit/cdk-pipeline",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "license": "Apache-2.0",
   "description": "Jumper Systems' cdk library",
-  "homepage": "https://github.com/p-mercury/jumper-de",
+  "homepage": "https://p-mercury.github.io/jumper-de/modules/_flit_cdk_pipeline",
   "keywords": [
     "aws",
     "awscdk",
     "codepipeline"
   ],
+  "author": {
+    "name": "Luis Vierroth",
+    "email": "luis@jumper.de"
+  },
   "repository": {
     "type": "git",
     "url": "https://github.com/p-mercury/jumper-de.git"
@@ -16,28 +20,67 @@
   "bugs": "https://github.com/p-mercury/jumper-de/issues",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
-  "files": [
-    "dist"
-  ],
+  "typedoc": {
+    "entryPoint": "./src/index.ts"
+  },
   "scripts": {
-    "build": "npm run prepack",
-    "prepack": "rm -rf ./dist && tsc -b"
+    "build": "jsii",
+    "prepack": "jsii"
   },
   "publishConfig": {
     "access": "public"
   },
-  "dependencies": {
-    "@aws-appsync/utils": "^1.1.0",
-    "@aws-lambda-powertools/tracer": "^1.7.0",
-    "@types/jest": "29.5.0",
-    "@types/node": "18.15.5",
-    "aws-cdk": "2.69.0",
-    "aws-cdk-lib": "2.69.0",
-    "cdk-aws-lambda-powertools-layer": "^3.3.0",
-    "constructs": "10.1.285",
+  "dependencies": {},
+  "devDependencies": {
+    "@types/node": "18.15.10",
+    "path": "^0.12.7",
+    "aws-cdk": "2.70.0",
+    "cdk-aws-lambda-powertools-layer": "3.3.0",
     "jest": "29.5.0",
+    "jsii": "5.0.1",
+    "jsii-pacmak": "1.79.0",
     "ts-jest": "29.0.5",
     "ts-node": "10.9.1",
-    "typescript": "5.0.2"
-  }
+    "typescript": "5.0.2",
+    "aws-cdk-lib": "2.70.0",
+    "constructs": "10.1.293"
+  },
+  "peerDependencies": {
+    "aws-cdk-lib": "2.70.0",
+    "constructs": "10.1.293"
+  },
+  "bundledDependencies": [
+    "path"
+  ],
+  "stability": "stable",
+  "jsii": {
+    "outdir": "./dist",
+    "tsc": {
+      "rootDir": "./src",
+      "outDir": "./dist"
+    },
+    "targets": {
+      "java": {
+        "package": "software.amazon.awscdk.flit.pipeline",
+        "maven": {
+          "groupId": "software.amazon.awscdk",
+          "artifactId": "flit.pipeline"
+        }
+      },
+      "dotnet": {
+        "namespace": "Amazon.CDK.Flit.Pipeline",
+        "packageId": "Amazon.CDK.Flit.Pipeline",
+        "iconUrl": "https://raw.githubusercontent.com/aws/aws-cdk/main/logo/default-256-dark.png"
+      },
+      "python": {
+        "distName": "aws-cdk.flit.pipeline",
+        "module": "aws_cdk.flit.pipeline",
+        "classifiers": [
+          "Framework :: AWS CDK",
+          "Framework :: AWS CDK :: 2"
+        ]
+      }
+    }
+  },
+  "bundleDependencies": []
 }

package/src/artifact.ts

@@ -0,0 +1,24 @@
+import { Artifact as AwsArtifact } from "aws-cdk-lib/aws-codepipeline";
+
+import { Segment } from "./segment";
+
+export class Artifact extends AwsArtifact {
+  private producer?: Segment;
+  private consumers: Segment[] = [];
+  constructor() {
+    super();
+  }
+  produce(producer: Segment) {
+    if (this.producer) throw new Error("Artifact is already produced");
+    this.producer = producer;
+  }
+  consume(producer: Segment) {
+    this.consumers.push(producer);
+  }
+  obtainProducer(): Segment | undefined {
+    return this.producer;
+  }
+  obtainConsumers(): Segment[] {
+    return this.consumers;
+  }
+}

package/{dist/index.d.ts → src/index.ts}

@@ -1,6 +1,7 @@
-export * from "./pipeline";
 export * from "./artifact";
-export * from "./source-segment";
 export * from "./pipeline-segment";
-export * from "./stack-segment";
+export * from "./pipeline";
 export * from "./publish-assets-action";
+export * from "./segment";
+export * from "./source-segment";
+export * from "./stack-segment";

package/src/pipeline-segment.ts

@@ -0,0 +1,68 @@
+import { BuildEnvironmentVariable } from "aws-cdk-lib/aws-codebuild";
+
+import { Artifact } from "./artifact";
+import { Segment, SegmentConstructed } from "./segment";
+import { StackSegmentConstructed } from "./stack-segment";
+import { Pipeline } from "./pipeline";
+
+export interface PipelineSegmentProps {
+  /**
+   * The input arfifact for the build stage.
+   */
+  readonly input: Artifact | Artifact[];
+  /**
+   * The command(s) to build the stack.
+   * @example "cdk synth StackName --strict --exclusively"
+   */
+  readonly command: string | string[];
+  /**
+   * The environmental variables for the build stage.
+   */
+  readonly environmentVariables?: { [key: string]: BuildEnvironmentVariable };
+  /**
+   * The name of the stack to apply this action to.
+   * @deafult The name of the given stack.
+   */
+  readonly stackName?: string;
+  /**
+   * The AWS account this Action is supposed to operate in.
+   */
+  readonly account?: string;
+  /**
+   * The AWS region the given Action resides in.
+   */
+  readonly region?: string;
+
+  /**
+   * The artifact to hold the stack deployment output file.
+   * @default no output artifact
+   */
+  readonly output?: Artifact;
+  /**
+   * Does this stage require manual approval of the change set?
+   * @default false
+   */
+  readonly manualApproval?: Boolean;
+}
+
+/**
+ * @category Segments
+ */
+export class PipelineSegment extends Segment {
+  readonly isPipeline: boolean = true;
+  readonly props: PipelineSegmentProps;
+
+  constructor(props: PipelineSegmentProps) {
+    super(props);
+    this.props = props;
+  }
+
+  construct(scope: Pipeline): SegmentConstructed {
+    return new StackSegmentConstructed(scope, `Deploy${scope.stackName}`, {
+      ...this.props,
+      stack: scope,
+      input: this.inputs[0],
+      extraInputs: this.inputs.slice(1),
+    });
+  }
+}

package/src/pipeline.ts

@@ -0,0 +1,94 @@
+import { App, Stack, StackProps } from "aws-cdk-lib";
+import { Construct } from "constructs";
+import { Pipeline as AwsPipeline, IAction } from "aws-cdk-lib/aws-codepipeline";
+import * as path from "path";
+
+import { Artifact } from "./artifact";
+import { Segment } from "./segment";
+import { SourceSegment } from "./source-segment";
+import { PipelineSegment } from "./pipeline-segment";
+
+export interface PipelineProps extends StackProps {
+  /**
+   * The name of the generated pipeline.
+   * @default Stack ID
+   */
+  readonly pipelineName?: string;
+  /**
+   * The path to the cdk projects root directory containing the cdk.json file
+   * relative to the asset root
+   */
+  readonly rootDir: string;
+  /**
+   * The segments to populating the pipeline.
+   */
+  readonly segments: Segment[];
+}
+
+/**
+ * @category Constructs
+ */
+export class Pipeline extends Stack {
+  readonly pipelineName: string;
+  readonly rootDir: string;
+  readonly buildDir: string;
+
+  constructor(scope: Construct, id: string, readonly props: PipelineProps) {
+    super(scope, id, props);
+
+    this.pipelineName = props.pipelineName ? props.pipelineName : id;
+    this.rootDir = props.rootDir;
+    this.buildDir = path.join(this.rootDir, (this.node.root as App).outdir);
+
+    if (!this.bundlingRequired) return;
+
+    props.segments.forEach((segment: Segment) => {
+      segment.inputs.forEach((artifact: Artifact) => {
+        if (!artifact.obtainProducer())
+          throw new Error("Artifact consumed but never produced.");
+      });
+    });
+
+    const sourceSegments: SourceSegment[] = props.segments.filter(
+      (segment: Segment) => segment.isSource
+    ) as SourceSegment[];
+
+    const pipelineSegment: PipelineSegment | undefined = props.segments.find(
+      (segment: Segment) => segment.isPipeline
+    ) as PipelineSegment;
+
+    const segments: Segment[] = props.segments.filter(
+      (segment: Segment) => !segment.isSource && !segment.isPipeline
+    );
+
+    new AwsPipeline(this, "Pipeline", {
+      pipelineName: props.pipelineName,
+      restartExecutionOnUpdate: true,
+      stages: [
+        {
+          stageName: "Source",
+          actions: [
+            ...sourceSegments.reduce(
+              (actions: IAction[], segment: SourceSegment) => [
+                ...actions,
+                ...segment.construct(this).actions,
+              ],
+              []
+            ),
+          ],
+        },
+        {
+          stageName: "Pipeline",
+          actions: [...pipelineSegment.construct(this).actions],
+        },
+        ...segments.map((segment: Segment) => {
+          const build = segment.construct(this);
+          return {
+            stageName: build.name,
+            actions: build.actions,
+          };
+        }),
+      ],
+    });
+  }
+}

package/src/publish-assets-action.ts

@@ -0,0 +1,126 @@
+import { Stack } from "aws-cdk-lib";
+import { Construct } from "constructs";
+import {
+  ActionBindOptions,
+  ActionConfig,
+  ActionProperties,
+  Artifact,
+  IAction,
+  IStage,
+} from "aws-cdk-lib/aws-codepipeline";
+import { BuildSpec, LinuxBuildImage, Project } from "aws-cdk-lib/aws-codebuild";
+import { CodeBuildAction } from "aws-cdk-lib/aws-codepipeline-actions";
+import {
+  AccountPrincipal,
+  CompositePrincipal,
+  PolicyDocument,
+  PolicyStatement,
+  Role,
+  ServicePrincipal,
+} from "aws-cdk-lib/aws-iam";
+import { IRuleTarget, RuleProps, Rule } from "aws-cdk-lib/aws-events";
+import * as path from "path";
+
+export interface PublishAssetsActionProps {
+  readonly actionName: string;
+  readonly input: Artifact;
+  readonly manifestPath: string;
+  readonly runOrder?: number;
+}
+
+export class PublishAssetsAction extends Construct implements IAction {
+  public readonly actionProperties: ActionProperties;
+
+  bound(
+    scope: Construct,
+    stage: IStage,
+    options: ActionBindOptions
+  ): ActionConfig {
+    throw new Error(`Method not implemented.${!scope && !stage! && options}`);
+  }
+
+  bind(
+    scope: Construct,
+    stage: IStage,
+    options: ActionBindOptions
+  ): ActionConfig {
+    throw new Error(`Method not implemented.${!scope && !stage! && options}`);
+  }
+
+  onStateChange(
+    name: string,
+    target?: IRuleTarget | undefined,
+    options?: RuleProps | undefined
+  ): Rule {
+    throw new Error(`Method not implemented.${!name && !target! && options}`);
+  }
+
+  constructor(scope: Construct, id: string, props: PublishAssetsActionProps) {
+    super(scope, id);
+    const codeBuild = new CodeBuildAction({
+      ...props,
+      input: props.input,
+      project: new Project(this, id, {
+        environment: {
+          buildImage: LinuxBuildImage.AMAZON_LINUX_2_4,
+        },
+        role: new Role(this, "UpdatePipelineCodeCuildRole", {
+          assumedBy: new CompositePrincipal(
+            new ServicePrincipal("codebuild.amazonaws.com"),
+            new AccountPrincipal(Stack.of(this).account)
+          ),
+          inlinePolicies: {
+            selfMutation: new PolicyDocument({
+              statements: [
+                new PolicyStatement({
+                  actions: ["sts:AssumeRole"],
+                  resources: [`arn:*:iam::${Stack.of(this).account}:role/*`],
+                  conditions: {
+                    "ForAnyValue:StringEquals": {
+                      "iam:ResourceTag/aws-cdk:bootstrap-role": [
+                        "image-publishing",
+                        "file-publishing",
+                        "deploy",
+                      ],
+                    },
+                  },
+                }),
+              ],
+            }),
+          },
+        }),
+        buildSpec: BuildSpec.fromObject({
+          version: "0.2",
+          phases: {
+            install: {
+              "runtime-versions": {
+                nodejs: 18,
+              },
+              commands: [
+                "npm install -g npm@latest",
+                "npm i -g @flit/publish-cdk-assets@latest",
+              ],
+            },
+            build: {
+              commands: `pca ${
+                props.manifestPath ? path.normalize(props.manifestPath) : "."
+              }`,
+            },
+          },
+        }),
+      }),
+    });
+
+    this.actionProperties = codeBuild.actionProperties;
+    this.bind = (
+      scope: Construct,
+      stage: IStage,
+      options: ActionBindOptions
+    ): ActionConfig => codeBuild.bind(scope, stage, options);
+    this.onStateChange = (
+      name: string,
+      target?: IRuleTarget,
+      options?: RuleProps
+    ): Rule => codeBuild.onStateChange(name, target, options);
+  }
+}

package/src/segment.ts

@@ -0,0 +1,45 @@
+import { Construct } from "constructs";
+import { Stack } from "aws-cdk-lib";
+import { IAction } from "aws-cdk-lib/aws-codepipeline";
+
+import { Artifact } from "./artifact";
+import { Pipeline } from "./pipeline";
+
+export interface SegmentProps {
+  readonly input?: Artifact | Artifact[];
+  readonly output?: Artifact | Artifact[];
+}
+
+export abstract class Segment {
+  readonly isSource: boolean = false;
+  readonly isPipeline: boolean = false;
+  readonly dependencies?: Stack[];
+  readonly inputs: Artifact[] = [];
+  readonly outputs: Artifact[] = [];
+  constructor(props: SegmentProps) {
+    if (props.input) {
+      this.inputs = (
+        props.input.constructor.name === "Array" ? props.input : [props.input]
+      ) as Artifact[];
+      this.inputs.forEach((artifact: Artifact) => {
+        artifact.consume(this);
+      }, this);
+    }
+    if (props.output) {
+      this.outputs = (
+        props.output.constructor.name === "Array"
+          ? props.output
+          : [props.output]
+      ) as Artifact[];
+      this.outputs.forEach((artifact: Artifact) => {
+        artifact.produce(this);
+      }, this);
+    }
+  }
+  abstract construct(scope: Pipeline): SegmentConstructed;
+}
+
+export abstract class SegmentConstructed extends Construct {
+  readonly name: string = "";
+  readonly actions: IAction[] = [];
+}