Your First Klotho App
This tutorial demonstrates how to create a C# REST API with ASP.Net Core 6.0 and use Klotho to transform it into a cloud-native one.
The tutorial will cover the Klotho expose feature that give your existing code cloud native capabilities. We call these Klotho capabilities.
Getting Started
Prerequisites
- Klotho CLI installed
- .NET Framework 6.0
- Node.js 16.x+ (& NPM)
Application Overview
This sample app has 2 GET endpoints, and is primarily to showcase the C# expose capability.
REST API Endpoints
GET
/GET
/api/valuesGET
/api/values/{id}POST
/api/values
This application will utilize the following annotations:
Repository
Clone our sample apps git repo and navigate to its cs-simple
app.
Compiling with Klotho
First, log in to Klotho. This will allow us to support you if you run into any issues, and give you the opportunity to shape the product in this early development stage.
klotho --login <email>
Now compile the application for AWS by running klotho
and passing --provider aws
as an argument on the command line.
klotho . --app cs-simple --provider aws
██╗ ██╗██╗ ██████╗ ████████╗██╗ ██╗ ██████╗
██║ ██╔╝██║ ██╔═══██╗╚══██╔══╝██║ ██║██╔═══██╗
█████╔╝ ██║ ██║ ██║ ██║ ███████║██║ ██║
██╔═██╗ ██║ ██║ ██║ ██║ ██╔══██║██║ ██║
██║ ██╗███████╗╚██████╔╝ ██║ ██║ ██║╚██████╔╝
╚═╝ ╚═╝╚══════╝ ╚═════╝ ╚═╝ ╚═╝ ╚═╝ ╚═════╝
Adding resource exec_unit:main
Adding resource gateway:sample-api
Found 4 route(s) on app 'app'
Adding resource topology:cs-simple
Adding resource aws_template_data:cs-simple
Adding resource infra_as_code:Pulumi (AWS)
The cloud version of the application is saved to the ./compiled
directory, and has everything you need to deploy, run and operate the application.
Examining the Compiled Output
As part of the compilation, Klotho generates a high-level topology diagram showing the cloud resources that will be used in your application's cloud deployment and their relationships.
Open ./compiled/cs-simple.png
to view the application's topology diagram:
We can see here that Klotho has defined the following AWS topology:
- main (Lambda) - The main Lambda function serves the ASP.NET Core app defined in
Startup.cs
using a Lambda-compatible interface. - sample-api (API Gateway) - The sample-api API gateway is used to expose the ASP.NET Core routes defined in Both the
Startup
andValuesController
classes.
Concepts
Execution Unit
In the Klotho world, the main Lambda function is what's referred to as an execution unit. An application is composed of one or more execution units, with each execution unit being responsible for executing a discrete portion of the application's code. When using AWS, execution units are backed by compute resources such as Lambda functions or Docker containers running on Fargate (ECS or EKS).
Because @klotho::execution_unit
annotation is not used in this application, Klotho created a default execution unit for the application called main. When a default execution unit is created, Klotho determines its entrypoint by using static analysis. However, the execution unit's entrypoint may be modified as a result of other Klotho annotations in the project (as we'll see in the next section).
Expose
Klotho was able to determine how to expose the application to the public using the @klotho::expose
annotation on the Startup
class's app.UseEndpoints
invocation.
...
public class Startup
{
...
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
...
/**
* @klotho::expose {
* id = "sample-api"
* target = "public"
* }
*/
app.UseEndpoints(endpoints =>
{
endpoints.MapControllers();
endpoints.MapGet("/", async context =>
{
await context.Response.WriteAsync("Welcome to running ASP.NET Core on AWS Lambda");
});
});
}
}
Annotating the invocation of an ASP.NET Core IApplicationBuilder
instance's UseEndpoints
method with @klotho::expose
tells Klotho that you want to expose the ASP.NET Core routes declared in that invocation's delegate application using an API Gateway, and also lets Klotho know that this ASP.NET Core app should be wired to the entrypoint for all RESTful invocations of the execution unit serving it.
The target = "public"
directive tells Klotho that this app should be accessible publicly on the internet.
Deploying the application
If you would like to deploy the application, refer to the deploying guide.
What next?
- Join Discord and chat with us. What went well, what went poorly, what are you looking forward to?
- Read through the C# API docs