Kubernetes 1.37 Pod-Level Resources Explained with a Real Example

Kubernetes normally lets us define CPU and memory requests and limits for individual containers.

For example:

resources:
  requests:
    cpu: "500m"
    memory: "256Mi"
  limits:
    cpu: "1"
    memory: "512Mi"

This works well for many applications. However, some workloads are not really about one container. They are about several containers working together inside the same Pod.

A common example is an application container with a sidecar.

Pod
|
+-- Application container
|
+-- Sidecar container

The application may need more CPU at one moment, while the sidecar needs more CPU at another moment.

Historically, Kubernetes resource configuration has been primarily container-focused. Newer Kubernetes releases have introduced a Pod-level resource model that allows resources to be defined for the Pod as a whole.

Kubernetes 1.37 makes this capability particularly relevant for teams working with multi-container Pods and workloads where resource sharing between containers is useful.

The key idea is simple:

Instead of describing only how much CPU and memory each container can use, you can describe a resource budget for the entire Pod.

What Is a Pod in Kubernetes?

A Pod is the basic deployable unit in Kubernetes.

A Pod can contain one or more containers that share the same network namespace and can share storage volumes.

For example:

apiVersion: v1
kind: Pod
metadata:
  name: orders
spec:
  containers:
    - name: api
      image: my-orders-api
    - name: logging
      image: my-log-sidecar

This Pod contains two containers:

orders Pod
|
+-- api
|
+-- logging

The containers are separate processes, but Kubernetes manages them as part of the same Pod.

This distinction becomes important when configuring resources.

Container-Level Resources

The traditional model defines resources on each container.

For example:

apiVersion: v1
kind: Pod
metadata:
  name: orders
spec:
  containers:
    - name: api
      image: my-orders-api
      resources:
        requests:
          cpu: "500m"
          memory: "256Mi"
        limits:
          cpu: "1"
          memory: "512Mi"

    - name: logging
      image: my-log-sidecar
      resources:
        requests:
          cpu: "100m"
          memory: "64Mi"
        limits:
          cpu: "200m"
          memory: "128Mi"

The API container has its own CPU and memory configuration.

The logging container has a separate configuration.

This gives the platform a clear resource configuration for every container.

Why Pod-Level Resources Are Useful

Imagine the application container normally needs:

CPU: 500m
Memory: 256Mi

while the sidecar normally needs:

CPU: 100m
Memory: 64Mi

But their usage changes throughout the day.

At one point:

API      -> 800m CPU
Sidecar  -> 50m CPU

Later:

API      -> 400m CPU
Sidecar  -> 180m CPU

A strict container-level configuration can limit each container independently even though the combined Pod has enough capacity.

Pod-level resources provide a way to describe the total resource budget at the Pod level.

This can be useful for tightly coupled containers that are designed to work together.

Pod-Level Resource Configuration

The Pod-level resource model uses a resources field at the Pod specification level.

A simplified example looks like this:

apiVersion: v1
kind: Pod
metadata:
  name: orders
spec:
  resources:
    requests:
      cpu: "1"
      memory: "512Mi"
    limits:
      cpu: "2"
      memory: "1Gi"

  containers:
    - name: api
      image: my-orders-api

    - name: logging
      image: my-log-sidecar

Here, the resource configuration describes the Pod as a whole.

The Pod has:

CPU request:  1 CPU
CPU limit:    2 CPU

Memory request: 512Mi
Memory limit:   1Gi

The two containers operate inside that Pod-level resource budget.

The exact behavior depends on the resource type and the Kubernetes configuration, so teams should validate the feature against their cluster version and workload before adopting it broadly.

A Realistic Application Example

Consider an API Pod with:

• A main application container

• A metrics sidecar

The YAML could look like this:

apiVersion: v1
kind: Pod
metadata:
  name: payment-api
spec:
  resources:
    requests:
      cpu: "750m"
      memory: "512Mi"
    limits:
      cpu: "2"
      memory: "1Gi"

  containers:
    - name: application
      image: payment-api:1.0

    - name: metrics
      image: metrics-agent:1.0

The application and metrics agent share the Pod's resource budget.

This model can be useful when the two containers are part of one logical workload and their CPU usage varies over time.

