Skip to content

Commit

Permalink
Updated readme
Browse files Browse the repository at this point in the history
  • Loading branch information
@pavangudiwada
pavangudiwada committed Jun 23, 2023
1 parent 61de25a commit f82f56f
Showing 1 changed file with 80 additions and 76 deletions.
156 changes: 80 additions & 76 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,21 +10,23 @@
<!-- PROJECT LOGO -->
<br />
<div align="center">
<a href="https://github.com/robusta-dev/krr">
<img src="images/logo.png" alt="Logo" width="320" height="320">
</a>
<h3 align="center">Robusta KRR</h3>
<p align="center">
Prometheus-based Kubernetes Resource Recommendations
<br />
<a href="#getting-started"><strong>Usage docs »</strong></a>
<br />
<a href="#installation"><strong>Installation</strong></a>
.
<a href="#usage"><strong>Usage</strong></a>
·
<a href="#how-it-works"><strong>How it works</strong></a>
.
<a href="#slack-integration"><strong>Slack Integration</strong></a>
<br />
<a href="https://github.com/robusta-dev/krr/issues">Report Bug</a>
·
<a href="https://github.com/robusta-dev/krr/issues">Request Feature</a>
·
<a href="https://robustacommunity.slack.com/archives/C054QUA4NHE">Slack Channel</a>
<a href="#support">Support</a>
</p>
</div>
<!-- TABLE OF CONTENTS -->
Expand Down Expand Up @@ -62,10 +64,10 @@ Robusta KRR (Kubernetes Resource Recommender) is a CLI tool for optimizing resou

### Features

