Kubernetes resource requests and limits determine where pods can run, how much capacity the scheduler reserves, and what happens when a container uses more than its allocation. This practical checklist explains how to size CPU and memory, choose a QoS class, investigate OOMKilled pods and throttling, and verify changes with workload history instead of guesswork.
Overview
A resource request is the amount of CPU or memory Kubernetes uses when making scheduling decisions. A resource limit is the maximum a container is permitted to consume for that resource, subject to the behavior of the resource and the container runtime. Requests and limits are configured per container, although teams usually reason about the resulting pod totals.
CPU is measured in cores or millicores: 500m represents half a CPU core. Memory is commonly expressed in bytes such as Mi or Gi. Be consistent with units; Mi and MB are not interchangeable representations.
| Setting | What it affects | What to inspect |
|---|---|---|
| CPU request | Scheduler placement and reserved capacity | Typical use, startup bursts, and node capacity |
| Memory request | Scheduler placement and eviction priority | Working set, startup usage, and memory spikes |
| CPU limit | Upper bound for CPU consumption; excess can result in throttling | Throttling symptoms and latency sensitivity |
| Memory limit | Maximum memory allocation for the container; exceeding it can lead to an OOM kill | Heap, cache, native memory, and peak usage |
| Ephemeral-storage request or limit | Scheduling and enforcement for writable layers, logs, and temporary files | Container logs, /tmp, and scratch space |
Requests are not a promise that an application will receive exactly that amount at every moment. They are a planning and scheduling input. Likewise, a limit is not a substitute for application-level memory management. A Java heap, Node.js process, database cache, or native library may need its own sizing settings that leave room for the rest of the process.
A reusable sizing worksheet
- Record steady-state CPU and memory usage for each container.
- Record a high percentile from representative traffic, deployments, scheduled jobs, and cache-warming periods.
- Identify startup and short-lived spikes separately from sustained usage.
- Set the request near the capacity the workload needs for reliable scheduling and normal operation.
- Set the limit only where an upper bound is useful and understood.
- Run the workload under realistic traffic, then compare observed behavior with the assumptions.
Do not size a pod from a single dashboard sample. Include sidecars, exporters, service-mesh proxies, init containers, and temporary files. A pod with a small application container can still require substantial capacity when a proxy or logging sidecar is included.
Checklist by scenario
For a new service
- Define requests and limits for every application and sidecar container.
- Test the image and process under representative startup, steady-state, and peak conditions.
- Set memory requests high enough to avoid routine eviction or impossible scheduling assumptions.
- Decide whether a CPU limit is necessary. For latency-sensitive workloads, measure the effect of throttling before enforcing a tight ceiling.
- Confirm that health checks, rollout settings, and replica counts can tolerate the selected resources.
- Validate the manifest before deployment. The JSON, YAML, and TOML developer tools guide can help with formatting and basic configuration review.
For an OOMKilled container
- Confirm the termination reason with
kubectl describe podand inspect the container's previous logs withkubectl logs --previous. - Determine whether the container exceeded its memory limit or whether the node experienced memory pressure.
- Compare the limit with peak working-set usage, not just the average.
- Check application heap settings, caches, buffers, file descriptors, and native allocations.
- Look for changes in traffic, payload size, query behavior, batch size, or a memory leak.
- Increase the limit only after checking the node and namespace capacity. A larger limit may make the pod unschedulable or reduce room for other workloads.
- After changing values, observe several representative workload cycles and verify that restart counts and latency improve.
For CPU throttling or slow requests
- Compare CPU usage with the request and limit over the same time window.
- Check throttling metrics from your metrics stack, but confirm metric names and collection behavior for your Kubernetes and runtime versions.
- Separate genuine CPU saturation from application lock contention, downstream latency, garbage collection, or insufficient replicas.
- Raise the request when the workload needs more guaranteed scheduling capacity.
- Raise or remove a restrictive CPU limit only after testing its effect on noisy-neighbor protection and node-level capacity.
- Consider scaling policy. The Kubernetes HPA guide covers how resource signals and replica scaling fit together.
For Pending pods
- Read scheduler events with
kubectl describe podrather than assuming the cluster is simply out of CPU. - Check the sum of container requests, node allocatable capacity, taints, tolerations, affinity rules, topology constraints, and quotas.
- Inspect whether an init container has an unusually large request. For scheduling, Kubernetes considers init-container requirements alongside app-container requirements; the effective pod requirement is not always the simple average of all containers.
- Review whether a recent request increase was applied to every replica in a deployment.
- Confirm that a cluster autoscaler, if used, can add a compatible node shape and that the relevant node group has room to scale.
For capacity or cost review
- Group usage and requests by namespace, team, workload, and node pool.
- Find workloads with requests far above observed use and workloads regularly approaching their limits.
- Account for replicas, rolling-update surge, daemonsets, jobs, and disruption budgets.
- Review namespace
ResourceQuotaandLimitRangepolicies before changing application manifests. - Use gradual changes and record the reason, date, traffic conditions, and rollback threshold.
What to double-check
QoS classes
Kubernetes assigns a pod a quality-of-service class based on its resource configuration. A pod is typically Guaranteed when every container has CPU and memory requests and limits, and each request equals its corresponding limit. A pod is generally BestEffort when no container has requests or limits. Other configurations usually result in Burstable.
QoS is one input to resource-pressure behavior; it is not a performance guarantee. Under node pressure, eviction decisions also depend on how a pod's usage compares with its requests and on other Kubernetes conditions. Treat QoS as a useful classification, not a replacement for capacity planning or application testing.
Requests versus limits for memory
Memory is not compressible in the same way CPU is. If a container reaches its memory limit, the process may be terminated. If the node is under memory pressure, a pod can also be evicted even when the immediate symptom is not a container-level limit breach. Check both container events and node conditions.
Requests versus limits for CPU
CPU can be shared, but a limit can restrict bursts. A low CPU request can make scheduling look efficient while leaving the application with too little guaranteed capacity. A high request can reserve capacity that is rarely used and cause unrelated pods to remain pending. Use observed demand and latency objectives to choose a balance.
Autoscaling interactions
Resource requests influence scheduling and can also influence utilization-based autoscaling. Changing a request changes the denominator of a utilization percentage, so an HPA may scale differently even if application traffic has not changed. Recheck scaling behavior after changing requests, limits, container composition, or metrics adapters. Vertical autoscaling recommendations should be reviewed as guidance and tested through a controlled rollout rather than applied blindly.
Manifest example
resources:
requests:
cpu: "250m"
memory: "256Mi"
limits:
cpu: "1"
memory: "512Mi"The values above are examples, not universal defaults. Replace them with measurements from the actual process and its operating environment. If the pod includes a sidecar, define resources for that sidecar too.
Common mistakes
- Copying values between services: Similar images can have different traffic patterns, runtimes, caches, and startup behavior.
- Using averages as limits: Averages hide peaks and can turn normal bursts into OOMKills or throttling.
- Increasing memory limits without checking nodes: The new value may never fit on available nodes, or it may reduce safe headroom.
- Ignoring non-application containers: Proxies, log shippers, and exporters consume real resources.
- Assuming a request guarantees performance: A request guides placement; it does not remove contention inside the container or on the node.
- Tuning one replica during a rollout: Compare old and new versions, rollout surge, and replacement capacity.
- Relying on one metric: Pair CPU and memory usage with restarts, events, latency, throughput, garbage collection, and node pressure.
- Changing several controls at once: If requests, limits, replica counts, and autoscaling targets all change together, it becomes difficult to identify the cause of an improvement or regression.
When to revisit
Revisit Kubernetes resource requests and limits whenever the underlying workload changes, not only when a pod fails. Schedule a review before seasonal planning cycles, major traffic events, cluster resizing, or a move to a different node type. Recheck after changing the base image, runtime version, sidecars, service-mesh configuration, logging volume, cache policy, batch size, or autoscaling rules.
A practical review loop is:
- Collect representative history for CPU, memory, restarts, throttling, evictions, latency, and replica counts.
- Write down the current requests, limits, QoS class, node pool, and scaling configuration.
- Form one hypothesis, such as “memory peaks during cache warming” or “CPU limit causes request latency during bursts.”
- Change one workload or one controlled group of replicas.
- Observe normal and peak operating conditions, including deployment and rollback behavior.
- Keep the change, revert it, or record a follow-up experiment with an owner and review date.
Use this checklist alongside your deployment and infrastructure process. For broader operational context, see the CI/CD release checklist, Terraform state management guide, and Dockerfile best practices guide. The goal is not to find one permanent number; it is to keep resource assumptions visible, testable, and aligned with how the workload actually runs.