All Products
Search
Document Center

Container Service for Kubernetes:Enable the CPU Burst performance optimization policy

Last Updated:Oct 23, 2026

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.

Note

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.

How it works

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.ack-slo-manager example.png

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. CPU Burst.png

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.

Note

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

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.

Note

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.

  1. 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-system
  2. Check whether a ConfigMap ack-slo-config exists 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.

  1. 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.
  2. Check whether a ConfigMap ack-slo-config exists 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

  1. Use the YAML content of the following example application to create a file named apache-demo.yaml.

    Configure the Annotation in the metadata field 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-scheduler
  2. Deploy Apache HTTP Server as the target application for evaluation.

    kubectl apply -f apache-demo.yaml
  3. Use 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.test
    Note
    • Change 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 -R parameter.

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.

Important

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:

Note

The Annotation and ConfigMap columns indicate whether a parameter can be configured through a Pod Annotation or through a ConfigMap, respectively. Specifically, Supported indicates that the configuration is supported, and Not supported indicates that the configuration is not supported.

Parameter

Type

Description

Annotation

ConfigMap

policy

string

  • none (default value): disables the CPU Burst policy, and the related parameters are restored to the initial values set at creation.

  • cpuBurstOnly: enables only the kernel-level CPU Burst elasticity of Alibaba Cloud Linux.

  • cfsQuotaBurstOnly: enables only the automatic Completely Fair Scheduler (CFS) quota elasticity, and supports all kernel versions.

  • auto: adaptively enables both of the preceding elasticity capabilities, including the Alibaba Cloud Linux kernel feature and the automatic CFS quota elasticity.

Supported

Supported

cpuBurstPercent

int

The default value is 1000, in percent.

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 cpu.cfs_burst_us. For more information, see Enable CPU Burst on the cgroup v1 interface.

For example, with the default configuration, CPU Limit = 1 corresponds to a cpu.cfs_quota_us value of 100,000, and cpu.cfs_burst_us is raised tenfold to 1,000,000.

Supported

Supported

cfsQuotaBurstPercent

int

The default value is 300, in percent.

The maximum ratio by which the Pod cgroup parameter (cpu.cfs_quota_us) can be raised when CFS quota elasticity is enabled. The default value is 3 times.

Supported

Supported

cfsQuotaBurstPeriodSeconds

int

The default value is -1, which means unlimited, in seconds.

When CFS quota elasticity is enabled, this parameter limits how long a Pod can continuously consume CPU at the upper limit (cfsQuotaBurstPercent). After an individual Pod exceeds the time limit, its increased cgroup parameter (cpu.cfs_quota_us) is restored to its original value. Other Pods are unaffected.

Supported

Supported

sharePoolThresholdPercent

int

The default value is 50, in percent.

When CFS quota elasticity is enabled, this parameter specifies the safe node-wide CPU utilization threshold. After the threshold is exceeded, the cgroup parameter (cpu.cfs_quota_us) of all Pods on the node whose quota was increased is restored to the initial value set at creation.

Not supported

Supported

Note
  • When you enable automatic CFS quota adjustment by setting policy to cfsQuotaBurstOnly or auto, 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 policy to cpuBurstOnly or none, 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.

Note

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 cfsQuotaBurstPercent because 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_us and cpu.cfs_burst_us. For more information, see Advanced parameter configuration. The cpu.cfs_quota_us parameter is set only after ack-koordinator detects CPU throttling, so there is a slight delay. The cpu.cfs_burst_us parameter 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 by sharePoolThresholdPercent. When overall node utilization is too high, cpu.cfs_quota_us is 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.

  1. Inject an environment variable: Use resourceFieldRef to inject the Pod limits.cpu value into the container as an environment variable.

    env: 
      - name: CPU_LIMIT 
        valueFrom: 
          resourceFieldRef: 
            resource: limits.cpu
  2. Modify application code: Change the application startup logic so that it reads CPU_LIMIT first 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.