How to Fix Kubernetes CPU Throttling

In this tutorial, you'll learn about How to Fix Kubernetes CPU Throttling. We cover key concepts, practical examples, and best practices.

The Problem

Your application is slow even though CPU usage seems low. Metrics show high throttled_time or the application experiences periodic latency spikes. Kubernetes CPU limits using CFS Completely Fair Scheduler quota can throttle containers even when the node has idle CPU.

Quick Fix

Fix 1: Check CPU Throttling

kubectl exec pod -- cat /sys/fs/cgroup/cpu.stat
# nr_periods 10000
# nr_throttled 5000
# throttled_time 15000000000
# (50% of periods were throttled — severe throttling)

Or use kubectl top:

kubectl top pod my-app
# NAME      CPU(cores)   MEMORY(bytes)
# my-app    150m         256Mi
# (uses 150m out of 200m limit — but throttling still occurs)

Fix 2: Remove CPU Limits (Burstable QoS)

WRONG — setting low CPU limits that cause throttling:

resources:
  requests:
    cpu: "200m"
  limits:
    cpu: "200m"    # container is throttled as soon as it exceeds 200m

RIGHT — set only requests (Burstable QoS, no throttling):

resources:
  requests:
    cpu: "200m"
  # no limits — container can burst to use idle CPU

This creates a Burstable pod that can use available CPU when the node is not busy.

Fix 3: Increase CPU Limits

If you need limits for fairness, set them high enough:

resources:
  requests:
    cpu: "200m"
  limits:
    cpu: "500m"    # allow bursts up to 0.5 core

Fix 4: Disable CFS Quota (kubelet flag)

On cluster level (for nodes where you trust the workloads):

# /var/lib/kubelet/config.yaml
cpuCFSQuota: false
# (disables CPU throttling entirely, but pods can starve each other)

Restart kubelet:

sudo systemctl restart kubelet

Fix 5: Use Guaranteed QoS Class (Equal Requests and Limits)

resources:
  requests:
    cpu: "1"
    memory: "512Mi"
  limits:
    cpu: "1"
    memory: "512Mi"

This gives the pod Guaranteed QoS — it is never throttled unless the entire node is overcommitted. Set the values to match the application's typical peak usage.

Fix 6: Reduce Thread Count

Applications with many threads compete for the same CPU quota:

# Java example: reduce thread pool size
-Djava.util.concurrent.ForkJoinPool.common.parallelism=2

Fix 7: Monitor Throttling Metrics

# Using Prometheus:
rate(container_cpu_cfs_throttled_seconds_total[5m])
# > 0.1 means the container is being throttled

Use DodaTech's CPU Performance Analyzer to visualize throttling events, recommend optimal CPU limits, and detect noisy neighbor issues in your cluster.

Prevention

• Consider omitting CPU limits for burstable workloads.
• Monitor container_cpu_cfs_throttled_seconds_total in Prometheus.
• Use Guaranteed QoS for latency-sensitive applications.
• Set CPU requests equal to the application's steady-state usage.
• Test application performance under different CPU limits during staging.

Common Mistakes with cpu throttling

1. Using head and tail instead of pattern matching, causing runtime errors on empty lists
2. Forgetting that lazy evaluation defers computation until the value is forced, causing space leaks with unevaluated thunks
3. Using return to exit a function early instead of wrapping a pure value in the monad

These mistakes appear frequently in real-world K8S code. DodaTech's contributors have identified these patterns through analysis of open-source projects and production systems.

Practice Exercise

Write a pure function that safely divides two integers using Maybe, then test it with edge cases like division by zero and negative numbers.

This exercise reinforces the concepts covered in this guide. Try implementing it before checking online solutions.

FAQ