feat(aws-lambda): allow placing Lambda in VPC

packages/@aws-cdk/aws-ec2/lib/connections.ts

@@ -61,8 +61,16 @@ export interface ConnectionsProps {
  *
  */
 export class Connections {
+    /**
+     * Underlying securityGroup for this Connections object, if present
+     *
+     * May be empty if this Connections object is not managing a SecurityGroup,
+     * but simply representing a Connectable peer.
+     */
+    public readonly securityGroup?: SecurityGroupRef;
+
     private readonly securityGroupRule: ISecurityGroupRule;
-    private readonly securityGroup?: SecurityGroupRef;
+
     private readonly defaultPortRange?: IPortRange;
 
     constructor(props: ConnectionsProps) {

packages/@aws-cdk/aws-lambda/lib/lambda-ref.ts

@@ -1,4 +1,5 @@
 import cloudwatch = require('@aws-cdk/aws-cloudwatch');
+import ec2 = require('@aws-cdk/aws-ec2');
 import events = require('@aws-cdk/aws-events');
 import iam = require('@aws-cdk/aws-iam');
 import logs = require('@aws-cdk/aws-logs');
@@ -22,10 +23,16 @@ export interface FunctionRefProps {
      * If the role is not specified, any role-related operations will no-op.
      */
     role?: iam.Role;
+
+    /**
+     * SecurityGroupId of the securityGroup for this Lambda, if configured.
+     */
+    securityGroupId?: ec2.SecurityGroupId;
 }
 
 export abstract class FunctionRef extends cdk.Construct
-    implements events.IEventRuleTarget, logs.ILogSubscriptionDestination, s3n.IBucketNotificationDestination {
+    implements events.IEventRuleTarget, logs.ILogSubscriptionDestination, s3n.IBucketNotificationDestination,
+    ec2.IConnectable   {
 
     /**
      * Creates a Lambda function object which represents a function not defined
@@ -134,6 +141,13 @@ export abstract class FunctionRef extends cdk.Construct
      */
     protected abstract readonly canCreatePermissions: boolean;
 
+    /**
+     * Actual connections object for this Lambda
+     *
+     * May be unset, in which case this Lambda is not configured use in a VPC.
+     */
+    protected _connections?: ec2.Connections;
+
     /**
      * Indicates if the policy that allows CloudWatch logs to publish to this lambda has been added.
      */
@@ -170,6 +184,18 @@ export abstract class FunctionRef extends cdk.Construct
         this.role.addToPolicy(statement);
     }
 
+    /**
+     * Access the Connections object
+     *
+     * Will fail if not a VPC-enabled Lambda Function
+     */
+    public get connections(): ec2.Connections {
+        if (!this._connections) {
+            throw new Error('Only VPC-associated Lambda Functions can have their security groups managed.');
+        }
+        return this._connections;
+    }
+
     /**
      * Returns a RuleTarget that can be used to trigger this Lambda as a
      * result from a CloudWatch event.
@@ -261,6 +287,9 @@ export abstract class FunctionRef extends cdk.Construct
     public export(): FunctionRefProps {
         return {
             functionArn: new cdk.Output(this, 'FunctionArn', { value: this.functionArn }).makeImportValue(),
+            securityGroupId: this._connections && this._connections.securityGroup
+                    ? new cdk.Output(this, 'SecurityGroupId', { value: this._connections.securityGroup.securityGroupId }).makeImportValue()
+                    : undefined
         };
     }
 
@@ -322,6 +351,14 @@ class LambdaRefImport extends FunctionRef {
         this.functionArn = props.functionArn;
         this.functionName = this.extractNameFromArn(props.functionArn);
         this.role = props.role;
+
+        if (props.securityGroupId) {
+            this._connections = new ec2.Connections({
+                securityGroup: ec2.SecurityGroupRef.import(this, 'SecurityGroup', {
+                    securityGroupId: props.securityGroupId
+                })
+            });
+        }
     }
 
     /**

packages/@aws-cdk/aws-lambda/lib/lambda.ts

@@ -1,3 +1,4 @@
+import ec2 = require('@aws-cdk/aws-ec2');
 import iam = require('@aws-cdk/aws-iam');
 import cdk = require('@aws-cdk/cdk');
 import { Code } from './code';
@@ -89,6 +90,31 @@ export interface FunctionProps {
      * Both supplied and generated roles can always be changed by calling `addToRolePolicy`.
      */
     role?: iam.Role;
+
+    /**
+     * VPC network to place Lambda network interfaces
+     *
+     * Specify this if the Lambda function needs to access resources in a VPC.
+     */
+    vpc?: ec2.VpcNetworkRef;
+
+    /**
+     * Where to place the network interfaces within the VPC.
+     *
+     * Only used if 'vpc' is supplied.
+     *
+     * @default Private subnets
+     */
+    vpcPlacement?: ec2.VpcPlacementStrategy;
+
+    /**
+     * What security group to associate with the Lambda's network interfaces.
+     *
+     * Only used if 'vpc' is supplied.
+     *
+     * @default A unique security group is created for this Lambda function.
+     */
+    securityGroup?: ec2.SecurityGroupRef;
 }
 
 /**
@@ -140,16 +166,31 @@ export class Function extends FunctionRef {
 
         this.environment = props.environment || { };
 
-        this.role = props.role || new iam.Role(this, 'ServiceRole', {
-            assumedBy: new cdk.ServicePrincipal('lambda.amazonaws.com'),
-            // the arn is in the form of - arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole
-            managedPolicyArns: [  cdk.Arn.fromComponents({
+        const managedPolicyArns = new Array<cdk.Arn>();
+
+        // the arn is in the form of - arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole
+        managedPolicyArns.push(cdk.Arn.fromComponents({
+            service: "iam",
+            region: "", // no region for managed policy
+            account: "aws", // the account for a managed policy is 'aws'
+            resource: "policy",
+            resourceName: "service-role/AWSLambdaBasicExecutionRole"
+        }));
+
+        if (props.vpc) {
+            // Policy that will have ENI creation permissions
+            managedPolicyArns.push(cdk.Arn.fromComponents({
                 service: "iam",
                 region: "", // no region for managed policy
                 account: "aws", // the account for a managed policy is 'aws'
                 resource: "policy",
-                resourceName: "service-role/AWSLambdaBasicExecutionRole",
-            })],
+                resourceName: "service-role/AWSLambdaVPCAccessExecutionRole"
+            }));
+        }
+
+        this.role = props.role || new iam.Role(this, 'ServiceRole', {
+            assumedBy: new cdk.ServicePrincipal('lambda.amazonaws.com'),
+            managedPolicyArns,
         });
 
         for (const statement of (props.initialPolicy || [])) {
@@ -166,6 +207,7 @@ export class Function extends FunctionRef {
             role: this.role.roleArn,
             environment: new cdk.Token(() => this.renderEnvironment()),
             memorySize: props.memorySize,
+            vpcConfig: this.addToVpc(props),
         });
 
         resource.addDependency(this.role);
@@ -226,4 +268,29 @@ export class Function extends FunctionRef {
             variables: this.environment
         };
     }
+
+    /**
+     * If configured, set up the VPC-related properties
+     *
+     * Returns the VpcConfig that should be added to the
+     * Lambda creation properties.
+     */
+    private addToVpc(props: FunctionProps): cloudformation.FunctionResource.VpcConfigProperty | undefined {
+        if (!props.vpc) { return undefined; }
+
+        let securityGroup = props.securityGroup;
+        if (!securityGroup) {
+            securityGroup = new ec2.SecurityGroup(this, 'SecurityGroup', {
+                vpc: props.vpc,
+                description: 'Automatic security group for Lambda Function ' + this.uniqueId,
+            });
+        }
+
+        this._connections = new ec2.Connections({ securityGroup });
+
+        return {
+            subnetIds: props.vpc.subnets(props.vpcPlacement).map(s => s.subnetId),
+            securityGroupIds: [securityGroup.securityGroupId]
+        };
+    }
 }

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

@@ -59,6 +59,7 @@
     "@aws-cdk/assets": "^0.8.2",
     "@aws-cdk/aws-cloudwatch": "^0.8.2",
     "@aws-cdk/aws-codepipeline-api": "^0.8.2",
+    "@aws-cdk/aws-ec2": "^0.8.2",
     "@aws-cdk/aws-events": "^0.8.2",
     "@aws-cdk/aws-iam": "^0.8.2",
     "@aws-cdk/aws-logs": "^0.8.2",