Skip to main content
Add or update the optional nr_hugepages parameter under spec.nodeParameters to allocate 2 MiB huge pages on each Node in a CoreWeave Kubernetes Service (CKS) Node Pool. Use it for applications that require huge-page-backed host memory, such as workloads that offload an LLM key-value (KV) cache to host memory. Configure the allocation on the Node Pool and apply it to existing Nodes with a reconfigure reboot. Request huge pages in your Pod specification. Standard CKS Node Pools don’t allocate 2 MiB huge pages unless configured to do so. This guide covers 2 MiB pages. For other page sizes, including 1 GiB pages, contact Support to confirm the configuration supported by your instance type and Node image. The nr_hugepages parameter sets a count of 2 MiB pages, not a page size.

Prerequisites

Before you begin, confirm that you meet these prerequisites:
  • An existing CKS cluster and Node Pool with sufficient memory for your allocation and other workloads.
  • Access to the cluster with permission to update Node Pools, inspect Nodes, and create and delete Pods in your workload Namespace.
  • kubectl and the CoreWeave Intelligent CLI installed and configured for the cluster.
  • A maintenance window to reconfigure existing Nodes. For custom Node images or instance types with different huge-page sizes, confirm the supported page size and allocation with Support.

Allocate huge pages on a Node Pool

Set the page count for each Node, then apply and verify the updated configuration:
  1. Calculate the number of 2 MiB pages required per Node:
    Round up to a whole page. For example, 2 GiB requires 1,024 pages. Size the allocation for the combined huge-page requests of the Pods that can run on one Node. Leave memory for the operating system and other workloads. Huge pages can’t be overcommitted.
  2. Edit the Node Pool. Replace NODE_POOL_NAME with its name:
    To allocate huge pages, add the optional nr_hugepages parameter under spec.nodeParameters. If nodeParameters isn’t present, add that section under spec. If nr_hugepages already exists, update its value. Preserve any other parameters. The value must be a quoted string. This excerpt allocates 2 GiB per Node:
    Save the change and exit the editor. If you manage the Node Pool with GitOps, make this change in the source manifest instead. See Modify a Node Pool using Kubernetes.
  3. Inspect the Node Pool configuration:
    Check spec.nodeParameters.nr_hugepages, status.nodeProfile, and status.pendingNodeConfiguration. With the default OnSpecUpdate configuration strategy, CKS stages your spec change automatically. With Manual, inspect the pending configuration and promote it:
    Review the configuration summary before confirming. The staged configuration can include other pending updates. For strategy details, see Stage Node Pool configurations.
  4. Identify existing Nodes that require reconfiguration:
    New Nodes use the active Node Pool configuration when they boot. Existing Nodes require a reconfigure reboot to apply the huge-page allocation.
  5. During your maintenance window, queue a safe reconfigure reboot for a small batch of Nodes. Replace NODE_NAMES with a space-separated list from the previous step:
    CKS requests a cordon to prevent new workload scheduling and waits for active workloads to stop before rebooting. Wait for the batch to return to service and verify its huge-page capacity before proceeding with another batch. For rollout details, see Apply Node Pool updates.
  6. Check the huge-page capacity reported by the Nodes in the Node Pool:
    For an allocation of 1,024 pages, each updated Node should report 2Gi in both columns. If capacity is absent, zero, or below the requested allocation, don’t deploy the workload yet. Confirm that the Node completed its reconfigure reboot with the updated configuration, then contact Support if the allocation still differs.

Use huge pages in a Pod

Request huge pages separately from ordinary memory. The huge-page request must equal its limit. An emptyDir volume with medium: HugePages-2Mi provides a mount for applications that use huge-page-backed files. Configure your application to use that mount. This example reserves 1 GiB of huge-page memory and 128 MiB of ordinary memory on a Node in your configured Node Pool. The container waits so you can inspect its allocation. It doesn’t exercise an application’s huge-page usage.
  1. Save the following manifest as the huge-pages-pod.yaml file. Replace POD_NAME with a name for the example Pod and NODE_POOL_NAME with the configured Node Pool:
    huge-pages-pod.yaml
  2. Deploy the Pod in your workload Namespace. Replace NAMESPACE with the Namespace name:
  3. Wait for the Pod to become ready and inspect its placement and resource reservation:
    Confirm that the Pod is Running on a Node in the configured Node Pool. Check that its requests and limits include hugepages-2Mi: 1Gi. If the Pod stays Pending, inspect its events for scheduling constraints, including insufficient hugepages-2Mi capacity or Node taints. Allocatable describes the Node’s schedulable capacity, not the unreserved remainder after other Pods’ requests.
  4. Delete the example Pod when you finish checking the reservation:
For application-specific consumption and resource rules, see Kubernetes Manage HugePages.
Last modified on November 17, 2026