token-injectable-docker-builder 0.1.1 → 0.1.3

package/README.md

@@ -1,12 +1,152 @@
-# Welcome to your CDK TypeScript Construct Library project
+# TokenInjectableDockerBuilder
 
-You should explore the contents of this project. It demonstrates a CDK Construct Library that includes a construct (`DockerImageAsset`)
-which contains an Amazon SQS queue that is subscribed to an Amazon SNS topic.
+The `TokenInjectableDockerBuilder` is a powerful AWS CDK construct that automates the building, pushing, and deployment of Docker images to Amazon Elastic Container Registry (ECR) using AWS CodeBuild and Lambda custom resources. This construct simplifies workflows by enabling token-based Docker image customization.
 
-The construct defines an interface (`DockerImageAssetProps`) to configure the visibility timeout of the queue.
+## Features
 
-## Useful commands
+- Automatically builds and pushes Docker images to ECR.
+- Supports custom build arguments for Docker builds.
+- Provides Lambda functions to handle `onEvent` and `isComplete` lifecycle events for custom resources.
+- Retrieves the latest Docker image from ECR for use in ECS or Lambda.
 
-* `npm run build`   compile typescript to js
-* `npm run watch`   watch for changes and compile
-* `npm run test`    perform the jest unit tests
+---
+
+## Installation
+
+First, install the construct using NPM:
+
+```bash
+npm install token-injectable-docker-builder
+```
+
+---
+
+## Constructor
+
+### `TokenInjectableDockerBuilder`
+
+#### Parameters
+
+- **`scope`**: The construct's parent scope.
+- **`id`**: The construct ID.
+- **`props`**: Configuration properties.
+
+#### Properties in `TokenInjectableDockerBuilderProps`
+
+| Property       | Type                              | Required | Description                                                |
+|----------------|-----------------------------------|----------|------------------------------------------------------------|
+| `path`         | `string`                         | Yes      | The file path to the Dockerfile or source code directory.  |
+| `buildArgs`    | `{ [key: string]: string }`       | No       | Build arguments to pass to the Docker build process.       |
+
+---
+
+## Usage Example
+
+Here is an example of how to use the `TokenInjectableDockerBuilder` in your AWS CDK application:
+
+```typescript
+import * as cdk from 'aws-cdk-lib';
+import { TokenInjectableDockerBuilder } from 'token-injectable-docker-builder';
+
+export class MyStack extends cdk.Stack {
+  constructor(scope: cdk.App, id: string, props?: cdk.StackProps) {
+    super(scope, id, props);
+
+    // Create a TokenInjectableDockerBuilder construct
+    const dockerBuilder = new TokenInjectableDockerBuilder(this, 'MyDockerBuilder', {
+      path: './docker', // Path to the directory containing your Dockerfile
+      buildArgs: {
+        TOKEN: 'my-secret-token', // Example of a build argument
+        ENV: 'production',
+      },
+    });
+
+    // Retrieve the container image for ECS
+    const containerImage = dockerBuilder.getContainerImage();
+
+    // Retrieve the Docker image code for Lambda
+    const dockerImageCode = dockerBuilder.getDockerImageCode();
+
+    // Example: Use the container image in an ECS service
+    new ecs.FargateTaskDefinition(this, 'TaskDefinition', {
+      containerImage,
+    });
+
+    // Example: Use the Docker image code in a Lambda function
+    new lambda.Function(this, 'DockerLambdaFunction', {
+      runtime: lambda.Runtime.FROM_IMAGE,
+      code: dockerImageCode,
+      handler: lambda.Handler.FROM_IMAGE,
+    });
+  }
+}
+```
+
+---
+
+## How It Works
+
+1. **Docker Source**: The construct packages the source code or Dockerfile specified in the `path` property as an S3 asset.
+2. **CodeBuild Project**:
+   - Uses the packaged asset and build arguments to build the Docker image.
+   - Pushes the image to an ECR repository.
+3. **Custom Resource**:
+   - Triggers the build process using a Lambda function (`onEvent`).
+   - Monitors the build status using another Lambda function (`isComplete`).
+4. **Outputs**:
+   - Provides the Docker image via `getContainerImage()` for ECS use.
+   - Provides the Docker image code via `getDockerImageCode()` for Lambda.
+
+---
+
+## Methods
+
+### `getContainerImage()`
+
+Returns a `ContainerImage` object that can be used in ECS services.
+
+```typescript
+const containerImage = dockerBuilder.getContainerImage();
+```
+
+### `getDockerImageCode()`
+
+Returns a `DockerImageCode` object that can be used in Lambda functions.
+
+```typescript
+const dockerImageCode = dockerBuilder.getDockerImageCode();
+```
+
+---
+
+## IAM Permissions
+
+This construct automatically grants the required IAM permissions for:
+- CodeBuild to pull and push images to ECR.
+- CodeBuild to write logs to CloudWatch.
+- Lambda functions to monitor the build status and retrieve logs.
+
+---
+
+## Notes
+
+- **Build Arguments**: Use the `buildArgs` property to pass custom arguments to the Docker build process. These are transformed into `--build-arg` flags.
+- **ECR Repository**: A new ECR repository is created automatically.
+- **Custom Resources**: Custom resources are used to handle lifecycle events and ensure the build is completed successfully.
+
+---
+
+## Prerequisites
+
+Ensure you have the following:
+1. Docker installed locally if you're testing builds.
+2. AWS CDK CLI installed (`npm install -g aws-cdk`).
+3. An AWS account and configured credentials.
+
+---
+
+## Troubleshooting
+
+1. **Build Errors**: Check the AWS CodeBuild logs in CloudWatch.
+2. **Lambda Function Errors**: Check the `onEvent` and `isComplete` Lambda logs in CloudWatch.
+3. **Permissions**: Ensure the IAM role for CodeBuild has the required permissions to interact with ECR and CloudWatch.

