From e457a0f0f703e1a89e7f817e6c3ed66bbddfc7fd Mon Sep 17 00:00:00 2001 From: Aaron Torres Date: Fri, 16 Aug 2024 13:36:11 -0500 Subject: [PATCH] updated readme for review --- README.md | 306 +++++++++++++++++------------------------------------- 1 file changed, 96 insertions(+), 210 deletions(-) diff --git a/README.md b/README.md index cacfe089f..55a318607 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@

- develop for local, deploy for the cloud + Terraform/CDK alternative designed for developers
@@ -10,221 +10,107 @@ [![formatting badge](https://github.com/klothoplatform/klotho/actions/workflows/prettier.yaml/badge.svg)](https://github.com/klothoplatform/klotho/actions/workflows/prettier.yaml) [![linter badge](https://github.com/klothoplatform/klotho/actions/workflows/lint.yaml/badge.svg)](https://github.com/klothoplatform/klotho/actions/workflows/lint.yaml) [![govulncheck](https://github.com/CloudCompilers/klotho/actions/workflows/govulncheck.yaml/badge.svg)](https://github.com/CloudCompilers/klotho/actions/workflows/govulncheck.yaml) -[![Go Coverage](https://github.com/klothoplatform/klotho/wiki/coverage.svg)](https://raw.githack.com/wiki/klothoplatform/klotho/coverage.html) - -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?](#why) -- [Adaptive Architectures](#adaptive-architectures) -- [Infrastructure-from-Code](#infrastructure-from-code) -- [Installation](#installation) -- [IDE Plugins & Extensions](#ide-plugins--extensions) -- [Getting Started](#getting-started) -- [Example usage](#example-usage) -- [Additional Resources](#additional-resources) -- [Language Support](#language-support) -- [Cloud Providers](#cloud-providers) -- [Developing](#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 Architectures](https://www.youtube.com/watch?v=GHt3FAEDfII&t=40392s). - -![image](https://user-images.githubusercontent.com/96867907/213884373-6b33a3e8-c00b-4c86-91c4-f89220f79ba5.png) - -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](https://klo.dev/) 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 to 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](https://klo.dev/docs/download-klotho) for additional installation options): - -Mac: - -```sh -brew install klothoplatform/tap/klotho -``` - -Linux/WSL2: - -```sh -curl -fsSL "https://github.com/klothoplatform/klotho/releases/latest/download/klotho_linux_amd64" -o klotho -chmod +x klotho +[![Go Coverage](https://github.com/klothoplatform/klotho/wiki/coverage.svg)](https://raw.githack.com/wiki/klothoplatform/klotho/coverage.html) +[![Latest Release](https://img.shields.io/github/v/release/klothoplatform/klotho)](https://github.com/klothoplatform/klotho/releases) +[![License](https://img.shields.io/github/license/klothoplatform/klotho)](https://github.com/klothoplatform/klotho/blob/main/LICENSE) + +## What is Klotho? +Klotho is a developer-centric cloud infra-as-code deployment tool with high level constructs. It lets you think in terms of containers, functions, APIs and databases and combining them freely. + +### Example Klotho infra.py +
+infra.py + +```python +import os +from pathlib import Path + +import klotho +import klotho.aws as aws + +# Create the Application instance +app = klotho.Application( + "my-sample-app", + project="my-project", + environment="default", + default_region="us-west-2", +) + +dir = Path(__file__).parent.absolute() + +# Create a dynamodb instance with 2 indexed attributes +dynamodb = aws.DynamoDB( + "my-dynamodb", + attributes=[ + {"Name": "id", "Type": "S"}, + {"Name": "data", "Type": "S"}, + ], + hash_key="id", + range_key="data" +) + +# Create a lambda function that reads in code and deploys it as a zip file +my_function = aws.Function( + "my-function", + handler="handler.handler", + runtime="python3.12", + code=str(dir), +) + +# Bind the dynamodb instance to the lambda function +my_function.bind(dynamodb) + +# Create an ECS container +my_container = aws.Container( + "my-container", + dockerfile=str(dir / "container" / "Dockerfile"), + context=str(dir), +) + +# Create a Postgres instance with plain text password +my_postgres = aws.Postgres( + "my-postgres", + username="admin", + password="password123!", + database="mydb", +) + +# Bind the postgres instance to the container +my_container.bind(my_postgres) + +# Create an API Gateway instance +api = aws.Api("my-api") + +# Bind the lambda function to the API Gateway on the /function route +api.route( + routes: [ + RouteArgs(path="/function", method="ANY") + ], my_function +) + +# Bind the container to the API Gateway on the /container route +api.route( + routes: [ + RouteArgs(path="/container", method="ANY") + ], my_container +) ``` - -## IDE Plugins & Extensions - -Get syntax highlighting and snippets for Klotho annotations in your favorite IDE. - -- [Visual Studio Code](https://github.com/klothoplatform/Klotho-vscode) -- Intellij IDEA (coming soon) +
## Getting Started +To get started with Klotho, visit our [documentation](https://klo.dev/docs-k2/) and follow the guides to quickly set up your environment. -The quickest way to get started is with the getting started tutorial for [Javascript/Typescript](https://klo.dev/docs/tutorials/your_first_klotho_app), [Python](https://klo.dev/docs/tutorials/your_first_klotho_app_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](https://github.com/KlothoPlatform/sample-apps/tree/main/js-my-first-app) app: - -```sh -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: - -```sh -klotho --login -``` - -### Compile with Klotho - -Now compile the application for AWS by running `klotho` and passing `--provider aws` as an argument on the command line. - -```sh -klotho . --app my-first-app --provider aws -``` - -Will result in: - -```sh -██╗ ██╗██╗ ██████╗ ████████╗██╗ ██╗ ██████╗ -██║ ██╔╝██║ ██╔═══██╗╚══██╔══╝██║ ██║██╔═══██╗ -█████╔╝ ██║ ██║ ██║ ██║ ███████║██║ ██║ -██╔═██╗ ██║ ██║ ██║ ██║ ██╔══██║██║ ██║ -██║ ██╗███████╗╚██████╔╝ ██║ ██║ ██║╚██████╔╝ -╚═╝ ╚═╝╚══════╝ ╚═════╝ ╚═╝ ╚═╝ ╚═╝ ╚═════╝ - -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](https://aws.amazon.com/lambda/)) - The main Lambda function serves the Express app defined in js-my-first-app using a Lambda-compatible interface. -- **pet-api** ([API Gateway](https://aws.amazon.com/api-gateway/)) - The pet-api API gateway is used to expose the Express routes defined in the main Lambda function. -- **petsByOwner** ([DynamoDB Table](https://aws.amazon.com/dynamodb/)) - The petsByOwner DynamoDB table is used by the main Lambda function to store the relationships between pets and their owners. - -[Continue reading the tutorial](https://klo.dev/docs/tutorials/your_first_klotho_app) - -## Additional Resources - -Here are some links to additional resources: - -- [Documentation](https://klo.dev/docs) -- Case Studies: [Amihan Entertainment](https://klo.dev/case-study-amihan-entertainment/), Remedy -- [Blog](https://klo.dev/blog/) -- Podcasts: [How to Reduce Cloud Development Complexity](https://www.devopsparadox.com/episodes/how-to-reduce-cloud-development-complexity-169/) - -## Language Support - -### Supported - -These languages support the majority of capabilities and a wide variety of code styles. - -![Languages](https://skillicons.dev/icons?i=ts,js,python) - -### Early Access - -These languages support only a minority of capabilities and/or small subset of code styles. - -![Languages](https://skillicons.dev/icons?i=go) - -### In-development - -These languages are not yet supported but are in design and development - -![Languages](https://skillicons.dev/icons?i=cs,java) - -## Cloud Providers - -### Supported - -These providers support the majority of capabilities and languages. - -![Cloud providers](https://skillicons.dev/icons?i=aws) - -### In-development - -These providers are not yet supported but are in design and development +## Example Projects +Check out some [example projects](https://github.com/klothoplatform/k2-sample-apps) built using Klotho. -![Cloud providers](https://skillicons.dev/icons?i=gcp,azure) +## Community and Support +Join our community of developers and get involved in shaping the future of Klotho: -[![Twitter](https://img.shields.io/badge/Twitter-%231DA1F2.svg?style=for-the-badge&logo=Twitter&logoColor=white)](https://twitter.com/GetKlotho) [![LinkedIn](https://img.shields.io/badge/linkedin-%230077B5.svg?style=for-the-badge&logo=linkedin&logoColor=white)](https://www.linkedin.com/company/klothoplatform/) -[![Discord](https://img.shields.io/badge/%3CServer%3E-%237289DA.svg?style=for-the-badge&logo=discord&logoColor=white)](https://klo.dev/discordurl) +[![Discord](https://img.shields.io/badge/Klotho-%237289DA.svg?style=for-the-badge&logo=discord&logoColor=white)](https://klo.dev/discordurl) -## Developing +## Contributing +We welcome contributions from the community. Check out our [contributing guide](https://github.com/klothoplatform/klotho/blob/main/CONTRIBUTING.md) to learn how to get involved in Klotho’s development. -- 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](https://github.com/klothoplatform/klotho/actions/workflows/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](https://github.com/klothoplatform/klotho/actions/workflows/nightly-integ-tests.yaml). 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. - - The tests use a Klothoh login token that's stored as a GH Action secret within the `integ-test` environment. The login credentials are in BitWarden, under the "GitHub CI/CD login" entry. +## License +Klotho is licensed under the Apache 2.0 License. See the [LICENSE](https://github.com/klothoplatform/klotho/blob/main/LICENSE) file for more details.