diff --git a/README.md b/README.md index fb62b8f79..dcdbd4054 100644 --- a/README.md +++ b/README.md @@ -11,22 +11,6 @@ Crane (FinOps Crane) is a cloud native open source project which manages cloud resources on Kubernetes stack, it is inspired by FinOps concepts. -- [Crane: Cloud Resource Analytics and Economics](#crane-cloud-resource-analytics-and-economics) - - [Introduction](#introduction) - - [Features](#features) - - [TimeSeriesPrediction](#Time-series-prediction) - - [Effective HorizontalPodAutoscaler](#effective-horizontalpodautoscaler) - - [Analytics](#analytics) - - [QoS Ensurance](#qos-ensurance) - - [Repositories](#repositories) - - [Getting Started](#getting-started) - - [Installation](#installation) - - [Get your Kubernetes Cost Report](#get-your-kubernetes-cost-report) - - [Analytics and Recommendation](#analytics-and-recommendation) - - [RoadMap](#roadmap) - - [Contributing](#Contributing) - - [Code of Conduct](#Code-of-Conduct) - ## Introduction The goal of Crane is to provide a one-stop-shop project to help Kubernetes users to save cloud resource usage with a rich set of functionalities: @@ -42,155 +26,28 @@ The goal of Crane is to provide a one-stop-shop project to help Kubernetes users Crane Overview -## Features -### Time Series Prediction - -TimeSeriesPrediction defines metric spec to predict kubernetes resources like Pod or Node. -The prediction module is the core component that other crane components relied on, like [EHPA](#effective-horizontalpodautoscaler) and [Analytics](#analytics). - -Please see [this document](./docs/tutorials/using-time-series-prediction.md) to learn more. - -### Effective HorizontalPodAutoscaler - -EffectiveHorizontalPodAutoscaler helps you manage application scaling in an easy way. It is compatible with native [HorizontalPodAutoscaler](https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale/) but extends more features like prediction-driven autoscaling. - -Please see [this document](./docs/tutorials/using-effective-hpa-to-scaling-with-effectiveness.md) to learn more. - -### Analytics - -Analytics model analyzes the workload and provide recommendations about resource optimize. - -Two Recommendations are currently supported: -- **ResourceRecommend**: Recommend container requests & limit resources based on historic metrics. -- **Effective HPARecommend**: Recommend which workloads are suitable for autoscaling and provide optimized configurations such as minReplicas, maxReplicas. - -### QoS Ensurance -Kubernetes is capable of starting multiple pods on same node, and as a result, some of the user applications may be impacted when there are resources(e.g. cpu) consumption competition. To mitigate this, Crane allows users defining PrioirtyClass for the pods and QoSEnsurancePolicy, and then detects disruption and ensure the high priority pods not being impacted by resource competition. - -Avoidance Actions: -- **Disable Schedule**: disable scheduling by setting node taint and condition -- **Throttle**: throttle the low priority pods by squeezing cgroup settings -- **Evict**: evict low priority pods - -Please see [this document](./docs/tutorials/using-qos-ensurance.md) to learn more. - -## Repositories - -Crane is composed of the following components: -- [craned](cmd/craned). - main crane control plane. - - **Predictor** - Predicts resources metrics trends based on historical data. - - **AnalyticsController** - Analyzes resources and generate related recommendations. - - **RecommendationController** - Recommend Pod resource requests and autoscaler. - - **ClusterNodePredictionController** - Create Predictor for nodes. - - **EffectiveHPAController** - Effective HPA for horizontal scaling. - - **EffectiveVPAController** - Effective VPA for vertical scaling. -- [metric-adaptor](cmd/metric-adapter). - Metric server for driving the scaling. -- [crane-agent](cmd/crane-agent). - Ensure critical workloads SLO based on abnormally detection. -- [gocrane/api](https://github.com/gocrane/api). This repository defines component-level APIs for the Crane platform. -- [gocrane/fadvisor](https://github.com/gocrane/fadvisor) Financial advisor which collect resource prices from cloud API. - ## Getting Started -### Installation - -**Prerequisites** - -- Kubernetes 1.18+ -- Helm 3.1.0 - -**Helm Installation** - -Please refer to Helm's [documentation](https://helm.sh/docs/intro/install/) for installation. +- [Introduction](https://docs.gocrane.io/getting-started/introduction) +- [Installation](https://docs.gocrane.io/getting-started/installation) +- [Tutorials](https://docs.gocrane.io/tutorials) -**Installing prometheus and grafana with helm chart** +## Documentation -> Note: -> If you already deployed prometheus, grafana in your environment, then skip this step. +Full documentation is available on the [Crane website](https://docs.gocrane.io). -Crane use prometheus to be the default metric provider. Using following command to install prometheus components: prometheus-server, node-exporter, kube-state-metrics. +## Community -```console -helm repo add prometheus-community https://prometheus-community.github.io/helm-charts -helm install prometheus -n crane-system --set pushgateway.enabled=false --set alertmanager.enabled=false --set server.persistentVolume.enabled=false -f https://raw.githubusercontent.com/gocrane/helm-charts/main/integration/prometheus/override_values.yaml --create-namespace prometheus-community/prometheus -``` +- Wechat Group (Chinese): Add it and Reply "Crane"，Robot will add you in Wechat group. -Fadvisor use grafana to present cost estimates. Using following command to install a grafana. +Wechat -```console -helm repo add grafana https://grafana.github.io/helm-charts -helm install grafana -f https://raw.githubusercontent.com/gocrane/helm-charts/main/integration/grafana/override_values.yaml -n crane-system --create-namespace grafana/grafana -``` +- Bi-weekly Community Call: [Meeting Notes](https://doc.weixin.qq.com/doc/w3_AHMAlwa_AFU7PT58rVhTFKXV0maR6?scode=AJEAIQdfAAo0gvbrCIAHMAlwa_AFU). -**Deploying Crane and Fadvisor** - -```console -helm repo add crane https://gocrane.github.io/helm-charts -helm install crane -n crane-system --create-namespace crane/crane -helm install fadvisor -n crane-system --create-namespace crane/fadvisor -``` - -**Verify Installation** - -Check deployments are all available by running: - -```console -kubectl get deploy -n crane-system -``` - -The output is similar to: -```console -NAME READY STATUS RESTARTS AGE -crane-agent-8h7df 1/1 Running 0 119m -crane-agent-8qf5n 1/1 Running 0 119m -crane-agent-h9h5d 1/1 Running 0 119m -craned-5c69c684d8-dxmhw 2/2 Running 0 20m -grafana-7fddd867b4-kdxv2 1/1 Running 0 41m -metric-adapter-94b6f75b-k8h7z 1/1 Running 0 119m -prometheus-kube-state-metrics-6dbc9cd6c9-dfmkw 1/1 Running 0 45m -prometheus-node-exporter-bfv74 1/1 Running 0 45m -prometheus-node-exporter-s6zps 1/1 Running 0 45m -prometheus-node-exporter-x5rnm 1/1 Running 0 45m -prometheus-server-5966b646fd-g9vxl 2/2 Running 0 45m -``` - -you can see [this](https://github.com/gocrane/helm-charts) to learn more. - -**Customize Installation** - -Deploy `Crane` by apply YAML declaration. - -```console -git checkout v0.2.0 -kubectl apply -f deploy/manifests -kubectl apply -f deploy/craned -kubectl apply -f deploy/metric-adapter -``` - -The following command will configure prometheus http address for crane if you want to customize it. Specify `CUSTOMIZE_PROMETHEUS` if you have existing prometheus server. - -```console -export CUSTOMIZE_PROMETHEUS= -if [ $CUSTOMIZE_PROMETHEUS ]; then sed -i '' "s/http:\/\/prometheus-server.crane-system.svc.cluster.local:8080/${CUSTOMIZE_PROMETHEUS}/" deploy/craned/deployment.yaml ; fi -``` - -### Get your Kubernetes Cost Report - -Get the Grafana URL to visit by running these commands in the same shell: - -```console -export POD_NAME=$(kubectl get pods --namespace crane-system -l "app.kubernetes.io/name=grafana,app.kubernetes.io/instance=grafana" -o jsonpath="{.items[0].metadata.name}") -kubectl --namespace crane-system port-forward $POD_NAME 3000 -``` - -visit [Cost Report](http://127.0.0.1:3000/dashboards) here with account(admin:admin). - -### Analytics and Recommendation - -Crane supports analytics and give recommend advise for your k8s cluster. - -Please follow [this guide](./docs/tutorials/analytics-and-recommendation.md) to learn more. +- Bi-weekly Chinese Community Call: [Video Records](https://www.wolai.com/33xC4HB1JXCCH1x8umfioS). ## RoadMap + Please see [this document](./docs/roadmaps/roadmap-1h-2022.md) to learn more. ## Contributing diff --git a/docs/assets/util.css b/docs/assets/util.css new file mode 100644 index 000000000..f273e7533 --- /dev/null +++ b/docs/assets/util.css @@ -0,0 +1,3 @@ +.md-nav__title { + display: none; +} \ No newline at end of file diff --git a/docs/code-standards.md b/docs/code-standards.md index bb0570604..9223c609b 100644 --- a/docs/code-standards.md +++ b/docs/code-standards.md @@ -1,4 +1,7 @@ +# Code standards + This doc describes the code standards and suggestion for crane project, mainly for new contributor of the project + ### import need to be organized import should be categorized with blank line as system imports, community imports and crane apis and crane imports, like the following example ```go diff --git a/docs/images/wechat.jpeg b/docs/images/wechat.jpeg new file mode 100644 index 000000000..d919b96c9 Binary files /dev/null and b/docs/images/wechat.jpeg differ diff --git a/docs/index.md b/docs/index.md index 74c50d6f6..44d815d80 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,17 +1,4 @@ -# Crane: Cloud Resource Analytics and Economics - -[![Go Report Card](https://goreportcard.com/badge/github.com/gocrane/crane)](https://goreportcard.com/report/github.com/gocrane/crane) -[![GoDoc](https://godoc.org/github.com/gocrane/crane?status.svg)](https://godoc.org/github.com/gocrane/crane) -[![License](https://img.shields.io/github/license/gocrane/crane)](https://www.apache.org/licenses/LICENSE-2.0.html) -![GoVersion](https://img.shields.io/github/go-mod/go-version/gocrane/crane) - -Crane logo - ---- - -Crane (FinOps Crane) is a cloud native open source project which manages cloud resources on Kubernetes stack, it is inspired by FinOps concepts. - -## Introduction +# Introduction The goal of Crane is to provide a one-stop-shop project to help Kubernetes users to save cloud resource usage with a rich set of functionalities: @@ -75,4 +62,3 @@ Crane is composed of the following components: - [crane-agent](https://github.com/gocrane/crane/tree/main/cmd/crane-agent) - Ensure critical workloads SLO based on abnormally detection. - [gocrane/api](https://github.com/gocrane/api) - This repository defines component-level APIs for the Crane platform. - [gocrane/fadvisor](https://github.com/gocrane/fadvisor) - Financial advisor which collect resource prices from cloud API. - diff --git a/docs/index.zh.md b/docs/index.zh.md index 9c3aea1ee..3ea987f38 100644 --- a/docs/index.zh.md +++ b/docs/index.zh.md @@ -1,17 +1,4 @@ -# Crane: Cloud Resource Analytics and Economics - -[![Go Report Card](https://goreportcard.com/badge/github.com/gocrane/crane)](https://goreportcard.com/report/github.com/gocrane/crane) -[![GoDoc](https://godoc.org/github.com/gocrane/crane?status.svg)](https://godoc.org/github.com/gocrane/crane) -[![License](https://img.shields.io/github/license/gocrane/crane)](https://www.apache.org/licenses/LICENSE-2.0.html) -![GoVersion](https://img.shields.io/github/go-mod/go-version/gocrane/crane) - -Crane logo - ---- - -Crane（FinOps Crane）是一个云原生开源项目，它管理Kubernetes上的云资源，其灵感来自FinOps理念。 - -## 介绍 +# 介绍 The goal of Crane is to provide a one-stop-shop project to help Kubernetes users to save cloud resource usage with a rich set of functionalities: @@ -65,12 +52,12 @@ Please see [this document](tutorials/using-qos-ensurance.md) to learn more. Crane is composed of the following components: - [craned](https://github.com/gocrane/crane/tree/main/cmd/craned) - main crane control plane. - - **Predictor** - Predicts resources metrics trends based on historical data. - - **AnalyticsController** - Analyzes resources and generate related recommendations. - - **RecommendationController** - Recommend Pod resource requests and autoscaler. - - **ClusterNodePredictionController** - Create Predictor for nodes. - - **EffectiveHPAController** - Effective HPA for horizontal scaling. - - **EffectiveHPAController** - Effective VPA for vertical scaling. + - **Predictor** - Predicts resources metrics trends based on historical data. + - **AnalyticsController** - Analyzes resources and generate related recommendations. + - **RecommendationController** - Recommend Pod resource requests and autoscaler. + - **ClusterNodePredictionController** - Create Predictor for nodes. + - **EffectiveHPAController** - Effective HPA for horizontal scaling. + - **EffectiveVPAController** - Effective VPA for vertical scaling. - [metric-adaptor](https://github.com/gocrane/crane/tree/main/cmd/metric-adapter) - Metric server for driving the scaling. - [crane-agent](https://github.com/gocrane/crane/tree/main/cmd/crane-agent) - Ensure critical workloads SLO based on abnormally detection. - [gocrane/api](https://github.com/gocrane/api) - This repository defines component-level APIs for the Crane platform. diff --git a/docs/getting-started.md b/docs/installation.md similarity index 83% rename from docs/getting-started.md rename to docs/installation.md index 412fa7c13..fef9c1ce0 100644 --- a/docs/getting-started.md +++ b/docs/installation.md @@ -1,17 +1,17 @@ -# Getting Started +# Installation -## Installation - -**Prerequisites** +## Prerequisites - Kubernetes 1.18+ - Helm 3.1.0 -**Helm Installation** +## Steps + +### Helm Installation Please refer to Helm's [documentation](https://helm.sh/docs/intro/install/) for installation. -**Installing prometheus and grafana with helm chart** +### Installing prometheus and grafana with helm chart !!! note If you already deployed prometheus, grafana in your environment, then skip this step. @@ -32,7 +32,7 @@ helm repo add grafana https://grafana.github.io/helm-charts helm install grafana -f https://raw.githubusercontent.com/gocrane/helm-charts/main/integration/grafana/override_values.yaml -n crane-system --create-namespace grafana/grafana ``` -**Deploying Crane and Fadvisor** +### Deploying Crane and Fadvisor ```bash helm repo add crane https://gocrane.github.io/helm-charts @@ -40,7 +40,7 @@ helm install crane -n crane-system --create-namespace crane/crane helm install fadvisor -n crane-system --create-namespace crane/fadvisor ``` -**Verify Installation** +### Verify Installation Check deployments are all available by running: @@ -66,7 +66,7 @@ prometheus-server-5966b646fd-g9vxl 2/2 Running 0 45 you can see [this](https://github.com/gocrane/helm-charts) to learn more. -**Customize Installation** +## Customize Installation Deploy `Crane` by apply YAML declaration. @@ -96,19 +96,3 @@ kubectl --namespace crane-system port-forward $POD_NAME 3000 ``` visit [Cost Report](http://127.0.0.1:3000/dashboards) here with account(admin:admin). - -## Analytics and Recommendation - -Crane supports analytics and give recommend advise for your k8s cluster. - -Please follow [this guide](tutorials/analytics-and-recommendation.md) to learn more. - -## RoadMap -Please see [this document](roadmaps/roadmap-1h-2022.md) to learn more. - -## Contributing - -Contributors are welcomed to join Crane project. Please check [CONTRIBUTING](./CONTRIBUTING.md) about how to contribute to this project. - -## Code of Conduct -Crane adopts [CNCF Code of Conduct](https://github.com/cncf/foundation/blob/master/code-of-conduct.md). diff --git a/docs/getting-started.zh.md b/docs/installation.zh.md similarity index 98% rename from docs/getting-started.zh.md rename to docs/installation.zh.md index fabc54870..28e08bcc5 100644 --- a/docs/getting-started.zh.md +++ b/docs/installation.zh.md @@ -1,8 +1,5 @@ # 产品部署指南 -!!! tip - 本页面来自 https://github.com/gocrane/crane/pull/243 @willemswang - 为了让您更快的部署 Crane ，本文档提供清晰的： * 部署环境要求 @@ -52,8 +49,6 @@ helm install crane -n crane-system --create-namespace crane/crane helm install fadvisor -n crane-system --create-namespace crane/fadvisor ``` - - ## 验证安装是否成功 使用如下命令检查安装的 Deployment 是否正常： @@ -92,8 +87,6 @@ kubectl port-forward -n crane-system svc/craned 9090 ![](images/crane-dashboard.png) - - ### 添加安装了 Crane 的集群 您可以点击上图中的“添加集群”的蓝色按钮，将 Crane 控制台的地址 `http://localhost:9090` 作为 Crane 的 URL，作为第一个集群添加到 Crane 控制台。 diff --git a/mkdocs.yml b/mkdocs.yml index b7be8c352..065102d4c 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -16,6 +16,8 @@ theme: text: Work Sans extra_javascript: - assets/util.js +extra_css: + - assets/util.css extra: version: provider: mike @@ -33,8 +35,9 @@ plugins: build: true nav_translations: zh: - Overview: 总览 Getting Started: 从这里开始 + Introduction: 介绍 + Installation: 安装 Tutorials: 教程 Proposals: 提案 Contributing: 贡献 @@ -58,13 +61,14 @@ markdown_extensions: repo_url: https://github.com/gocrane/crane repo_name: gocrane/crane nav: - - Overview: index.md - - Getting Started: getting-started.md + - Getting Started: + - Introduction: index.md + - Installation: installation.md - Tutorials: + - Effective HPA: tutorials/using-effective-hpa-to-scaling-with-effectiveness.md - Analytics and Recommendation: tutorials/analytics-and-recommendation.md - - Using Effective HPA To Scaling With Effectiveness: tutorials/using-effective-hpa-to-scaling-with-effectiveness.md - - Using Qos Ensurance: tutorials/using-qos-ensurance.md - - Using Time Series Prediction: tutorials/using-time-series-prediction.md + - Qos Ensurance: tutorials/using-qos-ensurance.md + - Time Series Prediction: tutorials/using-time-series-prediction.md - Proposals: - Advanced CpuSet Manager: proposals/20220228-advanced-cpuset-manger.md - Contributing: CONTRIBUTING.md