Creating an application with continuous delivery in the Lambda console - Amazon Lambda
PrerequisitesCreate an applicationInvoke the functionAdd an Amazon resourceUpdate the permissions boundaryUpdate the function codeNext stepsTroubleshootingClean up
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Creating an application with continuous delivery in the Lambda console

You can use the Lambda console to create an application with an integrated continuous delivery pipeline. With continuous delivery, every change that you push to your source control repository triggers a pipeline that builds and deploys your application automatically. The Lambda console provides starter projects for common application types with Node.js sample code and templates that create supporting resources.

In this tutorial, you create the following resources.

  • Application – A Node.js Lambda function, build specification, and Amazon Serverless Application Model (Amazon SAM) template.

  • Pipeline – An Amazon CodePipeline pipeline that connects the other resources to enable continuous delivery.

  • Repository – A Git repository in Amazon CodeCommit. When you push a change, the pipeline copies the source code into an Amazon S3 bucket and passes it to the build project.

  • Trigger – An Amazon EventBridge (CloudWatch Events) rule that watches the main branch of the repository and triggers the pipeline.

  • Build project – An Amazon CodeBuild build that gets the source code from the pipeline and packages the application. The source includes a build specification with commands that install dependencies and prepare the application template for deployment.

  • Deployment configuration – The pipeline's deployment stage defines a set of actions that take the processed Amazon SAM template from the build output, and deploy the new version with Amazon CloudFormation.

  • Bucket – An Amazon Simple Storage Service (Amazon S3) bucket for deployment artifact storage.

  • Roles – The pipeline's source, build, and deploy stages have IAM roles that allow them to manage Amazon resources. The application's function has an execution role that allows it to upload logs and can be extended to access other services.

Your application and pipeline resources are defined in Amazon CloudFormation templates that you can customize and extend. Your application repository includes a template that you can modify to add Amazon DynamoDB tables, an Amazon API Gateway API, and other application resources. The continuous delivery pipeline is defined in a separate template outside of source control and has its own stack.

The pipeline maps a single branch in a repository to a single application stack. You can create additional pipelines to add environments for other branches in the same repository. You can also add stages to your pipeline for testing, staging, and manual approvals. For more information about Amazon CodePipeline, see What is Amazon CodePipeline.

Prerequisites

This tutorial assumes that you have some knowledge of basic Lambda operations and the Lambda console. If you haven't already, follow the instructions in Create a Lambda function with the console to create your first Lambda function.

To complete the following steps, you need the Amazon Command Line Interface (Amazon CLI) version 2. Commands and the expected output are listed in separate blocks:

aws --version

You should see the following output:

aws-cli/2.13.27 Python/3.11.6 Linux/4.14.328-248.540.amzn2.x86_64 exe/x86_64.amzn.2

For long commands, an escape character (\) is used to split a command over multiple lines.

On Linux and macOS, use your preferred shell and package manager.

Note

In Windows, some Bash CLI commands that you commonly use with Lambda (such as zip) are not supported by the operating system's built-in terminals. To get a Windows-integrated version of Ubuntu and Bash, install the Windows Subsystem for Linux. Example CLI commands in this guide use Linux formatting. Commands which include inline JSON documents must be reformatted if you are using the Windows CLI.

This tutorial uses CodeCommit for source control. To set up your local machine to access and update application code, see Setting up in the Amazon CodeCommit User Guide.

Create an application

Create an application in the Lambda console. In Lambda, an application is an Amazon CloudFormation stack with a Lambda function and any number of supporting resources. In this tutorial, you create an application that has a function and its execution role.

To create an application

  1. Open the Lambda console Applications page.

  2. Choose Create application.

  3. Choose Author from scratch.

  4. Configure application settings.

    • Name – my-app.

    • Runtime – Node.js 18.x.

    • Template format – Amazon SAM (YAML).

    • Source control service – CodeCommit.

    • Repository name – my-app-repo.

    • Permissions – Create roles and permissions boundary.

  5. Choose Create.

Lambda creates the pipeline and related resources and commits the sample application code to the Git repository. As resources are created, they appear on the overview page.

Starter application resources during deployment.

The Infrastructure stack contains the repository, build project, and other resources that combine to form a continuous delivery pipeline. When this stack finishes deploying, it in turn deploys the application stack that contains the function and execution role. These are the application resources that appear under Resources.

Invoke the function

When the deployment process completes, invoke the function from the Lambda console.

