feat(assets): support networking mode for DockerImageAsset (#18114)

As we are not allowed to specify networking mode for DockerImageAsset, users deploying cdk on containerized environment like Kubernetes will not be able to bundle assets without the build option `--network host`.

With this support, we are allowed to:
* [x] bundle image assets on a specific networking mode with the new `networkMode` property of `DockerImageAsset` from `aws-ecr-assets`.
* [x] bundle DockerImageFunction from aws-lambda on a specific networking mode.
* [x] bundle container images for AWS Fargate from on a specific networking mode.

Close #15516.

---

## The possible values of `--network`

According to Docker CLI, the default value for `--network` will be `default` if omitted.
```shell
$ docker build --help
Usage:  docker build [OPTIONS] PATH | URL | -
Build an image from a Dockerfile

Options:
...
--network string          Set the networking mode for the RUN instructions during build (default "default")
...
```


According to the [Docker Official Docs- API 1.25](https://docs.docker.com/engine/api/v1.25/#operation/ImageBuild):
> supported standard values are: `bridge`, `host`, `none`, and `container:<name|id>`. Any other value is taken as a custom network's name to which this container should connect to.

But according to [Source Code - docker/engine BuildKit](https://github.com/docker/engine/blob/8955d8da8951695a98eb7e15bead19d402c6eb27/builder/builder-next/builder.go#L308-L314), the value `bridge` is not accepted by BuildKit & should use the value `default` instead.

Therefore, the static values for `NetworkMode` are `default`, `host` & `none`, with 2 static functions `NetworkMode.fromContainer()` to construct a `container:<name|id>` & `NetworkMode.custom()` to construct a custom networking mode.

```
$ DOCKER_BUILDKIT=1 docker build --network=bridge .
Error response from daemon: network mode "bridge" not supported by buildkit
```

References:
* [Docker Official Docs- API 1.25](https://docs.docker.com/engine/api/v1.25/#operation/ImageBuild)
* [Docker Official Docs - Use the default bridge network](https://docs.docker.com/network/bridge/#use-the-default-bridge-network)
* [Source Code - docker/engine BuildKit](https://github.com/docker/engine/blob/8955d8da8951695a98eb7e15bead19d402c6eb27/builder/builder-next/builder.go#L308-L314)


---
## Builder experience with `aws-ecr-assets`

Specify `networkMode` with `DEFAULT` or `HOST` for docker image assets
```ts
new assets.DockerImageAsset(stack, 'DockerImage', {
  directory: path.join(__dirname, 'demo-image'),
  networkMode: NetworkMode.HOST,
});
```

## Builder experience with `aws-ecs`

Specify `networkMode` with `DEFAULT` or `HOST` for container image
```ts
taskDefinition.addContainer('web', {
  image: ecs.ContainerImage.fromAsset(path.join(__dirname, '../demo-image'), {
    networkMode: NetworkMode.DEFAULT,
  }),
  portMappings: [{
    containerPort: 8000,
  }],
});
```

## Builder experience with `aws-lambda`

Specify `networkMode` with `DEFAULT` or `HOST` from docker image assets
```ts
new DockerImageFunction(this, 'MyLambda', {
  code: DockerImageCode.fromImageAsset(path.join(__dirname, 'docker-arm64-handler'), {
    networkMode: NetworkMode.DEFAULT,
  }),
});
```

Author: kirintwn

packages/@aws-cdk/aws-ecr-assets/README.md

@@ -80,6 +80,18 @@ const asset = new DockerImageAsset(this, 'MyBuildImage', {
 });
 ```
 
+You can optionally pass networking mode to the `docker build` command by specifying
+the `networkMode` property:
+
+```ts
+import { DockerImageAsset, NetworkMode } from '@aws-cdk/aws-ecr-assets';
+
+const asset = new DockerImageAsset(this, 'MyBuildImage', {
+  directory: path.join(__dirname, 'my-image'),
+  networkMode: NetworkMode.HOST,
+})
+```
+
 ## Images from Tarball
 
 Images are loaded from a local tarball, uploaded to ECR by the CDK toolkit and/or your app's CI-CD pipeline, and can be

packages/@aws-cdk/aws-ecr-assets/lib/image-asset.ts

@@ -12,6 +12,50 @@ import { FingerprintOptions, FollowMode, IAsset } from '@aws-cdk/assets';
 // eslint-disable-next-line no-duplicate-imports, import/order
 import { Construct as CoreConstruct } from '@aws-cdk/core';
 
+/**
+ * networking mode on build time supported by docker
+ */
+export class NetworkMode {
+  /**
+   * The default networking mode if omitted, create a network stack on the default Docker bridge
+   */
+  public static readonly DEFAULT = new NetworkMode('default');
+
+  /**
+   * Use the Docker host network stack
+   */
+  public static readonly HOST = new NetworkMode('host');
+
+  /**
+   * Disable the network stack, only the loopback device will be created
+   */
+  public static readonly NONE = new NetworkMode('none');
+
+  /**
+   * Reuse another container's network stack
+   *
+   * @param containerId The target container's id or name
+   */
+  public static fromContainer(containerId: string) {
+    return new NetworkMode(`container:${containerId}`);
+  }
+
+  /**
+   * Used to specify a custom networking mode
+   * Use this if the networking mode name is not yet supported by the CDK.
+   *
+   * @param mode The networking mode to use for docker build
+   */
+  public static custom(mode: string) {
+    return new NetworkMode(mode);
+  }
+
+  /**
+   * @param mode The networking mode to use for docker build
+   */
+  private constructor(public readonly mode: string) {}
+}
+
 /**
  * Options to control invalidation of `DockerImageAsset` asset hashes
  */
@@ -50,6 +94,13 @@ export interface DockerImageAssetInvalidationOptions {
    * @default true
    */
   readonly repositoryName?: boolean;
+
+  /**
+   * Use `networkMode` while calculating the asset hash
+   *
+   * @default true
+   */
+  readonly networkMode?: boolean;
 }
 
 /**
@@ -95,6 +146,13 @@ export interface DockerImageAssetOptions extends FingerprintOptions, FileFingerp
    */
   readonly file?: string;
 
+  /**
+   * Networking mode for the RUN commands during build. Support docker API 1.25+.
+   *
+   * @default - no networking mode specified (the default networking mode `NetworkMode.DEFAULT` will be used)
+   */
+  readonly networkMode?: NetworkMode;
+
   /**
    * Options to control which parameters are used to invalidate the asset hash.
    *
@@ -227,6 +285,7 @@ export class DockerImageAsset extends CoreConstruct implements IAsset {
     if (props.invalidation?.target !== false && props.target) { extraHash.target = props.target; }
     if (props.invalidation?.file !== false && props.file) { extraHash.file = props.file; }
     if (props.invalidation?.repositoryName !== false && props.repositoryName) { extraHash.repositoryName = props.repositoryName; }
+    if (props.invalidation?.networkMode !== false && props.networkMode) { extraHash.networkMode = props.networkMode; }
 
     // add "salt" to the hash in order to invalidate the image in the upgrade to
     // 1.21.0 which removes the AdoptedRepository resource (and will cause the
@@ -258,6 +317,7 @@ export class DockerImageAsset extends CoreConstruct implements IAsset {
       dockerBuildTarget: this.dockerBuildTarget,
       dockerFile: props.file,
       sourceHash: staging.assetHash,
+      networkMode: props.networkMode?.mode,
     });
 
     this.repository = ecr.Repository.fromRepositoryName(this, 'Repository', location.repositoryName);

packages/@aws-cdk/aws-ecr-assets/test/image-asset.test.ts

@@ -6,7 +6,7 @@ import { describeDeprecated, testDeprecated, testFutureBehavior } from '@aws-cdk
 import * as cxschema from '@aws-cdk/cloud-assembly-schema';
 import { App, DefaultStackSynthesizer, IgnoreMode, Lazy, LegacyStackSynthesizer, Stack, Stage } from '@aws-cdk/core';
 import * as cxapi from '@aws-cdk/cx-api';
-import { DockerImageAsset } from '../lib';
+import { DockerImageAsset, NetworkMode } from '../lib';
 
 /* eslint-disable quote-props */
 
@@ -147,6 +147,20 @@ describe('image asset', () => {
 
   });
 
+  testFutureBehavior('with networkMode', flags, App, (app) => {
+    // GIVEN
+    const stack = new Stack(app);
+    // WHEN
+    new DockerImageAsset(stack, 'Image', {
+      directory: path.join(__dirname, 'demo-image'),
+      networkMode: NetworkMode.DEFAULT,
+    });
+
+    // THEN
+    const assetMetadata = stack.node.metadataEntry.find(({ type }) => type === cxschema.ArtifactMetadataEntryType.ASSET);
+    expect(assetMetadata && (assetMetadata.data as cxschema.ContainerImageAssetMetadataEntry).networkMode).toEqual('default');
+  });
+
   testFutureBehavior('asset.repository.grantPull can be used to grant a principal permissions to use the image', flags, App, (app) => {
     // GIVEN
     const stack = new Stack(app);

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

@@ -62,6 +62,15 @@ export interface DockerImageSource {
    * @default - No additional build arguments
    */
   readonly dockerBuildArgs?: { [name: string]: string };
+
+  /**
+   * Networking mode for the RUN commands during build. _Requires Docker Engine API v1.25+_.
+   *
+   * Specify this property to build images on a specific networking mode.
+   *
+   * @default - no networking mode specified
+   */
+  readonly networkMode?: string;
 }
 
 /**

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

@@ -131,6 +131,13 @@ export interface ContainerImageAssetMetadataEntry extends BaseAssetMetadataEntry
    * @default - no file is passed
    */
   readonly file?: string;
+
+  /**
+   * Networking mode for the RUN commands during build.
+   *
+   * @default - no networking mode specified
+   */
+  readonly networkMode?: string;
 }
 
 /**

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

@@ -154,6 +154,10 @@
                     "additionalProperties": {
                         "type": "string"
                     }
+                },
+                "networkMode": {
+                    "description": "Networking mode for the RUN commands during build. _Requires Docker Engine API v1.25+_. (Default - no networking mode specified)",
+                    "type": "string"
                 }
             }
         },
@@ -189,4 +193,4 @@
         }
     },
     "$schema": "http://json-schema.org/draft-07/schema#"
-}
+}

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

@@ -226,6 +226,10 @@
                     "description": "Path to the Dockerfile (relative to the directory). (Default - no file is passed)",
                     "type": "string"
                 },
+                "networkMode": {
+                    "description": "Networking mode for the RUN commands during build. _Requires Docker Engine API v1.25+_. (Default - no networking mode specified)",
+                    "type": "string"
+                },
                 "id": {
                     "description": "Logical identifier for the asset",
                     "type": "string"
@@ -870,4 +874,4 @@
         }
     },
     "$schema": "http://json-schema.org/draft-07/schema#"
-}
+}

packages/@aws-cdk/core/lib/assets.ts

@@ -203,6 +203,15 @@ export interface DockerImageAssetSource {
    * @deprecated repository name should be specified at the environment-level and not at the image level
    */
   readonly repositoryName?: string;
+
+  /**
+   * Networking mode for the RUN commands during build. _Requires Docker Engine API v1.25+_.
+   *
+   * Specify this property to build images on a specific networking mode.
+   *
+   * @default - no networking mode specified
+   */
+  readonly networkMode?: string;
 }
 
 /**

packages/@aws-cdk/core/lib/stack-synthesizers/default-synthesizer.ts

@@ -424,6 +424,7 @@ export class DefaultStackSynthesizer extends StackSynthesizer {
         dockerBuildArgs: asset.dockerBuildArgs,
         dockerBuildTarget: asset.dockerBuildTarget,
         dockerFile: asset.dockerFile,
+        networkMode: asset.networkMode,
       },
       destinations: {
         [this.manifestEnvName]: {

packages/@aws-cdk/core/lib/stack-synthesizers/legacy.ts

@@ -136,6 +136,7 @@ export class LegacyStackSynthesizer extends StackSynthesizer {
         buildArgs: asset.dockerBuildArgs,
         target: asset.dockerBuildTarget,
         file: asset.dockerFile,
+        networkMode: asset.networkMode,
       };
 
       this.stack.node.addMetadata(cxschema.ArtifactMetadataEntryType.ASSET, metadata);

packages/aws-cdk/lib/assets.ts

@@ -122,6 +122,7 @@ async function prepareDockerImageAsset(
     dockerBuildArgs: asset.buildArgs,
     dockerBuildTarget: asset.target,
     dockerFile: asset.file,
+    networkMode: asset.networkMode,
   }, {
     repositoryName,
     imageTag,

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

@@ -14,6 +14,7 @@ interface BuildOptions {
   readonly target?: string;
   readonly file?: string;
   readonly buildArgs?: Record<string, string>;
+  readonly networkMode?: string;
 }
 
 export interface DockerCredentialsConfig {
@@ -53,6 +54,7 @@ export class Docker {
       '--tag', options.tag,
       ...options.target ? ['--target', options.target] : [],
       ...options.file ? ['--file', options.file] : [],
+      ...options.networkMode ? ['--network', options.networkMode] : [],
       '.',
     ];
     await this.execute(buildCommand, { cwd: options.directory });

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

@@ -125,6 +125,7 @@ export class ContainerImageAssetHandler implements IAssetHandler {
       buildArgs: source.dockerBuildArgs,
       target: source.dockerBuildTarget,
       file: source.dockerFile,
+      networkMode: source.networkMode,
     });
   }
 

packages/cdk-assets/test/docker-images.test.ts

@@ -73,6 +73,26 @@ beforeEach(() => {
         },
       },
     }),
+    '/default-network/cdk.out/assets.json': JSON.stringify({
+      version: Manifest.version(),
+      dockerImages: {
+        theAsset: {
+          source: {
+            directory: 'dockerdir',
+            networkMode: 'default',
+          },
+          destinations: {
+            theDestination: {
+              region: 'us-north-50',
+              assumeRoleArn: 'arn:aws:role',
+              repositoryName: 'repo',
+              imageTag: 'nopqr',
+            },
+          },
+        },
+      },
+    }),
+    '/default-network/cdk.out/dockerdir/Dockerfile': 'FROM scratch',
   });
 
   aws = mockAws();
@@ -164,6 +184,30 @@ describe('with a complete manifest', () => {
     expectAllSpawns();
     expect(true).toBeTruthy(); // Expect no exception, satisfy linter
   });
+
+  test('build with networkMode option', async () => {
+    pub = new AssetPublishing(AssetManifest.fromPath('/default-network/cdk.out'), { aws });
+    const defaultNetworkDockerpath = '/default-network/cdk.out/dockerdir';
+    aws.mockEcr.describeImages = mockedApiFailure('ImageNotFoundException', 'File does not exist');
+    aws.mockEcr.getAuthorizationToken = mockedApiResult({
+      authorizationData: [
+        { authorizationToken: 'dXNlcjpwYXNz', proxyEndpoint: 'https://proxy.com/' },
+      ],
+    });
+
+    const expectAllSpawns = mockSpawn(
+      { commandLine: ['docker', 'login', '--username', 'user', '--password-stdin', 'https://proxy.com/'] },
+      { commandLine: ['docker', 'inspect', 'cdkasset-theasset'], exitCode: 1 },
+      { commandLine: ['docker', 'build', '--tag', 'cdkasset-theasset', '--network', 'default', '.'], cwd: defaultNetworkDockerpath },
+      { 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', () => {