Full source code available here.
This post describes all the necessary steps in order to build, run/debug locally, package and deploy AWS Lambda functions using Visual Studio Code. By the end of this post, you will be able to have a complete setup on your local computer where you can write code on Visual Studio Code, test it by step-through. Well, the AWS SDK is a tool created for Visual Studio in order to ease your development process for AWS using Visual Studio. It lets you configure your own AWS user into your Visual Studio and monitor and manipulate different types of resources from the Visual Studio environment itself. It is quite similar to the Azure SDK for Visual Studio.
A few months ago AWS released a feature allowing Lambdas to run container images, for larger applications this is easier to work with than a zip file or set of layers, it also lets you move your already containerized apps to Lambda with a small effort.
To create a Lambda project. Open Visual Studio, and on the File menu, choose New, Project. Do one of the following: For Visual Studio 2017, in the New Project dialog box, expand Installed, expand Visual C#,select AWS Lambda, choose the AWS Lambda Project (.NET Core - C#) template, and then choose OK. With this, the API was already able to run locally in Visual Studio. Then you used a wizard to publish the API to AWS as a Lambda function and because the API interacts with a SQL Server database in Amazon RDS (using Entity Framework Core), you needed to enable a few more permissions. 20 hours ago The AWS Toolkit for Visual Studio provides a number of quickstart blueprints for AWS Lambda projects. A new AWS Lambda project will be created. Note that the project includes a.
I was interested to see if I could get a .NET 5 “Hello World” application running in this manner. There is a blog on the AWS site explaining how to do this with Visual Studio and the AWS Toolkit, but primarily use VS Code so I could not leverage those tools, and it would be fun to figure out.
UPDATE 1
When I published this blog post I was unaware of a pre-made .NET 5 Docker image for AWS Lambda so I built my own following instructions found on an AWS GitHub repo. Those instructions are below.But it is much easier to use the AWS provided image available here - https://gallery.ecr.aws/lambda/dotnet and use public.ecr.aws/lambda/dotnet:5.0.
UPDATE 2
The AWS Lambda image above seems to have the full .NET 5 ASP.NET Runtime as opposed to the .NET 5 Runtime, if all you are running in the container is a library, then having the full .NET 5 ASP.NET Runtime will be larger than you need. As of now, I don’t see an image on the AWS ECR page for the .NET 5 Runtime. But you can build it your self following the below instructions, with one change, on line 49 of this file https://github.com/aws/aws-lambda-dotnet/blob/087590ce99274e16e26d37e1dfd73b0b71d1230a/LambdaRuntimeDockerfiles/dotnet5/Dockerfile, change the linked tar.gz to the appropriate file in here https://versionsof.net/core/5.0/.
Building your own base image (optional)
You can’t use just any docker image for a .NET 5 application, it has to have special Lambda and AWS components included, here is how to build your own, if you want to, from the AWS code on GitHub.
- clone https://github.com/aws/aws-lambda-dotnet
- build this image https://github.com/aws/aws-lambda-dotnet/blob/master/LambdaRuntimeDockerfiles/dotnet5/Dockerfile
- reference this built image in the Dockerfile as the base
But it is much easier to use the one image AWS provides - https://gallery.ecr.aws/lambda/dotnetNow that you have a base image, let’s move to the application.
Building the hello world container
Create a new .NET Lambda using -
This crates a simple library that converts an input string to uppercase.If you wanted to, you could build this, zip it and deploy it to a Lambda as I showed in part 1 of this series.
But I want to put this in a container.
You need Docker for the rest of this, there are plenty of tutorials out there including one from my friend Steve Gordon.
In the source code directory add a file named Dockerfile with the below content. Note that it’s using the image I put on Docker Hub.
Everything is in place, build the image.
Over in AWS we need a repository to store the image.
Go to the Elastic Container Registry.
Create a repository.
Navigate into the repository and you will see a button labeled “View push commands”. Follow those instructions to upload the container image to repository.
That’s everything done here, over to the Lambda.
The Lambda
This is similar to what I showed in part one, but this time the function will be based on a container image.
Create a new Lambda function, select Container image from the options.
Give the function a name.
Hit Browse images, and select the container image from the repository created above.
It will take a few moments for AWS to create the function. Once it is up, open the test tool in the top right of the screen and click “Configure test events”.
Set the event name, and replace the body with this - “hello world”.
Aws Lambda Visual Studio Environment Variables
Hit the “Test” button in the top right.
You should see something like - “Execution result: succeeded(logs)”. Expand the Details and you will see “HELLO WORLD” and bunch of other information about the execution of the Lambda.
That is a .NET 5 library running inside container, running inside a Lambda, not bad!
But what if you could get Kestrel up and running and map API Gateway requests to it, that would be fun…and that’s in the next post of this series.
Full source code available here.
Related
Microservices are fun to build and offer us a scalable path to overcoming problems with tightly coupled dependencies that plague monolithic applications.
This post will walk you through building an AWS Lambda microservice written in C# with .NET Core 2.1, and communicating in JSON. We’re bringing together multiple exciting technologies here - microservices, serverless API via AWS Lambda, and authentication using Okta’s easy and convenient identity provider. Each of these technologies is deserving of their own deep-dive article, so there is a lot to cover on these subjects. This post is meant to provide a starting point implementing all three. It will be simple so that anyone can follow along. It will also be kept to a clean, basic implementation that you can expand easily if needed.
Let’s jump right in and build our first microservice - an authentication service.
There are a few things you will need to follow this tutorial.
Visual Studio 2017 If you don’t have it, you can download Visual Studio Community for free.An AWS Account. If you don’t already have one, you can create one here.
Create Your ASP.NET Core Microservice
Create a new AWS Serverless Application (.NET Core) project as shown below. If you do not have this option you need to install the AWS Toolkit for Visual Studio.
Aws Lambda Visual Studio Debug
You’ll also want to install the Newtonsoft.Json package as shown in the image below.
A microservice architecture is particularly empowering when it comes to scalability. Each component is isolated in its own executable or web service. This means components can run on dedicated hardware, and specific pieces of functionality can be scaled up and down with more granular precision than in an ESB (Enterprise Service Bus). This makes AWS Lambda a complementary medium to host your new microservice. Lambda is a serverless hosting solution that’s highly scalable.
Configure Authentication for Your ASP.NET Microservice
For this example, you’ll need an Okta developer account. If you don’t already have one you can sign up for a free developer account.
You’ll also need an Okta ApiToken. For security reasons, ApiTokens are only displayed once, so make sure you keep it safe once it’s generated. Login to your Okta Developer account, and click API in the main menu, then go to Tokens. On the Tokens screen click Create Token in the top left-hand corner of the page. Give your token a name then click Create Token.
At this point, Okta will generate your ApiToken and display it on the screen. This value will eventually be placed in appSettings.json, but for now, copy it somewhere to keep for later.
Determine the Scope of Your ASP.NET Core Microservice
The utility microservices provide is the loose coupling of dependencies. Everything inside your service is tightly coupled. Everything outside is loosely coupled. Keep this in mind while trying to determine how big your microservice should be. You don’t want your service to grow to the point where your writing class libraries that are tightly-coupled dependencies of more than one “micro-service”.
Following this rule, a microservice could offer a very deep pool of functionality, that can always be made deeper but should very rarely (if ever) be made wider.
Create the Objects for Your ASP.NET Core Microservice
In your project’s root folder, create a folder called Model. Inside that file, you’ll need to create the following model objects. It’s easiest to create all these first so that the objects for transferring data will already be in place when we start writing our logic.
OktaSettings
The OktaSettings object will be used to store your Okta domain and the API token that enables programmatic access to your Okta account. Notice that these members - Domain and ApiToken - match the attributes in our appSettings.json file under the Okta heading. When the program is initiated, the config file will be read and the values will be stored in memory, where they will then be accessible via IOptions<OktaSettings>.
OktaAuthenticationRequest
This class is used to send data to the Okta Authentication API at https://{yourOktaDomain}/api/v1/authn. An instance of this class will be passed to Okta with the username and password supplied to our authentication service. This is the call that tells us whether the login was successful.
For more information on Okta’s authentication API, including postman examples of HTTP requests, click here.
Credentials
Our AuthenticationController will expose a single action - Authenticate. That method accepts a single input - Credentials. Credentials is used to pass the username and password in need of authentication to our microservice.
Keeping your microservice small, with only a single controller and a single action, has beneficial consequences downstream on systems dependent upon your new microservice. On a microservice driven platform, disasters are isolated. If one service goes down, the rest of the services and the unrelated features of the application will still be operational. The impacted portion of the app can display a friendly message informing the user of the outage while your team sets to work fixing the production issue. If the service logic and app logic were tightly coupled, the entire app would be brought down with the service.
AuthenticationResponse
Just like Credentials is used to pass data to the Authenticate action, AuthenticationResponse is used to return data from the Authenticate action. It will tell the client calling your microservice if the call was successful or it will return an error message.
In the event of success, you will also define the User and Session members.
AuthenticatedSession
The AuthenticatedSession class is made to encapsulate details about the user’s session if they are successfully authenticated. This will be used to return that data to the client calling your microservice.
AuthenticatedUser
Much like AuthenticatedSession, AuthenticatedUser is made to encapsulate details about the user, if they are successfully authenticated. This will be used to return that data to the client calling our microservice.
Load the Configuration for the ASP.NET Core Microservice
At startup, we’ll want to process the config file so that we can get access to the configured Okta Domain, and ApiToken. To do this add the following lines to the bottom of the ConfigureServices method of your Startup.cs file. This tells dot net core where the config details are, and gives it our OktaSettings class, to be used for accessing the configuration settings.
Add the Authentication Steps to Your ASP.NET Core Microservice
The next step is to implement authentication by calling Okta’s Authentication API. Add a file called AuthenticationController.cs to your Controllers folder. Then paste the following code:
You may notice that the constructor of the class accepts an instance of IOptions<OktaSettings>. OktaSettings is the same class you defined above in your Model folder to store your Okta configuration settings.
The configuration code you added to Startup.cs enables IOptions<OktaSettings> to be recognized by .Net Core and the framework will automatically supply the input when the class is initialized. This gives you access to the Okta configuration settings in appSettings.json.
The Authenticate action has been well commented to help you understand what each line is doing. Here are the high-level steps that the action goes through:
Creates an instance of OktaAuthenticationRequest to pass the supplied username and password to Okta’s authentication serviceJSON encodes the dataCreates an instance of HttpClient to communicate with Okta, and sets the authentication header value using the ApiTokenPosts the JSON encoded data to Okta and awaits a responseDeserialized JSON response stream, and evaluates if 'SUCCESS' was the returned statusIf the login was unsuccessful it returns false for WasSuccess and 'Invalid username and password' for Message. If it was a success it returns true for WasSuccess, and returns the session and user data provided by Okta
Add Configuration Management to Your Microservice
All your configuration for the service can be found in the appSettings.json file. Following best practice, you’ll want to configure each environment to point at a different instance of Okta. This isolates each environment so tests in one environment don’t interfere with tests in another. It helps you become familiar with your Okta settings so that you can be deliberate when configuring Okta and your software. It presents an opportunity to rehearse deployment and configuration. All of these things are useful steps you don’t want to skip when working your solution to production.
You’ll have to populate the below settings from your Okta account.
Deploy Your Lambda Microservice
Deploying your new microservice as a Lambda function is easy. The AWS Toolkit for Visual Studio will create the cloud components for you. To deploy your microservice, in the Solution Explorer, right click on your web service project, and select Publish to AWS Lambda.
Click on the little person icon next to Account Profile to Use. In the resulting pop-up window, you can use “default” as the profile name. You’ll need to enter Access Key information. To create an Access Key in AWS, click on your account name in the top right of your AWS dashboard and choose My Security Credentials. Expand the Access Keys section and click Create New Access Key. In the pop-up window, there will be a link to show the Access Key ID and Secret Access Key. You can enter them in the deployment window in Visual Studio, or download the keyfile and click Import from csv file… to import it.
Then, you’ll need to get Provide a Stack Name. This can be whatever you want to name it and will be used by the wizard when creating your AWS resource to prefix automatically generated component names. You can also provide the S3 Bucket you’d like the code deployed to. You can click the New… button to create an S3 Bucket to use. Click Publish to start the deployment.
If your cloud resources have not already been created, publish will create them for you. During publish, the modal window will disappear and a deployment tab will appear in your IDE. Once the status shown in the tab displays UPDATE_COMPLETE, your deployment has finished.
Aws Lambda Visual Studio
Copy the AWS Serverless URL and use it to test your microservice. Your URL may look something like mine shown below:https://25ayfn7ecl.execute-api.us-east-2.amazonaws.com/Prod
This means the URL to our authenticate action looks like:https://25ayfn7ecl.execute-api.us-east-2.amazonaws.com/Prod/api/authentication/authenticate
Aws Lambda Visual Studio C#
Open Postman and POST to the above URL, while sending the following form data:
- PublicKey = {YOURUSERNAME}
- PrivateKey = {YOURPASSWORD}
If you get a response back like the following, you’re good to go!
ASP.NET Core Microservice Next Steps and Considerations for Production
If you’re going to take this to production you’re definitely going to want to have an SSL certificate. Select a certificate authority like AWS or GoDaddy, and check out their SSL offerings. Purchase your SSL and install it on your web server or AWS account.
Authentication is about verifying the identity of the client. Authorization, on the other hand, is what you sometimes do after you know who you’re dealing with and you want to know what they have permission to access. If your authorization logic is simple, it may be appropriate to add another controller and action to this existing microservice. If your logic is more complex, then it should be put into a new microservice. That new microservice could then be passed the session token (returned from the authentication microservice we built today), and the identity of a digital resource, and it will return the level of access to that resource.
Learn More About ASP.NET Core and Microservices
You can find the complete source code on GitHub here. Have fun coding!
For other examples using ASP.NET Core and microservices check out the following links:
Aws Lambda Visual Studio 2017
- Martin Fowler - Microservices (video).
If you have any questions, please post in the comments section below. Don’t forget to follow us on Twitter and check out our videos on YouTube!