Kubernetes resource requests and limits determine where workloads can run, how much capacity they reserve, and what happens when demand exceeds that capacity. This practical checklist explains CPU and memory behavior, provides reusable YAML examples, shows how to investigate OOMKilled containers with kubectl, and outlines a repeatable process for tuning values from observed metrics.
Overview
A container resource request is the amount of CPU or memory Kubernetes uses when scheduling a Pod. The scheduler compares requests with the remaining allocatable capacity on each node. A Pod can be scheduled only where its requests fit, even if its application is currently using less.
A limit is a boundary on container resource consumption. CPU limits generally result in throttling when a container attempts to use more CPU than allowed. Memory limits are different: memory cannot be throttled in the same way. When a container exceeds its memory limit, the kernel may terminate it, and Kubernetes commonly reports the result as OOMKilled.
Requests and limits are specified independently for each container. For a multi-container Pod, the effective Pod request and limit are based on the combined values of its containers. A sidecar, logging agent, or metrics container therefore affects both scheduling and capacity planning.
CPU and memory units
- CPU can be expressed in cores or millicores.
500mmeans half of one CPU core, while1means one core. - Memory is normally expressed with binary units such as
MiandGi. Use a consistent unit convention in manifests and dashboards. - A request is not a guaranteed performance level in every situation. It is a scheduling and accounting value, while actual performance also depends on node contention, application behavior, and limits.
Why the distinction matters
Requests that are too low can cause over-packing, contention, and unreliable capacity forecasts. Requests that are too high can leave usable node capacity stranded and may prevent Pods from being scheduled. Limits that are too low can cause CPU throttling or memory termination. Limits that are too high can allow a workload to consume capacity needed by other workloads, particularly when requests and limits differ substantially.
Resource settings also influence Kubernetes Quality of Service classification. Pods with matching CPU and memory requests and limits for every container can receive a higher QoS classification than Pods with partial or missing settings. During node pressure, QoS classification is one factor considered alongside actual usage and priority. Treat it as an operational signal, not as a substitute for sensible requests and limits.
Checklist by scenario
For a general web application
Start with measurements from representative traffic rather than copying values from another service. Set a request near the application's normal sustained usage, then set a limit that leaves room for ordinary bursts if your platform uses limits. For memory, leave enough headroom for the runtime, caches, request concurrency, and short-lived allocation spikes.
apiVersion: apps/v1
kind: Deployment
metadata:
name: web
spec:
replicas: 3
selector:
matchLabels:
app: web
template:
metadata:
labels:
app: web
spec:
containers:
- name: web
image: example/web:1.0
resources:
requests:
cpu: "250m"
memory: "256Mi"
limits:
cpu: "1"
memory: "512Mi"
Validate the application under realistic concurrency. If CPU throttling appears while latency rises, investigate the CPU limit and application workload together. If memory steadily grows over time, increasing the limit may delay failure without addressing a leak or unbounded cache.
For a batch job
Batch workloads often have predictable completion requirements but variable CPU demand. Set a memory request that covers the working set and a CPU request that reflects the desired share of node capacity. A CPU limit can prevent a job from affecting neighbors, but an unnecessarily tight limit may lengthen completion time.
apiVersion: batch/v1
kind: Job
metadata:
name: report-export
spec:
template:
spec:
restartPolicy: Never
containers:
- name: exporter
image: example/exporter:1.0
command: ["/app/export"]
resources:
requests:
cpu: "500m"
memory: "512Mi"
limits:
cpu: "2"
memory: "1Gi"
Check both successful and failed runs. A completed job can still have used too much capacity for the cluster's scheduling goals, and a failed job may have reached its memory limit only during a particular data shape or peak input size.
For a memory-sensitive service
Use a memory request based on the resident working set plus measured operational headroom. Account for language runtime behavior, native allocations, buffers, temporary files held in memory, and sidecars. Avoid treating a memory limit as a target. The application should remain healthy below the limit under expected peak conditions.
apiVersion: apps/v1
kind: Deployment
metadata:
name: api
spec:
replicas: 2
selector:
matchLabels:
app: api
template:
metadata:
labels:
app: api
spec:
containers:
- name: api
image: example/api:1.0
resources:
requests:
cpu: "300m"
memory: "768Mi"
limits:
cpu: "1"
memory: "1Gi"
For a sidecar-heavy Pod
List resource settings for every container, including proxies, log shippers, and exporters. Inspect the combined Pod footprint before changing the main application. A small sidecar multiplied across many replicas can become a significant part of cluster capacity.
For a workload using autoscaling
Review the metric used by the autoscaler and how requests affect its calculation. CPU utilization is commonly evaluated relative to a container's CPU request, so changing the request can change scaling behavior even when application traffic is unchanged. Check scale-up speed, scale-down stabilization, replica limits, and whether memory pressure is handled by a separate signal. Resource tuning and autoscaler tuning should be reviewed together.
Inspecting usage and diagnosing OOMKilled
Begin with the Pod's current and previous container state:
kubectl get pod <pod-name> -n <namespace> -o wide
kubectl describe pod <pod-name> -n <namespace>
kubectl get pod <pod-name> -n <namespace> -o jsonpath='{.status.containerStatuses[*]}'
Look for Last State, Reason: OOMKilled, restart counts, termination times, and recent Events. To view current usage, use:
kubectl top pod <pod-name> -n <namespace> --containers
kubectl top pods -n <namespace> --sort-by=memory
kubectl top nodes
The kubectl top commands depend on a working resource metrics provider and show a point-in-time view. They are useful for triage, but they do not replace historical monitoring. Compare usage with deployment changes, traffic, queue depth, request sizes, garbage-collection behavior, and application-level memory metrics.
An OOMKilled result does not always mean the entire node ran out of memory. A container can be killed after exceeding its own memory limit while the node still has capacity. Conversely, node-level memory pressure can lead to Pod eviction rather than a container-level OOMKilled status. Check both the container status and node events.
For a restarted container, retrieve earlier logs:
kubectl logs <pod-name> -n <namespace> -c <container-name> --previous
kubectl get events -n <namespace> --sort-by=.lastTimestamp
Use these commands to establish the symptom, then use historical monitoring and application profiling to identify the cause. Raising a limit is a valid short-term mitigation when the workload has a legitimate peak, but it should be followed by a capacity and behavior review.
What to double-check
- Node allocatable capacity: Compare total requests with allocatable CPU and memory, not the raw hardware size. System components and daemon workloads consume part of each node.
- Replica multiplication: Multiply per-Pod requests by the maximum expected replica count, including autoscaling limits.
- Rolling updates: Confirm that the deployment strategy can temporarily require old and new replicas at the same time.
- Init containers: Review their resource settings separately. Scheduling behavior can be affected by the largest relevant init-container requirement and by app-container totals.
- Sidecars: Measure proxy, logging, and telemetry overhead rather than assuming it is negligible.
- LimitRange and quotas: Namespace policies may apply defaults, enforce minimums, or cap resource usage. Inspect them before concluding that a manifest is the only source of effective values.
- Vertical and horizontal autoscaling: Make sure automated recommendations or adjustments do not conflict with manually maintained manifests or availability requirements.
- Probes and shutdown behavior: Resource pressure can cause slow startup or delayed responses. Review startup, readiness, and liveness probes so a transient resource problem does not create an avoidable restart loop. See the Kubernetes health checks checklist for a related review.
Common mistakes
- Copying requests from a different workload: Runtime, traffic, data size, and concurrency make resource profiles application-specific.
- Setting requests equal to limits without measurement: This can simplify policy, but it may reserve more capacity than the workload normally needs or make burst behavior less flexible.
- Raising memory limits indefinitely: A larger limit can conceal leaks, oversized caches, or unexpectedly large inputs while increasing the impact of failure.
- Ignoring CPU throttling: A service can show moderate average CPU usage while a restrictive limit causes short bursts to be throttled and latency to increase.
- Relying on one
kubectl topreading: Point-in-time usage misses peaks, rollout effects, and periodic jobs. - Inspecting only the application container: The Pod's sidecars and node-level agents also consume capacity.
- Changing values without checking scheduling: A larger request may cause Pending Pods if no node has enough allocatable capacity. Review events and placement constraints after each change.
When to revisit
Resource values should be treated as operational configuration, not permanent constants. Revisit them before seasonal planning cycles, after a meaningful traffic or data-volume change, when a new runtime or application version is deployed, and whenever workflows or cluster tools change.
Use this repeatable tuning checklist:
- Collect historical CPU and memory usage for normal, peak, and failure conditions.
- Record replica counts, sidecar overhead, node allocatable capacity, and rollout surge requirements.
- Compare sustained usage and peak usage with current requests and limits.
- Check for OOMKilled containers, CPU throttling, evictions, Pending Pods, and restart loops.
- Adjust one workload or one related setting at a time, preferably through version-controlled manifests.
- Observe autoscaler behavior, latency, completion time, and node utilization after the change.
- Document the reason, evidence, expected trade-off, and next review trigger.
Keep the investigation connected to the wider platform. A deployment change may expose resource problems, while a cluster capacity change may alter scheduling outcomes. For broader diagnosis, use the Kubernetes troubleshooting runbook. For container-level improvements, review Dockerfile best practices. The goal is not to find one universally correct number; it is to maintain resource settings that reflect observed workload behavior, available capacity, and the reliability requirements of the service.