diff --git a/docs/user-guide.md b/docs/user-guide.md index 65670de7..eaac200e 100644 --- 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