Manage stages in AWS API-Gateway

Best practice is to create separate stages (production / development / test etc) to manage different versions of your code. Not only the API-Gateway definitions (API paths and API-GW settings) can have different stages, also your lambda code can have different code stages using aliases. This will allow you to manage which version of the code of a single lambda function will be called in each environment (prod, dev etc), and also switch back to a previously published version with just a few clicks. There's no need to create separate lambda functions for each stage.

Lambda configuration

Open your lambda function in the AWS web console and publish a new version of the current code by using the menu "Actions > Publish new version".

Screenshot Lambda function AWS web
Screenshot Lambda function AWS web

In the dialog you can enter a short description for the new version:

Screenshot enter a short description
Screenshot enter a short description

You have now published a new version of your current code and a version number has been assigned. If this was your first publish, the version will be 1, each publish action will automatically increment the version number. 


Now configure stage names using the menu "Actions > Create alias":

Screenshot configure stage
Screenshot configure stage

Create an alias for dev (development stage) and select $LATEST as the version. $LATEST will always link the stage to the most recent version of the code in the code editor. 

Create a new alias
Create a new alias

After creating a new alias, make sure to return to the main function in the breadcrumbs navigation (Lambda > Functions > YourFunctionName), before you continue to create another alias. Repeat the steps above and create a second alias for prod (production), but this time select version 1 from the version dropdown field, so the alias already points to the version you just published.

When done creating all required aliases, you should see the list aliases in the "Qualifiers" dropdown menu. Dev should point to $LATEST and prod points to the published version 1. In my case prod is already on version 5:

Screenshot of the list aliases Qualifiers
Screenshot of the list aliases Qualifiers

Once published, it's not possible to modify the code of an already published version any longer, but you can always change to which version number the alias should point, by selecting the alias entry from the Qualifiers menu:

Screenshot about changing the version number
Screenshot about changing the version number

When you publish a new version, adjust the Version selection in the alias accordingly, or switch back to a previous version if required. 
Finally save your lambda function and proceed to the API-Gateway configuration.

Configure API-Gateway to call the lambda function based on stage name

Now that we have defined aliases for each stage in the lambda function, we must configure the API-Gateway to use the stage variables. 

Open you API in the API-Gateway Web-Console, navigate to "Stages" and select one of the stages of the API. In the tab "Stage Variables" create a new variable called "lambdaAlias" and assign the same value as used in the lambda alias (prod / dev / test). Also create and set the variable in all other stages of the API. 

 

Screenshot about creating a new variable
Screenshot about creating a new variable

The variable named "lambdaAlias" can now be used in the lambda function name to be invoked by the API-Gateway. Open the resources pages of your API and select one of the defined methods (POST / GET / ANY etc.). In the method open the properties of the "Integration Request", which usually configured as lambda proxy. 

The variable named "lambdaAlias" can now be used in the lambda function name
The variable named "lambdaAlias" can now be used in the lambda function name

Inside the Integration Request properties, you define the lambda function name to be invoked. 

Define the lambda function name to be invoked
Define the lambda function name to be invoked

The lambda function can take an alias as suffix separated by a colon:  functionname:alias

To use a variable (from the variables tab of the API-GW) use the ${stageVariables.lambdaAlias} syntax as shown in the screenshot above. 

IMPORTANT: If you try to save the changes, you will be prompted by a security warning, giving you rather complicated instructions how to grant permissions using the AWS CLI. There's a MUCH simpler way to do that without using the CLI at all! All you have to do is save the function name without the dynamic variable part, for every stage name you have definded. 

e.g. enter "waschanleitungen:dev" then save the name, enter "waschanleitungen:prod" and save again. This will grant permission for each entered alias.

How to save the changes
How to save the changes

..and finally save the function name again, but with the dynamic variable part:

Save again with the dynamic variable
Save again with the dynamic variable

The security warning with instructions will pop up again, but you can just dismiss it. 

Now you can deploy the changes made in the API-Gateway using the "Deploy API" function from the actions menu and your API is ready to be invoked using /dev/ or /prod/ variables in the path, and will invoke the corresponding code in the linked lambda function!

Deploy the changes made in the API-Gateway by using the "Deploy API" function
Deploy the changes made in the API-Gateway by using the "Deploy API" function
Kommentar einfügen: