Stages Deployments Demo

In this lesson, you'll learn how to use API Gateway stages and stage variables to manage different Lambda function versions. We will begin by creating a Lambda function that serves as an API for an e-commerce application, and then integrate it with API Gateway.

Creating the Lambda Function

First, navigate to the AWS Lambda console.

Next, create a new Lambda function. For this example, the function will return a list of products for an e-commerce website. Name the function something like "get products."

Use the following code as the initial version (version one) of the function:

export const handler = async (event, context) => {
    const response = {
        body: "Here is a list of all products",
    };
    return response;
};

Add a comment indicating that this is version one of your function, then deploy and test the changes. A sample test output might be:

{
  "body": "Here is a list of all products }"
}

If you test again, you could see something like:

Response
{
  "body": "Here is a list of all products \"%"
}

Function Logs
START RequestId: f64eab30-2c13-457a-b269-eeb69cc12b32 Version: $LATEST
END RequestId: f64eab30-2c13-457a-b269-eeb69cc12b32
REPORT RequestId: f64eab30-2c13-457a-b269-eeb69cc12b32 Duration: 143.16 ms Billed Duration: 144 ms Memory Size: 128 MB Max Memory Used: 65 MB

Once the function displays version one correctly, publish it as version one.

You will now simulate code changes over time by publishing two additional function versions.

Publishing Version Two

Edit your Lambda function code to implement version two:

export const handler = async (event, context) => {
    const response = {
        body: "Here is a list of all products v2",
    };
    return response;
};

Deploy this change and publish it as version two.

Publishing Version Three

Next, update the code to represent version three:

export const handler = async (event, context) => {
    const response = {
        body: "Here is a list of all products v3",
    };
    return response;
};

Deploy and publish this update as version three.

Creating Aliases for Lambda Versions

To enable API Gateway to reference specific versions of your Lambda function, complete the following steps:

1. Navigate to the "Aliases" section.
2. Create an alias named prod and point it to version one. This alias represents your production environment.
3. Create an alias named staging that points to version two.
4. Finally, create an alias named dev for the development environment, ideally pointing to the latest version (version three).

At this point, you should have three aliases:

• prod (version one)
• staging (version two)
• dev (version three)

Setting Up API Gateway

Now that your Lambda function has multiple versions and aliases, configure API Gateway as follows:

1. Open the AWS Management Console, search for API Gateway, and access it in a new tab.
2. Create a new REST API – for example, name it "eCommerce."

3. Create a resource named products.

4. Under the products resource, add a GET method and select Lambda function as the integration type.
5. Select the "getProducts" Lambda function. By default, API Gateway will use the latest version of the function.

If you need to invoke a specific version via an alias—for example, using the prod alias—you can modify the function ARN manually. The prod alias ARN contains the suffix ":prod", ensuring API Gateway calls the intended version.

To keep the integration flexible, instead of hardcoding a specific version, use stage variables. In the function integration configuration, append the following ARN:

:lambda:us-east-1:841860929733:function:getProducts

Then, append the stage variable reference:

:${stageVariables.ENV}

This instructs API Gateway to use the stage variable named ENV to determine which alias (prod, staging, or dev) to invoke.

Updating Lambda Permissions for API Gateway

To grant API Gateway permission to invoke your Lambda function, execute the following AWS CLI command. Replace the stage variable reference with the actual alias as needed (e.g., dev):

aws lambda add-permission \
  --function-name "arn:aws:lambda:us-east-1:184186097273:function:getProducts:dev" \
  --source-arn "arn:execute-api:us-east-1:184186097273:6gkxxg7et3:get/products" \
  --principal apigateway.amazonaws.com \
  --statement-id a227f988-a34e-4325-b5c9-8c6b686f982 \
  --action lambda:InvokeFunction

Repeat this process for the staging and prod aliases by updating the alias in the command accordingly. For example, for the prod alias:

aws lambda add-permission \
  --function-name "arn:aws:lambda:us-east-1:841860927373:function:getProducts:prod" \
  --source-arn "arn:aws:execute-api:us-east-1:841860927373:67gx8xm3f/*/GET/products" \
  --principal apigateway.amazonaws.com \
  --statement-id a22f988a-34fe-4352-ab59-3cc6b686f982 \
  --action lambda:InvokeFunction

You can run these commands on your local machine (with the AWS CLI installed) or directly within AWS CloudShell.

After updating the permissions, verify in the Lambda console that each alias has the appropriate API Gateway invocation permissions.

Completing the API Gateway Setup

With Lambda permissions in place, return to API Gateway to complete the GET method configuration. Test the method by setting the stage variable ENV. For example, setting ENV to prod should return:

{
  "body": "Here is a list of all products v1"
}

Switching the stage variable to dev or staging should return version three and version two, respectively.

Deploying the API

Deploy your API by creating stages for each environment:

1. Create a new stage for the dev environment:
   • In the stage editor, set a stage variable with the key ENV and the value dev.
2. Create another stage called staging, and set the stage variable ENV to staging.
3. Finally, create a production stage and set its stage variable ENV to prod.

After deploying, test each environment by modifying the URL path (e.g., /prod, /staging, or /dev). For instance, the prod stage URL should return the version one response.

When you test, you should see the following responses:

• prod returns "Here is a list of all products v1"
• staging returns "Here is a list of all products v2"
• dev returns "Here is a list of all products v3"

A sample response might be:

{
  "body": "Here is a list of all products v2"
}

This concludes our lesson on configuring stages and stage variables in API Gateway to manage multiple versions of your Lambda functions. Enjoy the streamlined deployment process for your e-commerce API!