Kotlin Serverless Framework
APACHE-2.0 License
Kotless stands for Kotlin serverless framework.
Its focus lies in reducing the routine of serverless deployment creation by generating it straight from the code of the application itself.
So, simply speaking, Kotless gives you one magic button to deploy your Web application as a serverless application on AWS and Azure!
Kotless consists of two main parts:
One of the key features of Kotless is its ability to embed into existing applications. Kotless makes super easy deployment of existing Spring and Ktor applications to AWS and Microsoft Azure serverless platforms.
Kotless uses Gradle to wrap around the existing building process and insert the deployment into it.
Consider using one of the latest versions of Gradle, starting with the 7.2 version.
Basically, if you already use Gradle, you only need to do two things.
Firstly, set up the Kotless Gradle plugin.
You will have to tell Gradle where to find the plugin by editing settings.gradle.kts
:
pluginManagement {
resolutionStrategy {
this.eachPlugin {
if (requested.id.id == "io.kotless") {
useModule("io.kotless:gradle:${this.requested.version}")
}
}
}
repositories {
maven(url = uri("https://packages.jetbrains.team/maven/p/ktls/maven"))
gradlePluginPortal()
mavenCentral()
}
}
And apply the plugin:
//Imports are necessary, for this example
import io.kotless.plugin.gradle.dsl.Webapp.Route53
import io.kotless.plugin.gradle.dsl.kotless
//Group may be used by Kotless DSL to reduce the number of introspected classes by package
//So, don't forget to set it
group = "org.example"
version = "0.1.0"
plugins {
//Version of Kotlin should be 1.3.72+
kotlin("jvm") version "1.5.31" apply true
id("io.kotless") version "0.2.0" apply true
}
Secondly, add Kotless DSL (or Ktor, or Spring Boot) as a library to your application:
repositories {
mavenCentral()
//Kotless repository
maven(url = uri("https://packages.jetbrains.team/maven/p/ktls/maven"))
}
dependencies {
implementation("io.kotless", "kotless-lang", "0.2.0")
implementation("io.kotless", "kotless-lang-aws", "0.2.0")
// if you want to deploy to Microsoft Azure, just replace -aws with -azure
// implementation("io.kotless", "ktor-lang-azure", "0.2.0")
//or for Ktor (Note, that `ktor-lang` depends on Ktor version 1.5.0)
//implementation("io.kotless", "ktor-lang", "0.2.0")
//implementation("io.kotless", "ktor-lang-aws", "0.2.0")
//implementation("io.kotless", "ktor-lang-azure", "0.2.0")
//or for Spring Boot (Note, that `spring-boot-lang` depends on Spring Boot version 2.3.0.RELEASE)
//implementation("io.kotless", "spring-boot-lang", "0.2.0")
//implementation("io.kotless", "spring-boot-lang-aws", "0.2.0")
//implementation("io.kotless", "spring-boot-lang-azure", "0.2.0")
}
Please note that if you use Ktor or Spring Boot you will need to replace existing in your project
dependency with a special Kotless *-lang
dependency. Also, after that you will need to align
version of dependent libraries (like Spring Security) with version bundled in *-lang
(see this paragraph)
This gives you access to DSL interfaces in your code and sets up a Lambda dispatcher inside your application.
Depending on a use case, you may want to deploy application either in an AWS or Microsoft Azure.
Note, that if you even don't have a cloud account, you can still use Kotless locally to run and
debug your application -- just use local
Gradle task.
If you don't have an AWS account, you can create it following simple instruction by Hadi Hariri.
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 {
aws {
storage {
bucket = "kotless.s3.example.com"
}
profile = "example"
region = "eu-west-1"
}
}
webapp {
dns("kotless", "example.com")
}
}
Here we set up the config of Kotless itself:
Then we set up a specific application to deploy:
And that's the whole setup!
Deployment to Microsoft Azure is also pretty straightforward and simple:
kotless {
config {
azure {
storage {
storageAccount = "your-storage-account"
container = "container-which-kotless-would-use"
}
terraform {
backend {
resourceGroup = "your-resource-group"
}
}
}
}
webapp {
dns("kotless", "example.com")
}
}
Here we set up the config of Kotless itself:
Then we set up a specific application to deploy:
And that's the whole setup!
Now you can create your first serverless application with Kotless DSL:
@Get("/")
fun main() = "Hello world!"
Or with Ktor:
class Server : Kotless() {
override fun prepare(app: Application) {
app.routing {
get("/") {
call.respondText { "Hello World!" }
}
}
}
}
Or with Spring Boot:
@SpringBootApplication
open class Application : Kotless() {
override val bootKlass: KClass<*> = this::class
}
@RestController
object Pages {
@GetMapping("/")
fun main() = "Hello World!"
}
Kotless-based applications can start locally as an HTTP server. This functionality is supported by all DSLs.
Moreover, Kotless local start may spin up an AWS emulation (docker required). 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 {
//enables AWS emulation (disabled by default)
useAWSEmulation = true
}
}
}
During the 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 an AWS account. Also, it gives you the possibility to debug your application locally from your IDE.
Kotless is able to deploy existing Spring Boot or Ktor application to AWS serverless platform. To do it, you'll need to set up a plugin and replace existing dependency with the appropriate Kotless DSL.
For Ktor, you should replace existing engine (
e.g. implementation("io.ktor", "ktor-server-netty", "1.5.0")
)
with implementation("io.kotless", "ktor-lang", "0.1.6")
. Note that this dependency bundles Ktor of
version
1.5.0
, so you may need to upgrade other Ktor libraries (like ktor-html-builder
) to this version.
For Spring Boot you should replace the starter you use (
e.g. implementation("org.springframework.boot", "spring-boot-starter-web", "2.3.0.RELASE)
)
with implementation("io.kotless", "spring-boot-lang", "0.1.6")
. Note that this dependency bundles
Spring Boot of version 2.4.2
, so you also may need to upgrade other Spring Boot libraries to this
version.
Once it is done, you may hit deploy
task and make your application serverless. Note, that you will
still be able to run application locally via local
Gradle task.
While Kotless can be used as a framework for the rapid creation of serverless applications, it has many more features covering different areas of application.
Including, but not limited to:
@Scheduled
jobs on schedule;Kotless is in active development, so we are currently working on extending this list with such features as:
Any explanation becomes much better with a proper example.
In the repository's examples
folder, you can find example projects built with Kotless DSL:
kotless/site
— a site about Kotless written with Kotless@StaticGet
@Get
(static and dynamic routes) usage, as well as Link API.kotless/shortener
— a simple URL shortener written with Kotless@Get
(@Scheduled
(scheduled lambdas), Permissions API (for DynamoDB access), andSimilar examples exist for Ktor:
ktor/site
— a site about Kotless written withstatic {...}
routing {...}
usage.ktor/shortener
— a simple URL shortener written withrouting { ... }
(dynamic routes), Permissions API (for DynamoDB access), andAnd for Spring Boot:
spring/site
— a site about Kotless written with Spring@RestController
.spring/shortener
— a simple URL shortener written with Spring@RestController
(dynamic routes), Permissions API (for DynamoDB access), and TerraformYou may take a look at Wiki where the client documentation on Kotless is located.
Apart from that, the 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 on #kotless
channel
in KotlinLang slack.
Special thanks to: