docs(lambda): document adding execution permissions to provided IAM roles

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

@@ -49,6 +49,39 @@ to our CDK project directory. This is especially important when we want to share
 this construct through a library. Different programming languages will have
 different techniques for bundling resources into libraries.
 
+### Execution Role
+
+Lambda functions assume an IAM role during execution. In CDK by default, Lambda
+functions will use an autogenerated Role if one is not provided.
+
+The autogenerated Role is automatically given permissions to execute the Lambda
+function. To reference the autogenerated Role:
+
+```ts
+const fn = new lambda.Function(this, 'MyFunction', {
+  runtime: lambda.Runtime.NODEJS_10_X,
+  handler: 'index.handler',
+  code: lambda.Code.fromAsset(path.join(__dirname, 'lambda-handler')),
+
+fn.role // the Role
+```
+
+You can also provide your own IAM role. Provided IAM roles will not automatically
+be given permissions to execute the Lambda function. To provide a role and grant
+it appropriate permissions:
+
+```ts
+const fn = new lambda.Function(this, 'MyFunction', {
+  runtime: lambda.Runtime.NODEJS_10_X,
+  handler: 'index.handler',
+  code: lambda.Code.fromAsset(path.join(__dirname, 'lambda-handler')),
+  role: myRole // user-provided role
+});
+
+myRole.addManagedPolicy(ManagedPolicy.fromAwsManagedPolicyName("service-role/AWSLambdaBasicExecutionRole"));
+myRole.addManagedPolicy(ManagedPolicy.fromAwsManagedPolicyName("service-role/AWSLambdaVPCAccessExecutionRole")); // only required if your function lives in a VPC
+```
+
 ### Versions and Aliases
 
 You can use

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

@@ -99,6 +99,12 @@ export interface FunctionOptions extends EventInvokeConfigOptions {
    * It controls the permissions that the function will have. The Role must
    * be assumable by the 'lambda.amazonaws.com' service principal.
    *
+   * The default Role automatically has permissions granted for Lambda execution. If you
+   * provide a Role, you must add the relevant AWS managed policies yourself.
+   *
+   * The relevant managed policies are "service-role/AWSLambdaBasicExecutionRole" and
+   * "service-role/AWSLambdaVPCAccessExecutionRole".
+   *
    * @default - A unique role will be generated for this lambda function.
    * Both supplied and generated roles can always be changed by calling `addToRolePolicy`.
    */