Requests and Limits Are Different

It is important to understand the difference between a request and a limit.

Resource Request

A request represents the amount of resource Kubernetes uses when making scheduling decisions.

For example:

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

The scheduler uses this information when deciding where the Pod can run.

Resource Limit

A limit represents an upper bound on resource usage under the applicable Kubernetes and runtime behavior.

For example:

limits:
  cpu: "2"
  memory: "1Gi"

Requests and limits should not be treated as the same thing.

A simple way to remember it is:

Request -> scheduling requirement
Limit   -> usage boundary

Pod-Level vs Container-Level Resources

The two models solve slightly different problems.

The right model depends on the workload.

When Container-Level Resources Make More Sense

Suppose a Pod contains two containers:

API
Sidecar

but they have very different resource requirements.

You may want:

API:
  CPU limit: 2
  Memory limit: 2Gi

Sidecar:
  CPU limit: 100m
  Memory limit: 128Mi

In this situation, container-level configuration gives you clear control over each process.

This can be important when one container must not consume resources needed by another.

When Pod-Level Resources Make More Sense

Pod-level resources can be useful when the containers are closely related and their resource consumption naturally varies.

For example:

Pod
|
+-- Application
+-- Proxy

The application might receive most of the traffic during one period, while the proxy may need more CPU during another period.

A shared Pod-level resource budget can better describe the workload when strict per-container limits are not necessary.

Pod-Level Resources and Scheduling

Resource requests are important because Kubernetes uses them when scheduling Pods.

Suppose:

spec:
  resources:
    requests:
      cpu: "2"
      memory: "1Gi"

The scheduler needs to find a node that can satisfy the Pod's resource requirements.

This is different from saying:

The Pod will always consume 2 CPUs.

A request is primarily a scheduling value.

The actual workload may use less or more CPU depending on the configured limits and runtime behavior.

CPU Units

Kubernetes CPU resources can be expressed in different forms.

For example:

cpu: "1"

represents one CPU unit.

You can also use millicores:

cpu: "500m"

which represents half of one CPU unit.

Common examples:

100m  = 0.1 CPU
250m  = 0.25 CPU
500m  = 0.5 CPU
1000m = 1 CPU

For teams new to Kubernetes resource configuration, millicores can initially look confusing.

The important thing is to keep resource values consistent and based on measured application requirements.

Memory Units

Memory is commonly expressed using binary units such as:

memory: "256Mi"

or:

memory: "1Gi"

For example:

256Mi
512Mi
1Gi
2Gi

Memory limits need particular attention because memory cannot be throttled in the same way CPU can.

If a container exceeds its available memory under the relevant conditions, it can be terminated by the system.

A Deployment Example

Most production applications are managed through a Deployment rather than creating individual Pods manually.

A simplified Deployment can look like this:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: orders-api
spec:
  replicas: 3
  selector:
    matchLabels:
      app: orders-api
  template:
    metadata:
      labels:
        app: orders-api
    spec:
      resources:
        requests:
          cpu: "500m"
          memory: "512Mi"
        limits:
          cpu: "1"
          memory: "1Gi"

      containers:
        - name: api
          image: orders-api:1.0

        - name: metrics
          image: metrics-agent:1.0

Each replica creates a separate Pod.

With three replicas:

Deployment
|
+-- Pod 1
|   +-- API
|   +-- Metrics
|
+-- Pod 2
|   +-- API
|   +-- Metrics
|
+-- Pod 3
    +-- API
    +-- Metrics

The resource configuration applies to each Pod created by the Deployment.

How Resource Sharing Helps

Consider a Pod with a total CPU limit of:

limits:
  cpu: "2"

The two containers may have changing workloads.

For example:

Normal traffic:
API       400m
Metrics    50m
Total     450m

During an API traffic spike:

API      1500m
Metrics   100m
Total    1600m

Later, when metrics processing increases:

API       600m
Metrics   500m
Total    1100m

The important idea is that the workload can use the Pod's available resources according to the runtime behavior rather than treating every container as an entirely independent resource island.

The exact resource enforcement behavior should still be verified for the Kubernetes version and configuration being used.

Pod-Level Resources Are Not a Replacement for Good Sizing

It is easy to misunderstand this feature.

