diff --git a/packages/@aws-cdk/aws-lambda/README.md b/packages/@aws-cdk/aws-lambda/README.md index 536d2a9e71d9d..92ed4dc61392b 100644 --- a/packages/@aws-cdk/aws-lambda/README.md +++ b/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 diff --git a/packages/@aws-cdk/aws-lambda/lib/function.ts b/packages/@aws-cdk/aws-lambda/lib/function.ts index f66a67f07e336..ea2d2bf1f18ef 100644 --- a/packages/@aws-cdk/aws-lambda/lib/function.ts +++ b/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`. */