Lambda: custom execution role

Add a `role` parameter so a role can be specified externally.  This is as
opposed to having the Function generate a role automatically.

This fixes #205.

CHANGELOG.md

@@ -2,6 +2,8 @@
 
 * _BREAKING_: naming change in Lambda library. Classes that used to be named "Lambda"
   are now named "Function" to match service terminology.
+* Lambda (feature): add `role` parameter, making it possible to specify an
+  externally defined execution role.
 
 ## 0.7.3 - 2018-07-09
 

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

@@ -77,6 +77,21 @@ export interface FunctionProps {
      * You can call `addToRolePolicy` to the created lambda to add statements post creation.
      */
     initialPolicy?: PolicyStatement[];
+
+    /**
+     * Lambda execution role.
+     *
+     * This is the role that will be assumed by the function upon execution.
+     * It controls the permissions that the function will have. The Role must
+     * be assumable by the 'lambda.amazonaws.com' service principal.
+     *
+     * Optional. If not supplied, a unique role will be generated for this
+     * lambda function. Both supplied and generated roles can always be changed
+     * by calling `addToRolePolicy`.
+     *
+     * @default generate unique role
+     */
+    role?: Role;
 }
 
 /**
@@ -118,7 +133,7 @@ export class Function extends FunctionRef {
 
         this.environment = props.environment || { };
 
-        this.role = new Role(this, 'ServiceRole', {
+        this.role = props.role || new Role(this, 'ServiceRole', {
             assumedBy: new ServicePrincipal('lambda.amazonaws.com'),
             // the arn is in the form of - arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole
             managedPolicyArns: [  Arn.fromComponents({

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

@@ -1,6 +1,7 @@
 import { expect, haveResource } from '@aws-cdk/assert';
 import { AccountPrincipal, Arn, ArnPrincipal, AwsAccountId, Construct, PolicyStatement, ServicePrincipal, Stack } from '@aws-cdk/core';
 import { EventRule } from '@aws-cdk/events';
+import { Role } from '@aws-cdk/iam';
 import { Test } from 'nodeunit';
 import { Function, FunctionInlineCode, FunctionRuntime } from '../lib';
 
@@ -192,6 +193,41 @@ export = {
 
             test.done();
         },
+
+        'BYORole'(test: Test) {
+            // GIVEN
+            const stack = new Stack();
+            const role = new Role(stack, 'SomeRole', {
+                assumedBy: new ServicePrincipal('lambda.amazonaws.com'),
+            });
+            role.addToPolicy(new PolicyStatement().addAction('confirm:itsthesame'));
+
+            // WHEN
+            const fn = new Function(stack, 'Function', {
+                code: new FunctionInlineCode('test'),
+                runtime: FunctionRuntime.Python36,
+                handler: 'index.test',
+                role,
+                initialPolicy: [
+                    new PolicyStatement().addAction('inline:inline')
+                ]
+            });
+
+            fn.addToRolePolicy(new PolicyStatement().addAction('explicit:explicit'));
+
+            // THEN
+            expect(stack).to(haveResource('AWS::IAM::Policy', {
+                "PolicyDocument": {
+                "Statement": [
+                    { "Action": "confirm:itsthesame", "Effect": "Allow" },
+                    { "Action": "inline:inline", "Effect": "Allow" },
+                    { "Action": "explicit:explicit", "Effect": "Allow" }
+                ],
+                },
+            }));
+
+            test.done();
+        }
     },
 
     'import/export': {