TokenInjectableDockerBuilder

The TokenInjectableDockerBuilder is a flexible AWS CDK construct that enables 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 and DockerImageCode, but these constructs are limited because they cannot accept CDK tokens as build-args. The TokenInjectableDockerBuilder allows injecting CDK tokens as build-time arguments into Docker-based assets, enabling more dynamic dependency relationships.

For example, a Next.js frontend Docker image may require an API Gateway URL as an argument to create a reference from the UI to the associated API in a given deployment. With this construct, you can deploy the API Gateway first, then pass its URL as a build-time argument to the Next.js Docker image. As a result, your Next.js frontend can dynamically fetch data from the API Gateway without hardcoding the URL or needing multiple separate stacks.

---

Features

• Build and Push Docker Images: Automatically builds and pushes Docker images to ECR.
• Token Support: Supports custom build arguments for Docker builds, including CDK tokens resolved at deployment time.
• Custom Install and Pre-Build Commands: Allows specifying custom commands to run during the install and pre_build phases of the CodeBuild build process.
• VPC Configuration: Supports deploying the CodeBuild project within a VPC, with customizable security groups and subnet selection.
• Docker Login: Supports Docker login using credentials stored in AWS Secrets Manager.
• ECR Repository Management: Creates an ECR repository with lifecycle rules and encryption.
• Integration with ECS and Lambda: Provides outputs for use in AWS ECS and AWS Lambda.
• Custom Build Query Interval: Configure how frequently the custom resource polls for build completion using the completenessQueryInterval property (defaults to 30 seconds).

---

Installation

For NPM

Install the construct using NPM:

1npm install token-injectable-docker-builder

For Python

Install the construct using pip:

1pip 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. These are transformed into --build-arg flags. To use in Dockerfile, leverage the ARG keyword. For more details, please see the official Docker docs.
dockerLoginSecretArn	string	No	ARN of an AWS Secrets Manager secret for Docker credentials. Skips login if not provided.
vpc	IVpc	No	The VPC in which the CodeBuild project will be deployed. If provided, the CodeBuild project will be launched within the specified VPC.
securityGroups	ISecurityGroup[]	No	The security groups to attach to the CodeBuild project. These should define the network access rules for the CodeBuild project.
subnetSelection	SubnetSelection	No	The subnet selection to specify which subnets to use within the VPC. Allows the user to select private, public, or isolated subnets.
installCommands	string[]	No	Custom commands to run during the install phase of the CodeBuild build process. Will be executed before the Docker image is built. Useful for installing necessary dependencies for running pre-build scripts.
preBuildCommands	string[]	No	Custom commands to run during the pre_build phase of the CodeBuild build process. Will be executed before the Docker image is built. Useful for running pre-build scripts, such as fetching configs.
kmsEncryption	boolean	No	Whether to enable KMS encryption for the ECR repository. If true, a KMS key will be created for encrypting ECR images; otherwise, AES-256 encryption is used. Defaults to false.
completenessQueryInterval	Duration	No	The query interval for checking if the CodeBuild project has completed. This determines how frequently the custom resource polls for build completion. Defaults to Duration.seconds(30).

---

Usage Examples

Simple Usage Example

This example demonstrates the basic usage of the TokenInjectableDockerBuilder, where a Next.js frontend Docker image requires an API Gateway URL as a build argument to create a reference from the UI to the associated API in a given deployment.

TypeScript/NPM Example

1import * as cdk from 'aws-cdk-lib';
2import { TokenInjectableDockerBuilder } from 'token-injectable-docker-builder';
3import * as ecs from 'aws-cdk-lib/aws-ecs';
4import * as ec2 from 'aws-cdk-lib/aws-ec2';
5import * as apigateway from 'aws-cdk-lib/aws-apigateway';
6
7export class SimpleStack extends cdk.Stack {
8  constructor(scope: cdk.App, id: string, props?: cdk.StackProps) {
9    super(scope, id, props);
10
11    // Create your API Gateway
12    const api = new apigateway.RestApi(this, 'MyApiGateway', {
13      restApiName: 'MyService',
14    });
15
16    // Create the Docker builder
17    const dockerBuilder = new TokenInjectableDockerBuilder(this, 'SimpleDockerBuilder', {
18      path: './nextjs-app', // Path to your Next.js app Docker context
19      buildArgs: {
20        API_URL: api.url, // Pass the API Gateway URL as a build argument
21      },
22      // Optionally override the default completeness query interval:
23      // completenessQueryInterval: cdk.Duration.seconds(45),
24    });
25
26    // Use in ECS
27    const cluster = new ecs.Cluster(this, 'EcsCluster', {
28      vpc: new ec2.Vpc(this, 'Vpc'),
29    });
30
31    const service = new ecs.FargateService(this, 'FargateService', {
32      cluster,
33      taskDefinition: new ecs.FargateTaskDefinition(this, 'TaskDef', {
34        cpu: 512,
35        memoryLimitMiB: 1024,
36      }).addContainer('Container', {
37        image: dockerBuilder.containerImage,
38        logging: ecs.LogDriver.awsLogs({ streamPrefix: 'MyApp' }),
39      }),
40    });
41
42    service.node.addDependency(dockerBuilder);
43  }
44}

