This plugin automatically creates a .env file during deployment by merging environment variables from one or more YAML files. During runtime these variables can then be loaded into process.env using dotenv.
For a brief introduction, read our blogpost about introducing serverless-env-generator.
- Support for multi-stage configurations and custom profiles
- Value of environment variables can be encrypted with AWS KMS, allowing teams to manage sensitive information in git.
- By using KMS, access to secrets can be controlled with IAM. We recommend to create one KMS key per serverless-profile, so you can limit access to credentials to deployment privileges.
- During deployment a temporary .env file is created and uploaded to Lambda by merging and decrypting values of your environment YAML files.
- Environment variables can be loaded with dotenv at startup in Lambda without delays from KMS.
- Supports serverless-local-dev-server for local development.
Please note that the uploaded .env file contains secrets in cleartext. Therefore we recommend to use Serverless Crypt for critical secrets. This tool aims to strike a balance between storing secrets in plaintext in Lambda environment variables and having to decrypt them at runtime using KMS.
Furthermore the tool does not support environment variables generated by Serverless. We recommend to set these variables directly in each functions configuration in serverless.yml.
When used with serverless-local-dev-server your environment variables are directly loaded into process.env. No .env file is created to make sure that your local development and deployment tasks do not interfere :-)
This package requires node >= 8.0. Due to the reliance on KMS, encryption is only supported for AWS.
The .env.local
file in the project root is here only for the tests.
npm install dotenv --save
npm install serverless-env-generator --save-dev
See: https://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html
Please make sure to create the KMS key in the same region as your deployment.
For aliases we recommend to use the service name, for administration privileges no user (your AWS account has full permissions by default) and for usage privileges "serverless-admin" to link access permissions to deployment permissions.
serverless.yml configuration example:
provider:
name: aws
runtime: nodejs6.10
functions:
hello:
handler: handler.hello
# Add serverless-env-generator to your plugins:
plugins:
- serverless-env-generator
# Plugin config goes into custom:
custom:
envFiles: #YAML files used to create .env file
- environment.yml
envEncryptionKeyId: #KMS Key used for encrypting values
dev: ${env:AWS_KMS_KEYID} #Key used for development-stage
As the generated .env file contains the secrets in cleartext, make sure that it will never be checked into git!
.gitignore code example:
.env
Command example:
serverless env --attribute name --value "This is not a secret"
serverless env --attribute secret_name --value "This is a secret" --encrypt
Note that the .env file is automatically created when you deploy your function, so you can just load those variables with dotenv ๐
Code example:
require('dotenv').config() // Load variables from .env file
module.exports.hello = (event, context, callback) => {
const response = {
statusCode: 200,
body: JSON.stringify({
message: process.env.secret_name,
input: event
})
}
callback(null, response)
}
Command example:
serverless deploy
serverless invoke -f $FUNCTION_NAME
Result example:
{
"body": "{\"input\": {}, \"message\": \"This is a secret\"}",
"statusCode": 200
}
You can use these commands to modify your YAML environment files.
If no stage is specified the default one as specified in serverless.yml is used.
Use the following commands to read and decrypt variables from your YAML environment files:
serverless env
serverless env --stage $STAGE
serverless env --attribute $NAME
serverless env --attribute $NAME --stage $STAGE
#shorthand:
sls env -a $NAME
sls env -a $NAME -s $STAGE
serverless env --decrypt
serverless env --attribute $NAME --decrypt
serverless env --attribute $NAME --stage $STAGE --decrypt
#shorthand:
sls env -a $NAME --decrypt
sls env -a $NAME -s $STAGE -d
Use the following commands to store and encrypt variables in your YAML environment files:
Note that variables are stored to the first file listed in envFiles.
serverless env --attribute $NAME --value $PLAINTEXT
serverless env --attribute $NAME --value $PLAINTEXT --stage $STAGE
#shorthand:
sls env -a $NAME -v $PLAINTEXT
sls env --a $NAME -v $PLAINTEXT --s $STAGE
serverless env --attribute $NAME --value $PLAINTEXT --encrypt
serverless env --attribute $NAME --value $PLAINTEXT --stage $STAGE --encrypt
#shorthand:
sls env -a $NAME -v $PLAINTEXT -e
sls env -a $NAME -v $PLAINTEXT -s $STAGE -e
Environment variables are stored in stage-agnostic YAML files, which are then merged into a .env file on deployment.
File example:
dev: #stage
foo: bar #cleartext variable
bla: crypted:bc89hwnch8hncoaiwjnd... #encrypted variable
production:
foo: baz
bla: crypted:ncibinv0iwokncoiao3d...
You can create additional YAML environment files, for example to include variables that are dynamically generated. Just add them to the envFiles in your serverless.yml.
In case you are also using the serverless-plugin-webpack
there are some caveats:
You have to place serverless-env-generator
before the serverless-plugin-webpack
in the serverless.yml
# serverless.yml
plugins:
- serverless-env-generator
- serverless-plugin-webpack
You need to have the dotenv-webpack
plugin installed:
npm install dotenv-webpack --save-dev
and configured:
// webpack.config.js
const Dotenv = require('dotenv-webpack')
module.exports = {
// ...
plugins: [
// ...
new Dotenv()
]
}
Licensed under the MIT license.
Created and maintained by DieProduktMacher.
Inspired by Serverless Crypt.