token-injectable-docker-builder 0.1.1 → 0.1.2

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "token-injectable-docker-builder",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
   "scripts": {

package/jest.config.js

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

package/lib/index.d.ts

@@ -1,16 +0,0 @@
-import { DockerImageCode } from 'aws-cdk-lib/aws-lambda';
-import { Construct } from 'constructs';
-import { ContainerImage } from 'aws-cdk-lib/aws-ecs';
-export interface TokenInjectableDockerBuilderProps {
-    path: string;
-    buildArgs?: {
-        [key: string]: string;
-    };
-}
-export declare class TokenInjectableDockerBuilder extends Construct {
-    private readonly ecrRepository;
-    private readonly buildTriggerResource;
-    constructor(scope: Construct, id: string, props: TokenInjectableDockerBuilderProps);
-    getContainerImage(): ContainerImage;
-    getDockerImageCode(): DockerImageCode;
-}

package/src/isCompleteHandler/index.js

@@ -1,97 +0,0 @@
-const { CodeBuildClient, ListBuildsForProjectCommand, BatchGetBuildsCommand } = require('@aws-sdk/client-codebuild');
-const { CloudWatchLogsClient, GetLogEventsCommand } = require('@aws-sdk/client-cloudwatch-logs');
-
-exports.handler = async (event, context) => {
-    console.log('isCompleteHandler Event:', JSON.stringify(event, null, 2));
-
-    // Initialize AWS SDK v3 clients
-    const codebuildClient = new CodeBuildClient({ region: process.env.AWS_REGION });
-    const cloudwatchlogsClient = new CloudWatchLogsClient({ region: process.env.AWS_REGION });
-
-    try {
-        const projectName = event.ResourceProperties.ProjectName;
-
-        if (!projectName) {
-            throw new Error('ProjectName is required in ResourceProperties');
-        }
-
-        console.log(`Checking status for CodeBuild project: ${projectName}`);
-
-        // Retrieve the latest build for the given project
-        const listBuildsCommand = new ListBuildsForProjectCommand({
-            projectName: projectName,
-            sortOrder: 'DESCENDING',
-            maxResults: 1,
-        });
-
-        const listBuildsResp = await codebuildClient.send(listBuildsCommand);
-        const buildIds = listBuildsResp.ids;
-
-        if (!buildIds || buildIds.length === 0) {
-            throw new Error(`No builds found for project: ${projectName}`);
-        }
-
-        const buildId = buildIds[0];
-        console.log(`Latest Build ID: ${buildId}`);
-
-        // Get build details
-        const batchGetBuildsCommand = new BatchGetBuildsCommand({
-            ids: [buildId],
-        });
-
-        const buildDetailsResp = await codebuildClient.send(batchGetBuildsCommand);
-        const build = buildDetailsResp.builds[0];
-
-        if (!build) {
-            throw new Error(`Build details not found for Build ID: ${buildId}`);
-        }
-
-        const buildStatus = build.buildStatus;
-        console.log(`Build Status: ${buildStatus}`);
-
-        if (buildStatus === 'IN_PROGRESS') {
-            // Build is still in progress
-            console.log('Build is still in progress.');
-            return { IsComplete: false };
-        } else if (buildStatus === 'SUCCEEDED') {
-            // Build succeeded
-            console.log('Build succeeded.');
-            return { IsComplete: true };
-        } else if (['FAILED', 'FAULT', 'STOPPED', 'TIMED_OUT'].includes(buildStatus)) {
-            // Build failed; retrieve last 5 log lines
-            const logsInfo = build.logs;
-            if (logsInfo && logsInfo.groupName && logsInfo.streamName) {
-                console.log(`Retrieving logs from CloudWatch Logs Group: ${logsInfo.groupName}, Stream: ${logsInfo.streamName}`);
-
-                const getLogEventsCommand = new GetLogEventsCommand({
-                    logGroupName: logsInfo.groupName,
-                    logStreamName: logsInfo.streamName,
-                    startFromHead: false, // Start from the end to get latest logs
-                    limit: 5,
-                });
-
-                const logEventsResp = await cloudwatchlogsClient.send(getLogEventsCommand);
-                const logEvents = logEventsResp.events;
-                const lastFiveMessages = logEvents.map((event) => event.message).reverse().join('\n');
-
-                const errorMessage = `Build failed with status: ${buildStatus}\nLast 5 build logs:\n${lastFiveMessages}`;
-                console.error(errorMessage);
-
-                // Throw an error to indicate failure to the CDK provider
-                throw new Error(errorMessage);
-            } else {
-                const errorMessage = `Build failed with status: ${buildStatus}, but logs are not available.`;
-                console.error(errorMessage);
-                throw new Error(errorMessage);
-            }
-        } else {
-            const errorMessage = `Unknown build status: ${buildStatus}`;
-            console.error(errorMessage);
-            throw new Error(errorMessage);
-        }
-    } catch (error) {
-        console.error('Error in isCompleteHandler:', error);
-        // Rethrow the error to inform the CDK provider of the failure
-        throw error;
-    }
-};

package/src/onEventHandler/index.js

@@ -1,39 +0,0 @@
-const { CodeBuildClient, StartBuildCommand } = require('@aws-sdk/client-codebuild');
-
-exports.handler = async (event, context) => {
-    console.log('Event:', JSON.stringify(event, null, 2));
-
-    // Initialize the AWS SDK v3 CodeBuild client
-    const codebuildClient = new CodeBuildClient({ region: process.env.AWS_REGION });
-
-    // Set the PhysicalResourceId
-    let physicalResourceId = event.PhysicalResourceId || event.LogicalResourceId;
-
-    if (event.RequestType === 'Create' || event.RequestType === 'Update') {
-        const params = {
-            projectName: event.ResourceProperties.ProjectName,
-        };
-
-        try {
-            const command = new StartBuildCommand(params); // Create the command
-            const build = await codebuildClient.send(command); // Send the command
-            console.log('Started build:', JSON.stringify(build, null, 2));
-        } catch (error) {
-            console.error('Error starting build:', error);
-
-            return {
-                PhysicalResourceId: physicalResourceId,
-                Data: {},
-                Reason: error.message,
-            };
-        }
-    } else if (event.RequestType === 'Delete') {
-        // No action needed for delete, but ensure PhysicalResourceId remains the same
-        console.log('Delete request received. No action required.');
-    }
-
-    return {
-        PhysicalResourceId: physicalResourceId,
-        Data: {},
-    };
-};

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=