Kotless
Kotless stands for Kotlin serverless framework.
Its focus lies in reducing the routine of serverless deployment creation and generating it straight from the code of the application itself.
Kotless consists of two main parts:
- DSL provides a way of defining serverless applications. There are two DSLs supported:
- Ktor DSL — Ktor engine that is introspected by Kotless. You use standard Ktor syntax and Kotless generates deployment for it.
- Kotless DSL — Kotless own DSL that provides annotations to declare routing, scheduled events, etc.
- Kotless Gradle Plugin provides a way of deploying serverless application. For that, it:
- performs the tasks of generating Terraform code from the application code and, subsequently, deploying it to AWS;
- runs application locally, emulates AWS environment and provides the possibility for in-IDE debugging.
Getting started
Kotless uses Gradle to wrap around the existing build process and insert the deployment into it.
Basically, if you already use Gradle, you only need to do two things.
Firstly, set up Kotless Gradle plugin. You need to apply the plugin:
//Imports needed for this example
import io.kotless.plugin.gradle.dsl.Webapp.Route53
import io.kotless.plugin.gradle.dsl.kotless
plugins {
//Version of Kotlin should 1.3.50+
kotlin("jvm") version "1.3.50" apply true
id("io.kotless") version "0.1.3" apply true
}
Secondly, add Kotless DSL as a library to your application:
repositories {
jcenter()
}
dependencies {
implementation("io.kotless", "lang", "0.1.3")
//or for Ktor
//implementation("io.kotless", "ktor-lang", "0.1.3")
}
This gives you access to Kotless DSL annotations in your code and sets up Lambda dispatcher inside of your application.
If you don't have an AWS account -- stop here. Now you can use local
task to run the application locally and debug it.
If you have an AWS account and want to perform the real deployment -- let's set up everything for it! It's rather simple:
kotless {
config {
bucket = "kotless.s3.example.com"
terraform {
profile = "example"
region = "us-east-1"
}
}
webapp {
//Optional parameter, by default technical name will be generated
route53 = Route53("kotless", "example.com")
//configuration of lambda created
lambda {
//needed only for Kotless DSL
kotless {
//Define packages in which scan for routes should be performed
//By default, will be set to gradle module group
packages = setOf("io.kotless.examples")
}
}
}
}
Here we set up the config of Kotless itself:
- the bucket, which will be used to store lambdas and configs;
- Terraform configuration with the name of the profile to access AWS.
Then we set up a specific application to deploy:
- Route53 alias for the resulting application (you need to pre-create ACM certificate for the DNS record);
- in case of Kotless DSL — a set of packages that should be scanned for Kotless DSL annotations.
And that's the whole setup!
Now you can create you first serverless application with Kotless DSL:
@Get("/")
fun gettingStartedPage() = html {
body {
+"Hello world!"
}
}
Or with Ktor:
class Server : Kotless() {
override fun prepare(app: Application) {
app.routing {
get("/") {
call.respondText { "Hello World!" }
}
}
}
}
HTML builder provided by implementation("org.jetbrains.kotlinx", "kotlinx-html-jvm", "0.6.11")
dependency.
Local start
Kotless application can start locally as an HTTP server. This functionality is supported for both Kotless and Ktor DSL.
Moreover, Kotless local start may spin up an AWS emulation. Just instantiate your AWS service client using override for Kotless local starts:
val client = AmazonDynamoDBClientBuilder.standard().withKotlessLocal(AwsResource.DynamoDB).build()
And enable it in Gradle:
kotless {
//<...>
extensions {
local {
//enable AWS emulation (disabled by default)
useAWSEmulation = true
}
}
}
During local run, LocalStack will be started and all clients will be pointed to its endpoint automatically.
Local start functionality does not require any access to cloud provider, so you may check how your application behaves without AWS account. Also, it gives you the possibility to debug your application locally from your IDE.
Advanced features
While Kotless can be used as a framework for a rapid creation of serverless applications, it has many more features covering different areas of application.
Including, but not limited to:
- Lambdas auto-warming — Kotless creates schedulers to execute warming sequences to never leave your lambdas cold.
It is possible to add various actions to the warming sequence via
@Warming
annotation; - Granular permissions — you can declare which permissions to which AWS resources are required for the code that calls the function via annotations on Kotlin functions. Permissions will be granted automatically.
- Static resources — Kotless will deploy files annotated with
@StaticResource
to S3 and create specified HTTP routes for them. - Scheduled events — Kotless sets up timers to execute
@Scheduled
jobs on schedule; - Terraform extensions — Kotless-generated code can be extended by custom Terraform code;
- Serialization and deserialization — Kotless will automatically deserialize parameters from an HTTP request into
function parameters and will serialize the result of the function as well. You can extend the number of supported
types of parameters by creating top-level
object
implementingConversionService
. It will be automatically added to the list of supported conversions.
Kotless is in active development, so we are currently working on extending this list with such features as:
- Support of other clouds — Kotless is based on a cloud-agnostic schema, so we are working on supporting other clouds.
- Support of multiplatform applications — Kotless will not use any platform-specific libraries to give you a choice of a Lambda runtime (JVM/JS/Native).
- Versioned deployment — Kotless will be able to deploy several versions of the application and maintain one of them as active.
- Implicit permissions granting — Kotless will be able to deduce permissions from AWS SDK function calls.
- Events handlers support — Kotless will generate events subscriptions for properly annotated events handlers.
Examples
Any explanation becomes much better with a proper example.
In the repository's examples
folder, you can find example projects built with Kotless:
kotless-site
— a site about Kotless written with Kotless DSL (site.kotless.io). This example demonstrates@StaticGet
and@Get
(static and dynamic routes), as well as Link API.kotless-shortener
— a simple URL shortener written with Kotless DSL (see the result at short.kotless.io). This example demonstrates@Get
(dynamic routes),@Scheduled
(scheduled lambdas), Permissions API (for DynamoDB access), and Terraform extensions.
Similar examples exist for Ktor DSL:
ktor-site
— a site about Kotless written with Ktor DSL (ktor.site.kotless.io). This example demonstratesstatic {...}
androuting {...}
.ktor-shortener
— a simple URL shortener written with Ktor DSL (see the result at ktor.short.kotless.io). This example demonstratesrouting { ... }
(dynamic routes), Permissions API (for DynamoDB access), and Terraform extensions.
Want to know more?
You may take a look at Wiki where the client documentation on Kotless is located.
Apart from that, Kotless code itself is widely documented, and you can take a look into its interfaces to get to know Kotless better.
You may ask questions and participate in discussions in #kotless
channel in KotlinLang slack.
Acknowledgements
Special thanks to:
- Alexandra Pavlova (aka sunalex) for our beautiful logo;
- Yaroslav Golubev for the help with documentation;
- Gregor Billing for the help with Gradle plugin and more.