feat: construct library for ECS

.gitignore

@@ -10,3 +10,5 @@ pack
 coverage
 .nyc_output
 .LAST_BUILD
+*.swp
+./examples/cdk-examples-typescript/hello-cdk-ecs/cdk.json

examples/cdk-examples-typescript/hello-cdk-ecs-declarative/cdk.json

@@ -0,0 +1,3 @@
+{
+    "app": "../node_modules/.bin/cdk-applet-js fargate-service.yml"
+}

examples/cdk-examples-typescript/hello-cdk-ecs-declarative/fargate-service.yml

@@ -0,0 +1,5 @@
+# applet is loaded from the local ./test-applet.js file
+applet: @aws-cdk/aws-ecs:LoadBalancedFargateServiceApplet
+image: 'amazon/amazon-ecs-sample'
+cpu: "2048"
+memoryMiB: "1024"

examples/cdk-examples-typescript/hello-cdk-ecs/index.ts

@@ -0,0 +1,37 @@
+import ec2 = require('@aws-cdk/aws-ec2');
+import { InstanceType } from '@aws-cdk/aws-ec2';
+import ecs = require('@aws-cdk/aws-ecs');
+import cdk = require('@aws-cdk/cdk');
+
+class BonjourECS extends cdk.Stack {
+  constructor(parent: cdk.App, name: string, props?: cdk.StackProps) {
+    super(parent, name, props);
+
+    // For better iteration speed, it might make sense to put this VPC into
+    // a separate stack and import it here. We then have two stacks to
+    // deploy, but VPC creation is slow so we'll only have to do that once
+    // and can iterate quickly on consuming stacks. Not doing that for now.
+    const vpc = new ec2.VpcNetwork(this, 'MyVpc', { maxAZs: 2 });
+    const cluster = new ecs.Ec2Cluster(this, 'Ec2Cluster', {
+      vpc,
+      size: 3,
+      instanceType: new InstanceType("t2.xlarge")
+    });
+
+    // Instantiate ECS Service with just cluster and image
+    const ecsService = new ecs.LoadBalancedEc2Service(this, "Ec2Service", {
+      cluster,
+      memoryLimitMiB: 512,
+      image: ecs.DockerHub.image("amazon/amazon-ecs-sample"),
+    });
+
+    // Output the DNS where you can access your service
+    new cdk.Output(this, 'LoadBalancerDNS', { value: ecsService.loadBalancer.dnsName });
+  }
+}
+
+const app = new cdk.App();
+
+new BonjourECS(app, 'Bonjour');
+
+app.run();

examples/cdk-examples-typescript/hello-cdk-fargate/index.ts

@@ -0,0 +1,29 @@
+import ec2 = require('@aws-cdk/aws-ec2');
+import ecs = require('@aws-cdk/aws-ecs');
+import cdk = require('@aws-cdk/cdk');
+
+class BonjourFargate extends cdk.Stack {
+  constructor(parent: cdk.App, name: string, props?: cdk.StackProps) {
+    super(parent, name, props);
+
+    // Create VPC and Fargate Cluster
+    // NOTE: Limit AZs to avoid reaching resource quotas
+    const vpc = new ec2.VpcNetwork(this, 'MyVpc', { maxAZs: 2 });
+    const cluster = new ecs.FargateCluster(this, 'Cluster', { vpc });
+
+    // Instantiate Fargate Service with just cluster and image
+    const fargateService = new ecs.LoadBalancedFargateService(this, "FargateService", {
+      cluster,
+      image: ecs.DockerHub.image("amazon/amazon-ecs-sample"),
+    });
+
+    // Output the DNS where you can access your service
+    new cdk.Output(this, 'LoadBalancerDNS', { value: fargateService.loadBalancer.dnsName });
+  }
+}
+
+const app = new cdk.App();
+
+new BonjourFargate(app, 'Bonjour');
+
+app.run();

examples/cdk-examples-typescript/package.json

@@ -28,7 +28,9 @@
     "@aws-cdk/aws-cognito": "^0.14.1",
     "@aws-cdk/aws-dynamodb": "^0.14.1",
     "@aws-cdk/aws-ec2": "^0.14.1",
