Serverless KMS Grants Plugin
A plugin for the Serverless Framework which creates
AWS KMS grants for an IAM role to give it permission to use a KMS key. The
plugin creates an AWS KMS grant as part of the serverless deploy
function, and
revokes it as part of the serverless remove
function. You can also run it from
the command line.
Table of Contents
Install
-
Add
serverless-kms-grants
plugin to your package.json:npm install --save-dev serverless-kms-grants
-
Add the
serverless-kms-grants
plugin to the serverless.yml file:plugins: - serverless-kms-grants
-
To verify that the plugin was added successfully, run
serverless
in your command line. The plugin should show up under the "Plugins" section asServerlessKmsGrants
.
Usage
Version 1.0.0
As of version 1.0.0 a list of grants can be configured. For each grant you'd
like to make, configure the AWS KMS key id and role arn or role name for the
plugin in serverless.yml. Using the ARN of a resource is the safest as it is
guaranteed to be unique in AWS. If only a kmsKeyId is given and neither the
roleName or roleArn are specified, the plugin will try to find and use the
default lambda role generated by Serverless. The default serverless lambda role
name follows the convention: <service>-<stage>-<region>-lambdaRole
.
- kmsKeyId: the
KeyId
,Alias
, orArn
used to identify the KMS key (Required) - roleName: the name of the AWS IAM role you wish to grant access to KMS key. (Optional).
- roleArn: the Arn of the AWS IAM role you wish to grant access to the KMS key (Optional).
Example:
custom:
kmsGrants:
# Grant the default serverless lambda role access to a KMS key
- kmsKeyId: <KMS Key Identifier>
# Grant a role with a unique name access to a KMS Key
- kmsKeyId: <KMS Key Identifier>
roleName: <IAM Role Name>
# Grant a role with a specific ARN access to a KMS Key
- kmsKeyId: <KMS Key Identifier>
roleArn: <IAM Role Arn>
Prior to 1.0.0
Configure the AWS KMS key id and lambdaArn for the plugin in serverless.yml:
- kmsKeyId: the
KeyId
,Alias
, orArn
used to identify the KMS key (Required) - lambdaRoleName: the name of the lambda role you wish to grant access to KMS key. (Optional). If name is not specified the plugin will try with default role name.
- lambdaRoleArn: the Arn of the lambda you wish to grant access to the KMS key
(Optional). If an arn is not specified, the plugin will look for the default
lambdaRole and obtain its arn. The default serverless lambda role follows the
convention:
<service>-<stage>-<region>-lambdaRole
.
custom:
kmsGrants:
kmsKeyId: <KMS Key Identifier>
lambdaRoleArn: <Lambda Arn>
For example:
custom:
kmsGrants:
kmsKeyId: "alias/myKey"
lambdaRoleArn: "arn:aws:iam::000123456789:role/myservice-mystage-us-east-1-lambdaRole"
Run Locally
The plugin can be used locally via the command line to create or revoke an AWS KMS Grant (using the specification in serverless.yml above)
serverless createKmsGrant
serverless revokeKmsGrant
You can specify the stage by adding --stage <stage>
to the end as follows:
serverless createKmsGrant --stage myStage
serverless revokeKmsGrant --stage myStage
Support
This is an Open Source community project. Project contributors may be able to help, depending on their time and availability. Please be specific about what you're trying to do, your system, and steps to reproduce the problem.
For bug reports or feature requests, please open an issue. You are welcome to contribute.
Official support from Trend Micro is not available. Individual contributors may be Trend Micro employees, but are not official support.
Contribute
We accept contributions from the community. To submit changes:
- Fork this repository.
- Create a new feature branch.
- Make your changes.
- Submit a pull request with an explanation of your changes or additions.
We will review and work with you to release the code.