feat(aws-ecs): add support for Event Targets

EC2 task definitions can now be used as CloudWatch event targets.

ALSO IN THIS COMMIT

* Improve hash calculation of Docker images.
* Add `grantPassRole()` method to iam.Role

Fixes #1370.

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

@@ -263,6 +263,15 @@ autoScalingGroup.scaleOnCpuUtilization('KeepCpuHalfwayLoaded', {
 See the `@aws-cdk/aws-autoscaling` library for more autoscaling options
 you can configure on your instances.
 
+### Integration with CloudWatch Events
+
+To start an ECS task on an EC2-backed Cluster, instantiate an
+`Ec2TaskEventRuleTarget` intead of an `Ec2Service`:
+
+[example of CloudWatch Events integration](test/ec2/integ.event-task.lit.ts)
+
+> Note: it is currently not possible to start Fargate tasks in this way.
+
 ### Roadmap
 
 - [ ] Service Discovery Integration

packages/@aws-cdk/aws-ecs/lib/base/task-definition.ts

@@ -133,6 +133,13 @@ export class TaskDefinition extends cdk.Construct {
    */
   public compatibility: Compatibility;
 
+  /**
+   * Execution role for this task definition
+   *
+   * May not exist, will be created as needed.
+   */
+  public executionRole?: iam.IRole;
+
   /**
    * All containers
    */
@@ -143,13 +150,6 @@ export class TaskDefinition extends cdk.Construct {
    */
   private readonly volumes: Volume[] = [];
 
-  /**
-   * Execution role for this task definition
-   *
-   * Will be created as needed.
-   */
-  private executionRole?: iam.Role;
-
   /**
    * Placement constraints for task instances
    */

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

@@ -147,6 +147,7 @@ export class Cluster extends cdk.Construct implements ICluster {
   public export(): ClusterImportProps {
     return {
       clusterName: new cdk.Output(this, 'ClusterName', { value: this.clusterName }).makeImportValue().toString(),
+      clusterArn: this.clusterArn,
       vpc: this.vpc.export(),
       securityGroups: this.connections.securityGroups.map(sg => sg.export()),
       hasEc2Capacity: this.hasEc2Capacity,
@@ -233,6 +234,11 @@ export interface ICluster extends cdk.IConstruct {
    */
   readonly clusterName: string;
 
+  /**
+   * The ARN of this cluster
+   */
+  readonly clusterArn: string;
+
   /**
    * VPC that the cluster instances are running in
    */
@@ -263,6 +269,13 @@ export interface ClusterImportProps {
    */
   clusterName: string;
 
+  /**
+   * ARN of the cluster
+   *
+   * @default Derived from clusterName
+   */
+  clusterArn?: string;
+
   /**
    * VPC that the cluster instances are running in
    */
@@ -290,6 +303,11 @@ class ImportedCluster extends cdk.Construct implements ICluster {
    */
   public readonly clusterName: string;
 
+  /**
+   * ARN of the cluster
+   */
+  public readonly clusterArn: string;
+
   /**
    * VPC that the cluster instances are running in
    */
@@ -311,6 +329,12 @@ class ImportedCluster extends cdk.Construct implements ICluster {
     this.vpc = ec2.VpcNetwork.import(this, "vpc", props.vpc);
     this.hasEc2Capacity = props.hasEc2Capacity !== false;
 
+    this.clusterArn = props.clusterArn !== undefined ? props.clusterArn : cdk.Stack.find(this).formatArn({
+      service: 'ecs',
+      resource: 'cluster',
+      resourceName: props.clusterName,
+    });
+
     let i = 1;
     for (const sgProps of props.securityGroups) {
       this.connections.addSecurityGroup(ec2.SecurityGroup.import(this, `SecurityGroup${i}`, sgProps));

packages/@aws-cdk/aws-ecs/lib/ec2/ec2-task-event-rule-target.ts

@@ -0,0 +1,101 @@
+import events = require ('@aws-cdk/aws-events');
+import iam = require('@aws-cdk/aws-iam');
+import cdk = require('@aws-cdk/cdk');
+import { TaskDefinition } from '../base/task-definition';
+import { ICluster } from '../cluster';
+import { isEc2Compatible } from '../util';
+
+/**
+ * Properties to define an EC2 Event Task
+ */
+export interface Ec2EventTaskProps {
+  /**
+   * Cluster where service will be deployed
+   */
+  cluster: ICluster;
+
+  /**
+   * Task Definition of the task that should be started
+   */
+  taskDefinition: TaskDefinition;
+
+  /**
+   * How many tasks should be started when this event is triggered
+   *
+   * @default 1
+   */
+  taskCount?: number;
+}
+
+/**
+ * Start a service on an EC2 cluster
+ */
+export class Ec2TaskEventRuleTarget extends cdk.Construct implements events.IEventRuleTarget {
+  private readonly cluster: ICluster;
+  private readonly taskDefinition: TaskDefinition;
+  private readonly taskCount: number;
+
+  constructor(scope: cdk.Construct, id: string, props: Ec2EventTaskProps) {
+    super(scope, id);
+
+    if (!isEc2Compatible(props.taskDefinition.compatibility)) {
+      throw new Error('Supplied TaskDefinition is not configured for compatibility with EC2');
+    }
+
+    this.cluster = props.cluster;
+    this.taskDefinition = props.taskDefinition;
+    this.taskCount = props.taskCount !== undefined ? props.taskCount : 1;
+  }
+
+  /**
+   * Allows using containers as target of CloudWatch events
+   */
+  public asEventRuleTarget(_ruleArn: string, _ruleUniqueId: string): events.EventRuleTargetProps {
+    const role = this.eventsRole;
+
+    role.addToPolicy(new iam.PolicyStatement()
+      .addAction('ecs:RunTask')
+      .addResource(this.taskDefinition.taskDefinitionArn)
+      .addCondition('ArnEquals', { "ecs:cluster": this.cluster.clusterArn }));
+
+    return {
+      id: this.node.id,
+      arn: this.cluster.clusterArn,
+      roleArn: role.roleArn,
+      ecsParameters: {
+        taskCount: this.taskCount,
+        taskDefinitionArn: this.taskDefinition.taskDefinitionArn
+      }
+    };
+  }
+
+  /**
+   * Create or get the IAM Role used to start this Task Definition.
+   *
+   * We create it under the TaskDefinition object so that if we have multiple EventTargets
+   * they can reuse the same role.
+   */
+  public get eventsRole(): iam.IRole {
+    let role = this.taskDefinition.node.tryFindChild('EventsRole') as iam.IRole;
+    if (role === undefined) {
+      role = new iam.Role(this.taskDefinition, 'EventsRole', {
+        assumedBy: new iam.ServicePrincipal('events.amazonaws.com')
+      });
+    }
+
+    return role;
+  }
+
+  /**
+   * Prepare the Event Rule Target
+   */
+  protected prepare() {
+    // If it so happens that a Task Execution Role was created for the TaskDefinition,
+    // then the CloudWatch Events Role must have permissions to pass it (otherwise it doesn't).
+    //
+    // It never needs permissions to the Task Role.
+    if (this.taskDefinition.executionRole !== undefined) {
+      this.taskDefinition.taskRole.grantPassRole(this.eventsRole);
+    }
+  }
+}

packages/@aws-cdk/aws-ecs/lib/index.ts

@@ -8,6 +8,7 @@ export * from './cluster';
 
 export * from './ec2/ec2-service';
 export * from './ec2/ec2-task-definition';
+export * from './ec2/ec2-task-event-rule-target';
 
 export * from './fargate/fargate-service';
 export * from './fargate/fargate-task-definition';

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

@@ -71,6 +71,7 @@
     "@aws-cdk/aws-cloudwatch": "^0.22.0",
     "@aws-cdk/aws-ec2": "^0.22.0",
     "@aws-cdk/aws-ecr": "^0.22.0",
+    "@aws-cdk/aws-events": "^0.22.0",
     "@aws-cdk/aws-elasticloadbalancing": "^0.22.0",
     "@aws-cdk/aws-elasticloadbalancingv2": "^0.22.0",
     "@aws-cdk/aws-iam": "^0.22.0",

packages/@aws-cdk/aws-ecs/test/ec2/integ.event-task.lit.ts

@@ -0,0 +1,48 @@
+import ec2 = require('@aws-cdk/aws-ec2');
+import events = require('@aws-cdk/aws-events');
+import cdk = require('@aws-cdk/cdk');
+import ecs = require('../../lib');
+
+const app = new cdk.App();
+const stack = new cdk.Stack(app, 'aws-ecs-integ-ecs');
+
+const vpc = new ec2.VpcNetwork(stack, 'Vpc', { maxAZs: 1 });
+
+const cluster = new ecs.Cluster(stack, 'EcsCluster', { vpc });
+cluster.addDefaultAutoScalingGroupCapacity({
+  instanceType: new ec2.InstanceType('t2.micro')
+});
+
+/// !show
+// Create a Task Definition for the container to start
+const taskDefinition = new ecs.Ec2TaskDefinition(stack, 'TaskDef');
+taskDefinition.addContainer('TheContainer', {
+  image: ecs.ContainerImage.fromAsset(stack, 'EventImage', { directory: 'eventhandler-image' }),
+  memoryLimitMiB: 256,
+  logging: new ecs.AwsLogDriver(stack, 'TaskLogging', { streamPrefix: 'EventDemo' })
+});
+
+// An EventRule that describes the event trigger (in this case a scheduled run)
+const rule = new events.EventRule(stack, 'Rule', {
+  scheduleExpression: 'rate(1 minute)',
+});
+
+// Use Ec2TaskEventRuleTarget as the target of the EventRule
+const target = new ecs.Ec2TaskEventRuleTarget(stack, 'EventTarget', {
+  cluster,
+  taskDefinition,
+  taskCount: 1
+});
+
+// Pass an environment variable to the container 'TheContainer' in the task
+rule.addTarget(target, {
+  jsonTemplate: JSON.stringify({
+    containerOverrides: [{
+      name: 'TheContainer',
+      environment: [{ name: 'I_WAS_TRIGGERED', value: 'From CloudWatch Events' }]
+    }]
+  })
+});
+/// !hide
+
+app.run();

packages/@aws-cdk/aws-ecs/test/eventhandler-image/Dockerfile

@@ -0,0 +1,5 @@
+FROM python:3.6
+EXPOSE 8000
+WORKDIR /src
+ADD . /src
+CMD python3 index.py

packages/@aws-cdk/aws-ecs/test/eventhandler-image/index.py

@@ -0,0 +1,6 @@
+#!/usr/bin/python
+import os
+import pprint
+
+print('Hello from ECS!')
+pprint.pprint(dict(os.environ))

packages/@aws-cdk/aws-iam/lib/role.ts

@@ -206,6 +206,26 @@ export class Role extends Construct implements IRole {
     this.attachedPolicies.attach(policy);
     policy.attachToRole(this);
   }
+
+  /**
+   * Grant the actions defined in actions to the identity Principal on this resource.
+   */
+  public grant(identity?: IPrincipal, ...actions: string[]) {
+      if (!identity) {
+        return;
+      }
+
+      identity.addToPolicy(new PolicyStatement()
+        .addResource(this.roleArn)
+        .addActions(...actions));
+  }
+
+  /**
+   * Grant permissions to the given principal to pass this role.
+   */
+  public grantPassRole(identity?: IPrincipal) {
+    this.grant(identity, 'iam:PassRole');
+  }
 }
 
 /**

packages/@aws-cdk/aws-iam/test/test.role.ts

@@ -1,7 +1,7 @@
-import { expect, haveResource } from '@aws-cdk/assert';
+import { expect, haveResource, haveResourceLike } from '@aws-cdk/assert';
 import { Resource, Stack } from '@aws-cdk/cdk';
 import { Test } from 'nodeunit';
-import { ArnPrincipal, CompositePrincipal, FederatedPrincipal, PolicyStatement, Role, ServicePrincipal } from '../lib';
+import { ArnPrincipal, CompositePrincipal, FederatedPrincipal, PolicyStatement, Role, ServicePrincipal, User } from '../lib';
 
 export = {
   'default role'(test: Test) {
@@ -24,6 +24,32 @@ export = {
     test.done();
   },
 
+  'a role can grant PassRole permissions'(test: Test) {
+    // GIVEN
+    const stack = new Stack();
+    const role = new Role(stack, 'Role', { assumedBy: new ServicePrincipal('henk.amazonaws.com') });
+    const user = new User(stack, 'User');
+
+    // WHEN
+    role.grantPassRole(user);
+
+    // THEN
+    expect(stack).to(haveResourceLike('AWS::IAM::Policy', {
+      PolicyDocument: {
+        Statement: [
+          {
+            Action: "iam:PassRole",
+            Effect: "Allow",
+            Resource: { "Fn::GetAtt": [ "Role1ABCC5F0", "Arn" ] }
+          }
+        ],
+        Version: "2012-10-17"
+      },
+    }));
+
+    test.done();
+  },
+
   'can supply externalId'(test: Test) {
     // GIVEN
     const stack = new Stack();

packages/aws-cdk/lib/docker.ts

@@ -102,6 +102,13 @@ async function calculateImageFingerprint(imageId: string) {
   // We're not interested in the Docker version used to create this image
   delete manifest.DockerVersion;
 
+  // On some Docker versions Metadata contains a LastTagTime which updates
+  // on every push, causing us to miss all cache hits.
+  delete manifest.Metadata;
+
+  // GraphDriver is about running the image, not about
+  delete manifest.GraphDriver;
+
   return crypto.createHash('sha256').update(JSON.stringify(manifest)).digest('hex');
 }