Kubernetes resource requests and limits determine where workloads can run, how autoscaling behaves, and what happens when a node or container runs short of capacity. This guide provides a repeatable sizing worksheet, YAML examples, monitoring queries, and scenario-based checks for setting CPU and memory values without reserving unnecessary capacity or inviting avoidable failures.
Overview
A request is the amount of CPU or memory Kubernetes uses when scheduling a Pod. It is a planning value: the scheduler looks for a node with enough allocatable capacity to satisfy the requests of the Pod. A limit is an upper boundary enforced while a container runs.
- CPU requests influence placement and are commonly used as the denominator for HPA utilization calculations.
- Memory requests influence placement and help Kubernetes make eviction decisions when a node experiences memory pressure.
- CPU limits can cause throttling when a container tries to use more CPU than its limit during a scheduling period.
- Memory limits are enforced by the Linux kernel through cgroups. A container that exceeds its limit may be terminated and reported as
OOMKilled.
Requests and limits are set per container, although capacity planning must consider the total for every container in the Pod. A sidecar, service-mesh proxy, log collector, or metrics agent can materially change the Pod's resource profile.
Reference table
| Situation | What Kubernetes does | What to inspect |
|---|---|---|
| Request is larger than available node capacity | The Pod remains Pending until a suitable node is available or scheduling constraints change. | kubectl describe pod, node allocatable capacity, taints, affinity, and other requests. |
| CPU usage reaches the limit | The container may be throttled rather than terminated. | CPU throttling metrics, latency, saturation, and the container's CPU limit. |
| Memory usage reaches the limit | The container may be terminated with an OOMKilled reason. | Container status, restart count, working-set or RSS trends, and recent workload changes. |
| Node runs short of memory | The kubelet may evict Pods according to node pressure and eviction behavior. | Node conditions, events, Pod QoS, requests, priority, and actual memory use. |
| Requests and limits are configured for every container | The Pod can receive the Guaranteed or Burstable QoS class depending on whether values match. | kubectl get pod -o jsonpath='{.status.qosClass}'. |
QoS class is useful context, not a substitute for capacity planning. A Pod is generally Guaranteed when every container has CPU and memory requests and limits, and each request equals its corresponding limit. A Pod is BestEffort when no container has requests or limits. Other configured Pods are Burstable. Exact eviction outcomes also depend on node pressure, Pod priority, and how far actual usage exceeds requests.
Checklist by scenario
For a new production workload
- Define the workload's normal, peak, and startup behavior. Record whether memory grows with concurrency, whether CPU spikes during initialization, and whether background jobs share the container.
- Separate application containers from sidecars. Measure or estimate each container instead of copying one value across the whole Pod.
- Set an initial request near a sustainable baseline that permits reliable scheduling. Set the limit based on tested burst behavior and the failure cost of unrestricted growth.
- Run a representative load test, including cold starts, cache warm-up, retries, and the largest expected request or batch.
- Check the result with the application's latency, error, and saturation objectives. Resource usage alone does not prove that a value is safe.
For a workload with OOMKilled containers
- Confirm the termination reason rather than assuming every restart is an out-of-memory event:
kubectl describe pod <pod>andkubectl get pod <pod> -o jsonpath='{.status.containerStatuses[*].lastState.terminated.reason}'. - Compare the memory limit with the container's observed working set, heap, native allocations, temporary files, and sidecar usage.
- Check whether the process has a leak, unbounded queue, excessive concurrency, or a cache that should be bounded. Raising the limit can hide the symptom while increasing node risk.
- Raise the limit only after testing the expected peak, and raise the request enough to make placement realistic. Then verify that the node pool has sufficient allocatable memory.
Before enabling HPA
- Ensure the target container has a meaningful CPU request if CPU utilization is the scaling signal. Utilization is commonly calculated relative to the request, so an inaccurate request distorts scaling behavior.
- Choose a metric that represents demand. CPU may be appropriate for compute-bound services; queue depth, request rate, or latency may better represent other workloads.
- Check startup and readiness behavior so new replicas do not receive traffic before they are ready. The Kubernetes health checks checklist is useful for this review.
- Allow for replica startup time, stabilization, and the capacity needed for a scale-out event.
Before using VPA
- Run recommendation-only or observation-oriented workflows first where your platform supports them.
- Review whether applying recommendations will restart Pods, conflict with HPA signals, or interact with disruption budgets and availability requirements.
- Use separate CPU and memory policies when their behavior differs. Memory growth often requires more cautious investigation than CPU variation.
- Test changes in a staging or controlled production segment before broad rollout.
What to double-check
Build a sizing worksheet
For each container, record the following values from a representative observation window:
| Field | Example question |
|---|---|
| Baseline CPU | What is the usual usage when the service is healthy and handling normal traffic? |
| Peak CPU | What happens during startup, bursts, batch work, and failover? |
| Baseline memory | Does memory stabilize, or does it continue to grow with traffic or uptime? |
| Peak memory | What is the highest value during a tested workload, including caches and concurrency? |
| Request | Is the reserved amount high enough for reliable scheduling but low enough to avoid artificial fragmentation? |
| Limit | Can the application tolerate throttling or termination at this boundary? |
| Confidence | Are these measurements from production-like traffic, or are they provisional estimates? |
Use a documented margin rather than an unexplained large buffer. For example, you might choose a request around a measured sustainable level and a higher limit for a tested CPU burst. For memory, be conservative about adding headroom and investigate growth patterns before selecting a limit. The right margin depends on workload variability, node size, availability objectives, and the consequences of eviction or restart.
Example manifest
apiVersion: apps/v1
kind: Deployment
metadata:
name: api
spec:
replicas: 3
template:
spec:
containers:
- name: api
image: example/api:1.0.0
resources:
requests:
cpu: "250m"
memory: "512Mi"
limits:
cpu: "1000m"
memory: "1Gi"
readinessProbe:
httpGet:
path: /ready
port: 8080
This is an example structure, not a universal recommendation. A request of 250m means one quarter of a CPU core, while 512Mi is a binary memory unit. Validate values against measurements and the resource profile of the actual image and runtime.
Use the right measurement source
kubectl top is convenient for a current view when Metrics Server is installed, but it is not a historical capacity-planning system. Use Prometheus or another time-series system for percentiles, trends, deployment comparisons, and peak analysis. Query names and label sets vary by metrics pipeline, so confirm them in your environment before using an alert or dashboard.
# Current usage, if Metrics Server is available
kubectl top pod -n production --containers
# Illustrative PromQL: CPU usage by container
sum by (namespace, pod, container) (
rate(container_cpu_usage_seconds_total{namespace="production",container!=""}[5m])
)
# Illustrative PromQL: memory working set by container
container_memory_working_set_bytes{namespace="production",container!=""}
Compare usage with requests and limits, not just with node capacity. Also check allocatable capacity: system reservations, DaemonSets, and platform agents reduce what application Pods can use.
Common mistakes
- Copying values from another service. Similar code can have different traffic, runtime, cache, and concurrency profiles.
- Setting every limit equal to the request. This may simplify predictability, but it can unnecessarily prevent safe CPU bursts and does not automatically make memory safe.
- Leaving requests unset. The scheduler then has less information, and HPA resource utilization signals may be unusable or misleading.
- Using a very high memory limit as a leak fix. The process may run longer before failing while consuming capacity needed by other workloads.
- Ignoring sidecars and init containers. Init containers affect scheduling requirements, and long-running sidecars consume resources throughout the Pod's life.
- Confusing throttling with OOMKilled. CPU pressure generally appears as throttling and latency; memory-limit breaches can terminate the container. The investigation and remedy are different.
- Changing values without observing rollout impact. New requests can make Pods Pending, while new limits can change latency, restarts, or node pressure.
- Assuming every managed Kubernetes platform behaves identically. Node sizing, system reservations, autoscaler settings, metrics availability, admission policies, and default limit behavior can differ. Verify platform-specific documentation and inspect the live cluster.
When to revisit
Resource sizing is an operating practice, not a one-time manifest decision. Recalculate values before seasonal planning cycles, after a traffic or architecture change, and whenever a workload is moved to a different node pool or managed platform. Revisit them after an OOMKilled event, repeated CPU throttling, unexplained latency, Pod evictions, or a change to runtime, image, sidecar, cache, or concurrency settings.
A practical monthly review can be short:
- Export the latest CPU and memory percentiles for each production container.
- Compare them with requests, limits, HPA targets, restart counts, and Pending or evicted Pod events.
- Identify workloads with consistently low requests, high throttling, memory growth, or large unused reservations.
- Propose one controlled adjustment at a time, record the reason, and observe the next rollout.
- Update dashboards and runbooks so the reasoning survives team and platform changes.
Use this checklist again before enabling HPA or VPA and after significant Kubernetes or autoscaler changes. For broader operational preparation, pair the review with a Kubernetes cluster upgrade checklist and your service's SLO and error budget targets. The goal is not to find one perfect number; it is to keep requests, limits, autoscaling, and observed workload behavior aligned as the system changes.