Merge branch 'master' into rds-secret-replication

packages/@aws-cdk-containers/ecs-service-extensions/README.md

@@ -19,7 +19,8 @@ The `Service` construct provided by this module can be extended with optional `S
 - [AWS AppMesh](https://aws.amazon.com/app-mesh/) for adding your application to a service mesh
 - [Application Load Balancer](https://docs.aws.amazon.com/elasticloadbalancing/latest/application/introduction.html), for exposing your service to the public
 - [AWS FireLens](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/using_firelens.html), for filtering and routing application logs
-- Queue to allow your service to consume messages from an SQS Queue which is populated by one or more SNS Topics that it is subscribed to
+- [Injecter Extension](#injecter-extension), for allowing your service connect to other AWS services by granting permission and injecting environment variables
+- [Queue Extension](#queue-extension), for allowing your service to consume messages from an SQS Queue which can be populated by one or more SNS Topics that it is subscribed to
 - [Community Extensions](#community-extensions), providing support for advanced use cases
 
 The `ServiceExtension` class is an abstract class which you can also implement in
@@ -322,9 +323,28 @@ const environment = Environment.fromEnvironmentAttributes(stack, 'Environment',
 
 ```
 
+## Injecter Extension
+
+This service extension accepts a list of `Injectable` resources. It grants access to these resources and adds the necessary environment variables to the tasks that are part of the service. 
+
+For example, an `InjectableTopic` is an SNS Topic that grants permission to the task role and adds the topic ARN as an environment variable to the task definition.
+
+### Publishing to SNS Topics
+
+You can use this extension to set up publishing permissions for SNS Topics.
+
+```ts
+nameDescription.add(new InjecterExtension({
+  injectables: [new InjectableTopic({
+    // SNS Topic the service will publish to
+    topic: new sns.Topic(stack, 'my-topic'),
+  })],
+}));
+```
+
 ## Queue Extension
 
-This service extension creates a default SQS Queue `eventsQueue` for the service (if not provided) and accepts a list of `ISubscribable` objects that the `eventsQueue` can subscribe to. The service extension creates the subscriptions and sets up permissions for the service to consume messages from the SQS Queue.
+This service extension creates a default SQS Queue `eventsQueue` for the service (if not provided) and optionally also accepts list of `ISubscribable` objects that the `eventsQueue` can subscribe to. The service extension creates the subscriptions and sets up permissions for the service to consume messages from the SQS Queue.
 
 ### Setting up SNS Topic Subscriptions for SQS Queues
 
