Serverless IAM Roles Per Function Plugin

[![serverless][sls-image]][sls-url]
[![npm package][npm-image]][npm-url]
[![Build Status][travis-image]][travis-url]
[![Coverage Status][coveralls-image]][coveralls-url]
[![Dependencies Status][david-image]][david-url]
[![Downloads][downloads-image]][npm-url]

A Serverless plugin to easily define IAM roles per function via the use of iamRoleStatements at the function definition block.

Installation

``
npm install --save-dev serverless-iam-roles-per-function
`

Or if you want to try out the next upcoming version:
`
npm install --save-dev serverless-iam-roles-per-function@next
`

Add the plugin to serverless.yml:

`yaml
plugins:
- serverless-iam-roles-per-function
`

Note: Node 6.10 or higher runtime required.

Usage

Define iamRoleStatements definitions at the function level:

`yaml
functions:
func1:
handler: handler.get
iamRoleStatementsName: my-custom-role-name #optional custom role name setting instead of the default generated one
iamRoleStatements:
- Effect: "Allow"
Action:
- dynamodb:GetItem
Resource: "arn:aws:dynamodb:${self:provider.region}:*:table/mytable"
...
func2:
handler: handler.put
iamRoleStatements:
- Effect: "Allow"
Action:
- dynamodb:PutItem
Resource: "arn:aws:dynamodb:${self:provider.region}:*:table/mytable"
...
`

The plugin will create a dedicated role for each function that has an iamRoleStatements definition. It will include the permissions for create and write to CloudWatch logs, stream events and if VPC is defined: AWSLambdaVPCAccessExecutionRole will be included (as is done when using iamRoleStatements at the provider level).

if iamRoleStatements are not defined at the function level default behavior is maintained and the function will receive the global iam role. It is possible to define an empty iamRoleStatements for a function and then the function will receive a dedicated role with only the permissions needed for CloudWatch and (if needed) stream events and VPC. Example of defining a function with empty iamRoleStatements and configured VPC. The function will receive a custom role with CloudWatch logs permissions and the policy AWSLambdaVPCAccessExecutionRole:

`yaml
functions:
func1:
handler: handler.get
iamRoleStatements: []
vpc:
securityGroupIds:
- sg-xxxxxx
subnetIds:
- subnet-xxxx
- subnet-xxxxx
`

By default, function level iamRoleStatements override the provider level definition. It is also possible to inherit the provider level definition by specifying the option iamRoleStatementsInherit: true:

serverless >= v2.24.0
`yaml
provider:
name: aws
iam:
role:
statements:
- Effect: "Allow"
Action:
- xray:PutTelemetryRecords
- xray:PutTraceSegments
Resource: "*"
...
functions:
func1:
handler: handler.get
iamRoleStatementsInherit: true
iamRoleStatements:
- Effect: "Allow"
Action:
- dynamodb:GetItem
Resource: "arn:aws:dynamodb:${self:provider.region}:*:table/mytable"
`

serverless < v2.24.0
`yaml
provider:
name: aws
iamRoleStatements:
- Effect: "Allow"
Action:
- xray:PutTelemetryRecords
- xray:PutTraceSegments
Resource: "*"
...
functions:
func1:
handler: handler.get
iamRoleStatementsInherit: true
iamRoleStatements:
- Effect: "Allow"
Action:
- dynamodb:GetItem
Resource: "arn:aws:dynamodb:${self:provider.region}:*:table/mytable"
`

The generated role for func1 will contain both the statements defined at the provider level and the ones defined at the function level.

If you wish to change the default behavior to inherit instead of override it is possible to specify the following custom configuration:

`yaml
custom:
serverless-iam-roles-per-function:
defaultInherit: true
`


Role Names


The plugin uses a naming convention for function roles which is similar to the naming convention used by the Serverless Framework. Function roles are named with the following convention:
`
----lambdaRole
`
AWS has a 64 character limit on role names. If the default naming exceeds 64 chars the plugin will remove the suffix: -lambdaRole to shorten the name. If it still exceeds 64 chars an error will be thrown containing a message of the form:
`
auto generated role name for function: ${functionName} is too long (over 64 chars).
Try setting a custom role name using the property: iamRoleStatementsName.
`
In this case you should set the role name using the property iamRoleStatementsName. For example:
`yaml
functions:
func1:
handler: handler.get
iamRoleStatementsName: my-custom-role-name
iamRoleStatements:
- Effect: "Allow"
Action:
- dynamodb:GetItem
Resource: "arn:aws:dynamodb:${self:provider.region}:*:table/mytable"
...
`

PermissionsBoundary

Define iamPermissionsBoundary definitions at the function level:

`yaml
functions:
func1:
handler: handler.get
iamPermissionsBoundary: !Sub arn:aws:iam::xxxxx:policy/your_permissions_boundary_policy
iamRoleStatementsName: my-custom-role-name
iamRoleStatements:
- Effect: "Allow"
Action:
- sqs:*
Resource: "*"
...
`

You can set permissionsBoundary for all roles with iamGlobalPermissionsBoundary in custom:

`yaml
custom:
serverless-iam-roles-per-function:
iamGlobalPermissionsBoundary: !Sub arn:aws:iam::xxxx:policy/permissions-boundary-policy
`

For more information, see Permissions Boundaries.




Contributing

Contributions are welcome and appreciated.

* Before opening a PR it is best to first open an issue. Describe in the issue what you want you plan to implement/fix. Based on the feedback in the issue, you should be able to plan how to implement your PR.
* Once ready, open a PR to contribute your code.
* To help updating the CHANGELOG.md file, we use standard-version. Make sure to use conventional commit messages as specified at: https://www.conventionalcommits.org/en/v1.0.0/.
* Update the release notes at CHANGELOG.md and bump the version by running:
`
npm run release
`
* Examine the CHANGELOG.md and update if still required.
* Don't forget to commit the files modified by npm run release (we have the auto-commit option disabled by default).
* Once the PR is approved and merged into master, travis-ci will automatically tag the version you created and deploy to npmjs under the next tag. You will see your version deployed at: https://www.npmjs.com/package/serverless-iam-roles-per-function?activeTab=versions.
* Test your deployed version by installing with the next tag. For example:
`
npm install --save-dev serverless-iam-roles-per-function@next
`

Publishing a Production Release (Maintainers)


Once a contributed PR (or multiple PRs) have been merged into master, there is need to publish a production release, after we are sure that the release is stable. Maintainers with commit access to the repository can publish a release by merging into the release branch. Steps to follow:
* Verify that the current deployed pre-release version under the next tag in npmjs is working properly. Usually, it is best to allow the next version to gain traction a week or two before releasing. Also, if the version solves a specific reported issue, ask the community on the issue to test out the next version.
* Make sure the version being used in master hasn't been released. This can happen if a PR was merged without bumping the version by running npm run release. If the version needs to be advanced, open a PR to advance the version as specified here.
* Open a PR to merge into the release branch. Use as a base the release branch and compare the tag version to release. For example:
!Example PR

* Once approved by another maintainer, merge the PR.
* Make sure to check after the Travis CI build completes that the release has been published to the latest tag on nmpjs.

More Info

Introduction post:
Serverless Framework: Defining Per-Function IAM Roles


Note: Serverless Framework provides support for defining custom IAM roles on a per function level through the use of the role property and creating CloudFormation resources, as documented here. This plugin doesn't support defining both the role property and iamRoleStatements` at the function level.

[npm-image]:https://img.shields.io/npm/v/serverless-iam-roles-per-function.svg
[npm-url]:http://npmjs.org/package/serverless-iam-roles-per-function
[sls-image]:http://public.serverless.com/badges/v3.svg
[sls-url]:http://www.serverless.com
[travis-image]:https://travis-ci.com/functionalone/serverless-iam-roles-per-function.svg?branch=master
[travis-url]:https://travis-ci.com/functionalone/serverless-iam-roles-per-function
[david-image]:https://david-dm.org/functionalone/serverless-iam-roles-per-function/status.svg
[david-url]:https://david-dm.org/functionalone/serverless-iam-roles-per-function
[coveralls-image]:https://coveralls.io/repos/github/functionalone/serverless-iam-roles-per-function/badge.svg?branch=master
[coveralls-url]:https://coveralls.io/github/functionalone/serverless-iam-roles-per-function?branch=master
[downloads-image]:https://img.shields.io/npm/dm/serverless-iam-roles-per-function.svg