Python Example

1from aws_cdk import (
2    aws_ecs as ecs,
3    aws_ec2 as ec2,
4    aws_apigateway as apigateway,
5    Duration,
6    core as cdk,
7)
8from token_injectable_docker_builder import TokenInjectableDockerBuilder
9
10class SimpleStack(cdk.Stack):
11
12    def __init__(self, scope: cdk.App, id: str, **kwargs):
13        super().__init__(scope, id, **kwargs)
14
15        # Create your API Gateway
16        api = apigateway.RestApi(self, "MyApiGateway",
17            rest_api_name="MyService",
18        )
19
20        # Create the Docker builder
21        docker_builder = TokenInjectableDockerBuilder(self, "SimpleDockerBuilder",
22            path="./nextjs-app",  # Path to your Next.js app Docker context
23            build_args={
24                "API_URL": api.url,  # Pass the API Gateway URL as a build argument
25            },
26            # Optionally override the default completeness query interval:
27            # completeness_query_interval=Duration.seconds(45)
28        )
29
30        # Use in ECS
31        vpc = ec2.Vpc(self, "Vpc")
32        cluster = ecs.Cluster(self, "EcsCluster", vpc=vpc)
33
34        task_definition = ecs.FargateTaskDefinition(self, "TaskDef",
35            cpu=512,
36            memory_limit_mib=1024,
37        )
38
39        task_definition.node.add_dependency(docker_builder)
40
41        task_definition.add_container("Container",
42            image=docker_builder.container_image,
43            logging=ecs.LogDriver.aws_logs(stream_prefix="MyApp"),
44        )
45
46        ecs.FargateService(self, "FargateService",
47            cluster=cluster,
48            task_definition=task_definition,
49        )

---

Advanced Usage Example

Building on the previous example, this advanced usage demonstrates how to include additional configurations, such as fetching private API endpoints and configuration files during the build process.

TypeScript/NPM Example

1import * as cdk from 'aws-cdk-lib';
2import { TokenInjectableDockerBuilder } from 'token-injectable-docker-builder';
3import * as ecs from 'aws-cdk-lib/aws-ecs';
4import * as ec2 from 'aws-cdk-lib/aws-ec2';
5import * as apigateway from 'aws-cdk-lib/aws-apigateway';
6
7export class AdvancedStack extends cdk.Stack {
8  constructor(scope: cdk.App, id: string, props?: cdk.StackProps) {
9    super(scope, id, props);
10
11    // Create your API Gateway
12    const api = new apigateway.RestApi(this, 'MyApiGateway', {
13      restApiName: 'MyService',
14    });
15
16    // VPC and Security Group for CodeBuild
17    const vpc = new ec2.Vpc(this, 'MyVpc');
18    const securityGroup = new ec2.SecurityGroup(this, 'MySecurityGroup', {
19      vpc,
20    });
21
22    // Create the Docker builder with additional pre-build commands
23    const dockerBuilder = new TokenInjectableDockerBuilder(this, 'AdvancedDockerBuilder', {
24      path: './nextjs-app',
25      buildArgs: {
26        API_URL: api.url,
27      },
28      vpc,
29      securityGroups: [securityGroup],
30      subnetSelection: { subnetType: ec2.SubnetType.PRIVATE_WITH_EGRESS },
31      installCommands: [
32        'echo "Updating package lists..."',
33        'apt-get update -y',
34        'echo "Installing necessary packages..."',
35        'apt-get install -y curl',
36      ],
37      preBuildCommands: [
38        'echo "Fetching private API configuration..."',
39        // Replace with your actual command to fetch configs
40        'curl -o config.json https://internal-api.example.com/config',
41      ],
42      // Optionally override the default completeness query interval:
43      // completenessQueryInterval: cdk.Duration.seconds(45),
44    });
45
46    // Use in ECS
47    const cluster = new ecs.Cluster(this, 'EcsCluster', { vpc });
48
49    const service = new ecs.FargateService(this, 'FargateService', {
50      cluster,
51      taskDefinition: new ecs.FargateTaskDefinition(this, 'TaskDef', {
52        cpu: 512,
53        memoryLimitMiB: 1024,
54      }).addContainer('Container', {
55        image: dockerBuilder.containerImage,
56        logging: ecs.LogDriver.awsLogs({ streamPrefix: 'MyApp' }),
57      }),
58    });
59
60    service.node.addDependency(dockerBuilder);
61  }
62}

Python Example

