token-injectable-docker-builder 1.13.3 → 2.0.0

package/README.md

@@ -16,13 +16,14 @@ For example, a Next.js frontend Docker image may require an API Gateway URL as a
 
 - **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.
-- **Shared Provider (Singleton)**: When building multiple Docker images in the same stack, use `TokenInjectableDockerBuilderProvider` to share a single pair of Lambda functions across all builders, reducing resource overhead from ~2 Lambdas per image to 2 Lambdas total.
+- **Per-stack Lambda singleton**: Every builder in a stack automatically shares one pair of `onEvent` / `isComplete` Lambdas via `TokenInjectableDockerBuilderProvider`. Two builders cost the same Lambda overhead as one.
+- **Cross-region replication**: Pass `replicaRegions: ['us-west-2', ...]` to replicate the built image to additional regions via ECR's native replication. Use `builder.dockerImageCodeFor(scope, region)` / `builder.containerImageFor(scope, region)` in a consumer stack in another region. The custom resource waits for replicas to land before signalling complete, so downstream stacks deploy safely.
 - **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 (keeps only 3 images by default, configurable via `maxImageCount`) and encryption.
+- **Safe ECR retention by default**: Untagged images expire after 30 days; tagged images are never deleted (Lambda pins by digest, so deleting an in-use tag would break the next config update).
 - **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).
+- **Configurable Build Polling**: Tune how often the provider checks for build completion via `TokenInjectableDockerBuilderProvider.getOrCreate(this, { queryInterval })` (defaults to 30 seconds).
 - **Custom Dockerfile**: Specify a custom Dockerfile name via the `file` property (e.g. `Dockerfile.production`), allowing multiple Docker images from the same source directory.
 - **ECR Docker Layer Caching**: By default, builds use `docker buildx` with ECR as a remote cache backend, reducing build times by reusing layers across deploys. Set `cacheDisabled: true` to force a clean build from scratch.
 - **Platform Support**: Build images for `linux/amd64` (x86_64) or `linux/arm64` (Graviton) using native CodeBuild instances — no emulation, no QEMU. ARM builds are faster and cheaper.
@@ -55,19 +56,19 @@ pip install token-injectable-docker-builder
 
 ### `TokenInjectableDockerBuilderProvider`
 
-A singleton construct that creates the `onEvent` and `isComplete` Lambda functions once per stack. When building multiple Docker images, share a single provider to avoid creating redundant Lambda functions.
+A singleton construct that creates the `onEvent` and `isComplete` Lambda functions once per stack. Every `TokenInjectableDockerBuilder` in the same stack automatically reuses this singleton, so two builders cost the same Lambda overhead as one. You only need to call this yourself if you want to customize `queryInterval`.
 
 #### Static Methods
 
 | Method | Description |
 |---|---|
-| `getOrCreate(scope, props?)` | Returns the existing provider for the stack, or creates one if it doesn't exist. |
+| `getOrCreate(scope, props?)` | Returns the existing provider for the stack, or creates one if it doesn't exist. Called automatically by every `TokenInjectableDockerBuilder`. |
 
 #### Properties in `TokenInjectableDockerBuilderProviderProps`
 
 | Property | Type | Required | Description |
 |---|---|---|---|
-| `queryInterval` | `Duration` | No | How often the provider polls for build completion. Defaults to `Duration.seconds(30)`. |
+| `queryInterval` | `Duration` | No | How often the provider polls for build completion. Defaults to `Duration.seconds(30)`. To override, call `getOrCreate` explicitly **before** creating any builders. |
 
 #### Instance Properties
 
@@ -79,7 +80,7 @@ A singleton construct that creates the `onEvent` and `isComplete` Lambda functio
 
 | Method | Description |
 |---|---|
-| `registerProject(project, ecrRepo, encryptionKey?)` | Grants the shared Lambdas permission to start builds and access ECR for a specific CodeBuild project. Called automatically when `provider` is passed to `TokenInjectableDockerBuilder`. |
+| `registerProject(project, ecrRepo, encryptionKey?)` | Grants the shared Lambdas permission to start builds and access ECR for a specific CodeBuild project. Called automatically by `TokenInjectableDockerBuilder`'s constructor. |
 
 ---
 