Pod-level resources do not mean you can ignore resource sizing.

You still need to determine:

• Normal CPU usage

• Peak CPU usage

• Normal memory usage

• Peak memory usage

• Expected traffic

• Number of replicas

• Node capacity

A good starting point is to collect actual workload data.

For example:

Average CPU: 350m
Peak CPU:    900m

Average memory: 320Mi
Peak memory:    620Mi

Those measurements provide a much better basis for resource configuration than guessing.

Common Mistakes

Setting Very Large Limits

A large limit does not automatically improve application performance.

It can make capacity planning more difficult and may allow a workload to consume resources that other workloads need.

Treating Requests as Actual Usage

A CPU request is not a guarantee that the application will constantly consume that amount.

It is used in scheduling and resource management.

Ignoring Memory Behavior

Memory is different from CPU.

A workload that continuously approaches its memory limit deserves investigation.

Using Pod-Level Resources Everywhere

Not every workload needs Pod-level resource sharing.

If containers have independent resource requirements, container-level resources may provide clearer control.

Skipping Load Testing

Resource configuration should be tested under realistic traffic.

Best Practices

1. Measure Before Setting Values

Use real workload metrics when choosing requests and limits.

2. Start With Clear Resource Ownership

Understand which container is responsible for which workload.

3. Use Pod-Level Resources for Closely Related Containers

This model is particularly useful when containers are part of one logical workload and resource usage can shift between them.

4. Keep Container Configuration Understandable

Do not create a resource model that the operations team cannot easily understand.

5. Test Under Peak Load

Normal traffic does not always reveal resource problems.

6. Monitor After Deployment

Resource configuration should be revisited when workload behavior changes.

Troubleshooting Resource Problems

If a Pod is being throttled or terminated, check the actual resource behavior.

Useful commands include:

kubectl get pods

To inspect a specific Pod:

kubectl describe pod <pod-name>

To check resource usage where metrics are available:

kubectl top pod <pod-name>

For a Pod with multiple containers, check the individual container usage as well.

The goal is to determine whether the problem is:

CPU pressure
Memory pressure
Incorrect request
Incorrect limit
Node capacity
Application behavior

Do not change resource values blindly.

Pod-Level Resources and Memory QoS

Resource configuration can also affect how Kubernetes manages memory pressure and quality-of-service behavior.

This is an area where teams should be careful because CPU and memory do not behave identically.

For memory-intensive applications, monitor:

• Working set

• Memory limits

• OOM events

• Container restarts

• Node memory pressure

A Pod-level memory budget should be chosen based on the combined behavior of its containers.

Advantages

Pod-level resources can provide:

• A resource budget for the whole Pod

• More flexibility for multi-container workloads

• A better fit for tightly coupled application and sidecar patterns

• Less dependence on rigid per-container allocation in suitable scenarios

• A simpler resource model for some workloads

Disadvantages

There are also trade-offs:

• Per-container resource control can become less explicit

• Existing operational tooling may need to account for Pod-level configuration

• Teams need to understand how requests and limits are interpreted

• Incorrect sizing can still cause CPU or memory pressure

• Not every workload benefits from shared resource configuration

When Should You Use Pod-Level Resources?

Consider Pod-level resources when:

• A Pod contains multiple closely related containers.

• Resource consumption shifts between those containers.

• A shared resource budget describes the workload better than fixed per-container limits.

• The cluster version and configuration support the feature you need.

• You have monitoring data to size the Pod correctly.

Continue using container-level resources when each container needs strict and independent resource control.

Summary

Pod-level resources provide another way to think about CPU and memory allocation in Kubernetes. Instead of treating every container as an isolated resource configuration, the Pod can have a resource budget that represents the combined workload.

This can be useful for multi-container Pods where an application and its sidecars have changing resource requirements. A shared budget can provide more flexibility when resource consumption moves between containers.

However, Pod-level resources do not remove the need for proper resource sizing. Requests, limits, CPU units, memory behavior, scheduling, and monitoring still matter.

Before using the feature in production, test it with a representative workload and confirm the behavior on the Kubernetes version and cluster configuration you operate. The best resource model is the one that accurately represents how the application actually uses CPU and memory while remaining easy for the team to monitor and maintain.