Skip to main content

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​

Application Overview​

This sample app has 2 GET endpoints, and is primarily to showcase the C# expose capability.

REST API Endpoints​

  • GET /
  • GET /api/values
  • GET /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:

topology diagram the sample-api api gateway exposing the main lambda function

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 and ValuesController 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.

Startup.cs
...
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