Merge branch 'master' into corymhall/dependabot-pip

.devcontainer.json

@@ -1,8 +1,8 @@
 {
     "name": "Dev Container Definition - AWS CDK",
-    "image": "jsii/superchain",
+    "image": "jsii/superchain:1-buster-slim",
     "postCreateCommand": "yarn build --skip-test --no-bail --skip-prereqs --skip-compat",
     "extensions": [
         "[email protected]"
     ]
-}
+}

CONTRIBUTING.md

@@ -22,7 +22,7 @@ let us know if it's not up-to-date (even better, submit a PR with your  correcti
   - [Step 5: Merge](#step-5-merge)
 - [Breaking Changes](#breaking-changes)
 - [Documentation](#documentation)
-  - [rosetta](#rosetta)
+  - [Rosetta](#rosetta)
 - [Tools](#tools)
   - [Linters](#linters)
   - [cfn2ts](#cfn2ts)
@@ -217,6 +217,8 @@ Work your magic. Here are some guidelines:
     Watch out for their error messages and adjust your code accordingly.
 * Every change requires a unit test
 * If you change APIs, make sure to update the module's README file
+  * When you add new examples to the module's README file, you must also ensure they compile - the PR build will fail
+    if they do not. To learn more about how to ensure that they compile, see [Documentation](#documentation).
 * Try to maintain a single feature/bugfix per pull request. It's okay to introduce a little bit of housekeeping
   changes along the way, but try to avoid conflating multiple features. Eventually, all these are going to go into a
   single commit, so you can use that to frame your scope.
@@ -508,7 +510,7 @@ the README for the `aws-ec2` module - https://docs.aws.amazon.com/cdk/api/latest
 
 ### Rosetta
 
-The README file contains code snippets written as typescript code.  Code snippets typed in fenced code blocks
+The README file contains code snippets written as typescript code. Code snippets typed in fenced code blocks
 (such as `` ```ts ``) will be automatically extracted, compiled and translated to other languages when the
 during the [pack](#pack) step. We call this feature 'rosetta'.
 
@@ -541,11 +543,12 @@ When no fixture is specified, the fixture with the name
 `rosetta/default.ts-fixture` will be used if present. `nofixture` can be used to
 opt out of that behavior.
 
-In an `@example` block, which is unfenced, the first line of the example can
-contain three slashes to achieve the same effect:
+In an `@example` block, which is unfenced, additional information pertaining to
+the example can be provided via the `@exampleMetadata` tag:
 
 ```
 /**
+ * @exampleMetadata fixture=with-bucket
  * @example
  *   /// fixture=with-bucket
  *   bucket.addLifecycleTransition({ ...props });
@@ -582,21 +585,21 @@ cases where some of those do not apply - good judgement is to be applied):
   // ...rest of the example...
   ```
 
-- Within `.ts-fixture` files, make use of `declare` statements instead of
-  writing a compatible value (this will make your fixtures more durable):
+- Make use of `declare` statements directly in examples for values that are
+  necessary for compilation but unimportant to the example:
 
   ```ts
-  // An hypothetical 'rosetta/default.ts-fixture' file in `@aws-cdk/core`
-  import * as kms from '@aws-cdk/aws-kms';
-  import * as s3 from '@aws-cdk/aws-s3';
-  import { StackProps } from '@aws-cdk/core';
-
-  declare const kmsKey: kms.IKey;
-  declare const bucket: s3.Bucket;
-
-  declare const props: StackProps;
+  // An example about adding a stage to a pipeline in the @aws-cdk/pipelines library
+  declare const pipeline: pipelines.CodePipeline;
+  declare const myStage: Stage;
+  pipeline.addStage(myStage);   
   ```
 
+- Utilize the `default.ts-fixture` that already exists rather than writing new
+  `.ts-fixture` files. This is because values stored in `.ts-fixture` files do
+  not surface to the examples visible in the docs, so while they help successful
+  compilation, they do not help users understand the example.
+
 ## Tools (Advanced)
 
 ### scripts/foreach.sh

packages/@aws-cdk/aws-ec2/lib/vpc-endpoint-service.ts

@@ -11,6 +11,8 @@ import { CfnVPCEndpointService, CfnVPCEndpointServicePermissions } from './ec2.g
 export interface IVpcEndpointServiceLoadBalancer {
   /**
    * The ARN of the load balancer that hosts the VPC Endpoint Service
+   *
+   * @attribute
    */
   readonly loadBalancerArn: string;
 }

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/aws-ecs/test/container-definition.test.ts

@@ -2006,9 +2006,9 @@ describe('container definition', () => {
 
   });
 
-  test('exposes image name', () => {
+  testFutureBehavior('exposes image name', { '@aws-cdk/core:newStyleStackSynthesis': true }, cdk.App, (app) => {
     // GIVEN
-    const stack = new cdk.Stack();
+    const stack = new cdk.Stack(app, 'MyStack');
     const taskDefinition = new ecs.FargateTaskDefinition(stack, 'TaskDef');
 
     // WHEN
@@ -2018,17 +2018,7 @@ describe('container definition', () => {
 
     // THEN
     expect(stack.resolve(container.imageName)).toEqual({
-      'Fn::Join': [
-        '',
-        [
-          { Ref: 'AWS::AccountId' },
-          '.dkr.ecr.',
-          { Ref: 'AWS::Region' },
-          '.',
-          { Ref: 'AWS::URLSuffix' },
-          '/aws-cdk/assets:baa2d6eb2a17c75424df631c8c70ff39f2d5f3bee8b9e1a109ee24ca17300540',
-        ],
-      ],
+      'Fn::Sub': '${AWS::AccountId}.dkr.ecr.${AWS::Region}.${AWS::URLSuffix}/cdk-hnb659fds-container-assets-${AWS::AccountId}-${AWS::Region}:baa2d6eb2a17c75424df631c8c70ff39f2d5f3bee8b9e1a109ee24ca17300540',
     });
   });
 });

packages/@aws-cdk/aws-eks/lib/cluster.ts

@@ -772,21 +772,25 @@ export interface ClusterProps extends ClusterOptions {
 export class KubernetesVersion {
   /**
    * Kubernetes version 1.14
+   * @deprecated Use newer version of EKS
    */
   public static readonly V1_14 = KubernetesVersion.of('1.14');
 
   /**
    * Kubernetes version 1.15
+   * @deprecated Use newer version of EKS
    */
   public static readonly V1_15 = KubernetesVersion.of('1.15');
 
   /**
    * Kubernetes version 1.16
+   * @deprecated Use newer version of EKS
    */
   public static readonly V1_16 = KubernetesVersion.of('1.16');
 
   /**
    * Kubernetes version 1.17
+   * @deprecated Use newer version of EKS
    */
   public static readonly V1_17 = KubernetesVersion.of('1.17');
 

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);