To invoke the application's function

  1. Open the Lambda console Applications page.

  2. Choose my-app.

  3. Under Resources, choose helloFromLambdaFunction.

  4. Choose Test.

  5. Configure a test event.

    • Event name – event

    • Body – {}

  6. Choose Create.

  7. Choose Test.

The Lambda console runs your function and displays the result. Expand the Details section under the result to see the output and execution details.

Output from a test invocation.

Add an Amazon resource

In the previous step, Lambda console created a Git repository that contains function code, a template, and a build specification. You can add resources to your application by modifying the template and pushing changes to the repository. To get a copy of the application on your local machine, clone the repository.

To clone the project repository

  1. Open the Lambda console Applications page.

  2. Choose my-app.

  3. Choose Code.

  4. Under Repository details, copy the HTTP or SSH repository URI, depending on the authentication mode that you configured during setup.

  5. To clone the repository, use the git clone command.

    git clone ssh://git-codecommit.us-east-2.amazonaws.com/v1/repos/my-app-repo

To add a DynamoDB table to the application, define an AWS::Serverless::SimpleTable resource in the template.

To add a DynamoDB table

  1. Open template.yml in a text editor.

  2. Add a table resource, an environment variable that passes the table name to the function, and a permissions policy that allows the function to manage it.

    Example template.yml - resources
    ...
Resources:
  ddbTable:
    Type: AWS::Serverless::SimpleTable
    Properties:
      PrimaryKey:
        Name: id
        Type: String
      ProvisionedThroughput:
        ReadCapacityUnits: 1
        WriteCapacityUnits: 1
  helloFromLambdaFunction:
    Type: AWS::Serverless::Function
    Properties:
      CodeUri: ./
      Handler: src/handlers/hello-from-lambda.helloFromLambdaHandler
      Runtime: nodejs18.x
      MemorySize: 128
      Timeout: 60
      Description: A Lambda function that returns a static string.
      Environment:
        Variables:
          DDB_TABLE: !Ref ddbTable
      Policies:
        - DynamoDBCrudPolicy:
            TableName: !Ref ddbTable
        - AWSLambdaBasicExecutionRole

  3. Commit and push the change.

    git commit -am "Add DynamoDB table"
git push

When you push a change, it triggers the application's pipeline. Use the Deployments tab of the application screen to track the change as it flows through the pipeline. When the deployment is complete, proceed to the next step.

Monitoring an application deployment in the Lambda console.

Update the permissions boundary

The sample application applies a permissions boundary to its function's execution role. The permissions boundary limits the permissions that you can add to the function's role. Without the boundary, users with write access to the project repository could modify the project template to give the function permission to access resources and services outside of the scope of the sample application.

In order for the function to use the DynamoDB permission that you added to its execution role in the previous step, you must extend the permissions boundary to allow the additional permissions. The Lambda console detects resources that aren't in the permissions boundary and provides an updated policy that you can use to update it.

To update the application's permissions boundary

  1. Open the Lambda console Applications page.

  2. Choose your application.

  3. Under Resources, choose Edit permissions boundary.

  4. Follow the instructions shown to update the boundary to allow access to the new table.

For more information about permissions boundaries, see Using permissions boundaries for Amazon Lambda applications.

Update the function code

Next, update the function code to use the table. The following code uses the DynamoDB table to track the number of invocations processed by each instance of the function. It uses the log stream ID as a unique identifier for the function instance.

To update the function code

  1. Add a new handler named index.js to the src/handlers folder with the following content.

    Example src/handlers/index.js
    const dynamodb = require('aws-sdk/clients/dynamodb');
const docClient = new dynamodb.DocumentClient();

exports.handler = async (event, context) => {
    const message = 'Hello from Lambda!';
    const tableName = process.env.DDB_TABLE;
    const logStreamName = context.logStreamName;
    var params = {
        TableName : tableName,
        Key: { id : logStreamName },
        UpdateExpression: 'set invocations = if_not_exists(invocations, :start) + :inc',
        ExpressionAttributeValues: {
            ':start': 0,
            ':inc': 1
        },
        ReturnValues: 'ALL_NEW'
    };
    await docClient.update(params).promise();

    const response = {
        body: JSON.stringify(message)
    };
    console.log(`body: ${response.body}`);
    return response;
}

  2. Open the application template and change the handler value to src/handlers/index.handler.

    Example template.yml
    ...
  helloFromLambdaFunction:
    Type: AWS::Serverless::Function
    Properties:
      CodeUri: ./
      Handler: src/handlers/index.handler
      Runtime: nodejs8.x

  3. Commit and push the change.

    git add . && git commit -m "Use DynamoDB table"