@@ -97,7 +98,7 @@ A singleton construct that creates the `onEvent` and `isComplete` Lambda functio
 |----------------------------|-----------------------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
 | `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](https://docs.docker.com/build/building/variables/).                             |
-| `provider`                 | `TokenInjectableDockerBuilderProvider` | No | Shared provider for the custom resource Lambdas. Use `TokenInjectableDockerBuilderProvider.getOrCreate(this)` to share a single pair of Lambdas across all builders in the same stack. When omitted, each builder creates its own Lambdas (original behavior). |
+| `provider`                 | `TokenInjectableDockerBuilderProvider` | No | Shared provider for the custom resource Lambdas. Defaults to the per-stack singleton — `TokenInjectableDockerBuilderProvider.getOrCreate(this)`. Only pass this explicitly when you need a non-default `queryInterval`. |
 | `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.                                                                                                                                                                  |
@@ -105,63 +106,64 @@ A singleton construct that creates the `onEvent` and `isComplete` Lambda functio
 | `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)`. Ignored when `provider` is set (the provider's `queryInterval` is used instead).                   |
 | `exclude`                  | `string[]`                  | No       | A list of file paths in the Docker directory to exclude from the S3 asset bundle. If a `.dockerignore` file is present in the source directory, its contents will be used if this prop is not set. Defaults to an empty list or `.dockerignore` contents.                                    |
 | `file`                     | `string`                    | No       | The name of the Dockerfile to use for the build. Passed as `--file` to `docker build`. Useful when a project has multiple Dockerfiles (e.g. `Dockerfile.production`, `Dockerfile.admin`). Defaults to `Dockerfile`.                                                                        |
 | `cacheDisabled`           | `boolean`                   | No       | When `true`, disables Docker layer caching. Every build runs from scratch. Use for debugging, corrupted cache, or major dependency changes. Defaults to `false`.                                                                                                                          |
 | `platform`                 | `'linux/amd64' \| 'linux/arm64'` | No  | Target platform for the Docker image. When set to `'linux/arm64'`, uses a native ARM/Graviton CodeBuild instance for fast builds without emulation. Defaults to `'linux/amd64'`.                                                                                                      |
 | `buildLogGroup`            | `ILogGroup`                 | No       | CloudWatch log group for CodeBuild build logs. When provided with RETAIN removal policy, logs survive rollbacks and stack deletion. If not provided, CodeBuild uses default logging (logs are deleted on rollback).                                                                          |
-| `maxImageCount`              | `number`                  | No       | Maximum number of images to retain in the ECR repository. A lifecycle rule automatically expires older images beyond this count. Defaults to `3`. |
+| `retainBuildLogs`          | `boolean`                   | No       | When `true`, the construct creates a CloudWatch log group at `/docker-builder/<projectName>` **outside** of CloudFormation and routes CodeBuild output there. Because the log group is managed imperatively, it survives stack rollbacks. 7-day retention applies. Defaults to `false`. |
 | `ecrPullThroughCachePrefixes` | `string[]`               | No       | ECR pull-through cache repository prefixes to grant pull access to. Use when your Dockerfile references base images from ECR pull-through cache (e.g. `docker-hub/library/node:20-slim`, `ghcr/org/image:tag`). The CodeBuild role is granted `ecr:BatchGetImage`, `ecr:GetDownloadUrlForLayer`, and `ecr:BatchCheckLayerAvailability` on repositories matching each prefix. Example: `['docker-hub', 'ghcr']`. Defaults to no pull-through cache access. |
+| `replicaRegions`           | `string[]`                  | No       | Additional regions to replicate the image to via ECR's native registry replication. Enables `dockerImageCodeFor(scope, region)` / `containerImageFor(scope, region)` for consumer stacks in those regions. See [Cross-Region Replication](#cross-region-replication) for details and caveats. Defaults to `[]` (no replication). |
 
 #### Instance Properties
 
 | Property | Type | Description |
 |---|---|---|
-| `containerImage` | `ContainerImage` | An ECS-compatible container image referencing the built Docker image. |
-| `dockerImageCode` | `DockerImageCode` | A Lambda-compatible Docker image code referencing the built Docker image. |
+| `containerImage` | `ContainerImage` | An ECS-compatible container image referencing the built Docker image **in the primary region**. |
+| `dockerImageCode` | `DockerImageCode` | A Lambda-compatible Docker image code referencing the built Docker image **in the primary region**. |
+| `repositoryName` | `string` | The ECR repository name (same name across all replica regions). |
+| `imageTag` | `string` | The resolved image tag (CFN token; available at deploy time). |
+
+#### Instance Methods (cross-region)
+
+| Method | Description |
+|---|---|
+| `containerImageFor(scope, region)` | Returns an ECS `ContainerImage` pointing at the same tag in `region`. Requires the region to be the primary or in `replicaRegions`. |
+| `dockerImageCodeFor(scope, region)` | Returns a Lambda `DockerImageCode` pointing at the same tag in `region`. Same constraints as above. |
+| `repositoryUriFor(region)` | Returns the regional ECR URI `<account>.dkr.ecr.<region>.amazonaws.com/<repoName>` as a string token. |
 
 ---
 
 ## Usage Examples
 
-### Shared Provider (Recommended for Multiple Images)
+### Multiple Images in One Stack
 
-When building multiple Docker images in the same stack, use a shared provider to avoid creating redundant Lambda functions. Without a shared provider, each builder creates 2 Lambdas + 1 Provider framework Lambda. With 10 images, that's 30 Lambdas. A shared provider reduces this to just 3 Lambdas total.
+Builders in the same stack automatically share a single pair of `onEvent` / `isComplete` Lambdas — there is no per-builder Lambda overhead. Just instantiate as many builders as you need.
 
 #### TypeScript/NPM Example
 
 ```typescript
 import * as cdk from 'aws-cdk-lib';
-import {
-  TokenInjectableDockerBuilder,
-  TokenInjectableDockerBuilderProvider,
-} from 'token-injectable-docker-builder';
+import { TokenInjectableDockerBuilder } from 'token-injectable-docker-builder';
 import * as ecs from 'aws-cdk-lib/aws-ecs';
 
 export class MultiImageStack extends cdk.Stack {
   constructor(scope: cdk.App, id: string, props?: cdk.StackProps) {
     super(scope, id, props);
 
-    // Create a shared provider once per stack (singleton)
-    const provider = TokenInjectableDockerBuilderProvider.getOrCreate(this);
-
-    // Build multiple Docker images sharing the same provider
+    // Each builder reuses the same per-stack provider automatically.
     const apiBuilder = new TokenInjectableDockerBuilder(this, 'ApiImage', {
       path: './src/api',
-      provider,
     });
 
     const workerBuilder = new TokenInjectableDockerBuilder(this, 'WorkerImage', {
       path: './src/worker',
-      provider,
     });
 
-    const frontendBuilder = new TokenInjectableDockerBuilder(this, 'FrontendImage', {
+    new TokenInjectableDockerBuilder(this, 'FrontendImage', {
       path: './src/frontend',
       buildArgs: { API_URL: 'https://api.example.com' },
       platform: 'linux/arm64', // Build natively on Graviton
-      provider,
     });
 
     // Use in ECS task definitions
@@ -176,36 +178,48 @@ export class MultiImageStack extends cdk.Stack {
 
 ```python
 from aws_cdk import aws_ecs as ecs, core as cdk
-from token_injectable_docker_builder import (
-    TokenInjectableDockerBuilder,
-    TokenInjectableDockerBuilderProvider,
-)
+from token_injectable_docker_builder import TokenInjectableDockerBuilder
 
 class MultiImageStack(cdk.Stack):
     def __init__(self, scope: cdk.App, id: str, **kwargs):
         super().__init__(scope, id, **kwargs)
 
-        # Create a shared provider once per stack (singleton)
-        provider = TokenInjectableDockerBuilderProvider.get_or_create(self)
-
-        # Build multiple Docker images sharing the same provider
+        # Each builder reuses the same per-stack provider automatically.
         api_builder = TokenInjectableDockerBuilder(self, "ApiImage",
             path="./src/api",
-            provider=provider,
         )
 
         worker_builder = TokenInjectableDockerBuilder(self, "WorkerImage",
             path="./src/worker",
-            provider=provider,
         )
 
-        frontend_builder = TokenInjectableDockerBuilder(self, "FrontendImage",
+        TokenInjectableDockerBuilder(self, "FrontendImage",
             path="./src/frontend",
             build_args={"API_URL": "https://api.example.com"},
-            provider=provider,
         )
 ```
 
+#### Overriding `queryInterval`
+
+If you need to tune how often the provider polls for build completion, create the provider singleton explicitly **before** instantiating any builders:
+
+```typescript
+import { Duration } from 'aws-cdk-lib';
+import {
+  TokenInjectableDockerBuilder,
+  TokenInjectableDockerBuilderProvider,
+} from 'token-injectable-docker-builder';
+
+const provider = TokenInjectableDockerBuilderProvider.getOrCreate(this, {
+  queryInterval: Duration.seconds(15),
+});
+
+new TokenInjectableDockerBuilder(this, 'ApiImage', {
+  path: './src/api',
+  provider, // optional — the builder would resolve the same singleton anyway
+});
+```
+
 ### 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.
@@ -234,8 +248,6 @@ export class SimpleStack extends cdk.Stack {
       buildArgs: {
         API_URL: api.url, // Pass the API Gateway URL as a build argument
       },
-      // Optionally override the default completeness query interval:
-      // completenessQueryInterval: cdk.Duration.seconds(45),
     });
 
     // Use in ECS
@@ -287,8 +299,6 @@ class SimpleStack(cdk.Stack):
             build_args={
                 "API_URL": api.url,  # Pass the API Gateway URL as a build argument
             },
-            # Optionally override the default completeness query interval:
-            # completeness_query_interval=Duration.seconds(45)
         )
 
         # Use in ECS
@@ -363,8 +373,6 @@ export class AdvancedStack extends cdk.Stack {
         // Replace with your actual command to fetch configs
         'curl -o config.json https://internal-api.example.com/config',
       ],
-      // Optionally override the default completeness query interval:
-      // completenessQueryInterval: cdk.Duration.seconds(45),
     });
 
     // Use in ECS
@@ -432,8 +440,6 @@ class AdvancedStack(cdk.Stack):
                 # Replace with your actual command to fetch configs
                 'curl -o config.json https://internal-api.example.com/config',
             ],
-            # Optionally override the default completeness query interval:
-            # completeness_query_interval=Duration.seconds(45)
         )
 
         # Use in ECS
@@ -463,24 +469,19 @@ When your Dockerfile uses base images from an ECR pull-through cache (e.g. to av
 
 ```typescript
 import * as cdk from 'aws-cdk-lib';
-import {
-  TokenInjectableDockerBuilder,
-  TokenInjectableDockerBuilderProvider,
-} from 'token-injectable-docker-builder';
+import { TokenInjectableDockerBuilder } from 'token-injectable-docker-builder';
 import * as lambda from 'aws-cdk-lib/aws-lambda';
 
 export class PullThroughCacheStack extends cdk.Stack {
   constructor(scope: cdk.App, id: string, props?: cdk.StackProps) {
     super(scope, id, props);
 
-    const provider = TokenInjectableDockerBuilderProvider.getOrCreate(this);
     const node20Slim = `${this.account}.dkr.ecr.${this.region}.amazonaws.com/docker-hub/library/node:20-slim`;
 
     const apiImage = new TokenInjectableDockerBuilder(this, 'ApiImage', {
       path: './src',
       file: 'api/Dockerfile',
       platform: 'linux/arm64',
-      provider,
       buildArgs: { NODE_20_SLIM: node20Slim },
       ecrPullThroughCachePrefixes: ['docker-hub', 'ghcr'],
     });
@@ -503,6 +504,58 @@ In this advanced example:
 
 ---
 
+### Cross-Region Replication
+
+Set `replicaRegions` to make the built image available in additional regions, then reference it from a consumer stack in any of those regions.
+
+```typescript
+import * as cdk from 'aws-cdk-lib';
+import { TokenInjectableDockerBuilder } from 'token-injectable-docker-builder';
+import * as lambda from 'aws-cdk-lib/aws-lambda';
+
+const app = new cdk.App();
+
+// Builder stack — us-east-1
+const builderStack = new cdk.Stack(app, 'BuilderStack', {
+  env: { account: '123456789012', region: 'us-east-1' },
+  crossRegionReferences: true,
+});
+
+const apiImage = new TokenInjectableDockerBuilder(builderStack, 'ApiImage', {
+  path: './src/api',
+  replicaRegions: ['us-west-2', 'eu-west-1'],
+});
+
+// Consumer stack — us-west-2
+const consumerStack = new cdk.Stack(app, 'ConsumerStack', {
+  env: { account: '123456789012', region: 'us-west-2' },
+  crossRegionReferences: true,
+});
+
+new lambda.DockerImageFunction(consumerStack, 'ApiLambda', {
+  code: apiImage.dockerImageCodeFor(consumerStack, 'us-west-2'),
+});
+```
+
+**How it works**
+
+1. The builder pushes to its primary-region ECR repository as usual.
+2. The provider singleton manages a single registry-replication custom resource that calls `PutReplicationConfiguration` with merged rules (one rule per unique destination set, filtered to each managed repository name).
+3. ECR asynchronously replicates the image to every region in `replicaRegions`. Most images replicate in under 30 minutes; rare cases take longer.
+4. The build's `isComplete` Lambda polls each replica region's ECR via `BatchGetImage` and only returns `IsComplete=true` once every replica has the tag. The Provider's `totalTimeout` is bumped to 1 hour to accommodate replication lag.
+5. The consumer stack's `dockerImageCodeFor` / `containerImageFor` imports the replicated repository by name in the consumer's region and references the tag via CDK's cross-region SSM mechanism.
+
+**Caveats to read before enabling**
+
+- **Stacks must have a concrete `env`**: env-agnostic stacks (where `region` is a token) don't work with `crossRegionReferences`. Pass `env: { account, region }` explicitly on both builder and consumer stacks.
+- **Replicas don't inherit settings**: ECR replication does NOT copy encryption (KMS), lifecycle policies, or repository policies. Replicated repos default to AES-256 encryption with no lifecycle rules. If you need stricter replica configuration, set up [ECR repository creation templates](https://docs.aws.amazon.com/AmazonECR/latest/userguide/repository-creation-templates.html) separately.
+- **Replicas persist on stack delete**: AWS does NOT auto-delete replicated repositories when the source replication rule is removed. After `cdk destroy`, manually delete leftover repos: `aws ecr delete-repository --region <replica> --repository-name <name> --force`.
+- **Registry-level limits enforced at synth time**: ECR allows 10 rules per registry and 25 unique destinations across all rules per AWS account. The construct enforces both caps **at synth time** — `cdk synth` will throw a clear error if the union of `replicaRegions` across all builders in the stack would exceed either limit, instead of failing at deploy time inside the replication CR. Rule-grouping by destination set keeps you under the 10-rules cap until you have more than 10 *distinct* destination sets (e.g. ten builders each replicating to a different single region). Note that this is a best-effort check: rules created outside this construct (other stacks, manual setup) aren't visible at synth time, so the runtime API can still surface them.
+- **Cross-partition is unsupported**: e.g. `us-east-1` → `cn-north-1` won't work. The construct will throw at synth time when both partition values are concrete and differ.
+- **Replication latency**: deploys can extend by up to ~30 min in rare cases while `isComplete` waits for replicas. The CDK Provider framework caps `totalTimeout` at 2 hours.
+
+---
+
 ## How It Works
 
 1. **Docker Source**: Packages the source code or Dockerfile specified in the `path` property as an S3 asset.
@@ -511,22 +564,25 @@ In this advanced example:
    - Executes any custom `installCommands` and `preBuildCommands` during the build process.
    - Pushes the image to an ECR repository.
    - By default, uses `docker buildx` with ECR registry cache to speed up builds.
-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).
-   - When using a shared `provider`, the same pair of Lambdas handles all builders in the stack.
+3. **Custom Resource** (one pair of Lambdas per stack):
+   - Triggers the build using `onEvent`.
+   - Monitors build status using `isComplete`, polling at the interval set on the provider singleton (defaults to 30 seconds; override via `TokenInjectableDockerBuilderProvider.getOrCreate(this, { queryInterval })`).
+   - The same Lambda pair handles every builder in the stack — they are not duplicated per builder.
 4. **Outputs**:
    - `.containerImage`: Returns the Docker image for ECS.
    - `.dockerImageCode`: Returns the Docker image code for Lambda.
 
 ### Resource Comparison
 
-| Scenario | Lambdas Created | CodeBuild Projects | ECR Repos |
+The provider singleton means a stack's Lambda overhead is fixed — adding more builders only adds CodeBuild projects and ECR repositories.
+
+| Scenario | Lambdas (total) | CodeBuild Projects | ECR Repos |
 |---|---|---|---|
-| 5 images, no shared provider | 15 (3 per image) | 5 | 5 |
-| 5 images, shared provider | 3 (shared) | 5 | 5 |
-| 10 images, no shared provider | 30 (3 per image) | 10 | 10 |
-| 10 images, shared provider | 3 (shared) | 10 | 10 |
+| 1 image | 5 (2 user + 3 framework) | 1 | 1 |
+| 5 images | 5 | 5 | 5 |
+| 10 images | 5 | 10 | 10 |
+
+The 3 framework Lambdas are CDK's [`Provider`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.custom_resources.Provider.html) framework internals (`framework.onEvent`, `framework.isComplete`, `framework.onTimeout`).
 
 ---
 
@@ -539,40 +595,69 @@ The construct automatically grants permissions for:
   - Pull from ECR pull-through cache prefixes when `ecrPullThroughCachePrefixes` is provided (e.g. `['docker-hub', 'ghcr']`).
   - Access to AWS Secrets Manager if `dockerLoginSecretArn` is provided.
   - Access to the KMS key for encryption.
-- **Lambda Functions** (per-instance or shared provider):
+- **Shared Provider Lambdas** (one pair per stack):
   - Start and monitor CodeBuild builds.
   - Access CloudWatch Logs.
   - Access to the KMS key for encryption.
   - Pull and push images to ECR.
 
-When using the shared provider, `registerProject()` incrementally adds IAM permissions for each CodeBuild project and ECR repository.
+Every new builder calls `provider.registerProject()` under the hood, incrementally adding `codebuild:StartBuild` for its project ARN and `ecr:PullPush` for its repository.
 
 ---
 
 ## Notes
 
-- **Shared Provider**: Use `TokenInjectableDockerBuilderProvider.getOrCreate(this)` when building multiple images in the same stack. This is the recommended approach for stacks with 2+ Docker images.
+- **Provider Singleton**: One pair of `onEvent` / `isComplete` Lambdas is created the first time a builder is instantiated in a stack and reused by every subsequent builder in the same stack. You generally do not need to touch `TokenInjectableDockerBuilderProvider` directly — only call `getOrCreate` yourself if you want to change `queryInterval`.
 - **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 (keeps 3 images by default, configurable via `maxImageCount`), 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 (per-instance) or `queryInterval` (shared provider).
+- **ECR Retention (safe by default)**: Tagged images are kept indefinitely; untagged images are removed after 30 days. There is no count-based expiration — Lambda pins images by digest internally and count-based deletion would silently remove an image that an in-use Lambda is still pinned to, breaking the next config update with `Image ID cannot be found`.
+- **Build Query Interval**: Tune polling frequency with `TokenInjectableDockerBuilderProvider.getOrCreate(this, { queryInterval })`. Call this **before** instantiating any builders, otherwise the builder will create the singleton with the default 30 second interval.
 - **Custom Dockerfile**: Use the `file` property to specify a Dockerfile other than the default `Dockerfile`. This is passed as the `--file` flag to `docker build`.
 - **Docker Layer Caching**: By default, builds use ECR as a remote cache backend (via `docker buildx`), which can reduce build times by up to 25%. Set `cacheDisabled: true` when you need a clean build—for example, when debugging, the cache is corrupted, or after major dependency upgrades.
 - **Platform / Architecture**: Set `platform: 'linux/arm64'` to build ARM64/Graviton images using a native ARM CodeBuild instance. Defaults to `'linux/amd64'` (x86_64). Native builds are faster and cheaper than cross-compilation with QEMU.
-- **Build Log Retention**: Pass `buildLogGroup` with a log group that has RETAIN removal policy to ensure build logs survive CloudFormation rollbacks and stack deletion.
+- **Build Log Retention**: Pass `buildLogGroup` with a log group that has RETAIN removal policy, or set `retainBuildLogs: true` to let the construct manage a `/docker-builder/<projectName>` log group imperatively (survives rollbacks; 7-day retention).
 - **ECR Pull-Through Cache**: When using ECR pull-through cache for base images (e.g. to avoid Docker Hub rate limits), pass `ecrPullThroughCachePrefixes: ['docker-hub', 'ghcr']` so the CodeBuild role can pull from those cached repositories. Your ECR registry must have a pull-through cache rule and registry policy configured separately.
-- **Backward Compatibility**: The `provider` prop is optional. Omitting it preserves the original behavior where each builder creates its own Lambdas. Existing code works without changes.
+
+### Migrating from v1
+
+**Recipe for the common case** (you're on `^1.x` and want to move to `^2.x`):
+
+```bash
+npm install token-injectable-docker-builder@^2
+```
+
+That's the entire required code change for most users. The construct handles the CFN-level migration internally.
+
+**What happens on the first `cdk deploy` after upgrading:**
+
+1. Every `BuildTriggerResource` in your stack is **replaced** by `BuildTriggerResourceV2`. CFN does this because the construct deliberately renames its internal custom resource between v1 and v2 — this is what sidesteps CFN's `Modifying service token is not allowed` rule when the CR's serviceToken changes from v1's per-instance provider to v2's singleton provider. **Without this rename, the upgrade would fail at the CFN level for users who didn't pass `provider` explicitly in v1.**
+2. Each replacement triggers **one fresh CodeBuild run per builder** (5–10 min each in parallel). Image tags transition from v1's random-UUID style to v2's deterministic-hash style.
+3. Downstream `DockerImageFunction` / `FargateTaskDefinition` resources update in place to the new tag. Lambda's blue/green update is transparent; ECS does a normal rolling deploy.
+4. v1's per-instance `OnEventHandlerFunction` / `IsCompleteHandlerFunction` / `CustomResourceProvider` Lambdas (one set per builder) are deleted. The singleton at `<Stack>/TokenInjectableDockerBuilderProvider/...` is the only provider left.
+5. ECR repositories keep their logical IDs and contents — **no images are lost**.
+
+**Behavior changes that come for free (no code edit needed):**
+
+- ECR retention switches from "keep 3 tagged images" (v1 default with `maxImageCount: 3`) to "keep all tagged images, untagged-after-30-days only". v1's count-based expiration could silently delete an image a Lambda was pinned to.
+- `imageTag` is now a deterministic SHA-256 hash of all build inputs. v1 regenerated a UUID on every synth, causing a build on every deploy; v2 only rebuilds when source / buildArgs / platform / commands actually change.
+
+**Breaking changes that may require a source edit:**
+
+- **`completenessQueryInterval`** was removed from `TokenInjectableDockerBuilderProps`. If you set it, move the value to `TokenInjectableDockerBuilderProvider.getOrCreate(this, { queryInterval })` (call before any builder; it now applies stack-wide). If you didn't set it, no edit needed.
+- **`maxImageCount`** was removed entirely. If you set it, just delete the prop from your builder props (no replacement; the behavior is now non-configurable).
+
+**This migration path is exercised end-to-end by `npm run integ-migration`** — see `test/migration/before-v1.ts` and `test/migration/after-v2.ts` for the executable recipe. The literal source-code diff between the two files is the import path; everything else is identical.
 
 ---
 
 ## Troubleshooting
 
-1. **Build Errors**: Check the CodeBuild logs in CloudWatch Logs for detailed error messages. If you pass `buildLogGroup` with RETAIN removal policy, logs persist even after rollbacks. Otherwise, logs are deleted when the CodeBuild project is removed during rollback.
-2. **Lambda Errors**: Check the `onEvent` and `isComplete` Lambda function logs in CloudWatch Logs. With a shared provider, both builders' events flow through the same Lambdas—filter by `ProjectName` in the logs.
+1. **Build Errors**: Check the CodeBuild logs in CloudWatch Logs for detailed error messages. If you pass `buildLogGroup` with RETAIN removal policy, or set `retainBuildLogs: true`, logs persist even after rollbacks. Otherwise, logs are deleted when the CodeBuild project is removed during rollback.
+2. **Lambda Errors**: Check the singleton `onEvent` and `isComplete` Lambda function logs in CloudWatch Logs (under `TokenInjectableDockerBuilderProvider/...`). All builders in the stack flow through the same Lambdas — filter by `ProjectName` in the logs to isolate a specific builder.
 3. **"Image manifest, config or layer media type not supported" (Lambda)**: Docker Buildx v0.10+ adds provenance attestations by default, producing OCI image indexes that Lambda rejects. This construct disables them with `--provenance=false --sbom=false` so images are Lambda-compatible. If you see this error, ensure you're using a recent version of the construct.
-4. **Permissions**: Ensure IAM roles have the required permissions for CodeBuild, ECR, Secrets Manager, and KMS if applicable. When using a shared provider, verify that `registerProject()` was called for each builder (this happens automatically when passing the `provider` prop).
+4. **Permissions**: Ensure IAM roles have the required permissions for CodeBuild, ECR, Secrets Manager, and KMS if applicable. `registerProject()` is called automatically by the builder's constructor — you do not need to call it manually.
 5. **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.
 
 ---

package/ecrReplication/ecrReplication.js

@@ -0,0 +1,156 @@
+const {
+    ECRClient,
+    DescribeRegistryCommand,
+    PutReplicationConfigurationCommand,
+} = require('@aws-sdk/client-ecr');
+
+const region = process.env.AWS_REGION;
+const ecr = new ECRClient({ region });
+
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function canonicalDestinationKey(destinations) {
+    return destinations
+        .map((d) => `${d.region}:${d.registryId}`)
+        .sort()
+        .join('|');
+}
+
+function ruleManagesRepo(rule, repoName) {
+    if (!rule.repositoryFilters) return false;
+    return rule.repositoryFilters.some(
+        (f) => f.filterType === 'PREFIX_MATCH' && f.filter === repoName,
+    );
+}
+
+/**
+ * Build the merged set of rules.
+ *
+ * `existingRules` is the current registry config returned by DescribeRegistry.
+ * `managedSpecs` is the array of { repositoryName, destinations[] } to (re)write.
+ * `stripNames` is the set of repo names to remove from existing rules first
+ *   (used on both Create/Update — strip the previous version of our rules
+ *   before re-emitting fresh ones — and Delete, where managedSpecs is empty
+ *   and we only want to strip).
+ *
+ * Strategy:
+ * 1. Strip out any filters matching `stripNames` from existing rules. If a
+ *    rule's filter list becomes empty, drop the rule entirely.
+ * 2. For each managedSpec, group by canonical destination set. One ECR rule
+ *    per destination set, holding all our managed repo filters that share
+ *    that destination set. This keeps us under the 10-rules-per-registry cap
+ *    until the user has more than 10 unique destination sets across all
+ *    builders in the account.
+ * 3. Preserve every other rule untouched.
+ */
+function buildMergedRules(existingRules, managedSpecs, stripNames) {
+    const stripSet = stripNames instanceof Set ? stripNames : new Set(stripNames);
+
+    const preserved = (existingRules || []).filter((rule) => {
+        if (!rule.repositoryFilters || rule.repositoryFilters.length === 0) {
+            // A rule with no filters means "replicate everything" — not ours.
+            return true;
+        }
+        const remainingFilters = rule.repositoryFilters.filter(
+            (f) => !(f.filterType === 'PREFIX_MATCH' && stripSet.has(f.filter)),
+        );
+        if (remainingFilters.length === 0) return false;
+        rule.repositoryFilters = remainingFilters;
+        return true;
+    });
+
+    const groupsByDestKey = new Map();
+    for (const spec of managedSpecs) {
+        if (!spec.destinations || spec.destinations.length === 0) continue;
+        const key = canonicalDestinationKey(spec.destinations);
+        let group = groupsByDestKey.get(key);
+        if (!group) {
+            group = { destinations: spec.destinations, repos: new Set() };
+            groupsByDestKey.set(key, group);
+        }
+        group.repos.add(spec.repositoryName);
+    }
+
+    const generated = [];
+    for (const group of groupsByDestKey.values()) {
+        generated.push({
+            destinations: group.destinations,
+            repositoryFilters: [...group.repos].map((repoName) => ({
+                filter: repoName,
+                filterType: 'PREFIX_MATCH',
+            })),
+        });
+    }
+
+    return [...preserved, ...generated];
+}
+
+async function putWithRetry(rules) {
+    const maxAttempts = 5;
+    let lastErr;
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+        try {
+            await ecr.send(new PutReplicationConfigurationCommand({
+                replicationConfiguration: { rules },
+            }));
+            return;
+        } catch (err) {
+            lastErr = err;
+            const retryable = err.name === 'LimitExceededException'
+                || err.name === 'ValidationException'
+                || err.name === 'ServerException'
+                || err.name === 'ThrottlingException';
+            if (!retryable) throw err;
+            const delay = 500 * 2 ** attempt;
+            console.warn(`PutReplicationConfiguration ${err.name}, retrying in ${delay}ms`);
+            await sleep(delay);
+        }
+    }
+    throw lastErr;
+}
+
+exports.handler = async (event) => {
+    console.log('Event:', JSON.stringify(event, null, 2));
+
+    const physicalResourceId = event.PhysicalResourceId || event.LogicalResourceId;
+    const isDelete = event.RequestType === 'Delete';
+
+    // ResourceProperties.ManagedSpecs is present on every event type — for
+    // Delete events, CFN sends the last-known property values, so we can
+    // still identify which repo names are "ours" and strip them.
+    const currentManagedSpecs = JSON.parse(
+        event.ResourceProperties?.ManagedSpecs || '[]',
+    );
+    const previousManagedSpecs = JSON.parse(
+        event.OldResourceProperties?.ManagedSpecs || '[]',
+    );
+
+    // Names to strip from existing rules: union of current and previous repo
+    // names. On Create/Update: strip the prior version of our rules and
+    // re-emit fresh ones. On Delete: strip everything we ever managed.
+    const stripNames = new Set([
+        ...currentManagedSpecs.map((s) => s.repositoryName),
+        ...previousManagedSpecs.map((s) => s.repositoryName),
+    ]);
+    const specsToWrite = isDelete ? [] : currentManagedSpecs;
+
+    const describe = await ecr.send(new DescribeRegistryCommand({}));
+    const existingRules = describe.replicationConfiguration?.rules || [];
+
+    const merged = buildMergedRules(existingRules, specsToWrite, stripNames);
+    console.log('Merged rules:', JSON.stringify(merged, null, 2));
+
+    await putWithRetry(merged);
+
+    return {
+        PhysicalResourceId: physicalResourceId,
+        Data: {
+            RulesApplied: String(merged.length),
+        },
+    };
+};
+
+// Exported for unit tests; not part of the Lambda handler contract.
+exports._internal = { buildMergedRules, canonicalDestinationKey };