klotho

README

develop for local, deploy for the cloud

Klotho is an open source tool that transforms plain code into cloud native code.

Klotho allows you to quickly and reliably add cloud functionality to your application with minimal modification to your code. In most cases, this is just a handful of klotho annotations.

It adds 3 main in-code cloud capabilities:

• expose web APIs to the Internet
• persist multi-modal data into different types of databases
• static_unit package static assets and upload into a CDN for distribution

Table of Contents

• Why?
• Adaptive Architectures
• Infrastructure-from-Code
• Installation
• IDE Plugins & Extensions
• Getting Started
• Example usage
• Additional Resources
• Language Support
• Cloud Providers
• Developing

Why?

Klotho is designed to absorb the complexity of building cloud applications, enabling everyone in large-scale organizations and teams to hobbyist developers to write and operate cloud applications at a fraction of the effort.

Its design principles are an outcome of industry collaborations focused on mid-sized companies and fast growing startups.

Adaptive Architectures

Klotho builds on a new architecture called Adaptive Architecutes.

It's a superset of monoliths, microservices and serverless architectures, combining their benefits like a stellar developer experience, immediate productivity, scalability and autonomy of development and deployment as well as a spectrum of NoOps to FullOps. It also introduces a host of new capabilities that have been out of reach do to their implementation complexity.

Infrastructure-from-Code

Klotho is part of a new generation of cloud tools that implements Infrastructure-from-Code (IfC), a process to automatically create, configure and manage cloud resources from the existing software application's source code without having describe it explicitly.

By annotating the clients, SDKs or language constructs used in the code with Klotho capabilities, they are automatically created, updated and wired into the application.

Exposing a Python FastAPI to the internet with the Klotho klotho::expose capability. View for NodeJS, Go

Persisting Redis and TypeORM instances in NodeJS with the the Klotho klotho::persist capability. View for Python, Go (soon)

Klotho ensures that developers/operators are able to select and adapt the underlying technologies even after their initial setup.

Installation

To install the latest Klotho release, run the following (see full installation instructions for additional installation options):

Mac:

brew install klothoplatform/tap/klotho

Linux/WSL2:

curl -fsSL "https://github.com/klothoplatform/klotho/releases/latest/download/klotho_linux_amd64" -o klotho
chmod +x klotho

IDE Plugins & Extensions

Get syntax highlighting and snippets for Klotho annotations in your favorite IDE.

• Visual Studio Code
• Intellij IDEA (coming soon)

Getting Started

The quickest way to get started is with the getting started tutorial for Javascript/Typescript, Python and Go (soon).

Example usage

Clone the sample app

Clone our sample apps git repo and install the npm packages for the js-my-first-app app:

git clone https://github.com/KlothoPlatform/sample-apps.git
cd sample-apps/js-my-first-app
npm install

Logging in

First log in to Klotho. This shares telemetry data for compiler improvements:

klotho --login <email>

Compile with Klotho

Now compile the application for AWS by running klotho and passing --provider aws as an argument on the command line.

klotho . --app my-first-app --provider aws

Will result in:

██╗  ██╗██╗      ██████╗ ████████╗██╗  ██╗ ██████╗
██║ ██╔╝██║     ██╔═══██╗╚══██╔══╝██║  ██║██╔═══██╗
█████╔╝ ██║     ██║   ██║   ██║   ███████║██║   ██║
██╔═██╗ ██║     ██║   ██║   ██║   ██╔══██║██║   ██║
██║  ██╗███████╗╚██████╔╝   ██║   ██║  ██║╚██████╔╝
╚═╝  ╚═╝╚══════╝ ╚═════╝    ╚═╝   ╚═╝  ╚═╝ ╚═════╝

Adding resource input_file_dependencies:
Adding resource exec_unit:main
Found 2 route(s) on server 'app'
Adding resource gateway:pet-api
Adding resource persist_kv:petsByOwner
Adding resource topology:my-first-app
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.

Examine the result

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/my-first-app.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 Express app defined in js-my-first-app using a Lambda-compatible interface.
• pet-api (API Gateway) - The pet-api API gateway is used to expose the Express routes defined in the main Lambda function.
• petsByOwner (DynamoDB Table) - The petsByOwner DynamoDB table is used by the main Lambda function to store the relationships between pets and their owners.

Continue reading the tutorial

Additional Resources

Here are some links to additional resources:

• Documentation
• Case Studies: Amihan Entertainment, Remedy
• Blog
• Podcasts: How to Reduce Cloud Development Complexity

Language Support

Supported

These languages support the majority of capabilities and a wide variety of code styles.

Early Access

These languages support only a minority of capabilities and/or small subset of code styles.

In-development

These languages are not yet supported but are in design and development

Cloud Providers

Supported

These providers support the majority of capabilities and languages.

In-development

These providers are not yet supported but are in design and development

Developing

• build: go build ./...
• test: go test ./...
• run without separate build: go run ./cmd/klotho
• to run CI checks on git push:

  git config --local core.hooksPath .githooks/
  

• to run integration tests against a branch, navigate to the run-integ-tests.yaml action and click the "run workflow ▾" button. Select your branch, optionally fill in or change any of the parameters, and then click the "run workflow" button.
  • For security reasons, only authorized members of the team may do this. You can run integration tests on your own fork, providing your own AWS and Pulumi credentials.
  • Note that the nightly integration tests are a different workflow. Authorized members of the team can manually kick off a run of that workflow, but it doesn't take any inputs. The nightly integration tests workflow simply invokes the run-integ-tests.yaml workflow, so they effectively do the same thing.