feat(ecs): VPC link for API Gatweay and ECS services (#1541)

Overview
========
The primary purpose of this work is to fill in the gaps in
implementation for deploying a VPC link between API Gateway, and an
ECS service. My goal was to allow setting up a {proxy+} API which would
forward to a Fargate service in a private VPC.

This has been tagged as 'ecs', but also involves changes to api gateway.

Since VPC links require an NLB, the LoadBalanced{Fargate|Ecs}Service classes
have been modified to support selecting either an ALB or an NLB.

Changes
=======
On the APIGW side, `IntegrationOptions` now accepts an optional connetion
type enum, as well as a VpcLink. `VpcLink` itself is a new construct
which accepts an array of Network Load Balancers. I also added the missing
`requestParameters` prop for `Method`, to allow properly setting up a proxy
path variable.

For ECS, in my use case I wanted to use the LoadBalanced*Service constructs, however
they only supported ALB. I have pulled all of the ELBv2 related setup
into the new `LoadBalancedService` base class, and also created a base
props interface `LoadBalancedServiceProps`. This deals with the common setup
between the Fargate and ECS services, and allows the selection of ALB or NLB.
As a side-effect of this refactoring, you can also now pass a Certificate to
`LoadBalancedEcsService`.

There is a new `Method` test for the VPC link props, as well as new tests
for both `VpcLink` and `LoadBalancedFargateService`.

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

@@ -6,6 +6,7 @@ export * from './deployment';
 export * from './stage';
 export * from './integrations';
 export * from './lambda-api';
+export * from './vpc-link';
 
 // AWS::ApiGateway CloudFormation Resources:
 export * from './apigateway.generated';

packages/@aws-cdk/aws-apigateway/lib/integration.ts

@@ -1,5 +1,6 @@
 import iam = require('@aws-cdk/aws-iam');
 import { Method } from './method';
+import { VpcLink } from './vpc-link';
 
 export interface IntegrationOptions {
  /**
@@ -93,6 +94,18 @@ export interface IntegrationOptions {
  * @see http://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-mapping-template-reference.html
  */
  selectionPattern?: string;
+
+ /**
+ * The type of network connection to the integration endpoint.
+ * @default ConnectionType.Internet
+ */
+ connectionType?: ConnectionType;
+
+ /**
+ * The VpcLink used for the integration.
+ * Required if connectionType is VPC_LINK
+ */
+ vpcLink?: VpcLink;
 }
 
 export interface IntegrationProps {
@@ -217,6 +230,18 @@ export enum PassthroughBehavior {
  WhenNoTemplates = 'WHEN_NO_TEMPLATES'
 }
 
+export enum ConnectionType {
+ /**
+ * For connections through the public routable internet
+ */
+ Internet = 'INTERNET',
+
+ /**
+ * For private connections between API Gateway and a network load balancer in a VPC
+ */
+ VpcLink = 'VPC_LINK'
+}
+
 export interface IntegrationResponse {
  /**
  * The status code that API Gateway uses to map the integration response to

packages/@aws-cdk/aws-apigateway/lib/method.ts

@@ -1,6 +1,6 @@
 import cdk = require('@aws-cdk/cdk');
 import { CfnMethod, CfnMethodProps } from './apigateway.generated';
-import { Integration } from './integration';
+import { ConnectionType, Integration } from './integration';
 import { MockIntegration } from './integrations/mock';
 import { IRestApiResource } from './resource';
 import { RestApi } from './restapi';
@@ -39,6 +39,7 @@ export interface MethodOptions {
  // - RequestModels
  // - RequestParameters
  // - MethodResponses
+ requestParameters?: { [param: string]: boolean };
 }
 
 export interface MethodProps {
@@ -91,6 +92,7 @@ export class Method extends cdk.Construct {
  apiKeyRequired: options.apiKeyRequired || defaultMethodOptions.apiKeyRequired,
  authorizationType: options.authorizationType || defaultMethodOptions.authorizationType || AuthorizationType.None,
  authorizerId: options.authorizerId || defaultMethodOptions.authorizerId,
+ requestParameters: options.requestParameters,
  integration: this.renderIntegration(props.integration)
  };
 
@@ -154,6 +156,14 @@ export class Method extends cdk.Construct {
  throw new Error(`'credentialsPassthrough' and 'credentialsRole' are mutually exclusive`);
  }
 
+ if (options.connectionType === ConnectionType.VpcLink && options.vpcLink === undefined) {
+ throw new Error(`'connectionType' of VPC_LINK requires 'vpcLink' prop to be set`);
+ }
+
+ if (options.connectionType === ConnectionType.Internet && options.vpcLink !== undefined) {
+ throw new Error(`cannot set 'vpcLink' where 'connectionType' is INTERNET`);
+ }
+
  if (options.credentialsRole) {
  credentials = options.credentialsRole.roleArn;
  } else if (options.credentialsPassthrough) {
@@ -173,6 +183,8 @@ export class Method extends cdk.Construct {
  requestTemplates: options.requestTemplates,
  passthroughBehavior: options.passthroughBehavior,
  integrationResponses: options.integrationResponses,
+ connectionType: options.connectionType,
+ connectionId: options.vpcLink ? options.vpcLink.vpcLinkId : undefined,
  credentials,
  };
  }

packages/@aws-cdk/aws-apigateway/lib/vpc-link.ts

@@ -0,0 +1,49 @@
+import elbv2 = require('@aws-cdk/aws-elasticloadbalancingv2');
+import cdk = require('@aws-cdk/cdk');
+import { CfnVpcLink } from './apigateway.generated';
+
+/**
+ * Properties for a VpcLink
+ */
+export interface VpcLinkProps {
+ /**
+ * The name used to label and identify the VPC link.
+ * @default automatically generated name
+ */
+ name?: string;
+
+ /**
+ * The description of the VPC link.
+ * @default no description
+ */
+ description?: string;
+
+ /**
+ * The network load balancers of the VPC targeted by the VPC link.
+ * The network load balancers must be owned by the same AWS account of the API owner.
+ */
+ targets: elbv2.INetworkLoadBalancer[];
+}
+
+/**
+ * Define a new VPC Link
+ * Specifies an API Gateway VPC link for a RestApi to access resources in an Amazon Virtual Private Cloud (VPC).
+ */
+export class VpcLink extends cdk.Construct {
+ /**
+ * Physical ID of the VpcLink resource
+ */
+ public readonly vpcLinkId: string;
+
+ constructor(scope: cdk.Construct, id: string, props: VpcLinkProps) {
+ super(scope, id);
+
+ const cfnResource = new CfnVpcLink(this, 'Resource', {
+ name: props.name || this.node.uniqueId,
+ description: props.description,
+ targetArns: props.targets.map(nlb => nlb.loadBalancerArn)
+ });
+
+ this.vpcLinkId = cfnResource.vpcLinkId;
+ }
+}

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

@@ -55,6 +55,7 @@
  "license": "Apache-2.0",
  "devDependencies": {
  "@aws-cdk/assert": "^0.22.0",
+ "@aws-cdk/aws-ec2": "^0.22.0",
  "cdk-build-tools": "^0.22.0",
  "cdk-integ-tools": "^0.22.0",
  "cfn2ts": "^0.22.0",
@@ -63,12 +64,14 @@
  "dependencies": {
  "@aws-cdk/aws-iam": "^0.22.0",
  "@aws-cdk/aws-lambda": "^0.22.0",
+ "@aws-cdk/aws-elasticloadbalancingv2": "^0.22.0",
  "@aws-cdk/cdk": "^0.22.0"
  },
  "homepage": "https://github.com/awslabs/aws-cdk",
  "peerDependencies": {
  "@aws-cdk/aws-iam": "^0.22.0",
  "@aws-cdk/aws-lambda": "^0.22.0",
+ "@aws-cdk/aws-elasticloadbalancingv2": "^0.22.0",
  "@aws-cdk/cdk": "^0.22.0"
  },
  "engines": {
@@ -79,4 +82,4 @@
  "resource-attribute:@aws-cdk/aws-apigateway.IRestApi.restApiRootResourceId"
  ]
  }
-}
+}

packages/@aws-cdk/aws-apigateway/test/test.method.ts

@@ -1,8 +1,11 @@
 import { expect, haveResource, haveResourceLike } from '@aws-cdk/assert';
+import ec2 = require('@aws-cdk/aws-ec2');
+import elbv2 = require('@aws-cdk/aws-elasticloadbalancingv2');
 import iam = require('@aws-cdk/aws-iam');
 import cdk = require('@aws-cdk/cdk');
 import { Test } from 'nodeunit';
 import apigateway = require('../lib');
+import { ConnectionType } from '../lib';
 
 export = {
  'default setup'(test: Test) {
@@ -254,4 +257,50 @@ export = {
  test.throws(() => api.root.addMethod('GET', integration), /'credentialsPassthrough' and 'credentialsRole' are mutually exclusive/);
  test.done();
  },
+
+ 'integration connectionType VpcLink requires vpcLink to be set'(test: Test) {
+ // GIVEN
+ const stack = new cdk.Stack();
+ const api = new apigateway.RestApi(stack, 'test-api', { deploy: false });
+
+ // WHEN
+ const integration = new apigateway.Integration({
+ type: apigateway.IntegrationType.HttpProxy,
+ integrationHttpMethod: 'ANY',
+ options: {
+ connectionType: ConnectionType.VpcLink,
+ }
+ });
+
+ // THEN
+ test.throws(() => api.root.addMethod('GET', integration), /'connectionType' of VPC_LINK requires 'vpcLink' prop to be set/);
+ test.done();
+ },
+
+ 'connectionType of INTERNET and vpcLink are mutually exclusive'(test: Test) {
+ // GIVEN
+ const stack = new cdk.Stack();
+ const api = new apigateway.RestApi(stack, 'test-api', { deploy: false });
+ const vpc = new ec2.VpcNetwork(stack, 'VPC');
+ const nlb = new elbv2.NetworkLoadBalancer(stack, 'NLB', {
+ vpc
+ });
+ const link = new apigateway.VpcLink(stack, 'link', {
+ targets: [nlb]
+ });
+
+ // WHEN
+ const integration = new apigateway.Integration({
+ type: apigateway.IntegrationType.HttpProxy,
+ integrationHttpMethod: 'ANY',
+ options: {
+ connectionType: ConnectionType.Internet,
+ vpcLink: link
+ }
+ });
+
+ // THEN
+ test.throws(() => api.root.addMethod('GET', integration), /cannot set 'vpcLink' where 'connectionType' is INTERNET/);
+ test.done();
+ }
 };

packages/@aws-cdk/aws-apigateway/test/test.vpc-link.ts

@@ -0,0 +1,31 @@
+import { expect, haveResourceLike } from '@aws-cdk/assert';
+import ec2 = require('@aws-cdk/aws-ec2');
+import elbv2 = require('@aws-cdk/aws-elasticloadbalancingv2');
+import cdk = require('@aws-cdk/cdk');
+import { Test } from 'nodeunit';
+import apigateway = require('../lib');
+
+export = {
+ 'default setup'(test: Test) {
+ // GIVEN
+ const stack = new cdk.Stack();
+ const vpc = new ec2.VpcNetwork(stack, 'VPC');
+ const nlb = new elbv2.NetworkLoadBalancer(stack, 'NLB', {
+ vpc
+ });
+
+ // WHEN
+ new apigateway.VpcLink(stack, 'VpcLink', {
+ name: 'MyLink',
+ targets: [nlb]
+ });
+
+ // THEN
+ expect(stack).to(haveResourceLike('AWS::ApiGateway::VpcLink', {
+ Name: "MyLink",
+ TargetArns: [ { Ref: "NLB55158F82" } ]
+ }));
+
+ test.done();
+ },
+};

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

@@ -13,6 +13,7 @@ export * from './fargate/fargate-service';
 export * from './fargate/fargate-task-definition';
 
 export * from './linux-parameters';
+export * from './load-balanced-service-base';
 export * from './load-balanced-ecs-service';
 export * from './load-balanced-fargate-service';
 export * from './load-balanced-ecs-service';

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

@@ -1,24 +1,12 @@
-import elbv2 = require('@aws-cdk/aws-elasticloadbalancingv2');
 import cdk = require('@aws-cdk/cdk');
-import { ICluster } from './cluster';
-import { IContainerImage } from './container-image';
 import { Ec2Service } from './ec2/ec2-service';
 import { Ec2TaskDefinition } from './ec2/ec2-task-definition';
+import { LoadBalancedServiceBase, LoadBalancedServiceBaseProps } from './load-balanced-service-base';
 
 /**
  * Properties for a LoadBalancedEc2Service
  */
-export interface LoadBalancedEc2ServiceProps {
- /**
- * The cluster where your EC2 service will be deployed
- */
- cluster: ICluster;
-
- /**
- * The image to start.
- */
- image: IContainerImage;
-
+export interface LoadBalancedEc2ServiceProps extends LoadBalancedServiceBaseProps {
  /**
  * The hard limit (in MiB) of memory to present to the container.
  *
@@ -40,47 +28,14 @@ export interface LoadBalancedEc2ServiceProps {
  * At least one of memoryLimitMiB and memoryReservationMiB is required.
  */
  memoryReservationMiB?: number;
-
- /**
- * The container port of the application load balancer attached to your EC2 service. Corresponds to container port mapping.
- *
- * @default 80
- */
- containerPort?: number;
-
- /**
- * Determines whether the Application Load Balancer will be internet-facing
- *
- * @default true
- */
- publicLoadBalancer?: boolean;
-
- /**
- * Number of desired copies of running tasks
- *
- * @default 1
- */
- desiredCount?: number;
-
- /**
- * Environment variables to pass to the container
- *
- * @default No environment variables
- */
- environment?: { [key: string]: string };
 }
 
 /**
  * A single task running on an ECS cluster fronted by a load balancer
  */
-export class LoadBalancedEc2Service extends cdk.Construct {
- /**
- * The load balancer that is fronting the ECS service
- */
- public readonly loadBalancer: elbv2.ApplicationLoadBalancer;
-
+export class LoadBalancedEc2Service extends LoadBalancedServiceBase {
  constructor(scope: cdk.Construct, id: string, props: LoadBalancedEc2ServiceProps) {
- super(scope, id);
+ super(scope, id, props);
 
  const taskDefinition = new Ec2TaskDefinition(this, 'TaskDef', {});
 
@@ -100,20 +55,6 @@ export class LoadBalancedEc2Service extends cdk.Construct {
  taskDefinition,
  });
 
- const internetFacing = props.publicLoadBalancer !== undefined ? props.publicLoadBalancer : true;
- const lb = new elbv2.ApplicationLoadBalancer(this, 'LB', {
- vpc: props.cluster.vpc,
- internetFacing
- });
-
- this.loadBalancer = lb;
-
- const listener = lb.addListener('PublicListener', { port: 80, open: true });
- listener.addTargets('ECS', {
- port: 80,
- targets: [service]
- });
-
- new cdk.Output(this, 'LoadBalancerDNS', { value: lb.dnsName });
+ this.addServiceAsTarget(service);
  }
 }