Skip to content

Commit

Permalink
docs: update README.md for tighter messaging on current kurtosis (#2155)
Browse files Browse the repository at this point in the history
## Description:
Emphasizing differentiation over dcompose and helm at the feature level

## Is this change user facing?
YES
  • Loading branch information
galenmarchetti authored Feb 13, 2024
1 parent cea7951 commit 5b606b5
Showing 1 changed file with 21 additions and 48 deletions.
69 changes: 21 additions & 48 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,26 +5,33 @@

What is Kurtosis?
=================
[Kurtosis](https://www.kurtosis.com) handles the complexity of your backend infrastructure so you can focus on building. Think Vercel-like experience for your backend. We’re actively learning more on how best to make that happen. If you are on board with that mission, consider giving us a star ⭐!

Have you ever tried to build on top of a colleague's work, or contribute to an open source project, just to get stuck on the first steps of spinning up a stack to play with? [Kurtosis](https://www.kurtosis.com) handles the complexity of spinning up ephemeral dev or test stacks so you can focus on developing, not configuring.

Kurtosis is formed of:
- A Pythonic language for defining your application (Starlark)
- A packaging system for sharing and running your distributed application
- A runtime that makes your package Just Work, locally or on the cloud
- A set of tools to ease common distributed app development needs (e.g. a log aggregator to ease log-diving, automatic port-forwarding to ease connectivity, a `kurtosis service shell` command to ease container filesystem exploration, etc.)
- A packaging system for distributing backend stack definitions, which can run on docker or on kubernetes
- A runtime with a per-stack file management system for reproducibly initializing the state of your stack
- A set of tools to enable devs to interact with their stacks, like they do on docker or k8s

Why should I use Kurtosis?
How is Kurtosis different than Docker Compose or Helm?
==========================
Kurtosis shines when creating, working with, and destroying self-contained distributed application environments. Currently, our users report this to be most useful when:

- You're developing on your application and you need to rapidly iterate on it
- You want to try someone's containerized service or distributed application without setting up an environment, dependencies, etc.
- You want to spin up your distributed application in ephemeral environments as part of your integration tests
- You want to ad-hoc test your application on a big cloud cluster
- You're the author of a containerized service or distributed application and you want to give your users a one-liner to try it
- You want to get an instance of your application running in the cloud without provisioning or administering a Kubernetes cluster
Kurtosis operates at a level higher than Docker Compose or Helm, and produces stacks running on either of the underlying engines (the Docker engine, or Kubernetes).
Because of this additional layer of abstraction, we are able to introduce several features to improve the experience of spinning up ephemeral stacks:

- A per-stack file management system that enables portable state initialization for dev or test stacks
- Stack-level parameterizability; users have a powerful and flexible way (beyond messing with env vars) to affect modifications in their stacks
- First-class plug-and-play composability; it's expected for users to import stack definitions into larger stacks, and this experience is optimized
- The ability to get all of the above, but running over _either_ the docker engine or k8s, at your election

Why use Kurtosis?
=========================

If you're in web3, we have even more specific web3 usecases [here](https://web3.kurtosis.com).
Kurtosis is best for:

- Reusing the logic in your stack definitions for all of: local dev, scheduled testing in CI, and ad-hoc larger-scale testing on k8s clusters
- Giving other devs a way to spin up your application, and commonly used variations of it, with one-liners, via Kurtosis' packaging and parameterization systems
- Handling complex setup logic in your backend stack, like passing arbitrary data between services as they start up, and enforcing arbitrary wait conditions

Check out an introductory demo video here:

Expand Down Expand Up @@ -66,40 +73,6 @@ To see where we're going with the product, check out the roadmap [here](https://

Got more questions? Drop them in our [Github Discussions](https://github.com/kurtosis-tech/kurtosis/discussions/new?category=q-a) where we, or other community members, can help answer.

Why Kurtosis over Compose, Helm, or Terraform?
==============================================
These tools have been around for over a decade, yet most developers still struggle to build distributed applications. Why? In a sentence: building distributed applications is hard, and these tools still haven't made it easy enough for the average developer.

Some of our observations:

- No tool works across the whole software lifecycle: Compose is oriented around quick local environments rather than Prod environments, while Helm and Terraform are the opposite. This often means a dedicated DevOps team handles Prod deployment, leading to the same "throw it across the wall" problem the DevOps movement was founded around.
- Compose, Helm, and Terraform use fully declarative paradigms, making difficult the sequential "first this, then this" logic necessary for many prototyping workflows.
- The inherently declarative nature of all three make [DRY](https://en.wikipedia.org/wiki/Don%27t_repeat_yourself) difficult, leading to frequent copy-pasting.
- All three tend to leave resources hanging around that the developer needs to manually clean up.
- Compose and Helm favor "run it and see what happens" over validation & error-checking, resulting in debugging time and longer dev cycles.
- A significant percentage of developers don't understand how Docker works, and [most don't understand Kubernetes or Terraform][stackoverflow-2022-developer-survey--other-tools].

Here's what our users tell us they like about Kurtosis:

- **It's understandable:** you write code in Python syntax, and you get your distributed application the other side. Variables and functions keep your code DRY.
- **It's portable:** your application runs with a one-liner independent of where you run it. You can build your application on your local Docker, and in seconds get the same thing on your friend's laptop or a Kubernetes cluster in the cloud.
- **It can handle sequential dependencies:** for example, "first generate these files, then use them when starting a service".
- **It's reliable and reproducible:** Kurtosis started as a testing tool and is built to be safe: deterministic execution order, validation to catch errors before runtime, built-in support for inter-service dependencies and readiness checks, etc. Your distributed app should spin up the same way, every time.
- **It abstracts away complexity while being configurable:** instantiating a distributed application is as simple as calling its function with the parameters you want. For example, instantiating a Postgres server with modified username and password:

On the CLI...
```bash
kurtosis run github.com/kurtosis-tech/postgres-package '{"user": "bobmarley", "password": "buffalosoldier"}'
```

Inside an environment definition...
```python
postgres = import_module("github.com/kurtosis-tech/postgres-package/main.star")

def run(plan):
postgres.run(plan, user = "bobmarley", password = "buffalosoldier")
```

Contributing to Kurtosis
========================

Expand Down

0 comments on commit 5b606b5

Please sign in to comment.