From f82f56fb39e5110ba12a2aade7484ca7e6b8bf9b Mon Sep 17 00:00:00 2001 From: Pavan Gudiwada <25551553+pavangudiwada@users.noreply.github.com> Date: Fri, 23 Jun 2023 10:20:59 +0530 Subject: Updated readme --- README.md | 156 ++++++++++++++++++++++++++++++++------------------------------ 1 file changed, 80 insertions(+), 76 deletions(-) diff --git a/README.md b/README.md index 5587ed6..41fecdb 100644 --- a/README.md +++ b/README.md @@ -10,21 +10,23 @@
- - Logo -

Robusta KRR

Prometheus-based Kubernetes Resource Recommendations
- Usage docs ยป -
+ Installation + . + Usage + ยท + How it works + . + Slack Integration
Report Bug ยท Request Feature ยท - Slack Channel + Support

@@ -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 @@ -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) + + + +## 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) + +

(back to top)

+ -#### Metrics Gathering +## How it works + +### Metrics Gathering Robusta KRR uses the following Prometheus queries to gather usage data: @@ -96,7 +155,7 @@ 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_): @@ -104,11 +163,11 @@ By default, we use a _simple_ strategy to calculate resource recommendations. It - 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 here. -### Difference with Kubernetes VPA +## Difference with Kubernetes VPA | Feature ๐Ÿ› ๏ธ | Robusta KRR ๐Ÿš€ | Kubernetes VPA ๐ŸŒ | | --------------------------- | ---------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- | @@ -123,6 +182,8 @@ Find about how KRR tries to find the default prometheus to connect (back to top)

- - -## 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) - -

(back to top)

@@ -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.

(back to top)

@@ -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.

(back to top)

-## 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)

(back to top)

-- cgit v1.2.3