Kubernetes resource requests and limits influence scheduling, autoscaling, performance, and failure behavior. This practical checklist explains how to size CPU and memory, interpret throttling and OOMKilled events, identify QoS classes, and roll out changes without guessing.
Overview
A resource request is the amount Kubernetes uses when deciding where a Pod can run. A resource limit is a ceiling enforced for a container. Requests affect placement and, in common Horizontal Pod Autoscaler configurations, utilization calculations. Limits affect runtime behavior: a container that reaches its CPU limit may be throttled, while a container that exceeds its memory limit may be terminated and reported as OOMKilled.
Requests and limits are configured per container, but scheduling considers the total requested resources for the Pod. Include application containers, sidecars, and relevant init-container behavior when reviewing a workload. A value that looks reasonable for the main process can still produce an under-sized Pod if a proxy, telemetry agent, or log sidecar is omitted from the worksheet.
Use this basic sizing worksheet for each workload:
- Record CPU and memory usage during normal traffic, peak traffic, deployments, cache warming, and batch activity.
- Separate steady-state usage from short-lived bursts.
- Choose a CPU request that represents the capacity the container normally needs to receive predictable scheduling.
- Choose a memory request above the observed working set, with room for expected variation and runtime overhead.
- Set limits only after deciding whether you need a hard boundary, controlled sharing, or protection from noisy neighbors.
- Test the values under representative load before applying them broadly.
There is no universal request-to-limit ratio. A latency-sensitive service, a batch worker, and a memory-heavy cache have different failure modes. Treat the values as operational settings that should be measured and revisited, not permanent application constants.
Checklist by scenario
When a Pod is Pending
- Inspect scheduling events with
kubectl describe pod <pod>. - Compare the Pod's total CPU and memory requests with allocatable capacity on eligible nodes.
- Check node selectors, affinity, taints, and tolerations before lowering resources.
- Confirm that a large request is not preventing placement even though average usage is low.
- Review whether a namespace quota or limit range is injecting or restricting values.
When CPU is throttled or latency rises
- Confirm whether the container has a CPU limit and whether throttling increases during the incident.
- Compare CPU usage, request, limit, and application latency over the same time window.
- Check whether the request is too low for the service's normal demand, causing poor placement or autoscaler behavior.
- Distinguish a CPU limit from a node-wide capacity problem; raising a limit will not create capacity on a saturated cluster.
- Test changes with a canary or small deployment slice before changing every replica.
CPU is compressible: a container can usually continue running while receiving less CPU time. Throttling can nevertheless increase queueing and tail latency. If a strict CPU ceiling is not required, evaluate the operational reason for the limit rather than copying a default into every manifest.
When a container is OOMKilled
- Check the container's last state and restart count using
kubectl describe pod <pod>. - Review Pod events and node memory pressure; do not assume every memory failure has the same cause.
- Compare the memory limit with peak working-set usage, not only a long-term average.
- Look for unbounded caches, queues, request bodies, concurrency, leaks, or runtime heap settings.
- Check all containers in the Pod, including sidecars and exporters.
- Increase the limit only alongside an investigation of why usage grew.
Memory is not compressible in the same way as CPU. Once a container reaches its enforced memory boundary, termination is a possible outcome. Raising the limit can prevent a repeat only if the node and namespace have enough capacity and the growth is understood. Otherwise, it can move the failure from one container to node pressure or make recovery slower.
When autoscaling behaves unexpectedly
- Verify that requests are present and realistic for every container included in the utilization calculation.
- Remember that utilization is commonly evaluated relative to the request; lowering a request can make the same usage appear as a higher percentage.
- Compare HPA decisions with actual traffic, queue depth, latency, and saturation signals.
- Review VPA, HPA, cluster autoscaler, and admission-policy interactions before allowing multiple systems to change the same values.
- Check rollout and stabilization behavior so a resource change is not mistaken for an autoscaling fix.
When choosing a QoS class
Kubernetes assigns a Pod a QoS class based on its resource configuration:
| Class | Typical configuration | Review point |
|---|---|---|
| Guaranteed | Each container has CPU and memory requests equal to its limits. | Provides a strict envelope, but can reserve substantial capacity and still fail if the limit is too low. |
| Burstable | At least one relevant request or limit is set, but the Pod does not meet Guaranteed conditions. | Often useful for services that need a baseline plus controlled variation. |
| BestEffort | No CPU or memory requests or limits are set. | Appropriate only when the workload can tolerate weak placement and eviction priority. |
QoS is not a replacement for capacity planning. Use it as one signal when reasoning about eviction and resource pressure, and confirm behavior against the Kubernetes version and runtime configuration used by your cluster.
What to double-check
- Metrics definition: Verify whether your dashboard shows usage, working set, RSS, throttled time, or another measurement. Different metrics answer different sizing questions.
- Time window: A five-minute average can hide a deployment spike or a periodic batch job. Inspect peaks and percentiles where available.
- Pod composition: Add every container and account for init-container resource behavior when interpreting scheduling and startup failures.
- Node allocatable capacity: Requests are compared with capacity available to workloads, not the node's raw physical total.
- Runtime and kernel details: cgroups, container runtime behavior, and node-level eviction settings can affect how limits and pressure appear. Validate assumptions in the actual environment.
- Application settings: Align JVM, Go, Node.js, Python, cache, worker, and connection-pool settings with the container's memory and CPU envelope.
- Rollout safety: Check readiness probes, PodDisruptionBudgets, surge settings, and available spare capacity before changing every replica.
Useful first commands include kubectl get pod <pod> -o yaml, kubectl describe pod <pod>, and kubectl top pod when the metrics pipeline supports it. Combine these with time-series dashboards and application logs; a point-in-time command rarely explains a recurring incident by itself. For a broader failure workflow, see the Kubernetes Pod Troubleshooting Decision Tree.
Common mistakes
- Copying one value everywhere: Workload profiles differ. A web API, worker, controller, and cron-style job should not automatically share a template.
- Using averages for memory: Memory peaks matter because memory cannot be safely throttled like CPU.
- Setting very high requests “for safety”: This can leave capacity stranded and create Pending Pods even when observed usage is modest.
- Removing all limits to stop OOMKilled events: This may hide the immediate symptom while increasing the risk of node contention. Investigate growth and capacity first.
- Lowering requests to force autoscaling: This changes utilization percentages and scheduling decisions, not the application's actual demand.
- Ignoring sidecars: A proxy or telemetry container can consume enough resources to change QoS, placement, and failure behavior.
- Changing resources during an incident without a rollback: Record the previous manifest, define success criteria, and make one controlled change at a time.
If a resource incident is part of a larger release or cluster change, pair this review with the Kubernetes Upgrade Readiness Checklist and keep an operational response plan linked to your alerts using the Production Alert Runbook Template.
When to revisit
Review requests and limits before seasonal planning cycles, capacity reviews, major releases, and planned changes to autoscaling or node pools. Revisit them sooner after an OOMKilled event, repeated CPU throttling, a change in traffic shape, a new sidecar, a runtime upgrade, or a significant change to cache size, concurrency, or batch volume.
Use this repeatable workflow:
- Export recent usage and failure data for normal and peak periods.
- Write down the proposed request, limit, QoS outcome, and expected scheduling effect.
- Test the change in a representative environment or with a small production slice.
- Watch restarts, throttling, latency, queue depth, node pressure, and autoscaler decisions.
- Keep or revert the change based on defined thresholds, then document the evidence and next review date.
Resource tuning works best as a feedback loop: measure, change narrowly, observe, and record what you learned. That habit makes Kubernetes troubleshooting faster when workloads, tools, or operating conditions change.