Each time a Lambda function is published, it gets assigned a sequential deployment number. You can invoke a particular version, and configure event sources to publish events to a particular Lambda deployment number, so Lambda makes it easy to roll deployments forwards and backwards and use multiple versions at the same time. In addition to sequential numeric versions, Lambda also supports aliases, named pointers to a particular numeric version. This makes it easy to use a single Lambda function for development, production and testing environments. For example, deploy a new Lambda version and mark it as
development, then test it thoroughly, and then move the
production alias to the same numeric version. You can configure event sources to invoke a particular alias, so after you declare the current version
production, all production sources will immediately start invoking it without any additional configuration.
Detecting the current environment from code
Beware that aliases are just pointers to a numeric version. So, for example, you can publish version 10, assign the
testing alias to it, test it, then reassign
production alias to that version, and both
production then point to the same configuration. Lambda may choose to reuse the same container for subsequent calls. This means that a container that was previously used for testing might now get production requests. If you cache local configuration, such as database connections, make sure to avoid reusing the values from different contexts. You can easily detect the alias or version used to invoke the function from the Lambda context object from the last address segment:
Check out the Detecting Lambda Context example project for a full example.
Configuration for different environments
The easiest way to manage code in multiple environments is to make the code environment-independent, and manage environment-specific tasks with configuration (eg connection strings for databases etc). There are several good ways for achieving that:
- Make the function environment-agnostic, and use the source event to control execution. For example, when a Lambda is triggered from a S3 file upload, save the result back to the same S3 bucket.
- Keep the configuration in API Gateway Stage Variables, if you use API Gateway
- Keep the configuration in Lambda environment variables
- Keep the configuration in a text file uploaded with the Lambda function, then select the right file based on the call context, for example:
Here are some key considerations to help you choose the right way for configuring your environment:
- Lambda Environment variables are tied to a particular numeric version of the deployment. If you have two aliases, eg
testingpointing to the same numerical version, they will share the same configuration. API Gateway stage variables are not tied to a numeric version of the deployment, so two API gateway configurations (eg
testing) can point to the same Lambda numerical version, and can pass different variable values.
- Lambda Environment variables are reused from previous versions unless you update them. For example, updating the variables while deploying a
testingalias, then deploying a new version to
productionwithout updating variables, will carry over the testing variable values to
production. API Gateway stage variables are isolated for different stages. Updating a value on the
testingstage, then redeploying
productionwithout changing the variables will not carry over the testing variable value to production.
- Lambda Environment variables are always updated as a group, so you need to re-specify all variable values on each update. Changing only the
DB_NAMEvariable will delete all other variables, unless you specify them again. API Gateway stage variables can be updated individually, so changing only the
DB_NAMEvariable will not delete any other values.
- Lambda Environment Variables can be used when Lambda is triggered from any source, API Gateway stage variables work only for events sent from the API Gateway. If you have a single Lambda function that handles both API Gateway requests and background processing, it might be easier to keep values in Environment Variables.
- Lambda Environment Variables are stored encrypted, API Gateway stage variables are not. This makes Environment variables more secure.
- Stage variables are more restricted in terms of the content that they can store (most importantly, spaces and many special characters are not allowed in stage variables). You can BASE64 encoded values to store more complex structures in stage variables (remember to replace + with -, for example, because API Gateway currently does not allow + in stage variable names, but BASE64 can produce that character as well). It’s easier to store larger and more complex content in Environment variables.
Setting version aliases
You can set version aliases easily using AWS command line tools or Claudia. With AWS CLI tools, use
aws lambda create-alias and
aws lambda update-alias. If you changed any configuration or uploaded a new package, you may need to use
aws lambda publish-version to publish a new numeric version before setting the alias.
Claudia helps to automate this, and keep the API gateway stages in sync with Lambda aliased. You can create a named alias by supplying
claudia create or
claudia update and Claudia will automatically publish the version and associate a named alias with the current deployment number. For example, the following command will create a
The next command will update the deployment and assign the
testing alias to the new version:
You can also re-assign a named alias to the last deployed version quickly. This is useful, for example, after you have finished testing and want to promote the current deployment to production without a full redeployment. Use:
Claudia will automatically create a new alias for the currently deployed version, or re-assign an existing alias to it. The big difference between
update is that
update causes a new deployment from your local file system, and
set-version uses the last deployed version.
If your project includes an API Gateway definition, this will also create a new deployment of the web API, and create or re-assign an API Gateway stage, linking it directly to the Lambda alias. Each API Gateway stage has a unique URL prefix, so this makes it easy to invoke the right version of the API from client code. Claudia will print out the current version URL after each deployment, so you can easily copy it.
Using Lambda environment variables
You can set Lambda environment variables using AWS CLI tools with
aws lambda create-function and
aws lambda update-function-configuration. Remember to publish a new version after updating the configuration.
You can then access these variables from the standard Node.js
If you’re using a single function for different purposes (eg development, testing and production), remember that the same container might be reused for different aliases, and that the configuration of environment variables is tied to a numerical version, not an alias. To avoid nasty surprises, it’s best to select environment variables based on the currently executing alias (eg set both
TESTING_DB in the environment variables, then select the right one based on the executing context).
Claudia (since version 2.2.0) helps with setting the environment variables as well, and you can provide variables in two ways:
- For a list of key-value pairs from the command line, use
--set-env. For example,
claudia update --set-env DBNAME=proddb,QUEUE=sqs
- To version-control configuration, and simplify command lines, you can also store the values in a JSON file, and use
- To use a custom KMS encryption key, use
--env-kms-key-arnand provide the ARN of your KMS key.
These options are available for
claudia update and
claudia set-version. If you provide a new configuration to
set-version, it will publish a new version after updating the configuration, not just reassign the alias to the last known version.
Check out the Environment Variables example project for a full example.
How to set stage variables for API Gateway
You can easily set API Gateway stage variables by using
aws apigateway create-deployment and provide a list of variables.
If you use
claudia-api-builder and API Gateway to invoke your function, you can then access those variables from the
request.env key in the request processor.
Claudia can also help you automate the configuration process during deployment. Claudia will then enable users to configure the variable value either from the command line, or by prompting interactively during deployment. The syntax is:
string– the name of the stage variable you want to configure. To stay safe, use alphanumeric characters only, API Gateway does not allow special characters in variable names
string– the text to display when prompting the users to interactively enter the variable
string– the name of the command-line option that will be used as a flag for the configuration process.
Here’s an example:
In this case,
message is the name of the stage variable (it will be available as
Enter a message: is the prompt that the users will see during deployment, and
custom-message is the configuration option required to trigger the step. Running this command line will make Claudia ask you to enter the value:
Likewise, you can provide the value directly in the command line for unattended operation:
To see this in action, see the Post-deploy configuration example project.
You can add several post-deployment steps to the same API, but note that the sequence of post-deployment steps is not guaranteed. Create isolated steps, don’t assume any particular order between them.