Merge branch 'master' into iotevents-dm-transitions

.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": [
         "dbaeumer.vscode-eslint@2.1.5"
     ]
-}
+}

.github/dependabot.yml

@@ -11,3 +11,10 @@ updates:
     labels:
       - "auto-approve"
     open-pull-requests-limit: 5
+  - package-ecosystem: "pip"
+    directory: "/packages/@aws-cdk/lambda-layer-awscli"
+    schedule:
+      interval: "weekly"
+    labels:
+      - "auto-approve"
+    open-pull-requests-limit: 5

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
@@ -662,7 +665,7 @@ extension](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-e
 
 #### pkglint
 
-The `pkglint` tool "lints" package.json files across the repo according to [rules.ts](tools/pkglint/lib/rules.ts).
+The `pkglint` tool "lints" package.json files across the repo according to [rules.ts](tools/@aws-cdk/pkglint/lib/rules.ts).
 
 To evaluate (and attempt to fix) all package linting issues in the repo, run the following command from the root of the
 repository (after bootstrapping):

design/aws-ecs/aws-ecs-fargate-capacity-providers.md

@@ -2,7 +2,7 @@
 
 ## Objective
 
-Since Capacity Providers are now supported in CloudFormation, incorporating support for Fargate Spot capacity has been one of the [top asks](https://github.com/aws/aws-cdk/issues?q=is%3Aissue+is%3Aopen+label%3A%40aws-cdk%2Faws-ecs+sort%3Areactions-%2B1-desc) for the ECS CDK module, with over 60 customer reactions. While there are still some outstanding issues regarding capacity provider support in general, specifically regarding cyclic workflows with named clusters (See: [CFN issue](http://%20https//github.com/aws/containers-roadmap/issues/631#issuecomment-702580141)), we should be able to move ahead with supporting `FARGATE` and `FARGATE_SPOT` capacity providers with our existing FargateService construct.
+Since Capacity Providers are now supported in CloudFormation, incorporating support for Fargate Spot capacity has been one of the [top asks](https://github.com/aws/aws-cdk/issues?q=is%3Aissue+is%3Aopen+label%3A%40aws-cdk%2Faws-ecs+sort%3Areactions-%2B1-desc) for the ECS CDK module, with over 60 customer reactions. While there are still some outstanding issues regarding capacity provider support in general, specifically regarding cyclic workflows with named clusters (See: [CFN issue](https://github.com/aws/containers-roadmap/issues/631#issuecomment-702580141)), we should be able to move ahead with supporting `FARGATE` and `FARGATE_SPOT` capacity providers with our existing FargateService construct.
 
 See: https://github.com/aws/aws-cdk/issues/5850
 
@@ -118,4 +118,3 @@ One alternative considered was to provide a more magical experience by populatin
 For future extensibility, we can however add an `addCapacityProvider` method on the Cluster resource, to allow modifying the cluster CapacityProviders field post-construction.
 
 Another option would be to create a new FargateCluster resource, that would have the two Fargate capacity providers set by default. The main advantage with this alternative would be that it would be consistent with the current Console experience, which sets the Fargate capacity providers for you if you choose the “Networking Only” cluster template via the cluster wizard. The downside is that it would be a more restrictive resource model that would go back on the decision to have a single generic ECS Cluster resource that could potentially contain both Fargate and EC2 services or tasks. Given that we are moving towards more generic versions of ECS resources, this is not a preferable solution. That being said, in the current iteration we can set the Fargate Capacity Providers on the cluster by default, but put them behind a feature flag, which we would be able to remove in the v2 version of the ECS module. Using the feature flag would ensure that there would not be a diff in the generated CFN template for existing customers defining ECS clusters in their stack who redeploy using an updated version of the CDK.
-

package.json

@@ -16,7 +16,7 @@
   },
   "devDependencies": {
     "@yarnpkg/lockfile": "^1.1.0",
-    "cdk-generate-synthetic-examples": "^0.1.3",
+    "cdk-generate-synthetic-examples": "^0.1.5",
     "conventional-changelog-cli": "^2.2.2",
     "fs-extra": "^9.1.0",
     "graceful-fs": "^4.2.9",

packages/@aws-cdk/aws-certificatemanager/lambda-packages/dns_validated_certificate_handler/package.json

@@ -33,7 +33,7 @@
     "@types/sinon": "^9.0.11",
     "@aws-cdk/cdk-build-tools": "0.0.0",
     "aws-sdk": "^2.596.0",
-    "aws-sdk-mock": "^5.6.0",
+    "aws-sdk-mock": "5.6.0",
     "eslint": "^7.32.0",
     "eslint-config-standard": "^14.1.1",
     "eslint-plugin-import": "^2.25.4",
@@ -43,7 +43,7 @@
     "jest": "^27.4.7",
     "lambda-tester": "^3.6.0",
     "sinon": "^9.2.4",
-    "nock": "^13.2.2",
+    "nock": "^13.2.4",
     "ts-jest": "^27.1.3"
   }
 }

packages/@aws-cdk/aws-dynamodb-global/lambda-packages/aws-global-table-coordinator/package.json

@@ -30,7 +30,7 @@
   "license": "Apache-2.0",
   "devDependencies": {
     "aws-sdk": "^2.596.0",
-    "aws-sdk-mock": "^5.6.0",
+    "aws-sdk-mock": "5.6.0",
     "eslint": "^7.32.0",
     "eslint-config-standard": "^14.1.1",
     "eslint-plugin-import": "^2.25.4",
@@ -39,6 +39,6 @@
     "eslint-plugin-standard": "^4.1.0",
     "jest": "^27.4.7",
     "lambda-tester": "^3.6.0",
-    "nock": "^13.2.2"
+    "nock": "^13.2.4"
   }
 }

