Kubernetes HugePage Resource Management

Kubernetes HugePage Resource Management is the mechanism for requesting and consuming pre-allocated large memory pages (hugepages) from the underlying Linux kernel within a Pod, exposed to Kubernetes as a size-specific extended resource type (hugepages-2Mi, hugepages-1Gi) rather than through the ordinary memory resource field. Hugepages reduce the overhead of virtual-to-physical memory address translation for applications with very large memory footprints — databases, in-memory caches, and certain high-performance computing workloads — by using far fewer, much larger page table entries than the kernel's standard 4Ki pages, at the cost of requiring the pages to be pre-allocated at the node's OS level before Kubernetes can schedule against them.

Because hugepage memory must be reserved from the kernel ahead of time and is fundamentally a fixed-size pool set outside Kubernetes' own control, hugepage resource management is unusually tied to node-level OS configuration in a way that ordinary memory management is not.

Node-Level Prerequisite: Kernel Allocation

Reserving Hugepages Before Kubernetes Can Use Them

Hugepages must be reserved at the OS level, independent of Kubernetes, typically via kernel boot parameters or a runtime sysctl setting specifying how many pages of a given size to reserve — Kubernetes cannot allocate or increase this pool itself; it can only schedule Pods against whatever pool the node's OS has already been configured to provide.

echo 1024 > /proc/sys/vm/nr_hugepages

Kubelet Discovery and Advertisement

Once hugepages are reserved at the OS level, the kubelet automatically discovers and advertises them as allocatable node capacity under resource names like hugepages-2Mi or hugepages-1Gi, one entry per distinct page size the node has reserved.

kubectl describe node node-worker-05 | grep hugepages

Requesting Hugepages in a Pod

Syntax

resources:
  requests:
    hugepages-2Mi: "512Mi"
    memory: "1Gi"
  limits:
    hugepages-2Mi: "512Mi"
    memory: "1Gi"

The quantity requested specifies the total amount of hugepage-backed memory needed, not a page count directly — Kubernetes divides this by the page size internally to determine how many individual pages must be reserved for the Pod.

Requests Must Equal Limits

Like other extended resources, hugepages do not support a request lower than the limit — the Pod either receives the full reserved allocation it specifies, or it is not scheduled, since hugepage memory (once reserved from the kernel pool) cannot be flexibly shared or overcommitted the way ordinary memory can.

Mounting Hugepages via Volumes

The medium: HugePages emptyDir

For applications that need to interact with hugepage memory as a filesystem (common with certain DPDK-based networking applications and some database engines), an emptyDir volume with medium: HugePages exposes the reserved hugepage memory as a mountable path.

volumes:
  - name: hugepage-volume
    emptyDir:
      medium: HugePages
volumeMounts:
  - name: hugepage-volume
    mountPath: /hugepages

Scheduling Behavior

Hard Filtering on Available Pool Size

A node whose reserved hugepage pool (of the specific requested page size) cannot accommodate the Pod's request is filtered out of the candidate set during scheduling, exactly like any other resource fit failure — a cluster with only some nodes configured for hugepages effectively segments hugepage-requiring workloads onto that specific subset, whether or not an explicit nodeSelector also targets them.

Combining with Node Selection for Efficiency

Because hugepage-reserving nodes are typically a deliberately configured subset of the cluster, workloads requesting hugepages commonly pair the request with a nodeSelector targeting nodes labeled as hugepage-enabled, avoiding wasted scheduling attempts against nodes that were never configured with any hugepage reservation at all.

nodeSelector:
  hugepages-enabled: "true"

Operational Considerations

Fixed Pool Size Requires Node-Level Change to Adjust

Because the hugepage pool is set at the OS level, increasing the total amount of hugepage memory available on a node requires a node-level configuration change (and, in many cases, a node reboot), not a Kubernetes-level action — capacity planning for hugepage-dependent workloads must account for this longer lead time compared to ordinary memory or CPU capacity adjustments.

Wasted Reservation if Underused

Reserved hugepage memory is unavailable for ordinary application use even if no Pod is currently requesting it, since the kernel has already carved it out of general-purpose memory — over-provisioning the hugepage pool relative to actual workload demand effectively wastes memory that could otherwise serve ordinary, non-hugepage workloads on that node.

Example

apiVersion: v1
kind: Pod
metadata:
  name: codartium-hugepage-example
spec:
  nodeSelector:
    hugepages-enabled: "true"
  containers:
    - name: database
      image: codartium/high-perf-db:latest
      resources:
        requests:
          hugepages-2Mi: "1Gi"
          memory: "512Mi"
        limits:
          hugepages-2Mi: "1Gi"
          memory: "512Mi"
      volumeMounts:
        - name: hugepage-volume
          mountPath: /hugepages
  volumes:
    - name: hugepage-volume
      emptyDir:
        medium: HugePages