feat(cdk-assets-lib): support --build-context flag for docker image builds (#1128)

Add support for `dockerBuildContexts` in the cloud assembly schema and
docker build logic. This allows passing additional named build contexts
to the `docker build` command via the `--build-context` flag, enabling
multi-context Docker builds where files can be sourced from directories,
URLs, or other Docker images outside the primary build directory.

This PR adds the CLI changes required to address
aws/aws-cdk#31598

---
By submitting this pull request, I confirm that my contribution is made
under the terms of the Apache-2.0 license

Co-authored-by: Ian Hou <45278651+iankhou@users.noreply.github.com>

Author: cogwirrel

packages/@aws-cdk/cdk-assets-lib/lib/private/docker.ts

@@ -20,6 +20,7 @@ interface BuildOptions {
   readonly target?: string;
   readonly file?: string;
   readonly buildArgs?: Record<string, string>;
+  readonly buildContexts?: Record<string, string>;
   readonly buildSecrets?: Record<string, string>;
   readonly buildSsh?: string;
   readonly networkMode?: string;
@@ -107,6 +108,9 @@ export class Docker {
       ...flatten(
         Object.entries(options.buildArgs || {}).map(([k, v]) => ['--build-arg', `${k}=${v}`]),
       ),
+      ...flatten(
+        Object.entries(options.buildContexts || {}).map(([k, v]) => ['--build-context', `${k}=${v}`]),
+      ),
       ...flatten(
         Object.entries(options.buildSecrets || {}).map(([k, v]) => ['--secret', `id=${k},${v}`]),
       ),

packages/@aws-cdk/cdk-assets-lib/lib/private/handlers/container-images.ts

@@ -232,6 +232,7 @@ class ContainerImageBuilder {
       directory: fullPath,
       tag: localTagName,
       buildArgs: source.dockerBuildArgs,
+      buildContexts: source.dockerBuildContexts,
       buildSecrets: source.dockerBuildSecrets,
       buildSsh: source.dockerBuildSsh,
       target: source.dockerBuildTarget,

packages/@aws-cdk/cdk-assets-lib/test/docker-images.test.ts

@@ -275,6 +275,29 @@ beforeEach(() => {
       },
     }),
     '/platform-arm64/cdk.out/dockerdir/Dockerfile': 'FROM scratch',
+    '/build-contexts/cdk.out/assets.json': JSON.stringify({
+      version: Manifest.version(),
+      dockerImages: {
+        theAsset: {
+          source: {
+            directory: 'dockerdir',
+            dockerBuildContexts: {
+              mycontext: '../context',
+              alpine: 'docker-image://alpine:latest',
+            },
+          },
+          destinations: {
+            theDestination: {
+              region: 'us-north-50',
+              assumeRoleArn: 'arn:aws:role',
+              repositoryName: 'repo',
+              imageTag: 'nopqr',
+            },
+          },
+        },
+      },
+    }),
+    '/build-contexts/cdk.out/dockerdir/Dockerfile': 'FROM scratch',
   });
   aws = new MockAws();
   mockEcr.on(DescribeImagesCommand).rejects(err);
@@ -610,6 +633,41 @@ describe('with a complete manifest', () => {
     expectAllSpawns();
     expect(true).toBeTruthy(); // Expect no exception, satisfy linter
   });
+
+  test('build with buildContexts option', async () => {
+    pub = new AssetPublishing(AssetManifest.fromPath(mockfs.path('/build-contexts/cdk.out')), {
+      aws,
+    });
+    const buildContextsDockerpath = '/build-contexts/cdk.out/dockerdir';
+
+    const expectAllSpawns = mockSpawn(
+      {
+        commandLine: ['docker', 'login', '--username', 'user', '--password-stdin', 'proxy.com'],
+      },
+      { commandLine: ['docker', 'inspect', 'cdkasset-theasset'], exitCode: 1 },
+      {
+        commandLine: [
+          'docker',
+          'build',
+          '--build-context',
+          'mycontext=../context',
+          '--build-context',
+          'alpine=docker-image://alpine:latest',
+          '--tag',
+          'cdkasset-theasset',
+          '.',
+        ],
+        cwd: buildContextsDockerpath,
+      },
+      { commandLine: ['docker', 'tag', 'cdkasset-theasset', '12345.amazonaws.com/repo:nopqr'] },
+      { commandLine: ['docker', 'push', '12345.amazonaws.com/repo:nopqr'] },
+    );
+
+    await pub.publish();
+
+    expectAllSpawns();
+    expect(true).toBeTruthy(); // Expect no exception, satisfy linter
+  });
 });
 
 describe('external assets', () => {

packages/@aws-cdk/cdk-assets-lib/test/private/docker.test.ts

@@ -115,5 +115,29 @@ describe('Docker', () => {
         }),
       );
     });