- No Agent Required: Robusta KRR is a CLI tool that runs on your local machine. It does not require running Pods in your cluster. (But it can optionally be run in-cluster for weekly Slack reports.)
- Prometheus Integration: Gather resource usage data using built-in Prometheus queries, with support for custom queries coming soon.
- Extensible Strategies: Easily create and use your own strategies for calculating resource recommendations.
- Future Support: Upcoming versions will support custom resources (e.g. GPUs) and custom metrics.
- **No Agent Required**: Robusta KRR is a CLI tool that runs on your local machine. It does not require running Pods in your cluster. (But it can optionally be run in-cluster for weekly [Slack reports](#slack-integration).)
- **Prometheus Integration**: Gather resource usage data using built-in Prometheus queries, with support for custom queries coming soon.
- **Extensible Strategies**: Easily create and use your own strategies for calculating resource recommendations.
- **Future Support**: Upcoming versions will support custom resources (e.g. GPUs) and custom metrics.

### Resource Allocation Statistics

Expand All @@ -76,9 +78,66 @@ According to a recent [Sysdig study](https://sysdig.com/blog/millions-wasted-kub

By right-sizing your containers with KRR, you can save an average of 69% on cloud costs.

### How it works
Read more about [how KRR works](#how-it-works) and [KRR vs Kubernetes VPA](#difference-with-kubernetes-vpa)

<!-- GETTING STARTED -->

## Installation

### With brew (MacOS/Linux):

1. Add our tap:
```sh
brew tap robusta-dev/homebrew-krr
```

2. Install KRR:
```sh
brew install krr
```

3. Check that installation was successfull (First launch might take a little longer):
```sh
krr --help
```

### On Windows:

You can install using brew (see above) on [WSL2](https://docs.brew.sh/Homebrew-on-Linux), or install manually:

#### Manual Installation

1. Make sure you have [Python 3.9](https://www.python.org/downloads/) (or greater) installed
2. Clone the repo:

```sh
git clone https://github.com/robusta-dev/krr
```

3. Navigate to the project root directory (`cd ./krr`)
4. Install requirements:

```sh
pip install -r requirements.txt
```

5. Run the tool:

```sh
python krr.py --help
```

Notice that using source code requires you to run as a python script, when installing with brew allows to run `krr`.
All above examples show running command as `krr ...`, replace it with `python krr.py ...` if you are using a manual installation.

[To use krr with Google Cloud Managed Service for Prometheus, some additional configuration is necessary.](./docs/google-cloud-managed-service-for-prometheus.md)

<p align="right">(<a href="#readme-top">back to top</a>)</p>


#### Metrics Gathering
## How it works

### Metrics Gathering

Robusta KRR uses the following Prometheus queries to gather usage data:

Expand All @@ -96,19 +155,19 @@ Robusta KRR uses the following Prometheus queries to gather usage data:

[_Need to customize the metrics? Tell us and we'll add support._](https://github.com/robusta-dev/krr/issues/new)

#### Algorithm
### Algorithm

By default, we use a _simple_ strategy to calculate resource recommendations. It is calculated as follows (_The exact numbers can be customized in CLI arguments_):

- For CPU, we set a request at the 99th percentile with no limit. Meaning, in 99% of the cases, your CPU request will be sufficient. For the remaining 1%, we set no limit. This means your pod can burst and use any CPU available on the node - e.g. CPU that other pods requested but aren’t using right now.

- For memory, we take the maximum value over the past week and add a 5% buffer.

#### Prometheus connection
### Prometheus connection

Find about how KRR tries to find the default prometheus to connect <a href="#prometheus-auto-discovery">here</a>.

### Difference with Kubernetes VPA
## Difference with Kubernetes VPA

| Feature 🛠️ | Robusta KRR 🚀 | Kubernetes VPA 🌐 |
| --------------------------- | ---------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- |
Expand All @@ -123,6 +182,8 @@ Find about how KRR tries to find the default prometheus to connect <a href="#pro
| Explainability 📖 | 🔄 Support in future versions (Robusta will send you additional graphs) | ❌ Not supported |
| Autoscaling 🔀 | 🔄 Support in future versions | ✅ Automatic application of recommendations |



### Robusta UI integration

If you are using [Robusta SaaS](https://platform.robusta.dev/), then KRR is integrated starting from [v0.10.15](https://github.com/robusta-dev/robusta/releases/tag/0.10.15). You can view all your recommendations (previous ones also), filter and sort them by either cluster, namespace or name.
Expand Down Expand Up @@ -167,62 +228,6 @@ customPlaybooks:

<p align="right">(<a href="#readme-top">back to top</a>)</p>

<!-- GETTING STARTED -->

## Getting Started

### Installation

#### Installing with brew (MacOS/Linux):

1. Add our tap:
```sh
brew tap robusta-dev/homebrew-krr
```

2. Install KRR:
```sh
brew install krr
```

3. Check that installation was successfull (First launch might take a little longer):
```sh
krr --help
```

#### Installing on Windows:

We will use chocolatey for easier installing on Windows, but currently it is not yet supported.
If you want to still run on Windows, you can do that by installing using brew (see above) on [WSL2](https://docs.brew.sh/Homebrew-on-Linux), or installing manually:

#### Manual

1. Make sure you have [Python 3.9](https://www.python.org/downloads/) (or greater) installed
2. Clone the repo:

```sh
git clone https://github.com/robusta-dev/krr
```

3. Navigate to the project root directory (`cd ./krr`)
4. Install requirements:

```sh
pip install -r requirements.txt
```

5. Run the tool:

```sh
python krr.py --help
```

Notice that using source code requires you to run as a python script, when installing with brew allows to run `krr`.
All above examples show running command as `krr ...`, replace it with `python krr.py ...` if you are using a manual installation.

[To use krr with Google Cloud Managed Service for Prometheus, some additional configuration is necessary.](./docs/google-cloud-managed-service-for-prometheus.md)

<p align="right">(<a href="#readme-top">back to top</a>)</p>

<!-- USAGE EXAMPLES -->

Expand Down Expand Up @@ -365,7 +370,7 @@ krr simple -f json

## Creating a Custom Strategy/Formatter

Look into the `examples` directory for examples on how to create a custom strategy/formatter.
Look into the [examples](https://github.com/robusta-dev/krr/tree/main/examples) directory for examples on how to create a custom strategy/formatter.

<p align="right">(<a href="#readme-top">back to top</a>)</p>

Expand Down Expand Up @@ -419,17 +424,16 @@ Don't forget to give the project a star! Thanks again!

## License

Distributed under the MIT License. See `LICENSE.txt` for more information.
Distributed under the MIT License. See [LICENSE.txt](https://github.com/robusta-dev/krr/blob/main/LICENSE) for more information.

<p align="right">(<a href="#readme-top">back to top</a>)</p>

<!-- CONTACT -->

## Contact
## Support

If you have any questions, feel free to contact support@robusta.dev
If you have any questions, feel free to contact **support@robusta.dev** or message us on [robustacommunity.slack.com](https://bit.ly/robusta-slack)

Project Link: [https://github.com/robusta-dev/krr](https://github.com/robusta-dev/krr)

<p align="right">(<a href="#readme-top">back to top</a>)</p>

Expand Down

0 comments on commit f82f56f

Please sign in to comment.