Tag: Lambda
Updates for .NET Core Lambda Libraries
With our release of .NET Core support in AWS Lambda, we also released many NuGet packages to help you develop Lambda functions. We’ve been constantly updating them on our GitHub repository as well. Let’s look at some of the recent updates.
Amazon.Lambda.Tools
This package contains the integration with the .NET Core CLI, which you can use to deploy your functions. The AWS Toolkit for Visual Studio also uses this package to perform the deployment. For information about this package, see this previous post.
Lambda supports .NET Core 1.0. If you add a dependency to your .NET Core project that requires .NET Core 1.1, the .NET Core publishing tooling used by Amazon.Lambda.Tools will run without errors. However, when you run the function you’ll get errors because of the incompatibility. In version 1.5.0 of Amazon.Lambda.Tools we added validation on top of the .NET Core publishing tool to ensure that none of the dependencies for the project require a later runtime than Lambda supports.
New Events Packages
We have many NuGet packages that contain typed classes modeling the Lambda event types for the services. We recently added two more packages: Amazon.Lambda.LexEvents and Amazon.Lambda.KinesisFirehoseEvents.
Amazon.Lambda.LexEvents
Amazon Lex is a service for creating bots. You can use Lambda functions to process the incoming requests to the bot. The Amazon.Lambda.LexEvents package contains the LexEvent and LexResponse classes that you can use as parameter and return for your Lambda functions.
In the Amazon Lex console you can create several getting started Amazon Lex bots. Book Trips is one of the getting started samples you can use to simulate booking a hotel or car. We added a blueprint in Visual Studio that you can use to create the Lambda processor for the Book Trips bot.
Amazon.Lambda.KinesisFirehoseEvents
Amazon Kinesis Firehose recently added support for using Lambda functions to transform the data being streamed to Amazon S3. The Amazon.Lambda.KinesisFirehoseEvents package contains the KinesisFirehoseEvent and KinesisFirehoseResponse classes. We also added a new getting started blueprint to Visual Studio for Firehose.
Serialization Debugging
As we mentioned, we have many packages providing typed classes that you can use for Lambda functions. You can also define your own classes, and the Amazon.Lambda.Serialization.Json package, which is registered in all of the blueprints we provide, will automatically handle all serializing and deserializing into JSON. In version 1.1.0 of the Amazon.Lambda.Serialization.Json package, we added a new debugging feature to help diagnose serialization issues you might have with your custom types. If you add the environment variable LAMBDA_NET_SERIALIZER_DEBUG with the value of true, the Amazon.Lambda.Serialization.Json package writes the incoming and outgoing JSON to the Amazon CloudWatch log stream. This can be very useful to verify that typed classes are being sent back as you expect.
ASP.NET Core Web API Support
We continue to add features to our ASP.NET Core Web API support on top of Lambda. We are also getting some great support from our community on this project with pull and feature requests. Please keep the feedback coming. In versions 0.10.1-preview1 of Amazon.Lambda.AspNetCoreServer we added:
- Binary support – see the README.md file for details on how to set this up.
- Filling in the RemoteIpAddress and RemotePort on HttpContext.Connection from the Amazon API Gateway request.
- New APIGatewayProxyRequest and ILambdaContext objects for the Lambda function to the HttpContext.Items collection with the collection keys APIGatewayRequest and LambdaContext.
Amazon.Lambda.Templates (1.2.1)
The NuGet package Amazon.Lambda.Templates makes all the blueprints offered in Visual Studio available to the dotnet new command. We recently released version 1.2.1 with the new Amazon Lex and Firehose blueprints, and we updated all the dependencies for the other blueprints. See this earlier blog post on how to install and use the blueprints from the dotnet new command.
Summary
We are continually improving our Lambda packages to enhance the experience of developing Lambda functions. Check out the GitHub repo, which is also a great place to give us your feedback. You can also track the releases of the packages in the RELEASE.CHANGELOG.md file.
Deploying .NET Core AWS Lambda Functions from the Command Line
In previous posts about our .NET Core support with AWS Lambda, we’ve shown how you can create Lambda functions and serverless applications with Visual Studio. But one of the most exciting things about .NET Core is its cross-platform support with the new command line interface (CLI) named dotnet. To help you develop Lambda functions outside of Visual Studio, we’ve released the Amazon.Lambda.Tools NuGet package that integrates with the dotnet CLI.
We released Amazon.Lambda.Tools as a preview with our initial release of .NET Core on Lambda. We kept it in preview while .NET Core tooling, including the dotnet CLI, was in preview. With the recent release of Visual Studio 2017, the dotnet CLI and our integration with it is now marked as generally available (GA). If you’re still using preview versions of the dotnet CLI and the pre-Visual Studio 2017 project structure, the GA release of Amazon.Lambda.Tools will still work for those projects.
.NET Core Project Structure
When .NET Core was originally released last summer, you would define a project in a JSON file named project.json. At that time, it was announced that this was temporary, that .NET Core was moving to be in line with other .NET projects and would be based on the msbuild XML format, and that each project would contain a .csproj file. As part of the GA release of the dotnet CLI tooling, the release includes the switch to the msbuild format.
Amazon.Lambda.Tools Registration
If you create an AWS Lambda project in Visual Studio, the command line integration is set up automatically so that you can easily transition from Visual Studio to the command line. If you inspect a project created in Visual Studio 2017, you’ll notice a DotNetCliToolReference for the Amazon.Lambda.Tools NuGet package.
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<TargetFramework>netcoreapp1.0</TargetFramework>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="Amazon.Lambda.Core" Version="1.0.0" />
<PackageReference Include="Amazon.Lambda.Serialization.Json" Version="1.0.1" />
</ItemGroup>
<ItemGroup>
<DotNetCliToolReference Include="Amazon.Lambda.Tools" Version="1.4.0" />
</ItemGroup>
</Project>
In Visual Studio 2015, which uses the older project.json format, the Amazon.Lambda.Tools package is declared as a build dependency and is also registered in the tools section.
{
"version": "1.0.0-*",
"buildOptions": {
},
"dependencies": {
"Microsoft.NETCore.App": {
"type": "platform",
"version": "1.0.0"
},
"Amazon.Lambda.Core": "1.0.0*",
"Amazon.Lambda.Serialization.Json": "1.0.1",
"Amazon.Lambda.Tools" : {
"type" :"build",
"version":"1.4.0 "
}
},
"tools": {
"Amazon.Lambda.Tools" : "1.4.0 "
},
"frameworks": {
"netcoreapp1.0": {
"imports": "dnxcore50"
}
}
}
Adding to an Existing Project
The Amazon.Lambda.Tools NuGet package is marked as DotNetCliTool package type. Right now Visual Studio 2017 doesn’t understand the new package type. If you attempt to add the NuGet package through Visual Studio’s Manage NuGet Packages dialog it won’t be able to add the reference. Till Visual Studio 2017 is updated you will need to manually add the DotNetCliToolReference in the csproj file.
Deploying Lambda Functions
All the tooling we developed for Visual Studio to deploy Lambda functions originated in the Amazon.Lambda.Tools package. That means all the deployment features you use inside Visual Studio you can also do from the command line.
To get started, in a command window navigate to a project you created in Visual Studio. To see the available commands, enter dotnet lambda help.
C:\BlogContent\BlogExample\BlogExample> dotnet lambda help
AWS Lambda Tools for .NET Core functions
Project Home: https://github.com/aws/aws-lambda-dotnet
Commands to deploy and manage AWS Lambda functions:
deploy-function Command to deploy the project to AWS Lambda
invoke-function Command to invoke a function in Lambda with an optional input
list-functions Command to list all your Lambda functions
delete-function Command to delete an AWS Lambda function
get-function-config Command to get the current runtime configuration for a Lambda function
update-function-config Command to update the runtime configuration for a Lambda function
Commands to deploy and manage AWS Serverless applications using AWS CloudFormation:
deploy-serverless Command to deploy an AWS Serverless application
list-serverless Command to list all your AWS Serverless applications
delete-serverless Command to delete an AWS Serverless application
Other Commands:
package Command to package a Lambda project into a zip file ready for deployment
To get help on individual commands execute:
dotnet lambda help <command>
By using the dotnet lambda command you have access to a collection of commands to manage Lambda functions and serverless applications. There is also a package command that packages your project into a .zip file, ready for deployment. This can be useful for CI systems.
To see help for an individual command, type dotnet lambda help followed by the command name; for example, dotnet lambda help deploy-function.
C:\BlogContent\BlogExample\BlogExample> dotnet lambda help deploy-function
AWS Lambda Tools for .NET Core functions
Project Home: https://github.com/aws/aws-lambda-dotnet
deploy-function:
Command to deploy the project to AWS Lambda
dotnet lambda deploy-function [arguments] [options]
Arguments:
<FUNCTION-NAME> The name of the function to deploy
Options:
--region The region to connect to AWS services, if not set region will be detected from the environment (Default Value: us-east-2)
--profile Profile to use to look up AWS credentials, if not set environment credentials will be used (Default Value: normj+vpc)
--profile-location Optional override to the search location for Profiles, points at a shared credentials file
-pl | --project-location The location of the project, if not set the current directory will be assumed
-cfg | --config-file Configuration file storing default values for command line arguments. Default is aws-lambda-tools-defaults.json
-c | --configuration Configuration to build with, for example Release or Debug (Default Value: Release)
-f | --framework Target framework to compile, for example netcoreapp1.0 (Default Value: netcoreapp1.0)
-pac | --package Application package to use for deployment, skips building the project
-fn | --function-name AWS Lambda function name
-fd | --function-description AWS Lambda function description
-fp | --function-publish Publish a new version as an atomic operation
-fh | --function-handler Handler for the function <assembly>::<type>::<method> (Default Value: BlogExample::BlogExample.Function::FunctionHandler)
-fms | --function-memory-size The amount of memory, in MB, your Lambda function is given (Default Value: 256)
-frole | --function-role The IAM role that Lambda assumes when it executes your function
-ft | --function-timeout The function execution timeout in seconds (Default Value: 30)
-frun | --function-runtime The runtime environment for the Lambda function (Default Value: dotnetcore1.0)
-fsub | --function-subnets Comma delimited list of subnet ids if your function references resources in a VPC
-fsec | --function-security-groups Comma delimited list of security group ids if your function references resources in a VPC
-dlta | --dead-letter-target-arn Target ARN of an SNS topic or SQS Queue for the Dead Letter Queue
-ev | --environment-variables Environment variables set for the function. Format is <key1>=<value1>;<key2>=<value2>
-kk | --kms-key KMS Key ARN of a customer key used to encrypt the function's environment variables
-sb | --s3-bucket S3 bucket to upload the build output
-sp | --s3-prefix S3 prefix for for the build output
-pcfg | --persist-config-file If true the arguments used for a successful deployment are persisted to a config file. Default config file is aws-lambda-tools-defaults.json
C:\BlogContent\BlogExample\BlogExample>
As you can see, you can set many options with this command. This is where the aws-lambda-tools-defaults.json file, which is created as part of your project, comes in handy. You can set the options in this file, which is read by the Lambda tooling by default. The project templates created in Visual Studio set many of these fields with default values.
{
"profile":"default",
"region" : "us-east-2",
"configuration" : "Release",
"framework" : "netcoreapp1.0",
"function-runtime":"dotnetcore1.0",
"function-memory-size" : 256,
"function-timeout" : 30,
"function-handler" : "BlogExample::BlogExample.Function::FunctionHandler"
}
When you use this aws-lambda-tools-default.json file, the only things left that the Lambda tooling needs to deploy the function are the name of the Lambda function and the IAM role. You do this by using the following command:
dotnet lambda deploy-function TheFunction --function-role TestRole
C:\BlogContent\BlogExample\BlogExample> dotnet lambda deploy-function TheFunction --function-role TestRole
Executing publish command
Deleted previous publish folder
... invoking 'dotnet publish', working folder 'C:\BlogContent\BlogExample\BlogExample\bin\Release\netcoreapp1.0\publish'
... publish: Microsoft (R) Build Engine version 15.1.548.43366
... publish: Copyright (C) Microsoft Corporation. All rights reserved.
... publish: BlogExample -> C:\BlogContent\BlogExample\BlogExample\bin\Release\netcoreapp1.0\BlogExample.dll
Zipping publish folder C:\BlogContent\BlogExample\BlogExample\bin\Release\netcoreapp1.0\publish to C:\BlogContent\BlogExample\BlogExample\bin\Release\netcoreapp1.0\BlogExample.zip
... zipping: Amazon.Lambda.Core.dll
... zipping: Amazon.Lambda.Serialization.Json.dll
... zipping: BlogExample.deps.json
... zipping: BlogExample.dll
... zipping: BlogExample.pdb
... zipping: Newtonsoft.Json.dll
... zipping: System.Runtime.Serialization.Primitives.dll
Creating new Lambda function TheFunction
New Lambda function created
C:\BlogContent\BlogExample\BlogExample>
You can also pass an alternative file that contains option defaults by using the –config-file option. This enables you to reuse multiple Lambda configurations.
“dotnet publish” vs “dotnet lambda” Commands
Using the Amazon.Lambda.Tools package is the preferred way to deploy functions to Lambda from the command line versus using the dotnet publish command, zipping that output folder, and sending the zip file to Lambda. The Lambda tooling looks at the publish folder and removes any duplicate native dependency in it, which reduces the size of your Lambda function. For example, if you reference the SQL Server client NuGet package, System.Data.SqlClient, the Lambda tooling produces a package file that is about 1 MB smaller than the zipped publish folder from dotnet publish. It also reworks the layout of native dependencies to ensure that the Lambda service finds the native dependencies.
Summary
We hope the Amazon.Lambda.Tools package helps you with the transition from working in Visual Studio to working in the command line to script and automate your deployments. Let us know what you think on our GitHub repository, and what you’d like to see us add to the tooling.
Deploy an Existing ASP.NET Core Web API to AWS Lambda
In the previous post, we talked about the new ASP.NET Core Web API blueprint for AWS Lambda, and the Amazon.Lambda.AspNetCoreServer NuGet package that made it possible to run the ASP.NET Core Web API through Lambda. But what if you already have an existing ASP.NET Core Web API that you want to try as a serverless application? You can do this by following these steps:
- Add the Amazon.Lambda.AspNetCoreServer NuGet package.
- Add a Lambda function and bootstrap the ASP.NET Core framework.
- Add the Amazon.Lambda.Tools NuGet package to enable the toolkit’s deployment features.
- Add a serverless.template file to define Amazon API Gateway.
- Deploy the project.
Let’s take a deeper look at each step.
Setting Up the Lambda Function
The first step is to add the Amazon.Lambda.AspNetCoreServer NuGet package that bridges the communication between Amazon API Gateway and the ASP.NET Core framework.
After you add the package, add a new class named LambdaFunction and have it extend from Amazon.Lambda.AspNetCoreServer.APIGatewayProxyFunction. You have to implement the abstract method Init to bootstrap the ASP.NET Core framework.
public class LambdaFunction : Amazon.Lambda.AspNetCoreServer.APIGatewayProxyFunction
{
protected override void Init(IWebHostBuilder builder)
{
builder
.UseContentRoot(Directory.GetCurrentDirectory())
.UseStartup()
.UseApiGateway();
}
}
Enable Tool Support in the AWS Toolkit for Visual Studio
In order for the AWS Toolkit for Visual Studio to recognize the project as a Lambda project, you have to add the Amazon.Lambda.Tools NuGet package. This package isn’t used as part of the runtime of the function and is added as a build tool.
{
"dependencies": {
...
"Amazon.Lambda.AspNetCoreServer": "0.8.4-preview1",
"Amazon.Lambda.Tools": {
"type": "build",
"version": "1.1.0-preview1"
}
},
...
}
To also enable the integration with the .NET Core CLI, list the Amazon.Lambda.Tools NuGet package in the tools section in the project.json file.
{
...
"tools": {
"Microsoft.AspNetCore.Server.IISIntegration.Tools": "1.0.0-preview2-final",
"Amazon.Lambda.Tools": "1.1.0-preview1"
},
...
}
Configuring Amazon API Gateway
At this point, you could right-click the project and deploy it to Lambda, but it wouldn’t be fronted by API Gateway exposing the function as an HTTP REST API. The easiest way to do that is to add a serverless.template file to the project and deploy the project as an AWS Serverless project.
Add a serverless.template file to the project by right-clicking the project and choosing Add, AWS Serverless Template.
The default serverless.template file contains one function definition configured to be exposed by API Gateway using proxy integration, so all requests will go to that function. This is exactly what you need for an ASP.NET Core Web API project. The only thing that needs to be updated is the handler field. The format for the handler field is <assembly-name>::<namespace>.LambdaFunction::FunctionHandlerAsync. The FunctionHandlerAsync method is inherited from the base class of our LambdaFunction class.
{
"AWSTemplateFormatVersion" : "2010-09-09",
"Transform" : "AWS::Serverless-2016-10-31",
"Description" : "Starting template for an AWS Serverless Application.",
"Parameters" : {
},
"Resources" : {
"DefaultFunction" : {
"Type" : "AWS::Serverless::Function",
"Properties": {
"Handler": "ExistingWebAPI::ExistingWebAPI.LambdaFunction::FunctionHandlerAsync",
"Runtime": "dotnetcore1.0",
"CodeUri": "",
"Description": "Default function",
"MemorySize": 256,
"Timeout": 30,
"Role": null,
"Policies": [ "AWSLambdaFullAccess" ],
"Events": {
"PutResource": {
"Type": "Api",
"Properties": {
"Path": "/{proxy+}",
"Method": "ANY"
}
}
}
}
}
},
"Outputs" : {
}
}
Deploy
Now you can deploy the ASP.NET Core Web API to either AWS Elastic Beanstalk or Lambda. The deployment process works in the same way that we’ve shown in previous blog posts about AWS Serverless projects.
And that’s all you have to do to deploy an existing ASP.NET Core Web API project to Lambda.
Visit our .NET Core Lambda GitHub repository to let us know what you think of running ASP.NET Core applications as an AWS Serverless functions and issues you might have. This will help us take the Amazon.Lambda.AspNetCoreServer NuGet package out of preview status.
Running Serverless ASP.NET Core Web APIs with Amazon Lambda
One of the coolest things we demoed at our recent AWS re:Invent talk about .NET Core support for AWS Lambda was how to run an ASP.NET Core Web API with Lambda. We did this with the NuGet package Amazon.Lambda.AspNetCoreServer (which is currently in preview) and Amazon API Gateway. Today we’ve released a new AWS Serverless blueprint that you’ll see in Visual Studio or with our Yeoman generator that makes it easy to set up an ASP.NET Core Web API project as a Lambda project.
How Does It Work?
Depending on your platform, a typically deployed ASP.NET Core application is fronted by either IIS or NGINX, which forwards requests to the ASP.NET Core web server named Kestrel. Kestrel marshals the request into the ASP.NET Core hosting framework.
When running an ASP.NET Core application as an AWS Serverless application, IIS is replaced with API Gateway and Kestrel is replaced with a Lambda function contained in the Amazon.Lambda.AspNetCoreServer package which marshals the request into the ASP.NET Core hosting framework.
The Blueprint
The blueprint creates a project that’s very similar to the one you would get if you selected the .NET Core ASP.NET Core Web Application and chose the Web API template. The key difference is instead of having a Program.cs file that contains a Main function bootstrapping the ASP.NET Core framework, the blueprint has LambdaEntryPoint.cs that bootstraps the ASP.NET Core framework.
public class LambdaEntryPoint : Amazon.Lambda.AspNetCoreServer.APIGatewayProxyFunction
{
protected override void Init(IWebHostBuilder builder)
{
builder
.UseContentRoot(Directory.GetCurrentDirectory())
.UseStartup()
.UseApiGateway();
}
}
The actual Lambda function comes from the base class. The function handler for the Lambda function is set in the AWS CloudFormation template named serverless.template, which will be in the format <assembly-name>::<namespace>.LambdaEntryPoint::FunctionHandlerAsync.
The blueprint also has LocalEntryPoint.cs that works in the same way as the original Program.cs file, enabling you to run and develop your application locally and then deploy it to Lambda.
The remainder of the project’s files are the usual ones you would find in an ASP.NET Core application. The blueprint contains two Web API controllers. The first is the example ValuesController, which is found in the starter ASP.NET Core Web API project. The other controller is S3ProxyController, which demonstrates how to use HTTP GET, PUT, and DELETE requests to a controller and uses the AWS SDK for .NET to make the calls to an Amazon S3 bucket. The name of the S3 bucket to use is obtained from the Configuration object, which means you can set the bucket in the appsettings.json file for local development.
{
...
"AppS3Bucket": "ExampleBucketName"
}
The Configuration object is built by using environment variables.
public Startup(IHostingEnvironment env)
{
var builder = new ConfigurationBuilder()
.SetBasePath(env.ContentRootPath)
.AddJsonFile("appsettings.json", optional: false, reloadOnChange: true)
.AddJsonFile($"appsettings.{env.EnvironmentName}.json", optional: true);
builder.AddEnvironmentVariables();
Configuration = builder.Build();
}
When the application is deployed, serverless.template is used to create the bucket and then pass the bucket’s name to the Lambda function as an environment variable.
...
"Get" : {
"Type" : "AWS::Serverless::Function",
"Properties": {
"Handler": "AspNetCoreWithLambda::AspNetCoreWithLambda.LambdaEntryPoint::FunctionHandlerAsync",
"Runtime": "dotnetcore1.0",
"CodeUri": "",
"MemorySize": 256,
"Timeout": 30,
"Role": null,
"Policies": [ "AWSLambdaFullAccess" ],
"Environment" : {
"Variables" : {
"AppS3Bucket" : { "Fn::If" : ["CreateS3Bucket", {"Ref":"Bucket"}, { "Ref" : "BucketName" } ] }
}
},
"Events": {
"PutResource": {
"Type": "Api",
"Properties": {
"Path": "/{proxy+}",
"Method": "ANY"
}
}
}
}
},
...
Logging
ASP.NET Core introduced a new logging framework. To help integrate with the logging framework, we’ve also released the NuGet package Amazon.Lambda.Logging.AspNetCore. This logging provider allows any code that uses the ILogger interface to record log messages to the associated Amazon CloudWatch log group for the Lambda function. When used outside of a Lambda function, the log messages are written to the console.
The blueprint enables the provider in Startup.cs, where other services are configured.
public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory)
{
loggerFactory.AddLambdaLogger(Configuration.GetLambdaLoggerOptions());
app.UseMvc();
}
This following snippet shows the call GetLambdaLoggerOptions from the Configuration object, which grabs the configuration of what messages to write to CloudWatch Logs. The appsettings.json file in the blueprint configures logging so that messages coming from classes under the Microsoft namespace are written if they’re informational level and above. For all other log messages, write debug level messages and above.
{
"Lambda.Logging": {
"LogLevel": {
"Default": "Debug",
"Microsoft": "Information"
}
},
...
}
For more information about this package, see the GitHub repository.
Deployment
Deploying the ASP.NET Core Web API works exactly as we showed you in the previous post about the AWS Serverless projects.
Once deployed, a single Lambda function and an API Gateway REST API are configured to send all requests to the Lambda function. Then the Lambda function uses the ASP.NET Core framework to route to the correct Web API controller. You can test the deployment by accessing the two controllers using the AWS Serverless URL found in the CloudFormation stack view.
- <aws-serverless-url>/api/values – Example controller
- <aws-serverless-url>/api/s3proxy – S3 Proxy controller.
Feedback
We’re very excited about running ASP.NET Core applications on AWS Lambda. As you can imagine, the option of running the ASP.NET Core framework on top of Lambda opens lots of possibilities. The Amazon.Lambda.AspNetCoreServer package is in preview while we explore those possibilities. I highly encourage .NET developers to check out this blueprint and the Amazon.Lambda.AspNetCoreServer package and let us know on our GitHub repository or our new Gitter channel what you think and how we can continue to improve the library.
AWS Lambda Support in Visual Studio
Today we released version 1.9.0 of the AWS Toolkit for Visual Studio with support for AWS Lambda. AWS Lambda is a new compute service in preview that runs your code in response to events and automatically manages the compute resources for you, making it easy to build applications that respond quickly to new information.
Lambda functions are written in Node.js. To help Visual Studio developers, we have integrated with the Node.js Tools for Visual Studio plugin, which you can download here. Once the Node.js plugin and the latest AWS Toolkit are installed, it is easy to develop and debug locally and then deploy to AWS Lambda when you are ready. Let’s walk through the process of developing and deploying a Lambda function.
Setting up the project
To get started, we need to create a new project. There is a new AWS Lambda project template in the Visual Studio New Project dialog.
The Lambda project wizard has three ways to get started. The first option is to create a simple project that just contains the bare necessities to get started developing and testing. The second option allows you to pull down the source of a function that was already deployed. The last option allows you to create a project from a sample. For this walkthrough, select the the "Thumbnail Creator" sample and choose Finish.
Once this function is deployed, it will get called when images are uploaded to an S3 bucket. The function will then resize the image into a thumbnail, and will upload the thumbnail to another bucket. The destination bucket for the thumbnail will be the same name as the bucket containing the original image plus a "-thumbnails" suffix.
The project will be set up containing three files and the dependent Node.js packages. This sample also has a dependency on the ImageMagick CLI, which you can download from http://www.imagemagick.org/. Lambda has ImageMagick pre-configured on the compute instances that will be running the Lambda function.
Let’s take a look at the files added to the project.
| app.js | Defines the function that Lambda will invoke when it receives events. |
| _sampleEvent.json | An example of what an event coming from S3 looks like. |
| _testdriver.js | Utility code for executing the Lambda function locally. It will read in the _sampleEvent.json file and pass it into the Lambda function defined in app.js |
Credentials
To access AWS resources from Lamdba, functions use the AWS SDK for Node.js which has a different path for finding credentials than the AWS SDK for .NET. The AWS SDK for Node.js looks for credentials in the environment variables AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY or through the shared credentials file. For further information about configuring the AWS SDK for Node.js refer to the AWS SDK for Node.js documentation
Running locally
To run this sample, you will need to create the source and target S3 buckets. Pick a bucket name for the source bucket, and then create the bucket using AWS Explorer. Create a second bucket with the same name as the source bucket but with the "-thumbnails" suffix. For example, you could have a pair of buckets called foobar and foobar-thumbnails. Note: the _testdriver.js defaults the region to us-west-2, so be sure to update this to whatever region you create the buckets in. Once the buckets are created, upload an image to the source bucket so that you have an image to test with.
Open the _sampleEvent.js file and update the bucket name property to the source bucket and the object key property to the image that was uploaded.
Now, you can run and debug this like any other Visual Studio project. Go ahead and open up _testdriver.js and set a breakpoint and press F5 to launch the debugger.
Deploying the function to AWS Lambda
Once we have verified the function works correctly locally, it is time to deploy it. To do that, right-click on the project and select Upload to AWS Lambda….
This opens the Upload Lambda Function dialog.
You need to enter a Function Name to identify the function. You can leave the File Name and Handler fields at the default, which indicates what function to call on behalf of the event. You then need to configure an IAM role that Lambda can use to invoke your function. For this walkthrough, you are going to create a new role by selecting that we need Amazon S3 access and Amazon CloudWatch access. It is very useful to give access to CloudWatch so that Lambda can write debugging information to Amazon CloudWatch Logs and give you monitoring on the usage of the function. You can always refine these permissions after the function is uploaded. Once all that is set, go ahead and choose OK.
Once the upload is complete the Lambda Function status view will be displayed. The last step is to tell Amazon S3 to send events to your Lambda function. To do that, click the Add button for adding an event source.
Leave the Source Type set to Amazon S3 and select the Source bucket. S3 will need permission to send events to Lambda. This is done by assigning a role to the event source. By default, the dialog will create a role that gives S3 permission. Event sources to S3 are unique in that the configuration is actually done to the S3 bucket’s notification configuration. When you choose OK on this dialog, the event source will not show up here, but you can view it by right-clicking on the bucket and selecting properties.
Now that the function is deployed and S3 is configured to send events to our function, you can test it by uploading an image to the source bucket. Very shortly after uploading an image to the source bucket, your thumbnail will show up in the thumbnails bucket.
Calling from S3 Browser
Your function is set up to create thumbnails for any newly uploaded images. But what if you want to run our Lambda function on images that have already been uploaded? You can do that by opening the S3 bucket from AWS Explorer and navigating to the image you need the Lambda function to run against and choosing Invoke Lambda Function.
Next select the function we want to invoke and choose OK. The toolkit will then create the event object that S3 would have sent to Lambda and then calls Invoke on the function.
This can be done for an individual file or by selecting multiple files or folders in the S3 Browser. This is helpful when you make a code change to your Lambda function and you want to reprocess all the objects in your bucket with the new code.
Conclusion
Creating thumbnails is just one example you can use AWS Lambda for, but I’m sure you can imagine many ways you can use the power of Lambda’s event-based compute power. Currently, you can create event sources to Amazon S3, Amazon Kinesis, and Amazon DynamoDB Streams, which is currently in preview. It is also possible to invoke Lambda functions for your own custom events using any of AWS SDKs.
Try out the new Lambda features in the toolkit and let us know what you think. Given that AWS Lambda is in preview, we would love to get your feedback about these new features and what else we can add to make you successful using Lambda.
