Working with AWS serverless applications using the AWS Toolkit

1. In the AWS Explorer, open the context (right-click) menu for the Lambda node, and then choose Create Lambda SAM Application.

   Note

   Alternatively, you can select the menu icon across from the AWS: Explorer heading, and choose Create Lambda SAM Application.

2. Choose the runtime for your SAM application. For this example, choose nodejs12.x.

   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 the Zip type. For more information about the difference between Image and Zip package types, see Lambda deployment packages in the AWS Lambda Developer Guide.

3. Choose one of the following templates for your serverless app:

   • AWS SAM Hello World: A basic template with a Lambda function that returns the classic "Hello World" message.

   • AWS Step Functions Sample App: A sample application that runs a stock-trading workflow. Step functions orchestrate the interactions of the Lambda functions that are involved.

4. Choose a location for your new project. If one is available, you can select an existing workspace folder. Otherwise, browse for a different folder. If you choose Select a different folder, a dialog box displays where you can select a folder location.

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

To use a SAM template to run and debug a serverless application

1. To view your application files that make up your serverless application, go to the Environment window.

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

3. For template.yaml, select Edit Launch Configuration.

   A new editor displays the launch.json file that provides a debugging configuration with default attributes.

4. Edit or confirm values for the following configuration properties:

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

   • "target" – Ensure that the value is "template". That way, the 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 that's specified in the Resources section of 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.

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

   Note

   If your SAM application fails to run, check the Output window to see if the error is caused by a Docker image not building. You might need to free up disk space in your environment.

   For more information, see Error running SAM applications locally in AWS Toolkit because the AWS Cloud9 environment doesn't have enough disk space.

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

   Note

   For Windows users, if you see a Docker mounting error during this process, you might need to refresh the credentials for your shared drives in Docker Settings. A Docker mounting error looks similar to the following.

   Fetching lambci/lambda:nodejs10.x Docker container image......
   2019-07-12 13:36:58 Mounting C:\Users\<username>\AppData\Local\Temp\ ... as /var/task:ro,delegated inside runtime container
   Traceback (most recent call last):
   ...requests.exceptions.HTTPError: 500 Server Error: Internal Server Error ...

To run and debug a serverless application directly from the application code

1. To view your serverless application files, navigate to the application folder by choosing the folder icon next to the editor.

2. From the application folder (for example, my-sample-app), expand the function folder (in this example, hello-world) and open the app.js file.

3. In the inline action that identifies an eligible Lambda handler function, choose Add Debug Configuration. If the add debug configuration option doesn't appear, you must enable code lenses. To enable code lenses, see Enabling AWS Toolkit code lenses .

   

4. Select the runtime where your SAM application runs.

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

   • "name" – Enter a reader-friendly name.

   • "target" – Ensure that the value is "code" so that a Lambda function handler is directly invoked.

   • "lambdaHandler" – Enter the name of the method within your code that Lambda calls to invoke your function. For example, for applications in JavaScript, the default is app.lambdaHandler.

   • "projectRoot" – Enter the path to the application file that contains the Lambda function.

   • "runtime" – Enter or confirm a valid runtime for the Lambda execution environment (for example, "nodejs.12x").

   • "payload" – Choose one of the following options to define the event payload that you want to provide to your Lambda function as input:

     • "json": JSON-formatted key-value pairs that define the event payload.

     • "path": A path to the file that's used as the event payload.

6. If you're satisfied with the debug configuration, choose the green play arrow next to RUN to start debugging.

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

   Note

   If you see Docker mentioned in error messages, see this note.

To run and debug local API Gateway resources

1. Choose one of the following approaches to create a launch config for an AWS SAM API Gateway resource:

   • Option 1: Visit the handler source code (specifically, a .js, .cs, or .py file) in your AWS SAM project, hover over the Lambda handler, and choose Add Debug Configuration If the add debug configuration option doesn't appear, enable code lenses. To enable code lenses, see Enabling AWS Toolkit code lenses .). Then, in the menu, choose the item marked API Event.

   • Option 2 Edit launch.json and create a new launch configuration using the following syntax.

     {
         "type": "aws-sam",
         "request": "direct-invoke",
         "name": "myConfig",
         "invokeTarget": {
             "target": "api",
             "templatePath": "n12/template.yaml",
             "logicalId": "HelloWorldFunction"
         },
         "api": {
             "path": "/hello",
             "httpMethod": "post",
             "payload": {
                 "json": {}
             }
         }, 
         "sam": {},
         "aws": {}
     }
                             

2. In the dropdown menu next to the Run button, choose the launch configuration (named myConfig in the preceding example).

3. (Optional) Add breakpoints to your Lambda project code.

4. Choose the Run button beside the green "play" button.

5. In the output pane, view the results.

1. In the AWS Explorer window, open the context (right-click) menu for the Lambda node and select Sync SAM Application.

2. Choose the AWS Region to deploy to.

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

4. 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. Add a unique identifier to the name given in the following example or choose another name.

5. 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.

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

7. Verify the success of the deployment on the AWS Toolkit tab of the Console.

   If an error occurs, a message pops up in the lower right.

   If this happens, check the text in the AWS Toolkit 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 didn't exist.