packages/@aws-cdk/aws-dynamodb/package.json

@@ -88,7 +88,7 @@
     "@types/jest": "^27.4.0",
     "@types/sinon": "^9.0.11",
     "aws-sdk": "^2.848.0",
-    "aws-sdk-mock": "^5.6.0",
+    "aws-sdk-mock": "5.6.0",
     "jest": "^27.4.7",
     "sinon": "^9.2.4",
     "ts-jest": "^27.1.3"

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-legacy/README.md

@@ -49,7 +49,7 @@ cluster.addResource('mypod', {
 });
 ```
 
-Here is a [complete sample](https://github.com/aws/aws-cdk/blob/master/packages/%40aws-cdk/aws-eks/test/integ.eks-kubectl.lit.ts).
+Here is a [complete sample](https://github.com/aws/aws-cdk/blob/master/packages/@aws-cdk/aws-eks-legacy/test/integ.eks-kubectl.lit.ts).
 
 ### Capacity
 

packages/@aws-cdk/aws-eks/README.md

@@ -1174,11 +1174,11 @@ chart2.node.addDependency(chart1);
 
 [CDK8s](https://cdk8s.io/) is an open-source library that enables Kubernetes manifest authoring using familiar programming languages. It is founded on the same technologies as the AWS CDK, such as [`constructs`](https://github.com/aws/constructs) and [`jsii`](https://github.com/aws/jsii).
 
-> To learn more about cdk8s, visit the [Getting Started](https://github.com/awslabs/cdk8s/tree/master/docs/getting-started) tutorials.
+> To learn more about cdk8s, visit the [Getting Started](https://cdk8s.io/docs/latest/getting-started/) tutorials.
 
 The EKS module natively integrates with cdk8s and allows you to apply cdk8s charts on AWS EKS clusters via the `cluster.addCdk8sChart` method.
 
-In addition to `cdk8s`, you can also use [`cdk8s+`](https://github.com/awslabs/cdk8s/tree/master/packages/cdk8s-plus), which provides higher level abstraction for the core kubernetes api objects.
+In addition to `cdk8s`, you can also use [`cdk8s+`](https://cdk8s.io/docs/latest/plus/), which provides higher level abstraction for the core kubernetes api objects.
 You can think of it like the `L2` constructs for Kubernetes. Any other `cdk8s` based libraries are also supported, for example [`cdk8s-debore`](https://github.com/toricls/cdk8s-debore).
 
 To get started, add the following dependencies to your `package.json` file:
@@ -1290,7 +1290,7 @@ export class LoadBalancedWebService extends constructs.Construct {
 
 If you find yourself unable to use `cdk8s+`, or just like to directly use the `k8s` native objects or CRD's, you can do so by manually importing them using the `cdk8s-cli`.
 
-See [Importing kubernetes objects](https://github.com/awslabs/cdk8s/tree/master/packages/cdk8s-cli#import) for detailed instructions.
+See [Importing kubernetes objects](https://cdk8s.io/docs/latest/cli/import/) for detailed instructions.
 
 ## Patching Kubernetes Resources