When usage reaches the CPU limit, the kernel throttles the container and degrades Quality of Service (QoS). CPU Burst dynamically detects throttling, adaptively adjusts container parameters, and can temporarily provide extra CPU during load bursts to relieve the CPU-limit bottleneck, improving QoS, especially for latency-sensitive applications.
To better understand this topic and use this feature, familiarize yourself with related concepts such as the CFS Scheduler and the node CPU management policy.
Why enable CPU Burst
Kubernetes clusters use the CPU limit to restrict the maximum amount of CPU resources that a container can use. This mechanism ensures fair resource allocation among containers and prevents a container from consuming excessive CPU resources, which would otherwise affect the performance of other containers.
CPU is a time-shared resource, which means that multiple processes or containers can share a CPU time slice. After you configure a CPU limit for a container, the operating system kernel uses the Completely Fair Scheduler (CFS) to control the CPU usage of the container in each scheduling period (cpu.cfs_period_us). The CPU time allowed in each period is defined by the CPU quota (cpu.cfs_quota_us). For example, if a container has a CPU limit of 4, the kernel allows it to use at most 400 ms of CPU time slices in each period. A scheduling period is typically 100 ms.
Benefits
CPU utilization is a key metric for measuring the running status of a container. Cluster administrators usually refer to this metric when they configure the CPU limit of a container. Compared with the commonly used second-level metrics, the CPU utilization of a container at the 100-millisecond level often shows more obvious spikes and reveals more instantaneous fluctuations. Take the following figure as an example: if you measure at the second level (the purple line), the CPU usage is clearly less than 4 cores; if you measure at the 100-millisecond level (the green line), the CPU usage of the container exceeds 4 cores during some periods. In this case, if you set the CPU limit to 4 cores, threads are suspended by the operating system because of CPU throttling.

