customrole.md

Using Custom AWS IAM Roles and Policies for Execution

The default IAM policy created by Zappa for executing the Lambda is very permissive. It grants access to all actions for all resources for types CloudWatch, S3, Kinesis, SNS, SQS, DynamoDB, and Route53; lambda:InvokeFunction for all Lambda resources; Put to all X-Ray resources; and all Network Interface operations to all EC2 resources. While this allows most Lambdas to work correctly with no extra permissions, it is generally not an acceptable set of permissions for most continuous integration pipelines or production deployments. Instead, you will probably want to explicitly manage your IAM Policies.

There are three options for explicitly managing the IAM Policies:

1. Manually manage the Role in IAM directly
2. Allow Zappa to manage the Role, but with an explicitly defined policy
3. Add additional permissions to the default Zappa policy

To manually manage Role, set manage_roles to false. With this set, you are expected to create and manage the Role outside of Zappa, for example, by creating it manually in the AWS Console or via a CloudFormation template. You may optionally override the default name of the Role that Zappa uses (<project_name>--ZappaExecutionRole) by setting either role_name or role_arn.

{
    "dev": {
        ...
        "manage_roles": false, // Disable Zappa client managing roles.
        ...and optionally, one of...
        "role_name": "MyLambdaRole", // Name of your Zappa execution role. Optional. Default: <project_name>-<env>-ZappaExecutionRole.
        ...or...
        "role_arn": "arn:aws:iam::12345:role/app-ZappaLambdaExecutionRole", // ARN of your Zappa execution role. Optional.
        ...
    }
}

To allow Zappa to manage the Role but specify explicit configuration, either do not specify manage_roles or set its value to true. Then, configure the attach_policy attribute to be the name of a file containing the IAM Policy JSON to be used in place of the default Zappa policy. This is called the attach policy because the Policy is associated with the Lambda with an operation known as 'attach'. Optionally, the role_name used can also be customized.

{
    "dev": {
        ...
        "manage_roles": true, // Enable Zappa client managing roles. Optional. Default: true.
        "attach_policy": "my_attach_policy.json", // custom IAM attach policy JSON file name. Optional.
        "role_name": "MyLambdaRole", // Name of your Zappa execution role. Optional. Default: <project_name>-<env>-ZappaExecutionRole.
        ...
    },
    ...
}

The extra_permissions setting will add permissions to the base Zappa execution policy (either the default policy or the policy defined by the attach_policy setting).

{
    "dev": {
        ...
        "extra_permissions": [{ // Attach any extra permissions to this policy.
            "Effect": "Allow",
            "Action": ["rekognition:*"], // AWS Service ARN
            "Resource": "*"
        }]
    },
    ...
}

Using Custom AWS IAM Roles and Policies for Assume

A custom assume policy can be specified by setting via the assume_policy configuration option to the name of the file containing your assume policy. The default assume policy allows access by apigateway.amazonaws.com, lambda.amazonaws.com and events.amazonaws.com.