Working with serverless applications

The AWS Toolkit for Visual Studio Code provides support for serverless applications. Using the Toolkit for VS Code, you can create serverless applications that contain AWS Lambda functions, and then deploy the applications to an AWS CloudFormation stack.

Topics

• Assumptions and prerequisites
• IAM permissions for serverless applications
• Creating a new serverless application (local)
• Opening a serverless application (local)
• Running and debugging a serverless application from template (local)
• Deploying a serverless application to the AWS Cloud
• Deleting a serverless application from the AWS Cloud
• Running and debugging Lambda functions directly from code
• Running and debugging local Amazon API Gateway resources
• Configuration options for debugging serverless applications
• Troubleshooting serverless applications

Assumptions and prerequisites

• Be sure that your system meets the required prerequisites specified in Installing the AWS Toolkit for Visual Studio Code.

• Install the AWS Serverless Application Model (AWS SAM) command line interface (CLI) and its prerequisites. See AWS SAM CLI in the setup prerequisites. If Visual Studio Code is open when you perform these installations, you might need to close and reopen the editor.

• Identify your default AWS Region in your AWS config file. For more information, see Configuration and credential file settings in the AWS Command Line Interface User Guide. If Visual Studio Code is open when you update your config file, you might need to close and reopen the editor.

• After installing your language SDK, be sure to configure your toolchain.

• To ensure that you can access the CodeLens feature in AWS SAM template files, install the YAML language support VS Code extension.

IAM permissions for serverless applications

In the Toolkit for VS Code you must have a credentials profile that contains the AWS Identity and Access Management (IAM) permissions necessary to deploy and run serverless applications. You must have appropriate read/write access to the following services: AWS CloudFormation, IAM, Lambda, Amazon API Gateway, Amazon Simple Storage Service (Amazon S3), and Amazon Elastic Container Registry (Amazon ECR).

For information about ensuring that you have the necessary permissions to deploy and run serverless applications, see Permissions in the AWS Serverless Application Model Developer Guide. For information on how to set up your credentials profile, see Setting up your AWS credentials.

Creating a new serverless application (local)

This procedure shows how to create a serverless application with the Toolkit for VS Code by using AWS SAM. The output of this procedure is a local directory on your development host containing a sample serverless application, which you can build, locally test, modify, and deploy to the AWS Cloud.

1. To open the Command Palette, choose View, Command Palette, and then enter AWS.

2. Choose AWS Toolkit Create Lambda SAM Application.

   
   Note

   If the AWS SAM CLI isn't installed, you get an error in the lower-right corner of the VS Code editor. If this happens, verify that you've met all the assumptions and prerequisites.

3. Choose the runtime for your AWS SAM application.

   Note

   If you select one of the runtimes with "(Image)", your application is package type Image. If you select one of the runtimes without "(Image)", your application is type Zip. For more information about the difference between Image and Zip package types, see Lambda deployment packages in the AWS Lambda Developer Guide.

4. Depending on the runtime you select, you may be asked to select a dependency manager and a runtime architecture for your SAM application.

   Dependency Manager

   Choose between Gradle or Maven.

   Note

   This choice of build automation tools is available only for Java runtimes.

   Architecture

   Choose between x86_64 or arm64.

   The option to run your serverless application in an ARM64-based emulated environment instead of the default x86_64-based environment is available for the following runtimes:

   • nodejs12.x (ZIP and image)

   • nodejs14.x (ZIP and image)

   • python3.8 (ZIP and image)

   • python3.9 (ZIP and image)

   • java8.al2 with Gradle (ZIP and image)

   • java8.al2 with Maven (ZIP only)

   • java11 with Gradle (ZIP and image)

   • java11 with Maven (ZIP only)

   Important

   You must install AWS CLI version 1.33.0 or later to allow applications to run in ARM64-based environments. For more information, see Prerequisites.

5. Choose a location for your new project. You can use an existing workspace folder if one is open, Select a different folder that already exists, or create a new folder and select it. For this example, choose There are no workspace folders open to create a folder named MY-SAM-APP.

6. Enter a name for your new project. For this example, use my-sam-app-nodejs. After you press Enter, the Toolkit for VS Code takes a few moments to create the project.

When the project is created, your application is added to your current workspace. You should see it listed in the Explorer window.

Opening a serverless application (local)

To open a serverless application on your local development host, open the folder that contains the application's template file.

1. From the File, choose Open Folder....

2. In the Open Folder dialog box, navigate to the serverless application folder that you want to open.

3. Choose the Select Folder button.

When you open an application's folder, it is added to the Explorer window.

Running and debugging a serverless application from template (local)

You can use the Toolkit for VS Code to configure how to debug serverless applications and run them locally in your development environment.

You start to configure debug behavior by using the VS Code CodeLens feature to identify an eligible Lambda function. CodeLens enables content-aware interactions with your source code. For information about ensuring that you can access the CodeLens feature, review the Assumptions and prerequisites section from earlier in this topic.

Note

In this example, you debug an application that uses JavaScript. However, you can use Toolkit for VS Code debugging features with the following languages and runtimes:

• C# – .NET Core 2.1, 3.1; .NET 5.0