1from aws_cdk import (
2    aws_ecs as ecs,
3    aws_ec2 as ec2,
4    aws_apigateway as apigateway,
5    Duration,
6    core as cdk,
7)
8from token_injectable_docker_builder import TokenInjectableDockerBuilder
9
10class AdvancedStack(cdk.Stack):
11
12    def __init__(self, scope: cdk.App, id: str, **kwargs):
13        super().__init__(scope, id, **kwargs)
14
15        # Create your API Gateway
16        api = apigateway.RestApi(self, "MyApiGateway",
17            rest_api_name="MyService",
18        )
19
20        # VPC and Security Group for CodeBuild
21        vpc = ec2.Vpc(self, "MyVpc")
22        security_group = ec2.SecurityGroup(self, "MySecurityGroup", vpc=vpc)
23
24        # Create the Docker builder with additional pre-build commands
25        docker_builder = TokenInjectableDockerBuilder(self, "AdvancedDockerBuilder",
26            path="./nextjs-app",
27            build_args={
28                "API_URL": api.url,
29            },
30            vpc=vpc,
31            security_groups=[security_group],
32            subnet_selection=ec2.SubnetSelection(subnet_type=ec2.SubnetType.PRIVATE_WITH_EGRESS),
33            install_commands=[
34                'echo "Updating package lists..."',
35                'apt-get update -y',
36                'echo "Installing necessary packages..."',
37                'apt-get install -y curl',
38            ],
39            pre_build_commands=[
40                'echo "Fetching private API configuration..."',
41                # Replace with your actual command to fetch configs
42                'curl -o config.json https://internal-api.example.com/config',
43            ],
44            # Optionally override the default completeness query interval:
45            # completeness_query_interval=Duration.seconds(45)
46        )
47
48        # Use in ECS
49        cluster = ecs.Cluster(self, "EcsCluster", vpc=vpc)
50
51        task_definition = ecs.FargateTaskDefinition(self, "TaskDef",
52            cpu=512,
53            memory_limit_mib=1024,
54        )
55
56        task_definition.node.add_dependency(docker_builder)
57
58        task_definition.add_container("Container",
59            image=docker_builder.container_image,
60            logging=ecs.LogDriver.aws_logs(stream_prefix="MyApp"),
61        )
62
63        ecs.FargateService(self, "FargateService",
64            cluster=cluster,
65            task_definition=task_definition,
66        )

In this advanced example:

• VPC Configuration: The CodeBuild project is configured to run inside a VPC with specified security groups and subnet selection, allowing it to access internal resources such as a private API endpoint.
• Custom Install and Pre-Build Commands: The installCommands and preBuildCommands properties are used to install necessary packages and fetch configuration files from a private API before building the Docker image.
• Access to Internal APIs: By running inside a VPC and configuring the security groups appropriately, the CodeBuild project can access private endpoints not accessible over the public internet.

---

How It Works

1. Docker Source: Packages the source code or Dockerfile specified in the path property as an S3 asset.
2. CodeBuild Project:
   • Uses the packaged asset and buildArgs to build the Docker image.
   • Executes any custom installCommands and preBuildCommands during the build process.
   • 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) which polls at the interval specified by completenessQueryInterval (defaulting to 30 seconds if not provided).
4. Outputs:
   • .containerImage: Returns the Docker image for ECS.
   • .dockerImageCode: Returns the Docker image code for Lambda.

---

IAM Permissions

The construct automatically grants permissions for:

• CodeBuild:
  • Pull and push images to ECR.
  • Access to AWS Secrets Manager if dockerLoginSecretArn is provided.
  • Access to the KMS key for encryption.
• Lambda Functions:
  • Start and monitor CodeBuild builds.
  • Access CloudWatch Logs.
  • Access to the KMS key for encryption.
  • Pull and push images to ECR.

---

Notes

• Build Arguments: Pass custom arguments via buildArgs as --build-arg flags. CDK tokens can be used to inject dynamic values resolved at deployment time.
• Custom Commands: Use installCommands and preBuildCommands to run custom shell commands during the build process. This can be useful for installing dependencies or fetching configuration files.
• VPC Configuration: If your build process requires access to resources within a VPC, you can specify the VPC, security groups, and subnet selection.
• Docker Login: If you need to log in to a private Docker registry before building the image, provide the ARN of a secret in AWS Secrets Manager containing the Docker credentials.
• ECR Repository: Automatically creates an ECR repository with lifecycle rules to manage image retention, encryption with a KMS key, and image scanning on push.
• Build Query Interval: The polling frequency for checking build completion can be customized via the completenessQueryInterval property.

---

Troubleshooting

1. Build Errors: Check the CodeBuild logs in CloudWatch Logs for detailed error messages.
2. Lambda Errors: Check the onEvent and isComplete Lambda function logs in CloudWatch Logs.
3. Permissions: Ensure IAM roles have the required permissions for CodeBuild, ECR, Secrets Manager, and KMS if applicable.
4. Network Access: If the build requires network access (e.g., to download dependencies or access internal APIs), ensure that the VPC configuration allows necessary network connectivity, and adjust security group rules accordingly.

---

Support

For issues or feature requests, please open an issue on GitHub.

---

Reference Links

---

License

This project is licensed under the terms of the MIT license.

---

Acknowledgements

• Inspired by the need for more dynamic Docker asset management in AWS CDK.
• Thanks to the AWS CDK community for their continuous support and contributions.

---

Feel free to reach out if you have any questions or need further assistance!