The following figure shows how CPU resources are allocated to each thread (Thread) of a web service container with a CPU limit of 2 on a 4-core node after the container receives requests (req). The left figure shows the normal case, and the right figure shows the case after CPU Burst is enabled.
Even if the overall CPU utilization of the container in the last 1s is low, Thread 2 must still wait for the next scheduling period to finish processing req 2 because of CPU throttling, which increases the response time (RT) of the request. This is an important cause of the long-tail RT problem in containers. | After the CPU Burst feature is enabled, a container can accumulate CPU time slices when it is idle and use them to meet resource demands during bursts. This improves container performance and reduces latency. |
In addition to the preceding scenarios, CPU Burst also applies to scenarios in which the CPU resource demand of a container surges. For example, when business traffic suddenly increases, ack-koordinator can quickly resolve CPU resource bottlenecks within seconds while ensuring that the node-wide load stays at a safe level.
ack-koordinator adjustment involves only cfs quota in the node cgroup parameters and does not modify the CPU limit field in the Pod spec.
Scenarios
The typical scenarios of the CPU Burst feature are as follows:
Most of the time, the CPU resource usage of a container is lower than the configured CPU limit, but CPU throttling still occurs frequently and affects application performance. Enabling CPU Burst allows the container to use the accumulated time slices during load bursts, which effectively resolves CPU throttling and improves the Quality of Service (QoS) of the application.
A container application consumes a large amount of CPU resources during the startup and loading phase. After loading is complete and the application enters a stable running state, its CPU usage drops to a lower and stable level. After you enable CPU Burst, you do not need to configure an excessively high CPU limit for the container. The application can use more time slices during the startup phase, which ensures that the application starts quickly.
Billing
Installing or using the ack-koordinator component is free. However, you may incur costs in the following scenarios:
ack-koordinator is a non-managed component that consumes worker node resources after installation. You can configure resource requests for each module during installation.
By default, ack-koordinator exposes monitoring metrics for features such as resource profiling and fine-grained scheduling in Prometheus format. If you select the Enable Prometheus monitoring metrics for ack-koordinator option and use Managed Service for Prometheus, these metrics are billed as custom metrics. The fees vary based on factors such as cluster size and the number of applications. Before you enable this feature, we recommend reading Billing of Prometheus instances to understand the free tier and pricing for custom metrics. To monitor and manage your resource usage, use usage query.
Prerequisites
An ACK managed Pro cluster is created and its cluster version is 1.18 or later. For more information, see Create an ACK managed cluster and Manually upgrade a cluster.
NoteUse Alibaba Cloud Linux as the operating system. For more information, see Must I use Alibaba Cloud Linux to enable the CPU Burst policy?.
The ack-koordinator add-on is installed, and the add-on version is 0.8.0 or later. For more information, see ack-koordinator.
Configuration description
CPU Burst can be enabled for a specified Pod through a Pod Annotation, or at the cluster or namespace level through a ConfigMap.
Enable for a specified Pod through an Annotation
Configure the CPU Burst policy Annotation in the metadata field of the Pod YAML. The configuration takes effect for the specified Pod.
To apply configurations to a workload, such as a deployment, set the appropriate annotations for the pod in the template.metadata field.
annotations:
# Set to auto to enable CPU Burst for this Pod.
koordinator.sh/cpuBurst: '{"policy": "auto"}'
# Set to none to disable CPU Burst for this Pod.
koordinator.sh/cpuBurst: '{"policy": "none"}'Enable at the cluster level through a ConfigMap
By default, the CPU Burst policy configured through a ConfigMap takes effect for the entire cluster.
Use the following ConfigMap example to create a configmap.yaml file.
apiVersion: v1 data: cpu-burst-config: '{"clusterStrategy": {"policy": "auto"}}' #cpu-burst-config: '{"clusterStrategy": {"policy": "cpuBurstOnly"}}' #cpu-burst-config: '{"clusterStrategy": {"policy": "none"}}' kind: ConfigMap metadata: name: ack-slo-config namespace: kube-systemCheck whether a ConfigMap
ack-slo-configexists in the kube-system namespace.Exists: Update it by using a PATCH request to avoid affecting other configuration items in the ConfigMap.
kubectl patch cm -n kube-system ack-slo-config --patch "$(cat configmap.yaml)"Does not exist: Create the ConfigMap.
kubectl apply -f configmap.yaml
Enable at the namespace level through a ConfigMap
When you configure the CPU Burst policy for some Pods by specifying a namespace, the configuration takes effect for the specified namespace.
Use the following ConfigMap example to create a configmap.yaml file.
apiVersion: v1 kind: ConfigMap metadata: name: ack-slo-pod-config namespace: koordinator-system # You must manually create this namespace before first use. data: # Individually enable or disable the policy for Pods in specific namespaces. cpu-burst: | { "enabledNamespaces": ["allowed-ns"], "disabledNamespaces": ["blocked-ns"] } # The CPU Burst policy is enabled for all Pods in the allowed-ns namespace, with policy set to auto. # The CPU Burst policy is disabled for all Pods in the blocked-ns namespace, with policy set to none.Check whether a ConfigMap
ack-slo-configexists in the kube-system namespace.Exists: Update it by using a PATCH request to avoid affecting other configuration items in the ConfigMap.
kubectl patch cm -n kube-system ack-slo-config --patch "$(cat configmap.yaml)"Does not exist: Run the following command to create the ConfigMap.
kubectl apply -f configmap.yaml
Procedure
This example uses a web service application to compare access latency before and after the CPU Burst policy is enabled, and verifies the optimization effect of the CPU Burst policy.
Verification steps
Use the YAML content of the following example application to create a file named apache-demo.yaml.
Configure the Annotation in the
metadatafield of the Pod object to enable the CPU Burst policy for the Pod individually.apiVersion: v1 kind: Pod metadata: name: apache-demo annotations: koordinator.sh/cpuBurst: '{"policy": "auto"}' # Enable the CPU Burst policy. spec: containers: - command: - httpd - -D - FOREGROUND image: registry.cn-zhangjiakou.aliyuncs.com/acs/apache-2-4-51-for-slo-test:v0.1 imagePullPolicy: Always name: apache resources: limits: cpu: "4" memory: 10Gi requests: cpu: "4" memory: 10Gi nodeName: $nodeName # Set to the actual node name. hostNetwork: False restartPolicy: Never schedulerName: default-schedulerDeploy Apache HTTP Server as the target application for evaluation.
kubectl apply -f apache-demo.yamlUse the wrk2 load testing tool to send requests.
# Download the wrk2 open source testing tool, and then extract and install it. For more information, see https://github.com/giltene/wrk2. # The Gzip compression module is currently enabled in the Apache image configuration to simulate the compute logic that the server uses to process requests. # Run the load generation command, and remember to change the IP address to that of the target application. ./wrk -H "Accept-Encoding: deflate, gzip" -t 2 -c 12 -d 120 --latency --timeout 2s -R 24 http://$target_ip_address:8010/static/file.1m.testNoteChange the target address in the command to the IP address of the Apache Pod.
Adjust the queries per second (QPS) load on the request side by changing the
-Rparameter.
Result analysis
The following data shows the performance of Alibaba Cloud Linux and open-source CentOS, before and after the CPU Burst policy is enabled.
All disabled indicates that the CPU Burst policy is set to
none.All enabled indicates that the CPU Burst policy is set to
auto.
The following data is theoretical only. Actual results depend on your environment.
Alibaba Cloud Linux | All disabled | All enabled |
Apache RT-p99 | 107.37 ms | 67.18 ms (-37.4%) |
CPU Throttled Ratio | 33.3% | 0% |
Average Pod CPU utilization | 31.8% | 32.6% |
CentOS | All disabled | All enabled |
Apache RT-p99 | 111.69 ms | 71.30 ms (-36.2%) |
CPU Throttled Ratio | 33% | 0% |
Average Pod CPU utilization | 32.5% | 33.8% |
The preceding comparison data shows the following:
After CPU Burst is enabled, the p99 percentile of the application response time (RT) metric is significantly improved.
After CPU Burst is enabled, CPU throttling is substantially reduced, while the overall Pod CPU utilization remains basically unchanged.
Advanced parameter configuration
Configure the advanced parameters of the CPU Burst policy in a ConfigMap or in a Pod Annotation. For a parameter that is configured in both a Pod Annotation and a ConfigMap, the Pod Annotation configuration takes precedence over the ConfigMap configuration. If the Pod Annotation does not contain the corresponding configuration, ack-koordinator further refers to the namespace-level ConfigMap configuration. If the namespace level also does not contain the corresponding configuration, ack-koordinator uses the cluster-level ConfigMap configuration.
The following example shows the configuration.
# ConfigMap ack-slo-config example.
data:
cpu-burst-config: |
{
"clusterStrategy": {
"policy": "auto",
"cpuBurstPercent": 1000,
"cfsQuotaBurstPercent": 300,
"sharePoolThresholdPercent": 50,
"cfsQuotaBurstPeriodSeconds": -1
}
}
# Pod Annotation example.
koordinator.sh/cpuBurst: '{"policy": "auto", "cpuBurstPercent": 1000, "cfsQuotaBurstPercent": 300, "cfsQuotaBurstPeriodSeconds": -1}'The following are the advanced parameters related to the CPU Burst policy:
The Annotation and ConfigMap columns indicate whether a parameter can be configured through a Pod Annotation or through a ConfigMap, respectively. Specifically,
indicates that the configuration is supported, and
indicates that the configuration is not supported.
Parameter | Type | Description | Annotation | ConfigMap |
| string |
|
|
|
| int | The default value is The kernel-level CPU Burst elasticity of Alibaba Cloud Linux indicates the percentage by which CPU Burst is scaled up relative to the CPU limit. It corresponds to the Pod cgroup parameter For example, with the default configuration, |
|
|
| int | The default value is The maximum ratio by which the Pod cgroup parameter ( |
|
|
| int | The default value is When CFS quota elasticity is enabled, this parameter limits how long a Pod can continuously consume CPU at the upper limit ( |
|
|
| int | The default value is When CFS quota elasticity is enabled, this parameter specifies the safe node-wide CPU utilization threshold. After the threshold is exceeded, the cgroup parameter ( |
|
|
When you enable automatic CFS quota adjustment by setting
policytocfsQuotaBurstOnlyorauto, the parameter that corresponds to the Pod CPU limit on the node (cpu.cfs_quota_us) is dynamically adjusted based on CPU throttling.When you stress test a Pod, we recommend that you also monitor the CPU usage of the Pod, or temporarily disable automatic CFS quota adjustment by setting
policytocpuBurstOnlyornone, to maintain better resource elasticity in the production environment.
FAQ
If I already use CPU Burst through the earlier ack-slo-manager protocol, is it still supported after I upgrade to ack-koordinator?
The earlier Pod protocol requires you to specify alibabacloud.com/cpuBurst in the Annotation. ack-koordinator is fully compatible with this earlier protocol, so you can seamlessly upgrade the add-on to the new version.
ack-koordinator was compatible with the earlier protocol only until July 30, 2023. Promptly upgrade the resource fields of the earlier protocol to the new version.
ack-koordinatorsupports the protocols in the following versions:
ack-koordinator Version | alibabacloud.com protocol | koordinator.sh protocol |
≥0.2.0 | Supported | Not supported |
≥0.8.0 | Supported | Supported |
Why does CPU throttling still occur on a Pod after the CPU Burst configuration is enabled?
Common causes and corresponding adjustments are as follows.
An incorrect configuration format prevents the CPU Burst policy from taking effect. Modify and verify the configuration by following Advanced parameter configuration.
CPU throttling still occurs when CPU utilization reaches the upper limit configured by
cfsQuotaBurstPercentbecause CPU resources are insufficient.Adjust the CPU requests and limits based on your application's actual requirements.
The CPU Burst policy adjusts two cgroup parameters of a Pod:
cpu.cfs_quota_usandcpu.cfs_burst_us. For more information, see Advanced parameter configuration. Thecpu.cfs_quota_usparameter is set only after ack-koordinator detects CPU throttling, so there is a slight delay. Thecpu.cfs_burst_usparameter is set directly based on the configuration and takes effect more quickly.Use Alibaba Cloud Linux for better results.
The CPU Burst policy has a protection mechanism when it adjusts
cpu.cfs_quota_us: the safe node-wide CPU utilization threshold configured bysharePoolThresholdPercent. When overall node utilization is too high,cpu.cfs_quota_usis reset to its initial value to prevent a single Pod from causing further disruption.Set the safe node-wide CPU utilization threshold based on the actual requirements of your application to prevent high overall node utilization from affecting application performance.
Must I use Alibaba Cloud Linux to enable the CPU Burst policy?
ack-koordinator supports the CPU Burst policy on all Alibaba Cloud Linux and open-source CentOS kernels. We recommend Alibaba Cloud Linux. With Alibaba Cloud Linux kernel features, ack-koordinator can provide a more fine-grained CPU elasticity management mechanism. For more information, see Enable CPU Burst on the cgroup v1 interface.
Why does the number of threads obtained by application code change after CPU Burst is enabled?
This is because the way CPU Burst works conflicts with the way some applications obtain system resources. ack-koordinator dynamically adjusts the container's underlying cgroup parameter cpu.cfs_quota_us when it implements CPU Burst. This value represents the CPU time quota available to the container in the current scheduling period. ack-koordinator dynamically scales this quota based on the application load.
Many applications (such as Java's Runtime.getRuntime().availableProcessors()) directly read cpu.cfs_quota_us to estimate the number of available CPU cores. Therefore, when the CPU quota is dynamically adjusted, the number of cores obtained by the application also changes. Parameters that depend on this value, such as the thread pool size, become unstable.
Applications should rely on the fixed limits.cpu value defined in the Pod.
Inject an environment variable: Use
resourceFieldRefto inject the Podlimits.cpuvalue into the container as an environment variable.env: - name: CPU_LIMIT valueFrom: resourceFieldRef: resource: limits.cpuModify application code: Change the application startup logic so that it reads
CPU_LIMITfirst when calculating and setting the thread pool size. After configuration, the application runs based on a stable and reliable value regardless of how CPU Burst adjusts the quota.