• JavaScript/TypeScript – Node.js 12.x, 14.x

• Python – 2.7, 3.6, 3.7, 3.8, 3.9

• Java – 8, 8.al2, 11

• Go – 1.x

Your language choice also affects how CodeLens detects eligible Lambda handlers. For more information, see Running and debugging Lambda functions directly from code.

In this procedure, you use the example application created in the Creating a new serverless application (local) section earlier in this topic.

1. To view your application files in VS Code's File Explorer, choose View, Explorer.

2. From the application folder (for example, my-sample-app), open the template.yaml file.

   Note

   If you use a template with a name that's different from template.yaml, the CodeLens indicator isn't automatically available in the YAML file. This means that you must manually add a debug configuration.

3. In the editor for template.yaml, go to the Resources section of the template that defines serverless resources. In this case, this is the HelloWorldFunction resource of type AWS::Serverless::Function.

   In the CodeLens indicator for this resource, choose Add Debug Configuration.

   

4. In the Command Palette, select the runtime in which your AWS SAM application will run.

5. In the editor for the launch.json file, edit or confirm values for the following configuration properties:

   • "name" – Enter a reader-friendly name to appear in the Configuration drop-down field in the Run view.

   • "target" – Ensure that the value is "template" so that the AWS SAM template is the entry point for the debug session.

   • "templatePath" – Enter a relative or absolute path for the template.yaml file.

   • "logicalId" – Ensure that the name matches the one specified in the Resources section of the AWS SAM template. In this case, it's the HelloWorldFunction of type AWS::Serverless::Function.

   

   For more information about these and other entries in the launch.json file, see Configuration options for debugging serverless applications.

6. If you're satisfied with your debug configuration, save launch.json. Then, to start debugging, choose the green "play" button in the RUN view.

   When the debugging sessions starts, the DEBUG CONSOLE panel shows debugging output and displays any values returned by the Lambda function. (When debugging AWS SAM applications, the AWS Toolkit is selected as the Output channel in the Output panel.)

Deploying a serverless application to the AWS Cloud

This example shows how to deploy the serverless application that created in the previous section (Creating a new serverless application (local)) to the AWS Cloud using the Toolkit for VS Code.

Before you perform a deployment, make sure that the following items are covered:

• For applications with deployment type Zip, be sure to have a globally unique Amazon S3 bucket name to use for the deployment.

• For applications with deployment type Image, be sure to have both a globally unique Amazon S3 bucket name and an Amazon ECR repository URI to use for the deployment.

For more information about Lambda package types, see Lambda deployment packages in the AWS Lambda Developer Guide.

To deploy a serverless application, follow these steps:

1. To open the Command Palette, choose View, Command Palette, and then enter AWS.

2. Choose AWS Toolkit Deploy SAM Application.

   

3. Choose the template.yaml file to use for the deployment.

4. Choose the AWS Region to deploy to.

5. Enter the name of an Amazon S3 bucket that this deployment can use. The bucket must be in the Region that you're deploying to.

   Warning

   The Amazon S3 bucket name must be globally unique across all existing bucket names in Amazon S3. Therefore, you should add a unique identifier to the name given in the following example, or choose a different name.

6. If your serverless application includes a function with package type Image, enter the name of an Amazon ECR repository that this deployment can use. The repository must be in the Region that you're deploying to.

7. Enter a name for the deployed stack, either a new stack name or an existing stack name.

8. Verify the success of the deployment on the OUTPUT tab of VS Code.

   If an error occurs, a message pops up in the lower-right that is similar to the following:

   

   If this happens, check the text in the OUTPUT tab for details. The following is an example of error details:

   Error with child process: Unable to upload artifact HelloWorldFunction referenced by CodeUri parameter of HelloWorldFunction resource.
   S3 Bucket does not exist. Execute the command to create a new bucket
   AWS s3 mb s3://pbart-my-sam-app-bucket
   An error occurred while deploying a SAM Application. Check the logs for more information by running the "View AWS Toolkit Logs" command from the Command Palette.

   In this example, the error occurred because the Amazon S3 bucket did not exist.

   If an error occurs, you can also view the AWS Toolkit logs using the Command Palette. To do this, go to the View menu, choose Command Palette, enter AWS, and choose AWS Toolkit View AWS Toolkit Logs.

When the deployment is complete, you see your application listed in the AWS Explorer. To learn how to invoke the Lambda function that was created as part of the application, see Interacting with Remote Lambda Functions.

Deleting a serverless application from the AWS Cloud

Deleting a serverless application involves deleting the AWS CloudFormation stack that you previously deployed to the AWS Cloud. Note that this procedure does not delete your application directory from your local host.

1. Open the AWS Explorer.

2. In the AWS Toolkit Explorer window, expand the Region containing the deployed application that you want to delete, and then expand AWS CloudFormation.

3. Open the context (right-click) menu for the name of the AWS CloudFormation stack that corresponds to the serverless application that you want to delete, and then choose Delete AWS CloudFormation Stack.

4. To confirm that you want to delete the selected stack, choose Yes.

If the stack deletion succeeds, the Toolkit for VS Code removes the stack name from the AWS CloudFormation list in AWS Explorer.