+    "@aws-cdk/aws-ecs": "^0.14.1",
     "@aws-cdk/aws-elasticloadbalancing": "^0.14.1",
+    "@aws-cdk/aws-elasticloadbalancingv2": "^0.14.1",
     "@aws-cdk/aws-iam": "^0.14.1",
     "@aws-cdk/aws-lambda": "^0.14.1",
     "@aws-cdk/aws-neptune": "^0.14.1",

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

@@ -124,7 +124,7 @@ export class Asset extends cdk.Construct {
     // for tooling to be able to package and upload a directory to the
     // s3 bucket and plug in the bucket name and key in the correct
     // parameters.
-    const asset: cxapi.AssetMetadataEntry = {
+    const asset: cxapi.FileAssetMetadataEntry = {
       path: this.assetPath,
       id: this.uniqueId,
       packaging: props.packaging,

packages/@aws-cdk/aws-ecr/lib/repository-ref.ts

@@ -1,3 +1,4 @@
+import ecs = require('@aws-cdk/aws-ecs');
 import iam = require('@aws-cdk/aws-iam');
 import cdk = require('@aws-cdk/cdk');
 
@@ -44,6 +45,13 @@ export abstract class RepositoryRef extends cdk.Construct {
     const parts = cdk.ArnUtils.parse(this.repositoryArn);
     return `${parts.account}.dkr.ecr.${parts.region}.amazonaws.com/${parts.resourceName}`;
   }
+
+  /**
+   * Refer to a particular image tag from this repository
+   */
+  public getImage(tag: string = "latest"): ecs.IContainerImage {
+    return new EcrImage(this, tag);
+  }
 }
 
 export interface RepositoryRefProps {
@@ -67,3 +75,24 @@ class ImportedRepository extends RepositoryRef {
     // FIXME: Add annotation about policy we dropped on the floor
   }
 }
+
+class EcrImage implements ecs.IContainerImage {
+  public readonly imageName: string;
+  private readonly repositoryArn: string;
+
+  constructor(repository: RepositoryRef, tag: string) {
+    this.imageName = `${repository.repositoryUri}:${tag}`;
+    this.repositoryArn = repository.repositoryArn;
+  }
+
+  public bind(containerDefinition: ecs.ContainerDefinition): void {
+    // This image will be in ECR, so we need appropriate permissions.
+    containerDefinition.addToExecutionPolicy(new iam.PolicyStatement()
+      .addActions("ecr:BatchCheckLayerAvailability", "ecr:GetDownloadUrlForLayer", "ecr:BatchGetImage")
+      .addResource(this.repositoryArn));
+
+    containerDefinition.addToExecutionPolicy(new iam.PolicyStatement()
+      .addActions("ecr:GetAuthorizationToken", "logs:CreateLogStream", "logs:PutLogEvents")
+      .addAllResources());
+  }
+}

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

@@ -60,6 +60,7 @@
   },
   "dependencies": {
     "@aws-cdk/aws-iam": "^0.14.1",
+    "@aws-cdk/aws-ecs": "^0.14.1",
     "@aws-cdk/cdk": "^0.14.1"
   },
   "homepage": "https://github.com/awslabs/aws-cdk"

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

@@ -1,2 +1,142 @@
-## The CDK Construct Library for AWS Elastic Container Service (ECS)
-This module is part of the [AWS Cloud Development Kit](https://github.com/awslabs/aws-cdk) project.
+## AWS Elastic Container Service (ECS) Construct Library
+
+This package contains constructs for working with **AWS Elastic Container
+Service** (ECS). The simplest example of using this library looks like this:
+
+```ts
+// Create an ECS cluster (backed by an AutoScaling group)
+const cluster = new ecs.Ec2Cluster(this, 'Cluster', {
+  vpc,
+  size: 3,
+  instanceType: new InstanceType("t2.xlarge")
+});
+
+// Instantiate ECS Service with an automatic load balancer
+const ecsService = new ecs.LoadBalancedEc2Service(this, 'Service', {
+  cluster,
+  memoryLimitMiB: 512,
+  image: ecs.DockerHub.image("amazon/amazon-ecs-sample"),
+});
+```
+
+### Fargate vs ECS
+
+There are two sets of constructs in this library; one to run tasks on ECS and
+one to run Tasks on fargate.
+
+- Use the `Ec2Cluster`, `Ec2TaskDefinition` and `Ec2Service` constructs to
+  run tasks on EC2 instances running in your account.
+- Use the `FargateCluster`, `FargateTaskDefinition` and `FargateService`
+  constructs to run tasks on instances that are managed for you by AWS.
+
+## Cluster
+
+An `Ec2Cluster` or `FargateCluster` defines the infrastructure to run your
+tasks on. If you create an ECS cluster, an AutoScalingGroup of EC2 instances
+running the latest ECS Optimized AMI will implicitly be created for you.
+
+You can run many tasks on a single cluster.
+
+To create a cluster, go:
+
+```ts
+const cluster = new ecs.FargateCluster(this, 'Cluster', {
+  vpc: vpc
+});
+```
+
+## TaskDefinition
+
+A `TaskDefinition` describes what a single copy of a **Task** should look like.
+A task definition has one or more containers; typically, it has one
+main container (the *default container* is the first one that's added
+to the task definition, and it will be marked *essential*) and optionally
+some supporting containers which are used to support the main container,
+doings things like upload logs or metrics to monitoring services.
+
+To add containers to a `TaskDefinition`, call `addContainer()`:
+
+```ts
+const taskDefinition = new ecs.FargateTaskDefinition(this, 'TaskDef', {
+  memoryMiB: '512'
+  cpu: 256
+});
+
+taskDefinition.addContainer('main', {
+  // Use an image from DockerHub
+  image: ecs.DockerHub.image('amazon/amazon-ecs-sample')
+});
+```
+
+### Images
+
+Images supply the software that runs inside the container. Images can be
+obtained from either DockerHub or from ECR repositories:
+
+* `ecs.DockerHub.image(imageName)`: use a publicly available image from
+  DockerHub.
+* `repository.getImage(tag)`: use the given ECR repository as the image
+  to start.
+
+## Service
+
+A `Service` instantiates a `TaskDefinition` on a `Cluster` a given number of
+times, optionally associating them with a load balancer. Tasks that fail will
+automatically be restarted.
+
+```ts
+const taskDefinition;
+
+const service = new ecs.Ec2Service(this, 'Service', {
+  cluster,
+  taskDefinition,
+  desiredCount: 5
+});
+```
+
+### Include a load balancer
+
+`Services` are load balancing targets and can be directly attached to load
+balancers:
+
+```ts
+const service = new ecs.FargateService(this, 'Service', { /* ... */ });
+
+const lb = new elbv2.ApplicationLoadBalancer(this, 'LB', { vpc, internetFacing: true });
+const listener = lb.addListener('Listener', { port: 80 });
+listener.addTargets('ECS', {
+  port: 80,
+  targets: [service]
+});
+```
+
+There are two higher-level constructs available which include a load balancer for you:
+
+* `LoadBalancedFargateService`
+* `LoadBalancedEc2Service`
+
+## Task AutoScaling
+
+You can configure the task count of a service to match demand. Task AutoScaling is
+configured by calling `autoScaleTaskCount()`:
+
+```ts
+const scaling = service.autoScaleTaskCount({ maxCapacity: 10 });
+scaling.scaleOnCpuUtilization('CpuScaling', {
+  targetUtilizationPercent: 50
+});
+```
+
+Task AutoScaling is powered by *Application AutoScaling*. Refer to that for
+more information.
+
+## Instance AutoScaling
+
+If you're running on Fargate, AWS will manage the physical machines that your
+containers are running on for you. If you're running an ECS cluster however,
+your EC2 instances might fill up as your number of Tasks goes up.
+
+To avoid placement errors, you will want to configure AutoScaling for your
+EC2 instance group so that your instance count scales with demand.
+
+TO BE IMPLEMENTED