Skip to content
This repository has been archived by the owner on Jan 9, 2025. It is now read-only.

Commit

Permalink
chore: Update README.md (#160)
Browse files Browse the repository at this point in the history
Readme rework

---------

Signed-off-by: tc87 <[email protected]>
  • Loading branch information
tc87 authored Aug 16, 2024
1 parent 5bfd902 commit 56ddadc
Showing 1 changed file with 28 additions and 63 deletions.
91 changes: 28 additions & 63 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,32 +4,37 @@

![Kardi B](https://kardinal.dev/_next/static/media/kardinal-orange.65ea335b.png)

## Guide

1. [What is Kardinal?](https://github.com/kurtosis-tech/kardinal/?tab=readme-ov-file#what-is-kardinal)
2. [Playground](https://github.com/kurtosis-tech/kardinal/?tab=readme-ov-file#try-it-out-in-a-playground)
3. [Quick start](https://github.com/kurtosis-tech/kardinal/?tab=readme-ov-file#quick-start-with-a-demo-application)
4. [Helpful links](https://github.com/kurtosis-tech/kardinal/?tab=readme-ov-file#helpful-links)

## What is Kardinal?

Kardinal is a framework for creating extremely lightweight ephemeral development environments within a shared Kubernetes cluster.

In Kardinal, an environment is called a "[flow](https://kardinal.dev/docs/concepts/flows)" because it represents a path that a request takes through the cluster. Versions of services that are under development are deployed on-demand, and then shared across all development work that depends on that version. When you create a flow to test a feature, Kardinal deploys only the set of services that are changing for that feature. Then, any requests related to testing that feature are routed to those versions.
Kardinal is a framework for creating extremely lightweight ephemeral development environments within a shared Kubernetes cluster. Read more about Kardinal in our [docs](https://kardinal.dev/docs).

As your team onboards to Kardinal, you will be able to create flows with escalating levels of configurability:
### Why choose Kardinal?
- **Ephemeral Environments**: Spin up a new environment exactly when you need it, and just as quickly spin it down when you’re done.
- **Minimal Resource Usage**: Only deploy the services you’re actively working on. Kardinal takes care of the rest, so you don’t waste resources.
- **Flexible Flow Types**: Whether you need to test a single service or an entire application, Kardinal has you covered:
- Single-Service Flows: Perfect for when you’re tweaking just one service.
- Multi-Service Flows: Ideal for when your feature involves multiple services.
- State-Isolated Flows: Great for features that need their own databases or caches.
- Full Application Flows: For those times when you need end-to-end testing with full isolation.
- **Cost Savings**: Kardinal can help you save big by avoiding unnecessary resource duplication. It’s a game-changer for teams looking to cut costs.

1. **Single-service flows**: deploy a single service to test a new version of a service, sharing application state with all other flows
2. **Multi-service flows**: deploy a set of services together to test a larger feature change involving multiple services, sharing application state with all other flows
3. **State-isolated flows**: deploy a set of services together with new, isolated state (dbs, caches, queues) to test database migrations or other state-layer changes
4. **Full application flows**: deploy an independent, full application with its own state layer for completely isolated end-to-end testing
## Installation

Even with isolated state and e2e full application flows, Kardinal will still deploy the absolute minimum resources necessary to test your changes. Isolation is done at the level of the request route, not by duplicating services in your cluster unnecessarily.

To see how Kardinal compares to other tools, and to get an idea of how would fit into your workflow, check out our [comparisons to alternatives](https://kardinal.dev/docs/references/comparisons).
### **Step 1: Install Kardinal**
To install Kardinal, run the following command:
```
curl get.kardinal.dev -sL | sh
```
### **Step 2: Set up a development Kubernetes cluster**

Read more about Kardinal in our [docs](https://kardinal.dev/docs).
All you need is a Kubernetes cluster with Istio enabled, and kubectl installed on your machine, pointing to your cluster. If you need help with this, read more [here](https://kardinal.dev/docs/getting-started/install)

### **Step 3: Deploy the Kardinal Manager to your cluster**
Make sure that kubectl is pointing to your cluster, and then run the following command:
```
kardinal manager deploy kloud-kontrol
```
Once installed check out our docs on [creating your first flow](https://kardinal.dev/docs/getting-started/own-app).
## Try it out in a Playground

We have a playground that runs in Github Codespaces so you can try Kardinal right now without installing anything. Click below to open a Codespace with the playground. The default settings for the Codespace will work just fine.
Expand All @@ -38,45 +43,9 @@ We have a playground that runs in Github Codespaces so you can try Kardinal righ

## Quick start with a demo application

If you want to get started with your own application, check out [our docs](https://kardinal.dev/docs/getting-started/install).

Otherwise, continue in this section to run Kardinal with a demo application to see how it works before trying it on your own.

### Prerequisites

Before getting started make sure you have the following installed:

- [Docker](https://docs.docker.com/get-docker/)
- [Minikube](https://minikube.sigs.k8s.io/docs/start/?arch=%2Fmacos%2Fx86-64%2Fstable%2Fbinary+download)
- [Kubectl](https://kubernetes.io/docs/tasks/tools/)
- [Istio](https://istio.io/latest/docs/setup/getting-started/)

The last prerequisite is you'll need to run Minikube with Istio enabled. To do this, run the following:

```bash
minikube start --driver=docker --cpus=10 --memory 8192 --disk-size 32g;
minikube addons enable ingress;
minikube addons enable metrics-server;
istioctl install --set profile=default -y;
```

### Step 1: Install Kardinal

To install Kardinal, run the following command:

```bash
curl get.kardinal.dev -sL | sh
```
### Step 1: Deploy the demo app

### Step 2: Deploy the Kardinal Manager to your cluster

```bash
kardinal manager deploy kloud-kontrol
```

### Step 3: Deploy the demo app

Since this guide is using minikube, you'll need to set up the minikube tunnel to access the frontend of the application you're about to deploy:
Once you have Kardinal installed, you can run through the following demo. For step 1, since this guide is using minikube, you'll need to set up the minikube tunnel to access the frontend of the application you're about to deploy:

```bash
minikube tunnel
Expand All @@ -103,7 +72,7 @@ kardinal dashboard

and click on the "Traffic configuration" sidebar item.

### Step 4: Create a lightweight development environment (dev flow)
### Step 2: Create a lightweight development environment (dev flow)

Create a new flow by specifying a service name and a container image.

Expand All @@ -125,7 +94,7 @@ kardinal dashboard

and click on the "Traffic configuration" sidebar item.

### Step 5: Clean up your development flow
### Step 3: Clean up your development flow

When you're done with your development flow, you can delete it by running:

Expand All @@ -141,10 +110,6 @@ kardinal flow ls

Once you've deleted the flow, you can verify that the resources have been cleaned up by going to the dashboard again.

### Ready to test on your own application?

Check out [our docs](https://kardinal.dev/docs/getting-started/install) to learn how.

## Helpful links

- Explore our [docs](https://kardinal.dev/docs) to learn more about how Kardinal works.
Expand Down

0 comments on commit 56ddadc

Please sign in to comment.