Merge pull request #365 from qmhu/smart-recommend-2

Update docs for smart recommend
gocrane · Jun 17, 2022 · ac3caa9 · ac3caa9
2 parents 0c144e7 + 08394cb
commit ac3caa9
Show file tree

Hide file tree

Showing 10 changed files with 224 additions and 98 deletions.
diff --git a/docs/index.md b/docs/index.md
@@ -35,8 +35,8 @@ Analytics model analyzes the workload and provide recommendations about resource
 
 Two Recommendations are currently supported:
 
-- [**ResourceRecommend**](tutorials/resource-recommendation.md): Recommend container requests & limit resources based on historic metrics.
-- [**Effective HPARecommend**](tutorials/replicas-recommendation.md): Recommend which workloads are suitable for autoscaling and provide optimized configurations such as minReplicas, maxReplicas.
+- [**ResourceRecommend**](tutorials/resource-recommendation.md): Replicas recommendation analyze the actual application usage and give advice for replicas and HPA configurations.
+- [**HPARecommend**](tutorials/replicas-recommendation.md): Resource recommendation allows you to obtain recommended values for resources in a cluster and use them to improve the resource utilization of the cluster.
 
 Please see [this document](tutorials/analytics-and-recommendation.md) to learn more.
 

diff --git a/docs/index.zh.md b/docs/index.zh.md
@@ -30,12 +30,10 @@ Please see [this document](tutorials/using-effective-hpa-to-scaling-with-effecti
 
 ### Analytics
 
-Analytics model analyzes the workload and provide recommendations about resource optimize.
+智能推荐能够帮助用户自动分析集群并给出优化建议。就像手机助手一样，智能推荐会定期的扫描、分析你的集群并给出推荐建议。目前，我们提供了两种优化能力：
 
-Two Recommendations are currently supported:
-
-- [**ResourceRecommend**](tutorials/resource-recommendation.md): Recommend container requests & limit resources based on historic metrics.
-- [**Effective HPARecommend**](tutorials/replicas-recommendation.md): Recommend which workloads are suitable for autoscaling and provide optimized configurations such as minReplicas, maxReplicas.
+- [**资源推荐**](tutorials/resource-recommendation.zh.md): 通过资源推荐的算法分析应用的真实用量推荐更合适的资源配置，您可以参考并采纳它提升集群的资源利用率。
+- [**副本数推荐**](tutorials/replicas-recommendation.zh.md): 通过副本数推荐的算法分析应用的真实用量推荐更合适的副本和 EHPA 配置，您可以参考并采纳它提升集群的资源利用率。
 
 Please see [this document](tutorials/analytics-and-recommendation.md) to learn more.
 

diff --git a/docs/tutorials/analytics-and-recommendation.md b/docs/tutorials/analytics-and-recommendation.md
@@ -4,8 +4,8 @@ Analytics and Recommendation provide capacity that analyzes the workload in k8s
 
 Two Recommendations are currently supported:
 
-- [**ResourceRecommend**](resource-recommendation.md): Recommend container requests & limit resources based on historic metrics.
-- [**HPARecommend**](replicas-recommendation.md): Recommend which workloads are suitable for autoscaling and provide optimized configurations such as minReplicas, maxReplicas.
+- [**ResourceRecommend**](resource-recommendation.md): Replicas recommendation analyze the actual application usage and give advice for replicas and HPA configurations.
+- [**HPARecommend**](replicas-recommendation.md): Resource recommendation allows you to obtain recommended values for resources in a cluster and use them to improve the resource utilization of the cluster.
 
 ## Architecture
 

diff --git a/docs/tutorials/analytics-and-recommendation.zh.md b/docs/tutorials/analytics-and-recommendation.zh.md
@@ -1,9 +1,11 @@
-# 分析和推荐
+# 智能推荐
 
-分析和推荐提供了一套自动化的成本优化能力，它帮助用户自动的发现问题并提供优化的方案。就像电脑/手机助手一样，它会定期的扫描、分析你的集群并给出推荐建议。目前，我们提供了两种优化能力：
+智能推荐能够帮助用户自动分析集群并给出优化建议。就像手机助手一样，智能推荐会定期的扫描、分析你的集群并给出推荐建议。目前，我们提供了两种优化能力：
 
-- [**资源推荐**](resource-recommendation.zh.md): Kubernetes 的用户在创建应用资源时常常是基于经验值来设置 request 和 limit。通过资源推荐的算法分析应用的真实用量推荐更合适的资源配置，您可以参考并采纳它提升集群的资源利用率。
-- [**弹性推荐**](replicas-recommendation.zh.md): 筛选工作负载，推荐出适合做弹性的工作负载并给出弹性建议
+- [**资源推荐**](resource-recommendation.zh.md): 通过资源推荐的算法分析应用的真实用量推荐更合适的资源配置，您可以参考并采纳它提升集群的资源利用率。
+- [**副本数推荐**](replicas-recommendation.zh.md): 通过副本数推荐的算法分析应用的真实用量推荐更合适的副本和 EHPA 配置，您可以参考并采纳它提升集群的资源利用率。
+
+应用可以根据资源推荐调整 request 也可以根据副本数推荐调整副本数，这两种优化都能帮助您降低成本，您可以根据您的需求选择采用相应的优化建议。
 
 ## 架构
 

diff --git a/docs/tutorials/replicas-recommendation.md b/docs/tutorials/replicas-recommendation.md
@@ -1,6 +1,12 @@
 # Replicas Recommendation
 
-Using hpa recommendations, you can find resources in the cluster that are suitable for autoscaling, and use Crane's recommended result to create an autoscaling object: [Effective HorizontalPodAutoscaler](using-effective-hpa-to-scaling-with-effectiveness.md).
+Kubernetes' users often set the replicas of workload or HPA configurations based on empirical values. Replicas recommendation analyze the actual application usage and give advice for replicas and HPA configurations. You can refer to and adopt it for your workloads to improve cluster resource utilization.
+
+## Features
+
+1. Algorithm: The algorithm for calculating the replicas refers to HPA, and supports to customization algo args
+2. HPA recommendations: Scan for applications that suitable for configuring horizontal elasticity (EHPA), And give advice for configuration of EHPA, [EHPA](using-effective-hpa-to-scaling-with-effectiveness.md) is a smart horizontal elastic product provided by Crane
+3. Support batch analysis: With the ResourceSelector, users can batch analyze multiple workloads
 
 ## Create HPA Analytics
 
@@ -50,7 +56,7 @@ kubectl get analytics nginx-replicas -o yaml
 
 The output is similar to:
 
-```yaml hl_lines="32"
+```yaml
 apiVersion: analysis.crane.io/v1alpha1
 kind: Analytics
 metadata:
@@ -164,6 +170,32 @@ metadata:
    selfLink: ""
 ```
 
+## Batch recommendation
+
+Use a sample to show how to recommend all Deployments and StatefulSets by one `Analytics`:
+
+```yaml
+apiVersion: analysis.crane.io/v1alpha1
+kind: Analytics
+metadata:
+   name: workload-replicas
+   namespace: crane-system               # The Analytics in Crane-system will select all resource across all namespaces.
+spec:
+   type: Replicas                        # This can only be "Resource" or "Replicas".
+   completionStrategy:
+      completionStrategyType: Periodical  # This can only be "Once" or "Periodical".
+      periodSeconds: 86400                # analytics selected resources every 1 day
+   resourceSelectors:                    # defines all the resources to be select with
+      - kind: Deployment
+        apiVersion: apps/v1
+      - kind: StatefulSet
+        apiVersion: apps/v1
+```
+
+1. when using `crane-system` as your namespace，`Analytics` selected all namespaces，when namespace not equal `crane-system`，`Analytics` selected the resource that in `Analytics` namespace
+2. resourceSelectors defines the resource to analysis，kind and apiVersion is mandatory，name is optional
+3. resourceSelectors supoort any resource that are [Scale Subresource](https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/#scale-subresource)
+
 ## HPA Recommendation Algorithm model
 
 ### Inspecting

diff --git a/docs/tutorials/replicas-recommendation.zh.md b/docs/tutorials/replicas-recommendation.zh.md
@@ -1,6 +1,12 @@
-# 弹性推荐
+# 副本数推荐
 
-通过弹性推荐，你可以发现集群中适合弹性的资源，并使用 Crane 推荐的弹性配置创建自动弹性器: [Effective HorizontalPodAutoscaler](using-effective-hpa-to-scaling-with-effectiveness.md)
+Kubernetes 用户在创建应用资源时常常是基于经验值来设置副本数或者 EHPA 配置。通过副本数推荐的算法分析应用的真实用量推荐更合适的副本配置，您可以参考并采纳它提升集群的资源利用率。
+
+## 产品功能
+
+1. 算法：计算副本数的算法参考了 HPA 的计算公式，并且支持自定义算法的关键配置
+2. HPA 推荐：副本数推荐会扫描出适合配置水平弹性（EHPA）的应用，并给出 EHPA 的配置, [EHPA](using-effective-hpa-to-scaling-with-effectiveness.md) 是 Crane 提供了智能水平弹性产品
+3. 支持批量分析：通过 `Analytics` 的 ResourceSelector，用户可以批量分析多个工作负载
 
 ## 创建弹性分析
 
@@ -27,9 +33,9 @@
 apiVersion: analysis.crane.io/v1alpha1
 kind: Analytics
 metadata:
-  name: nginx-hpa
+  name: nginx-replicas
 spec:
-  type: HPA                        # This can only be "Resource" or "HPA".
+  type: Replicas                        # This can only be "Resource" or "Replicas".
   completionStrategy:
     completionStrategyType: Periodical  # This can only be "Once" or "Periodical".
     periodSeconds: 600                  # analytics selected resources every 10 minutes
@@ -38,129 +44,166 @@ spec:
       apiVersion: apps/v1
       name: nginx-deployment
   config:                               # defines all the configuration for this analytics
-    ehpa.deployment-min-replicas: "1"
-    ehpa.fluctuation-threshold: "0"
-    ehpa.min-cpu-usage-threshold: "0"
+    replicas.workload-min-replicas: "1"
+    replicas.fluctuation-threshold: "0"
+    replicas.min-cpu-usage-threshold: "0"
 ```
 
 结果如下:
 
 ```bash
-NAME        AGE
-nginx-hpa   16m
+NAME             AGE
+nginx-replicas   16m
 ```
 
-查看 Analytics 的 Status，通过 status.recommendations[0].name 得到 Recommendation 的 name:
+查看 Analytics 详情:
 
 ```bash
-kubectl get analytics nginx-hpa -o yaml
+kubectl get analytics nginx-replicas -o yaml
 ```
 
 结果如下:
 
-```yaml hl_lines="32"
+```yaml
 apiVersion: analysis.crane.io/v1alpha1
 kind: Analytics
 metadata:
-  creationTimestamp: "2022-05-15T13:34:19Z"
-  name: nginx-hpa
+  name: nginx-replicas
   namespace: default
 spec:
   completionStrategy:
     completionStrategyType: Periodical
     periodSeconds: 600
   config:
-    ehpa.deployment-min-replicas: "1"
-    ehpa.fluctuation-threshold: "0"
-    ehpa.min-cpu-usage-threshold: "0"
+    replicas.fluctuation-threshold: "0"
+    replicas.min-cpu-usage-threshold: "0"
+    replicas.workload-min-replicas: "1"
   resourceSelectors:
   - apiVersion: apps/v1
     kind: Deployment
     labelSelector: {}
     name: nginx-deployment
-  type: HPA
+  type: Replicas
 status:
   conditions:
-  - lastTransitionTime: "2022-05-15T13:34:19Z"
+  - lastTransitionTime: "2022-06-17T06:56:07Z"
     message: Analytics is ready
     reason: AnalyticsReady
     status: "True"
     type: Ready
-  lastUpdateTime: "2022-05-15T13:34:19Z"
+  lastUpdateTime: "2022-06-17T06:56:06Z"
   recommendations:
-  - lastStartTime: "2022-05-15T13:34:19Z"
+  - lastStartTime: "2022-06-17T06:56:06Z"
     message: Success
-    name: nginx-hpa-hpa-cd86s
+    name: nginx-replicas-replicas-wq6wm
     namespace: default
     targetRef:
       apiVersion: apps/v1
       kind: Deployment
       name: nginx-deployment
       namespace: default
-    uid: b3cea8cb-259d-4cb2-bbbe-cd0e6544daaf
+    uid: 59f3eb3c-f786-4b15-b37e-774e5784c2db
 ```
 
 ## 查看分析结果
 
 查看 **Recommendation** 结果：
 
 ```bash
-kubectl get recommend nginx-hpa-hpa-cd86s -o yaml
+kubectl get recommend -l analysis.crane.io/analytics-name=nginx-replicas -o yaml
 ```
 
 分析结果如下：
 
+```yaml
+apiVersion: v1
+items:
+  - apiVersion: analysis.crane.io/v1alpha1
+    kind: Recommendation
+    metadata:
+      creationTimestamp: "2022-06-17T06:56:06Z"
+      generateName: nginx-replicas-replicas-
+      generation: 2
+      labels:
+        analysis.crane.io/analytics-name: nginx-replicas
+        analysis.crane.io/analytics-type: Replicas
+        analysis.crane.io/analytics-uid: 795f245b-1e1f-4f7b-a02b-885d7a495e5b
+        app: nginx
+      name: nginx-replicas-replicas-wq6wm
+      namespace: default
+      ownerReferences:
+        - apiVersion: analysis.crane.io/v1alpha1
+          blockOwnerDeletion: false
+          controller: false
+          kind: Analytics
+          name: nginx-replicas
+          uid: 795f245b-1e1f-4f7b-a02b-885d7a495e5b
+      resourceVersion: "2182455668"
+      selfLink: /apis/analysis.crane.io/v1alpha1/namespaces/default/recommendations/nginx-replicas-replicas-wq6wm
+      uid: 59f3eb3c-f786-4b15-b37e-774e5784c2db
+    spec:
+      adoptionType: StatusAndAnnotation
+      completionStrategy:
+        completionStrategyType: Once
+      targetRef:
+        apiVersion: apps/v1
+        kind: Deployment
+        name: nginx-deployment
+        namespace: default
+      type: Replicas
+    status:
+      conditions:
+        - lastTransitionTime: "2022-06-17T06:56:07Z"
+          message: Recommendation is ready
+          reason: RecommendationReady
+          status: "True"
+          type: Ready
+      lastUpdateTime: "2022-06-17T06:56:07Z"
+      recommendedValue: |
+        effectiveHPA:
+          maxReplicas: 3
+          metrics:
+          - resource:
+              name: cpu
+              target:
+                averageUtilization: 75
+                type: Utilization
+            type: Resource
+          minReplicas: 3
+        replicasRecommendation:
+          replicas: 3
+kind: List
+metadata:
+  resourceVersion: ""
+  selfLink: ""
+```
+
+## 批量推荐
+
+我们通过一个例子来演示如何使用 `Analytics` 推荐集群中所有的 Deployment 和 StatefulSet：
+
 ```yaml
 apiVersion: analysis.crane.io/v1alpha1
-kind: Recommendation
+kind: Analytics
 metadata:
-  creationTimestamp: "2022-05-15T13:34:19Z"
-  generateName: nginx-hpa-hpa-
-  generation: 2
-  labels:
-    analysis.crane.io/analytics-name: nginx-hpa
-    analysis.crane.io/analytics-type: HPA
-    analysis.crane.io/analytics-uid: 5564edd0-d7cd-4da6-865b-27fa4fddf7c4
-    app: nginx
-  name: nginx-hpa-hpa-cd86s
-  namespace: default
-  ownerReferences:
-  - apiVersion: analysis.crane.io/v1alpha1
-    blockOwnerDeletion: false
-    controller: false
-    kind: Analytics
-    name: nginx-hpa
-    uid: 5564edd0-d7cd-4da6-865b-27fa4fddf7c4
+  name: workload-replicas
+  namespace: crane-system               # The Analytics in Crane-system will select all resource across all namespaces.
 spec:
-  adoptionType: StatusAndAnnotation
+  type: Replicas                        # This can only be "Resource" or "Replicas".
   completionStrategy:
-    completionStrategyType: Once
-  targetRef:
-    apiVersion: apps/v1
-    kind: Deployment
-    name: nginx-deployment
-    namespace: default
-  type: HPA
-status:
-  conditions:
-  - lastTransitionTime: "2022-05-15T13:34:19Z"
-    message: Recommendation is ready
-    reason: RecommendationReady
-    status: "True"
-    type: Ready
-  lastUpdateTime: "2022-05-15T13:34:19Z"
-  recommendedValue: |
-    maxReplicas: 2
-    metrics:
-    - resource:
-        name: cpu
-        target:
-          averageUtilization: 75
-          type: Utilization
-      type: Resource
-    minReplicas: 2
+    completionStrategyType: Periodical  # This can only be "Once" or "Periodical".
+    periodSeconds: 86400                # analytics selected resources every 1 day
+  resourceSelectors:                    # defines all the resources to be select with
+    - kind: Deployment
+      apiVersion: apps/v1
+    - kind: StatefulSet
+      apiVersion: apps/v1
 ```
 
+1. 当 namespace 等于 `crane-system` 时，`Analytics` 选择的资源是集群中所有的 namespace，当 namespace 不等于 `crane-system` 时，`Analytics` 选择 `Analytics` namespace 下的资源
+2. resourceSelectors 通过数组配置需要分析的资源，kind 和 apiVersion 是必填字段，name 选填
+3. resourceSelectors 支持配置任意支持 [Scale Subresource](https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/#scale-subresource) 的资源
+
 ## 弹性推荐计算模型
 
 ### 筛选阶段
@@ -243,3 +286,5 @@ status:
 | ehpa.min-cpu-target-utilization| 30 | |
 | ehpa.max-cpu-target-utilization| 75 | |
 | ehpa.reference-hpa| true | 继承现有的 HPA 配置 |
+
+