git push

After the code change is deployed, invoke the function a few times to update the DynamoDB table.

To view the DynamoDB table

  1. Open the Tables page of the DynamoDB console.

  2. Choose the table that starts with my-app.

  3. Choose Items.

  4. Choose Start search.

A DynamoDB table that shows the number of times an instance of a function has processed an event.

Lambda creates additional instances of your function to handle multiple concurrent invocations. Each log stream in the CloudWatch Logs log group corresponds to a function instance. A new function instance is also created when you change your function's code or configuration. For more information on scaling, see Lambda function scaling.

Next steps

The Amazon CloudFormation template that defines your application resources uses the Amazon Serverless Application Model transform to simplify the syntax for resource definitions, and automate uploading the deployment package and other artifacts. Amazon SAM also provides a command line interface (the Amazon SAM CLI), which has the same packaging and deployment functionality as the Amazon CLI, with additional features specific to Lambda applications. Use the Amazon SAM CLI to test your application locally in a Docker container that emulates the Lambda execution environment.

Amazon Cloud9 provides an online development environment that includes Node.js, the Amazon SAM CLI, and Docker. With Amazon Cloud9, you can start developing quickly and access your development environment from any computer. For instructions, see Getting started in the Amazon Cloud9 User Guide.

For local development, Amazon toolkits for integrated development environments (IDEs) let you test and debug functions before pushing them to your repository.

Troubleshooting

As you develop your application, you will likely encounter the following types of errors.

  • Build errors – Issues that occur during the build phase, including compilation, test, and packaging errors.

  • Deployment errors – Issues that occur when Amazon CloudFormation isn't able to update the application stack. These include permissions errors, account quotas, service issues, or template errors.

  • Invocation errors – Errors that are returned by a function's code or runtime.

For build and deployment errors, you can identify the cause of an error in the Lambda console.

To troubleshoot application errors

  1. Open the Lambda console Applications page.

  2. Choose an application.

  3. Choose Deployments.

  4. To view the application's pipeline, choose Deployment pipeline.

  5. Identify the action that encountered an error.

  6. To view the error in context, choose Details.

For deployment errors that occur during the ExecuteChangeSet action, the pipeline links to a list of stack events in the Amazon CloudFormation console. Search for an event with the status UPDATE_FAILED. Because Amazon CloudFormation rolls back after an error, the relevant event is under several other events in the list. If Amazon CloudFormation could not create a change set, the error appears under Change sets instead of under Events.

A common cause of deployment and invocation errors is a lack of permissions in one or more roles. The pipeline has a role for deployments (CloudFormationRole) that's equivalent to the user permissions that you would use to update an Amazon CloudFormation stack directly. If you add resources to your application or enable Lambda features that require user permissions, the deployment role is used. You can find a link to the deployment role under Infrastructure in the application overview.

If your function accesses other Amazon services or resources, or if you enable features that require the function to have additional permissions, the function's execution role is used. All execution roles that are created in your application template are also subject to the application's permissions boundary. This boundary requires you to explicitly grant access to additional services and resources in IAM after adding permissions to the execution role in the template.

For example, to connect a function to a virtual private cloud (VPC), you need user permissions to describe VPC resources. The execution role needs permission to manage network interfaces. This requires the following steps.

  1. Add the required user permissions to the deployment role in IAM.

  2. Add the execution role permissions to the permissions boundary in IAM.

  3. Add the execution role permissions to the execution role in the application template.

  4. Commit and push to deploy the updated execution role.

After you address permissions errors, choose Release change in the pipeline overview to rerun the build and deployment.

Clean up

You can continue to modify and use the sample to develop your own application. If you are done using the sample, delete the application to avoid paying for the pipeline, repository, and storage.

To delete the application

  1. Open the Amazon CloudFormation console.

  2. Delete the application stack – my-app.

  3. Open the Amazon S3 console.

  4. Delete the artifact bucket – us-east-2-123456789012-my-app-pipe.

  5. Return to the Amazon CloudFormation console and delete the infrastructure stack – serverlessrepo-my-app-toolchain.

Function logs are not associated with the application or infrastructure stack in Amazon CloudFormation. Delete the log group separately in the CloudWatch Logs console.

To delete the log group

  1. Open the Log groups page of the Amazon CloudWatch console.

  2. Choose the function's log group (/aws/lambda/my-app-helloFromLambdaFunction-YV1VXMPLK7QK).

  3. Choose Actions, and then choose Delete log group.

  4. Choose Yes, Delete.