@@ -356,6 +376,60 @@ nameDescription.add(new QueueExtension({
 }));
 ```
 
+## Publish/Subscribe Service Pattern
+
+The [Publish/Subscribe Service Pattern](https://aws.amazon.com/pub-sub-messaging/) is used for implementing asynchronous communication between services. It involves 'publisher' services emitting events to SNS Topics, which are passed to subscribed SQS queues and then consumed by 'worker' services. 
+
+The following example adds the `InjecterExtension` to a `Publisher` Service which can publish events to an SNS Topic and adds the `QueueExtension` to a `Worker` Service which can poll its `eventsQueue` to consume messages populated by the topic.
+
+```ts
+const environment = new Environment(stack, 'production');
+
+const pubServiceDescription = new ServiceDescription();
+pubServiceDescription.add(new Container({
+  cpu: 256,
+  memoryMiB: 512,
+  trafficPort: 80,
+  image: ecs.ContainerImage.fromRegistry('sns-publish'),
+}));
+
+const myTopic = new sns.Topic(stack, 'myTopic');
+
+// Add the `InjecterExtension` to the service description to allow publishing events to `myTopic`
+pubServiceDescription.add(new InjecterExtension({
+  injectables: [new InjectableTopic({
+    topic: myTopic,
+  }],
+}));
+
+// Create the `Publisher` Service
+new Service(stack, 'Publisher', {
+  environment: environment,
+  serviceDescription: pubServiceDescription,
+});
+
+const subServiceDescription = new ServiceDescription();
+subServiceDescription.add(new Container({
+  cpu: 256,
+  memoryMiB: 512,
+  trafficPort: 80,
+  image: ecs.ContainerImage.fromRegistry('sqs-reader'),
+}));
+
+// Add the `QueueExtension` to the service description to subscribe to `myTopic`
+subServiceDescription.add(new QueueExtension({
+  subscriptions: [new TopicSubscription({
+    topic: myTopic,
+  }],
+}));
+
+// Create the `Worker` Service
+new Service(stack, 'Worker', {
+  environment: environment,
+  serviceDescription: subServiceDescription,
+});
+```
+
 ## Community Extensions
 
 We encourage the development of Community Service Extensions that support

packages/@aws-cdk-containers/ecs-service-extensions/lib/extensions/index.ts

@@ -6,4 +6,5 @@ export * from './cloudwatch-agent';
 export * from './scale-on-cpu-utilization';
 export * from './xray';
 export * from './assign-public-ip';
-export * from './queue';
+export * from './queue';
+export * from './injecter';

packages/@aws-cdk-containers/ecs-service-extensions/lib/extensions/injecter.ts

@@ -0,0 +1,154 @@
+import * as ecs from '@aws-cdk/aws-ecs';
+import * as sns from '@aws-cdk/aws-sns';
+import { Service } from '../service';
+import { Container } from './container';
+import { ContainerMutatingHook, ServiceExtension } from './extension-interfaces';
+
+// Keep this import separate from other imports to reduce chance for merge conflicts with v2-main
+// eslint-disable-next-line no-duplicate-imports, import/order
+import { Construct } from '@aws-cdk/core';
+
+/**
+ * An interface that will be implemented by all the resources that can be published events or written data to.
+ */
+export interface Injectable {
+  environmentVariables(): { [key: string]: string };
+}
+
+/**
+ * An interface that will be implemented by all the injectable resources that need to grant permissions to the task role.
+ */
+export interface GrantInjectable extends Injectable {
+  grant(taskDefinition: ecs.TaskDefinition): void;
+}
+
+/**
+ * The settings for the `InjectableTopic` class.
+ */
+export interface InjectableTopicProps {
+  /**
+   * The SNS Topic to publish events to.
+   */
+  readonly topic: sns.ITopic;
+}
+
+/**
+ * The `InjectableTopic` class represents SNS Topic resource that can be published events to by the parent service.
+ */
+
+export class InjectableTopic implements GrantInjectable {
+  public readonly topic: sns.ITopic;
+
+  constructor(props: InjectableTopicProps) {
+    this.topic = props.topic;
+  }
+
+  public grant(taskDefinition: ecs.TaskDefinition) {
+    this.topic.grantPublish(taskDefinition.taskRole);
+  }
+
+  public environmentVariables(): { [key: string]: string } {
+    let environment: { [key: string]: string } = {};
+    environment[`${this.topic.node.id.toUpperCase()}_TOPIC_ARN`] = this.topic.topicArn;
+    return environment;
+  }
+}
+
+/**
+ * The settings for the Injecter extension.
+ */
+export interface InjecterExtensionProps {
+  /**
+   * The list of injectable resources for this service.
+   */
+  readonly injectables: Injectable[];
+}
+
+/**
+ * Settings for the hook which mutates the application container
+ * to add the injectable resource environment variables.
+ */
+interface ContainerMutatingProps {
+  /**
+   * The resource environment variables to be added to the container environment.
+   */
+  readonly environment: { [key: string]: string };
+}
+
+/**
+ * This hook modifies the application container's environment to
+ * add the injectable resource environment variables.
+ */
+class InjecterExtensionMutatingHook extends ContainerMutatingHook {
+  private environment: { [key: string]: string };
+
+  constructor(props: ContainerMutatingProps) {
+    super();
+    this.environment = props.environment;
+  }
+
+  public mutateContainerDefinition(props: ecs.ContainerDefinitionOptions): ecs.ContainerDefinitionOptions {
+    return {
+      ...props,
+
+      environment: { ...(props.environment || {}), ...this.environment },
+    } as ecs.ContainerDefinitionOptions;
+  }
+}
+
+/**
+ * This extension accepts a list of `Injectable` resources that the parent service can publish events or write data to.
+ * It sets up the corresponding permissions for the task role of the parent service.
+ */
+export class InjecterExtension extends ServiceExtension {
+  private props: InjecterExtensionProps;
+
+  private environment: { [key: string]: string } = {};
+
+  constructor(props: InjecterExtensionProps) {
+    super('injecter');
+
+    this.props = props;
+  }
+
+  // @ts-ignore - Ignore unused params that are required for abstract class extend
+  public prehook(service: Service, scope: Construct) {
+    this.parentService = service;
+
+    for (const injectable of this.props.injectables) {
+      for (const [key, val] of Object.entries(injectable.environmentVariables())) {
+        this.environment[key] = val;
+      }
+    }
+  }
+
+  /**
+   * Add hooks to the main application extension so that it is modified to
+   * add the injectable resource environment variables to the container environment.
+   */
+  public addHooks() {
+    const container = this.parentService.serviceDescription.get('service-container') as Container;
+
+    if (!container) {
+      throw new Error('Injecter Extension requires an application extension');
+    }
+
+    container.addContainerMutatingHook(new InjecterExtensionMutatingHook({
+      environment: this.environment,
+    }));
+  }
+
+  /**
+   * After the task definition has been created, this hook grants the required permissions to the task role for the
+   * parent service.
+   *
+   * @param taskDefinition The created task definition
+   */
+  public useTaskDefinition(taskDefinition: ecs.TaskDefinition) {
+    for (const injectable of this.props.injectables) {
+      if ((injectable as GrantInjectable).grant !== undefined) {
+        (injectable as GrantInjectable).grant(taskDefinition);
+      }
+    }
+  }
+}

packages/@aws-cdk-containers/ecs-service-extensions/test/injecter.test.ts

@@ -0,0 +1,114 @@
+import { countResources, expect, haveResource } from '@aws-cdk/assert-internal';
+import * as ecs from '@aws-cdk/aws-ecs';
+import * as sns from '@aws-cdk/aws-sns';
+import * as cdk from '@aws-cdk/core';
+import { Container, Environment, InjecterExtension, InjectableTopic, Service, ServiceDescription } from '../lib';
+
+describe('injecter', () => {
+  test('correctly sets publish permissions for given topics', () => {
+    // GIVEN
+    const stack = new cdk.Stack();
+
+    const environment = new Environment(stack, 'production');
+    const serviceDescription = new ServiceDescription();
+
+    serviceDescription.add(new Container({
+      cpu: 256,
+      memoryMiB: 512,
+      trafficPort: 80,
+      image: ecs.ContainerImage.fromRegistry('nathanpeck/name'),
+      environment: {
+        PORT: '80',
+      },
+    }));
+
+    // WHEN
+    const topic1 = new InjectableTopic({
+      topic: new sns.Topic(stack, 'topic1'),
+    });
+
+    const topic2 = new InjectableTopic({
+      topic: new sns.Topic(stack, 'topic2'),
+    });
+
+    serviceDescription.add(new InjecterExtension({
+      injectables: [topic1, topic2],
+    }));
+
+    new Service(stack, 'my-service', {
+      environment,
+      serviceDescription,
+    });
+
+    // THEN
+    // Ensure creation of provided topics
+    expect(stack).to(countResources('AWS::SNS::Topic', 2));
+
+    // Ensure the task role is given permissions to publish events to topics
+    expect(stack).to(haveResource('AWS::IAM::Policy', {
+      PolicyDocument: {
+        Statement: [
+          {
+            Action: 'sns:Publish',
+            Effect: 'Allow',
+            Resource: {
+              Ref: 'topic152D84A37',
+            },
+          },
+          {
+            Action: 'sns:Publish',
+            Effect: 'Allow',
+            Resource: {
+              Ref: 'topic2A4FB547F',
+            },
+          },
+        ],
+        Version: '2012-10-17',
+      },
+    }));
+
+    // Ensure that the topic ARNs have been correctly appended to the environment variables
+    expect(stack).to(haveResource('AWS::ECS::TaskDefinition', {
+      ContainerDefinitions: [
+        {
+          Cpu: 256,
+          Environment: [
+            {
+              Name: 'PORT',
+              Value: '80',
+            },
+            {
+              Name: 'TOPIC1_TOPIC_ARN',
+              Value: {
+                Ref: 'topic152D84A37',
+              },
+            },
+            {
+              Name: 'TOPIC2_TOPIC_ARN',
+              Value: {
+                Ref: 'topic2A4FB547F',
+              },
+            },
+          ],
+          Image: 'nathanpeck/name',
+          Essential: true,
+          Memory: 512,
+          Name: 'app',
+          PortMappings: [
+            {
+              ContainerPort: 80,
+              Protocol: 'tcp',
+            },
+          ],
+          Ulimits: [
+            {
+              HardLimit: 1024000,
+              Name: 'nofile',
+              SoftLimit: 1024000,
+            },
+          ],
+        },
+      ],
+    }));
+  });
+});