package/lib/index.ts

@@ -0,0 +1,171 @@
+import * as path from 'path';
+import { Duration, CustomResource, Stack } from 'aws-cdk-lib';
+import { Project, Source, LinuxBuildImage, BuildSpec } from 'aws-cdk-lib/aws-codebuild';
+import { Repository } from 'aws-cdk-lib/aws-ecr';
+import { PolicyStatement } from 'aws-cdk-lib/aws-iam';
+import { Code, DockerImageCode, Runtime } from 'aws-cdk-lib/aws-lambda';
+import { Asset } from 'aws-cdk-lib/aws-s3-assets';
+import { Provider } from 'aws-cdk-lib/custom-resources';
+import { Construct } from 'constructs';
+import { ContainerImage } from 'aws-cdk-lib/aws-ecs';
+import * as crypto from 'crypto';
+import { Function } from 'aws-cdk-lib/aws-lambda';
+
+export interface TokenInjectableDockerBuilderProps {
+  path: string;
+  buildArgs?: { [key: string]: string };
+}
+
+export class TokenInjectableDockerBuilder extends Construct {
+  private readonly ecrRepository: Repository;
+  private readonly buildTriggerResource: CustomResource;
+
+  constructor(scope: Construct, id: string, props: TokenInjectableDockerBuilderProps) {
+    super(scope, id);
+
+    const { path: sourcePath, buildArgs } = props; // Default to linux/amd64
+
+    // Define absolute paths for Lambda handlers
+    const onEventHandlerPath = path.resolve(__dirname, '../src/onEventHandler');
+    const isCompleteHandlerPath = path.resolve(__dirname, '../src/isCompleteHandler');
+
+    // Create an ECR repository
+    this.ecrRepository = new Repository(this, 'ECRRepository');
+
+    // Package the source code as an asset
+    const sourceAsset = new Asset(this, 'SourceAsset', {
+      path: sourcePath, // Path to the Dockerfile or source code
+    });
+
+    // Transform buildArgs into a string of --build-arg KEY=VALUE
+    const buildArgsString = buildArgs
+      ? Object.entries(buildArgs)
+          .map(([key, value]) => `--build-arg ${key}=${value}`)
+          .join(' ')
+      : '';
+
+    // Pass the buildArgsString and platform as environment variables
+    const environmentVariables: { [name: string]: { value: string } } = {
+      ECR_REPO_URI: { value: this.ecrRepository.repositoryUri },
+      BUILD_ARGS: { value: buildArgsString },
+    };
+
+    // Create a CodeBuild project
+    const codeBuildProject = new Project(this, 'UICodeBuildProject', {
+      source: Source.s3({
+        bucket: sourceAsset.bucket,
+        path: sourceAsset.s3ObjectKey,
+      }),
+      environment: {
+        buildImage: LinuxBuildImage.STANDARD_7_0,
+        privileged: true, // Required for Docker builds
+      },
+      environmentVariables: environmentVariables,
+      buildSpec: BuildSpec.fromObject({
+        version: '0.2',
+        phases: {
+          pre_build: {
+            commands: [
+              'echo "Retrieving AWS Account ID..."',
+              'export ACCOUNT_ID=$(aws sts get-caller-identity --query Account --output text)',
+              'echo "Logging in to Amazon ECR..."',
+              'aws ecr get-login-password --region $AWS_DEFAULT_REGION | docker login --username AWS --password-stdin $ACCOUNT_ID.dkr.ecr.$AWS_DEFAULT_REGION.amazonaws.com',
+            ],
+          },
+          build: {
+            commands: [
+              'echo Build phase: Building the Docker image...',
+              'docker build $BUILD_ARGS -t $ECR_REPO_URI:latest $CODEBUILD_SRC_DIR',
+            ],
+          },
+          post_build: {
+            commands: [
+              'echo Post-build phase: Pushing the Docker image...',
+              'docker push $ECR_REPO_URI:latest',
+            ],
+          },
+        },
+      }),
+    });
+
+    // Grant permissions to interact with ECR
+    this.ecrRepository.grantPullPush(codeBuildProject);
+
+    codeBuildProject.role!.addToPrincipalPolicy(
+      new PolicyStatement({
+        actions: ['ecr:GetAuthorizationToken'],
+        resources: ['*'],
+      })
+    );
+
+    // Grant permissions to CodeBuild for CloudWatch Logs
+    codeBuildProject.role!.addToPrincipalPolicy(
+      new PolicyStatement({
+        actions: ['logs:PutLogEvents', 'logs:CreateLogGroup', 'logs:CreateLogStream'],
+        resources: [`arn:aws:logs:${Stack.of(this).region}:${Stack.of(this).account}:*`],
+      })
+    );
+
+    // Create Node.js Lambda function for onEvent
+    const onEventHandlerFunction = new Function(this, 'OnEventHandlerFunction', {
+      runtime: Runtime.NODEJS_18_X, // Use Node.js runtime
+      code: Code.fromAsset(onEventHandlerPath), // Path to handler code
+      handler: 'index.handler', // Entry point (adjust as needed)
+      timeout: Duration.minutes(15),
+    });
+
+    onEventHandlerFunction.addToRolePolicy(
+      new PolicyStatement({
+        actions: ['codebuild:StartBuild'],
+        resources: [codeBuildProject.projectArn], // Restrict to specific project
+      })
+    );
+
+    // Create Node.js Lambda function for isComplete
+    const isCompleteHandlerFunction = new Function(this, 'IsCompleteHandlerFunction', {
+      runtime: Runtime.NODEJS_18_X,
+      code: Code.fromAsset(isCompleteHandlerPath),
+      handler: 'index.handler',
+      timeout: Duration.minutes(15),
+    });
+
+    isCompleteHandlerFunction.addToRolePolicy(
+      new PolicyStatement({
+        actions: [
+          'codebuild:BatchGetBuilds',
+          'codebuild:ListBuildsForProject',
+          'logs:GetLogEvents',
+          'logs:DescribeLogStreams',
+          'logs:DescribeLogGroups'
+        ],
+        resources: ['*'],
+      })
+    );
+
+    // Create a custom resource provider
+    const provider = new Provider(this, 'CustomResourceProvider', {
+      onEventHandler: onEventHandlerFunction,
+      isCompleteHandler: isCompleteHandlerFunction,
+      queryInterval: Duration.minutes(1),
+    });
+
+    // Define the custom resource
+    this.buildTriggerResource = new CustomResource(this, 'BuildTriggerResource', {
+      serviceToken: provider.serviceToken,
+      properties: {
+        ProjectName: codeBuildProject.projectName,
+        Trigger: crypto.randomUUID(),
+      },
+    });
+
+    this.buildTriggerResource.node.addDependency(codeBuildProject);
+  }
+
+  public getContainerImage(): ContainerImage {
+    return ContainerImage.fromEcrRepository(this.ecrRepository, 'latest');
+  }
+
+  public getDockerImageCode(): DockerImageCode {
+    return DockerImageCode.fromEcr(this.ecrRepository);
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "token-injectable-docker-builder",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
   "scripts": {
@@ -21,5 +21,30 @@
   "peerDependencies": {
     "aws-cdk-lib": "2.166.0",
     "constructs": "^10.0.0"
-  }
+  },
+  "keywords": [
+    "aws",
+    "cdk",
+    "aws-cdk",
+    "docker",
+    "ecr",
+    "lambda",
+    "custom-resource",
+    "docker-build",
+    "codebuild",
+    "token-injection",
+    "docker-image",
+    "aws-codebuild",
+    "aws-ecr",
+    "docker-builder",
+    "cdk-construct",
+    "lambda-custom-resource",
+    "container-image",
+    "aws-lambda",
+    "aws-cdk-lib",
+    "cloud-development-kit",
+    "ci-cd",
+    "aws-ci-cd",
+    "infrastructure-as-code"
+  ]
 }

package/jest.config.js

@@ -1,8 +0,0 @@
-module.exports = {
-  testEnvironment: 'node',
-  roots: ['<rootDir>/test'],
-  testMatch: ['**/*.test.ts'],
-  transform: {
-    '^.+\\.tsx?$': 'ts-jest'
-  }
-};

package/test/docker_image_asset.test.d.ts

@@ -1 +0,0 @@
-export {};

package/test/docker_image_asset.test.js

@@ -1,30 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-const cdk = require("aws-cdk-lib");
-const assertions_1 = require("aws-cdk-lib/assertions");
-const index_1 = require("../lib/index");
-test('DockerImageAsset creates required resources', () => {
-    const app = new cdk.App();
-    const stack = new cdk.Stack(app, 'TestStack');
-    new index_1.TokenInjectableDockerBuilder(stack, 'TestDockerImageAsset', {
-        path: './src/onEventHandler', // Path to Docker context
-        buildArgs: { ENV: 'test' },
-    });
-    const template = assertions_1.Template.fromStack(stack);
-    // Verify that an ECR repository is created
-    template.resourceCountIs('AWS::ECR::Repository', 1);
-    // Verify that a CodeBuild project is created with expected properties
-    template.hasResourceProperties('AWS::CodeBuild::Project', {
-        Environment: {
-            ComputeType: 'BUILD_GENERAL1_SMALL',
-            PrivilegedMode: true,
-            Image: 'aws/codebuild/standard:7.0',
-        },
-        Source: {
-            Type: 'S3',
-        },
-    });
-    // Verify the Custom Resource is created with the expected service token
-    template.resourceCountIs('AWS::CloudFormation::CustomResource', 1);
-});
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZG9ja2VyX2ltYWdlX2Fzc2V0LnRlc3QuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyJkb2NrZXJfaW1hZ2VfYXNzZXQudGVzdC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiOztBQUFBLG1DQUFtQztBQUNuQyx1REFBa0Q7QUFDbEQsd0NBQTREO0FBRTVELElBQUksQ0FBQyw2Q0FBNkMsRUFBRSxHQUFHLEVBQUU7SUFDdkQsTUFBTSxHQUFHLEdBQUcsSUFBSSxHQUFHLENBQUMsR0FBRyxFQUFFLENBQUM7SUFDMUIsTUFBTSxLQUFLLEdBQUcsSUFBSSxHQUFHLENBQUMsS0FBSyxDQUFDLEdBQUcsRUFBRSxXQUFXLENBQUMsQ0FBQztJQUU5QyxJQUFJLG9DQUE0QixDQUFDLEtBQUssRUFBRSxzQkFBc0IsRUFBRTtRQUM5RCxJQUFJLEVBQUUsc0JBQXNCLEVBQUUseUJBQXlCO1FBQ3ZELFNBQVMsRUFBRSxFQUFFLEdBQUcsRUFBRSxNQUFNLEVBQUU7S0FDM0IsQ0FBQyxDQUFDO0lBRUgsTUFBTSxRQUFRLEdBQUcscUJBQVEsQ0FBQyxTQUFTLENBQUMsS0FBSyxDQUFDLENBQUM7SUFFM0MsMkNBQTJDO0lBQzNDLFFBQVEsQ0FBQyxlQUFlLENBQUMsc0JBQXNCLEVBQUUsQ0FBQyxDQUFDLENBQUM7SUFFcEQsc0VBQXNFO0lBQ3RFLFFBQVEsQ0FBQyxxQkFBcUIsQ0FBQyx5QkFBeUIsRUFBRTtRQUN4RCxXQUFXLEVBQUU7WUFDWCxXQUFXLEVBQUUsc0JBQXNCO1lBQ25DLGNBQWMsRUFBRSxJQUFJO1lBQ3BCLEtBQUssRUFBRSw0QkFBNEI7U0FDcEM7UUFDRCxNQUFNLEVBQUU7WUFDTixJQUFJLEVBQUUsSUFBSTtTQUNYO0tBQ0YsQ0FBQyxDQUFDO0lBRUgsd0VBQXdFO0lBQ3hFLFFBQVEsQ0FBQyxlQUFlLENBQUMscUNBQXFDLEVBQUUsQ0FBQyxDQUFDLENBQUM7QUFDckUsQ0FBQyxDQUFDLENBQUMiLCJzb3VyY2VzQ29udGVudCI6WyJpbXBvcnQgKiBhcyBjZGsgZnJvbSAnYXdzLWNkay1saWInO1xuaW1wb3J0IHsgVGVtcGxhdGUgfSBmcm9tICdhd3MtY2RrLWxpYi9hc3NlcnRpb25zJztcbmltcG9ydCB7IFRva2VuSW5qZWN0YWJsZURvY2tlckJ1aWxkZXIgfSBmcm9tICcuLi9saWIvaW5kZXgnO1xuXG50ZXN0KCdEb2NrZXJJbWFnZUFzc2V0IGNyZWF0ZXMgcmVxdWlyZWQgcmVzb3VyY2VzJywgKCkgPT4ge1xuICBjb25zdCBhcHAgPSBuZXcgY2RrLkFwcCgpO1xuICBjb25zdCBzdGFjayA9IG5ldyBjZGsuU3RhY2soYXBwLCAnVGVzdFN0YWNrJyk7XG5cbiAgbmV3IFRva2VuSW5qZWN0YWJsZURvY2tlckJ1aWxkZXIoc3RhY2ssICdUZXN0RG9ja2VySW1hZ2VBc3NldCcsIHtcbiAgICBwYXRoOiAnLi9zcmMvb25FdmVudEhhbmRsZXInLCAvLyBQYXRoIHRvIERvY2tlciBjb250ZXh0XG4gICAgYnVpbGRBcmdzOiB7IEVOVjogJ3Rlc3QnIH0sXG4gIH0pO1xuXG4gIGNvbnN0IHRlbXBsYXRlID0gVGVtcGxhdGUuZnJvbVN0YWNrKHN0YWNrKTtcblxuICAvLyBWZXJpZnkgdGhhdCBhbiBFQ1IgcmVwb3NpdG9yeSBpcyBjcmVhdGVkXG4gIHRlbXBsYXRlLnJlc291cmNlQ291bnRJcygnQVdTOjpFQ1I6OlJlcG9zaXRvcnknLCAxKTtcblxuICAvLyBWZXJpZnkgdGhhdCBhIENvZGVCdWlsZCBwcm9qZWN0IGlzIGNyZWF0ZWQgd2l0aCBleHBlY3RlZCBwcm9wZXJ0aWVzXG4gIHRlbXBsYXRlLmhhc1Jlc291cmNlUHJvcGVydGllcygnQVdTOjpDb2RlQnVpbGQ6OlByb2plY3QnLCB7XG4gICAgRW52aXJvbm1lbnQ6IHtcbiAgICAgIENvbXB1dGVUeXBlOiAnQlVJTERfR0VORVJBTDFfU01BTEwnLFxuICAgICAgUHJpdmlsZWdlZE1vZGU6IHRydWUsXG4gICAgICBJbWFnZTogJ2F3cy9jb2RlYnVpbGQvc3RhbmRhcmQ6Ny4wJyxcbiAgICB9LFxuICAgIFNvdXJjZToge1xuICAgICAgVHlwZTogJ1MzJyxcbiAgICB9LFxuICB9KTtcblxuICAvLyBWZXJpZnkgdGhlIEN1c3RvbSBSZXNvdXJjZSBpcyBjcmVhdGVkIHdpdGggdGhlIGV4cGVjdGVkIHNlcnZpY2UgdG9rZW5cbiAgdGVtcGxhdGUucmVzb3VyY2VDb3VudElzKCdBV1M6OkNsb3VkRm9ybWF0aW9uOjpDdXN0b21SZXNvdXJjZScsIDEpO1xufSk7XG4iXX0=