Merge branch 'master' into lambda-nodejs-more-esbuild-options

CONTRIBUTING.md

@@ -382,6 +382,31 @@ Here are a few useful commands:
    evaluate only the rule specified [awslint README](./packages/awslint/README.md)
    for details on include/exclude rule patterns.
 
+
+#### jsii-rosetta
+
+**jsii-rosetta** can be used to verify that all code examples included in documentation for a package (including those
+in `README.md`) successfully compile against the library they document. It is recommended to run it to ensure all
+examples are still accurate. Successfully building examples is also necessary to ensure the best possible translation to
+other supported languages (`C#`, `Java`, `Python`, ...).
+
+> Note that examples may use libraries that are not part of the `dependencies` or `devDependencies` of the documented
+> package. For example `@aws-cdk/core` contains mainy examples that leverage libraries built *on top of it* (such as
+> `@aws-cdk/aws-sns`). Such libraries must be built (using `yarn build`) before **jsii-rosetta** can verify that
+> examples are correct.
+
+To run **jsii-rosetta** in *strict* mode (so that it always fails when encountering examples that fail to compile), use
+the following command:
+
+```console
+$ yarn rosetta:extract --strict
+```
+
+For more information on how you can address examples that fail compiling due to missing fixtures (declarations that are
+necessary for the example to compile, but which would distract the reader away from what is being demonstrated), you
+might need to introduce [rosetta fixtures](https://github.com/aws/jsii/tree/main/packages/jsii-rosetta#fixtures). Refer
+to the [Examples](#examples) section.
+
 ### cfn2ts
 
 This tool is used to generate our low-level CloudFormation resources
@@ -685,6 +710,8 @@ can be used in these cases.
 
 ### Examples
 
+#### Fixture Files
+
 Examples typed in fenced code blocks (looking like `'''ts`, but then with backticks
 instead of regular quotes) will be automatically extrated, compiled and translated
 to other languages when the bindings are generated.
@@ -694,7 +721,7 @@ a *fixture*, which looks like this:
 
 ```
 '''ts fixture=with-bucket
-bucket.addLifecycleTransition({ ... });
+bucket.addLifecycleTransition({ ...props });
 '''
 ```
 
@@ -717,8 +744,8 @@ contain three slashes to achieve the same effect:
 ```
 /**
  * @example
- * /// fixture=with-bucket
- * bucket.addLifecycleTransition({ ... });
+ *   /// fixture=with-bucket
+ *   bucket.addLifecycleTransition({ ...props });
  */
 ```
 
@@ -732,12 +759,52 @@ the current package.
 For a practical example of how making sample code compilable works, see the
 `aws-ec2` package.
 
+#### Recommendations
+
+In order to offer a consistent documentation style throughout the AWS CDK
+codebase, example code should follow the following recommendations (there may be
+cases where some of those do not apply - good judgement is to be applied):
+
+- Types from the documented module should be **un-qualified**
+
+  ```ts
+  // An example in the @aws-cdk/core library, which defines Duration
+  Duration.minutes(15);
+  ```
+
+- Types from other modules should be **qualified**
+
+  ```ts
+  // An example in the @aws-cdk/core library, using something from @aws-cdk/aws-s3
+  const bucket = new s3.Bucket(this, 'Bucket');
+  // ...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):
+
+  ```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;
+  ```
+
+> Those recommendations are not verified or enforced by automated tooling. Pull
+> request reviewers may however request that new sample code is edited to meet
+> those requirements as needed.
+
+#### Checking a single package
+
 Examples of all packages are extracted and compiled as part of the packaging
 step. If you are working on getting rid of example compilation errors of a
-single package, you can run `scripts/compile-samples` on the package by itself.
-
-For now, non-compiling examples will not yet block the build, but at some point
-in the future they will.
+single package, you can run `yarn rosetta:extract --strict` in the package's
+directory (see the [**jsii-rosetta**](#jsii-rosetta) section).
 
 ### Feature Flags
 

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

@@ -405,10 +405,6 @@ export class InterfaceVpcEndpoint extends VpcEndpoint implements IInterfaceVpcEn
    * Imports an existing interface VPC endpoint.
    */
   public static fromInterfaceVpcEndpointAttributes(scope: Construct, id: string, attrs: InterfaceVpcEndpointAttributes): IInterfaceVpcEndpoint {
-    if (!attrs.securityGroups && !attrs.securityGroupId) {
-      throw new Error('Either `securityGroups` or `securityGroupId` must be specified.');
-    }
-
     const securityGroups = attrs.securityGroupId
       ? [SecurityGroup.fromSecurityGroupId(scope, 'SecurityGroup', attrs.securityGroupId)]
       : attrs.securityGroups;

packages/@aws-cdk/aws-ec2/test/vpc-endpoint.test.ts

@@ -290,6 +290,24 @@ nodeunitShim({
       test.done();
     },
 
+    'import/export without security group'(test: Test) {
+      // GIVEN
+      const stack2 = new Stack();
+
+      // WHEN
+      const importedEndpoint = InterfaceVpcEndpoint.fromInterfaceVpcEndpointAttributes(stack2, 'ImportedEndpoint', {
+        vpcEndpointId: 'vpc-endpoint-id',
+        port: 80,
+      });
+      importedEndpoint.connections.allowDefaultPortFromAnyIpv4();
+
+      // THEN
+      test.deepEqual(importedEndpoint.vpcEndpointId, 'vpc-endpoint-id');
+      test.deepEqual(importedEndpoint.connections.securityGroups.length, 0);
+
+      test.done();
+    },
+
     'with existing security groups'(test: Test) {
       // GIVEN
       const stack = new Stack();

packages/@aws-cdk/aws-ecs-patterns/README.md

@@ -371,6 +371,25 @@ scalableTarget.scaleOnMemoryUtilization('MemoryScaling', {
 });
 ```
 
+### Change the default Deployment Controller
+
+```ts
+import { ApplicationLoadBalancedFargateService } from './application-load-balanced-fargate-service';
+
+const loadBalancedFargateService = new ApplicationLoadBalancedFargateService(stack, 'Service', {
+  cluster,
+  memoryLimitMiB: 1024,
+  desiredCount: 1,
+  cpu: 512,
+  taskImageOptions: {
+    image: ecs.ContainerImage.fromRegistry("amazon/amazon-ecs-sample"),
+  },
+  deploymentController: {
+    type: ecs.DeploymentControllerType.CODE_DEPLOY,
+  },
+});
+```
+
 ### Set deployment configuration on QueueProcessingService
 
 ```ts

packages/@aws-cdk/aws-ecs-patterns/lib/base/application-load-balanced-service-base.ts

@@ -1,6 +1,6 @@
 import { Certificate, CertificateValidation, ICertificate } from '@aws-cdk/aws-certificatemanager';
 import { IVpc } from '@aws-cdk/aws-ec2';
-import { AwsLogDriver, BaseService, CloudMapOptions, Cluster, ContainerImage, ICluster, LogDriver, PropagatedTagSource, Secret } from '@aws-cdk/aws-ecs';
+import { AwsLogDriver, BaseService, CloudMapOptions, Cluster, ContainerImage, DeploymentController, ICluster, LogDriver, PropagatedTagSource, Secret } from '@aws-cdk/aws-ecs';
 import {
   ApplicationListener, ApplicationLoadBalancer, ApplicationProtocol, ApplicationTargetGroup,
   IApplicationLoadBalancer, ListenerCertificate, ListenerAction, AddApplicationTargetsProps,
@@ -212,6 +212,14 @@ export interface ApplicationLoadBalancedServiceBaseProps {
    * @default ApplicationLoadBalancedServiceRecordType.ALIAS
    */
   readonly recordType?: ApplicationLoadBalancedServiceRecordType;
+
+  /**
+   * Specifies which deployment controller to use for the service. For more information, see
+   * [Amazon ECS Deployment Types](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/deployment-types.html)
+   *
+   * @default - Rolling update (ECS)
+   */
+  readonly deploymentController?: DeploymentController;
 }
 
 export interface ApplicationLoadBalancedTaskImageOptions {

packages/@aws-cdk/aws-ecs-patterns/lib/base/network-load-balanced-service-base.ts

@@ -1,5 +1,5 @@
 import { IVpc } from '@aws-cdk/aws-ec2';
-import { AwsLogDriver, BaseService, CloudMapOptions, Cluster, ContainerImage, ICluster, LogDriver, PropagatedTagSource, Secret } from '@aws-cdk/aws-ecs';
+import { AwsLogDriver, BaseService, CloudMapOptions, Cluster, ContainerImage, DeploymentController, ICluster, LogDriver, PropagatedTagSource, Secret } from '@aws-cdk/aws-ecs';
 import { INetworkLoadBalancer, NetworkListener, NetworkLoadBalancer, NetworkTargetGroup } from '@aws-cdk/aws-elasticloadbalancingv2';
 import { IRole } from '@aws-cdk/aws-iam';
 import { ARecord, CnameRecord, IHostedZone, RecordTarget } from '@aws-cdk/aws-route53';
@@ -162,6 +162,14 @@ export interface NetworkLoadBalancedServiceBaseProps {
    * @default NetworkLoadBalancedServiceRecordType.ALIAS
    */
   readonly recordType?: NetworkLoadBalancedServiceRecordType;
+
+  /**
+ * Specifies which deployment controller to use for the service. For more information, see
+ * [Amazon ECS Deployment Types](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/deployment-types.html)
+ *
+ * @default - Rolling update (ECS)
+ */
+  readonly deploymentController?: DeploymentController;
 }
 
 export interface NetworkLoadBalancedTaskImageOptions {

packages/@aws-cdk/aws-ecs-patterns/lib/base/queue-processing-service-base.ts

@@ -1,6 +1,6 @@
 import { ScalingInterval } from '@aws-cdk/aws-applicationautoscaling';
 import { IVpc } from '@aws-cdk/aws-ec2';
-import { AwsLogDriver, BaseService, Cluster, ContainerImage, ICluster, LogDriver, PropagatedTagSource, Secret } from '@aws-cdk/aws-ecs';
+import { AwsLogDriver, BaseService, Cluster, ContainerImage, DeploymentController, ICluster, LogDriver, PropagatedTagSource, Secret } from '@aws-cdk/aws-ecs';
 import { IQueue, Queue } from '@aws-cdk/aws-sqs';
 import { CfnOutput, Duration, Stack } from '@aws-cdk/core';
 import { Construct } from 'constructs';
@@ -170,6 +170,14 @@ export interface QueueProcessingServiceBaseProps {
    * @default - default from underlying service.
    */
   readonly minHealthyPercent?: number;
+
+  /**
+   * Specifies which deployment controller to use for the service. For more information, see
+   * [Amazon ECS Deployment Types](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/deployment-types.html)
+   *
+   * @default - Rolling update (ECS)
+   */
+  readonly deploymentController?: DeploymentController;
 }
 
 /**

packages/@aws-cdk/aws-ecs-patterns/lib/ecs/application-load-balanced-ecs-service.ts

@@ -131,6 +131,7 @@ export class ApplicationLoadBalancedEc2Service extends ApplicationLoadBalancedSe
       propagateTags: props.propagateTags,
       enableECSManagedTags: props.enableECSManagedTags,
       cloudMapOptions: props.cloudMapOptions,
+      deploymentController: props.deploymentController,
     });
     this.addServiceAsTarget(this.service);
   }

packages/@aws-cdk/aws-ecs-patterns/lib/ecs/network-load-balanced-ecs-service.ts

@@ -129,6 +129,7 @@ export class NetworkLoadBalancedEc2Service extends NetworkLoadBalancedServiceBas
       propagateTags: props.propagateTags,
       enableECSManagedTags: props.enableECSManagedTags,
       cloudMapOptions: props.cloudMapOptions,
+      deploymentController: props.deploymentController,
     });
     this.addServiceAsTarget(this.service);
   }

packages/@aws-cdk/aws-ecs-patterns/lib/ecs/queue-processing-ecs-service.ts

@@ -100,6 +100,7 @@ export class QueueProcessingEc2Service extends QueueProcessingServiceBase {
       maxHealthyPercent: props.maxHealthyPercent,
       propagateTags: props.propagateTags,
       enableECSManagedTags: props.enableECSManagedTags,
+      deploymentController: props.deploymentController,
     });
     this.configureAutoscalingForService(this.service);
     this.grantPermissionsToService(this.service);

packages/@aws-cdk/aws-ecs-patterns/lib/fargate/application-load-balanced-fargate-service.ts

@@ -166,6 +166,7 @@ export class ApplicationLoadBalancedFargateService extends ApplicationLoadBalanc
       enableECSManagedTags: props.enableECSManagedTags,
       cloudMapOptions: props.cloudMapOptions,
       platformVersion: props.platformVersion,
+      deploymentController: props.deploymentController,
       securityGroups: props.securityGroups,
       vpcSubnets: props.taskSubnets,
     });

packages/@aws-cdk/aws-ecs-patterns/lib/fargate/network-load-balanced-fargate-service.ts

@@ -155,6 +155,7 @@ export class NetworkLoadBalancedFargateService extends NetworkLoadBalancedServic
       enableECSManagedTags: props.enableECSManagedTags,
       cloudMapOptions: props.cloudMapOptions,
       platformVersion: props.platformVersion,
+      deploymentController: props.deploymentController,
       vpcSubnets: props.taskSubnets,
     });
     this.addServiceAsTarget(this.service);

packages/@aws-cdk/aws-ecs-patterns/lib/fargate/queue-processing-fargate-service.ts

@@ -106,6 +106,7 @@ export class QueueProcessingFargateService extends QueueProcessingServiceBase {
       propagateTags: props.propagateTags,
       enableECSManagedTags: props.enableECSManagedTags,
       platformVersion: props.platformVersion,
+      deploymentController: props.deploymentController,
     });
     this.configureAutoscalingForService(this.service);
     this.grantPermissionsToService(this.service);

packages/@aws-cdk/aws-ecs-patterns/test/ec2/test.l3s.ts

@@ -943,6 +943,64 @@ export = {
     test.done();
   },
 
+  'ALB - having deployment controller'(test: Test) {
+    // GIVEN
+    const stack = new cdk.Stack();
+    const vpc = new ec2.Vpc(stack, 'VPC');
+    const cluster = new ecs.Cluster(stack, 'Cluster', { vpc });
+    cluster.addCapacity('DefaultAutoScalingGroup', { instanceType: new ec2.InstanceType('t2.micro') });
+
+    // WHEN
+    new ecsPatterns.ApplicationLoadBalancedEc2Service(stack, 'Service', {
+      cluster,
+      memoryLimitMiB: 1024,
+      taskImageOptions: {
+        image: ecs.ContainerImage.fromRegistry('amazon/amazon-ecs-sample'),
+      },
+      deploymentController: {
+        type: ecs.DeploymentControllerType.CODE_DEPLOY,
+      },
+    });
+
+    // THEN
+    expect(stack).to(haveResourceLike('AWS::ECS::Service', {
+      DeploymentController: {
+        Type: 'CODE_DEPLOY',
+      },
+    }));
+
+    test.done();
+  },
+
+  'NLB - having  deployment controller'(test: Test) {
+    // GIVEN
+    const stack = new cdk.Stack();
+    const vpc = new ec2.Vpc(stack, 'VPC');
+    const cluster = new ecs.Cluster(stack, 'Cluster', { vpc });
+    cluster.addCapacity('DefaultAutoScalingGroup', { instanceType: new ec2.InstanceType('t2.micro') });
+
+    // WHEN
+    new ecsPatterns.NetworkLoadBalancedEc2Service(stack, 'Service', {
+      cluster,
+      memoryLimitMiB: 1024,
+      taskImageOptions: {
+        image: ecs.ContainerImage.fromRegistry('amazon/amazon-ecs-sample'),
+      },
+      deploymentController: {
+        type: ecs.DeploymentControllerType.CODE_DEPLOY,
+      },
+    });
+
+    // THEN
+    expect(stack).to(haveResourceLike('AWS::ECS::Service', {
+      DeploymentController: {
+        Type: 'CODE_DEPLOY',
+      },
+    }));
+
+    test.done();
+  },
+
   'NetworkLoadbalancedEC2Service accepts previously created load balancer'(test: Test) {
     // GIVEN
     const stack = new cdk.Stack();

packages/@aws-cdk/aws-ecs-patterns/test/ec2/test.queue-processing-ecs-service.ts

@@ -183,6 +183,9 @@ export = {
       maxHealthyPercent: 150,
       serviceName: 'ecs-test-service',
       family: 'ecs-task-family',
+      deploymentController: {
+        type: ecs.DeploymentControllerType.CODE_DEPLOY,
+      },
     });
 
     // THEN - QueueWorker is of EC2 launch type, an SQS queue is created and all optional properties are set.
@@ -194,6 +197,9 @@ export = {
       },
       LaunchType: 'EC2',
       ServiceName: 'ecs-test-service',
+      DeploymentController: {
+        Type: 'CODE_DEPLOY',
+      },
     }));
 
     expect(stack).to(haveResource('AWS::SQS::Queue', {