AWS Lambda
Developer Guide

The AWS Documentation website is getting a new look!
Try it now and let us know what you think. Switch to the new look >>

You can return to the original look by selecting English in the language selector above.

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 templates to build common application types with sample code and templates that create supporting resources.

Note

This feature is in beta.

In this tutorial, you create the following resources.

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

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

  • Repository – A Git repository in AWS 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 CloudWatch Events rule that watches the master branch of the repository and triggers the pipeline.

  • Build project – An AWS 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 AWS SAM template from the build output, and deploy the new version with AWS 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 AWS 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 AWS 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 AWS CodePipeline, see What Is AWS 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 Getting Started with AWS Lambda to create your first Lambda function.

To follow the procedures in this guide, you will need a command line terminal or shell to run commands. Commands are shown in listings preceded by a prompt symbol ($) and the name of the current directory, when appropriate:

~/lambda-project$ this is a command this is output

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. On Windows 10, you can install the Windows Subsystem for Linux to get a Windows-integrated version of Ubuntu and Bash.

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

Create an Application

Create an application in the Lambda console.

To create an application

  1. Open the Lambda console.

  2. Choose Applications.

  3. Choose Create application.

  4. Choose Author from scratch.

  5. Configure application settings.

    • Application namemy-app.

    • Application descriptionmy application.

    • RuntimeNode.js 10.x.

    • Repository providerCodeCommit.

    • Repository providermy-app-repo.

    • PermissionsCreate roles and permissions boundary.

  6. Choose Deploy.

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.

Invoke the Function

Invoke the function to verify that it works.

To invoke the application's function

  1. Open the Lambda console.

  2. Choose Applications.

  3. Choose my-app.

  4. Under Resources, choose helloFromLambdaFunction.

  5. Choose Test.

  6. Configure a test event.

    • Event nametest

    • Body{}

  7. Choose Create.

  8. Choose Test.

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

Add an AWS Resource

When you create your application, the Lambda console creates a Git repository that contains the sample application. To get a copy of the application code on your local machine, clone the project repository.

To clone the project repository

  1. Open the Lambda console.

  2. Choose Applications.

  3. Choose my-app.

  4. Choose Code.

  5. Copy the HTTP or SSH repository URI, depending on the authentication mode that you configured during setup.

  6. Clone the repository.

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

The repository contains the template for the application, a build specification, and code. Add a DynamoDB table to the application 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: Handler: src/handlers/hello-from-lambda.helloFromLambdaHandler Runtime: nodejs10.x MemorySize: 128 Timeout: 100 Description: This is a hello from Lambda example. Environment: Variables: DDB_TABLE: !Ref ddbTable Policies: - DynamoDBCrudPolicy: TableName: !Ref ddbTable - AWSLambdaBasicExecutionRole
  3. Commit and push the change.

    ~/my-app-repo$ git commit -am "Add DynamoDB table" ~/my-app-repo$ 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.

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.

  2. Choose Applications.

  3. Choose your application.

  4. Under Resources, choose Edit permissions boundary.

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

For more information about permissions boundaries, see Permissions Boundaries in the IAM user guide.

Update the Function Code

Next, update the function code to use the table. The following code uses the table to track the number of invocations processed by each instance of the function. It uses the log stream ID as a unique identifier. New instances are created when you update a function, and to handle multiple concurrent invocations.

To update the function code

  1. Open src/handlers/hello-from-lambda.js in a text editor.

  2. Change the code to the following.

    Example hello-from-lambda.js

    const dynamodb = require('aws-sdk/clients/dynamodb'); const docClient = new dynamodb.DocumentClient(); exports.helloFromLambdaHandler = 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; }
  3. Commit and push the change.

    ~/my-app-repo$ git commit -am "Use DynamoDB table" ~/my-app-repo$ 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.

Next Steps

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

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

For local development, AWS 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 AWS CloudFormation isn't able to update the application stack. These include permissions errors, account limits, 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.

  2. Choose Applications.

  3. Choose an application.

  4. Choose Deployments.

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

  6. Identify the action that encountered an error.

  7. 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 AWS CloudFormation console. Search for an event with the status UPDATE_FAILED. Because AWS CloudFormation rolls back after an error, the relevant event is under several other events in the list. If AWS 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 AWS 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 AWS 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 AWS CloudFormation console.

  2. Delete the application stack – my-app.

  3. Open the Amazon S3 console.

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

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