token-injectable-docker-builder 0.1.2 → 0.1.4

package/README.md

@@ -1,6 +1,12 @@
 # TokenInjectableDockerBuilder
 
-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 `TokenInjectableDockerBuilder` is a flexible AWS CDK construct that enabled the usage of AWS CDK tokens in the building, pushing, and deployment of Docker images to Amazon Elastic Container Registry (ECR). It leverages AWS CodeBuild and Lambda custom resources. 
+
+## Why?
+
+AWS CDK already provides mechanisms for creating deployable assets using Docker, such as [DockerImageAsset](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_ecr_assets.DockerImageAsset.html) and [DockerImageCode](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_lambda.DockerImageCode.html), but these Constructs are limited because they cannot accept CDK tokens as build-args. With the TokenInjectableDockerBuilder, one can inject CDK tokens as build-time args into their Docker-based assets to satisfy a much larger range of dependency relationships.
+
+For example, imagine a NextJS frontend Docker image that calls an API Gateway endpoint. Logically, one would first deploy the API Gateway, then deploy the NextJS frontend such that it has reference to the API Gateway endpoint through a [build-time environment variable](https://nextjs.org/docs/pages/building-your-application/configuring/environment-variables). In this case, building the Docker-based asset before deployment time doesn't work since it is dependent on the deployment of the API Gateway.
 
 ## Features
 
@@ -149,4 +155,10 @@ Ensure you have the following:
 
 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.
+3. **Permissions**: Ensure the IAM role for CodeBuild has the required permissions to interact with ECR and CloudWatch.
+
+---
+
+## Support
+
+Open an issue on [GitHub](https://github.com/AlexTech314/TokenInjectableDockerBuilder) :)

package/lib/index.d.ts

@@ -0,0 +1,16 @@
+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/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.2",
+  "version": "0.1.4",
   "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/src/isCompleteHandler/index.js

@@ -0,0 +1,97 @@
+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

@@ -0,0 +1,39 @@
+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: {},
+    };
+};