Update tortoise user document (#403)

mercari · May 20, 2024 · 04b6df1 · 04b6df1
1 parent 88e7410
commit 04b6df1
Showing 1 changed file with 61 additions and 40 deletions.
diff --git a/docs/user-guide.md b/docs/user-guide.md
@@ -25,47 +25,9 @@ spec:
 
 This is the example for a minimum required configuration. 
 
-### updateMode
-
-```yaml
-apiVersion: autoscaling.mercari.com/v1beta3
-kind: Tortoise
-spec:
-...
-  updateMode: Auto 
-```
-
-`.spec.updateMode` could contain three values:
-- `Off` (default): DryRun mode. The tortoise doesn't change anything in your workload or autoscaler.
-- `Auto`: The tortoise keep updating your workload or autoscaler to be optimized.
-- `Emergency`: The tortoise scale up/out your workload to be big enough so that the workload can handle unexpectedly bigger traffic.
-
-#### updateMode: `Off`
-
-`Off` is the default value of `updateMode`. 
-It means a DryRun mode - the tortoise doesn't change anything in your workload or autoscaler.
-
-But, even during `Off` mode, the tortoise actually generates the recommendation for your workload's resource request, and your HPA's target utilization.
+### Configure how each container's each resource is scaled (`.spec.AutoscalingPolicy` / `.spec.TargetRefs.HorizontalPodAutoscalerName`)
 
-You can observe the recommendation values with these metrics:
-- `mercari.tortoise.proposed_cpu_request`: CPU request a tortoise proposes.
-- `mercari.tortoise.proposed_memory_request`: memory request that a tortoise proposes.
-- `mercari.tortoise.proposed_hpa_minreplicas`: HPA `.spec.minReplicas` that a tortoise proposes.
-- `mercari.tortoise.proposed_hpa_maxreplicas`: HPA `.spec.maxReplicas` that a tortoise proposes.
-- `mercari.tortoise.proposed_hpa_utilization_target`: HPA `.spec.metrics[*].containerResource.target.averageUtilization` that a tortoise proposes.
-
-#### updateMode: `Auto`
-
-`Auto` is a update mode to let tortoise keep updating your workload or autoscaler to be optimized.
-
-#### updateMode: `Emergency`
-
-`Emergency` is a update mode to enable the emergency mode.
-Please refer to [Emergency mode](./emergency.md) for more details.
-
-### `.spec.AutoscalingPolicy`
-
-There are two primary options for configuring resource scaling within containers:
+There are two options for configuring resource scaling:
 1. Allow Tortoise to automatically determine the appropriate autoscaling policy for each resource.
 2. Manually define the autoscaling policy for each resource.
 
@@ -84,6 +46,27 @@ Additionally, if a `ContainerResource` metric is later added to an HPA associate
 Tortoise will automatically update relevant resources to utilize a `Horizontal` policy in AutoscalingPolicy.
 - if a container doesn't have the resource request, that container's autoscaling policy is always set to "Off" because tortoise cannot generate any recommendation without the resource request.
 
+You can see how actually your tortoise scales your Pods with `.status.autoscalingPolicy`:
+
+```yaml
+apiVersion: autoscaling.mercari.com/v1beta3
+kind: Tortoise
+metadata:
+  name: your-tortoise-name
+  namespace: your-namespace
+...
+status:
+  autoscalingPolicy:
+  - containerName: awesome-mercari-container
+    policy:
+      cpu: Horizontal
+      memory: Vertical
+  - containerName: istio-proxy
+    policy:
+      cpu: Horizontal
+      memory: Vertical
+```
+
 #### 2. Manually define the autoscaling policy for each resource.
 
 With the second option, you must manually specify the AutoscalingPolicy for the resources of each container within this field.
@@ -114,6 +97,44 @@ Be aware that when new containers are introduced to the workload, the Autoscalin
 if you want to configure autoscaling for a new container,
 as Tortoise will default to an `Off` policy for resources within the new container, preventing scaling.
 
+### updateMode
+
+```yaml
+apiVersion: autoscaling.mercari.com/v1beta3
+kind: Tortoise
+spec:
+...
+  updateMode: Auto 
+```
+
+`.spec.updateMode` could contain three values:
+- `Off` (default): DryRun mode. The tortoise doesn't change anything in your workload or autoscaler.
+- `Auto`: The tortoise keep updating your workload or autoscaler to be optimized.
+- `Emergency`: The tortoise scale up/out your workload to be big enough so that the workload can handle unexpectedly bigger traffic.
+
+#### updateMode: `Off`
+
+`Off` is the default value of `updateMode`. 
+It means a DryRun mode - the tortoise doesn't change anything in your workload or autoscaler.
+
+But, even during `Off` mode, the tortoise actually generates the recommendation for your workload's resource request, and your HPA's target utilization.
+
+You can observe the recommendation values with these metrics:
+- `mercari.tortoise.proposed_cpu_request`: CPU request a tortoise proposes.
+- `mercari.tortoise.proposed_memory_request`: memory request that a tortoise proposes.
+- `mercari.tortoise.proposed_hpa_minreplicas`: HPA `.spec.minReplicas` that a tortoise proposes.
+- `mercari.tortoise.proposed_hpa_maxreplicas`: HPA `.spec.maxReplicas` that a tortoise proposes.
+- `mercari.tortoise.proposed_hpa_utilization_target`: HPA `.spec.metrics[*].containerResource.target.averageUtilization` that a tortoise proposes.
+
+#### updateMode: `Auto`
+
+`Auto` is a update mode to let tortoise keep updating your workload or autoscaler to be optimized.
+
+#### updateMode: `Emergency`
+
+`Emergency` is a update mode to enable the emergency mode.
+Please refer to [Emergency mode](./emergency.md) for more details.
+
 ### `.spec.DeletionPolicy`
 
 ```yaml