+
+    test('includes --build-context flags when buildContexts are provided', async () => {
+      const spy = makeShellExecuteMock(() => undefined);
+
+      await docker.build({
+        directory: 'foo',
+        tag: 'bar',
+        buildContexts: {
+          mycontext: '../context',
+          alpine: 'docker-image://alpine:latest',
+        },
+      });
+
+      expect(spy.mock.calls[0][0]).toEqual([
+        'build',
+        '--build-context',
+        'mycontext=../context',
+        '--build-context',
+        'alpine=docker-image://alpine:latest',
+        '--tag',
+        'bar',
+        '.',
+      ]);
+    });
   });
 });

packages/@aws-cdk/cloud-assembly-api/lib/assets.ts

@@ -12,6 +12,7 @@ export const ASSET_RESOURCE_METADATA_ENABLED_CONTEXT = 'aws:cdk:enable-asset-met
 export const ASSET_RESOURCE_METADATA_PATH_KEY = 'aws:asset:path';
 export const ASSET_RESOURCE_METADATA_DOCKERFILE_PATH_KEY = 'aws:asset:dockerfile-path';
 export const ASSET_RESOURCE_METADATA_DOCKER_BUILD_ARGS_KEY = 'aws:asset:docker-build-args';
+export const ASSET_RESOURCE_METADATA_DOCKER_BUILD_CONTEXTS_KEY = 'aws:asset:docker-build-contexts';
 export const ASSET_RESOURCE_METADATA_DOCKER_BUILD_SECRETS_KEY = 'aws:asset:docker-build-secrets';
 export const ASSET_RESOURCE_METADATA_DOCKER_BUILD_SSH_KEY = 'aws:asset:docker-build-ssh';
 export const ASSET_RESOURCE_METADATA_DOCKER_BUILD_TARGET_KEY = 'aws:asset:docker-build-target';

packages/@aws-cdk/cloud-assembly-schema/lib/assets/docker-image-asset.ts

@@ -70,6 +70,15 @@ export interface DockerImageSource {
    */
   readonly dockerBuildArgs?: { [name: string]: string };
 
+  /**
+   * Additional build contexts
+   *
+   * Only allowed when `directory` is set.
+   *
+   * @default - No additional build contexts
+   */
+  readonly dockerBuildContexts?: { [name: string]: string };
+
   /**
    * SSH agent socket or keys
    *

packages/@aws-cdk/cloud-assembly-schema/lib/cloud-assembly/metadata-schema.ts

@@ -161,6 +161,13 @@ export interface ContainerImageAssetMetadataEntry extends BaseAssetMetadataEntry
    */
   readonly buildArgs?: { [key: string]: string };
 
+  /**
+   * Build contexts to pass to the `docker build` command
+   *
+   * @default no build contexts are passed
+   */
+  readonly buildContexts?: { [key: string]: string };
+
   /**
    * SSH agent socket or keys to pass to the `docker build` command
    *

packages/@aws-cdk/cloud-assembly-schema/schema/assets.schema.json

@@ -168,6 +168,13 @@
                         "type": "string"
                     }
                 },
+                "dockerBuildContexts": {
+                    "description": "Additional build contexts\n\nOnly allowed when `directory` is set. (Default - No additional build contexts)",
+                    "type": "object",
+                    "additionalProperties": {
+                        "type": "string"
+                    }
+                },
                 "dockerBuildSsh": {
                     "description": "SSH agent socket or keys\n\nRequires building with docker buildkit. (Default - No ssh flag is set)",
                     "type": "string"

packages/@aws-cdk/cloud-assembly-schema/schema/cloud-assembly.schema.json

@@ -232,6 +232,13 @@
                         "type": "string"
                     }
                 },
+                "buildContexts": {
+                    "description": "Build contexts to pass to the `docker build` command (Default no build contexts are passed)",
+                    "type": "object",
+                    "additionalProperties": {
+                        "type": "string"
+                    }
+                },
                 "buildSsh": {
                     "description": "SSH agent socket or keys to pass to the `docker build` command (Default no ssh arg is passed)",
                     "type": "string"

packages/@aws-cdk/cloud-assembly-schema/schema/version.json

@@ -1,5 +1,5 @@
 {
-  "schemaHash": "22c511a4ddd185761b8d56ac21d48c8384873ffe4b953b3567654746f8dd26f1",
+  "schemaHash": "25d8ad154190878ec8a9e970fa21a0e182fa834304913d43be86f9b0613271f5",
   "$comment": "Do not hold back the version on additions: jsonschema validation of the manifest by the consumer will trigger errors on unexpected fields.",
-  "revision": 52
+  "revision": 53
 }