> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coreweave.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Configure huge pages

> Allocate 2 MiB huge pages on a Node Pool and make them available to Kubernetes workloads

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](https://docs.coreweave.com/support/contact.md) 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](https://docs.coreweave.com/products/cks/clusters/create.md) and [Node Pool](https://docs.coreweave.com/products/cks/nodes/create.md) with sufficient memory for your allocation and other workloads.
* [Access to the cluster](https://docs.coreweave.com/products/cks/auth-access/managed-auth/kubeconfig.md) with permission to update Node Pools, inspect Nodes, and create and delete Pods in your workload Namespace.
* `kubectl` and the [CoreWeave Intelligent CLI](https://github.com/coreweave/cwic) 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:

   ```text theme={"system"}
   page count = required bytes / 2097152
   ```

   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:

   ```bash theme={"system"}
   kubectl edit nodepool NODE_POOL_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:

   ```yaml theme={"system"}
   spec:
     nodeParameters:
       nr_hugepages: "1024"
   ```

   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](https://docs.coreweave.com/products/cks/nodes/manage.md#modify-a-node-pool-using-kubernetes).

3. Inspect the Node Pool configuration:

   ```bash theme={"system"}
   kubectl get nodepool NODE_POOL_NAME -o yaml
   cwic nodepool get NODE_POOL_NAME
   ```

   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:

   ```bash theme={"system"}
   cwic nodepool upgrade NODE_POOL_NAME
   ```

   Review the configuration summary before confirming. The staged configuration can include other pending updates. For strategy details, see [Stage Node Pool configurations](https://docs.coreweave.com/products/cks/nodes/manage.md#stage-node-pool-configurations).

4. Identify existing Nodes that require reconfiguration:

   ```bash theme={"system"}
   cwic nodepool nodes get NODE_POOL_NAME --requiring-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:

   ```bash theme={"system"}
   cwic node reboot --safe --reconfigure NODE_NAMES
   ```

   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](https://docs.coreweave.com/products/cks/nodes/apply-updates.md).

6. Check the huge-page capacity reported by the Nodes in the Node Pool:

   ```bash theme={"system"}
   kubectl get nodes -l compute.coreweave.com/node-pool=NODE_POOL_NAME \
     -o custom-columns='NAME:.metadata.name,CAPACITY:.status.capacity.hugepages-2Mi,ALLOCATABLE:.status.allocatable.hugepages-2Mi'
   ```

   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:

   ```yaml title="huge-pages-pod.yaml" theme={"system"}
   apiVersion: v1
   kind: Pod
   metadata:
     name: POD_NAME
   spec:
     restartPolicy: Never
     nodeSelector:
       compute.coreweave.com/node-pool: NODE_POOL_NAME
     containers:
       - name: huge-pages
         image: busybox:1.37
         command: ["sh", "-c", "sleep 3600"]
         resources:
           requests:
             cpu: "100m"
             memory: "128Mi"
             hugepages-2Mi: "1Gi"
           limits:
             memory: "128Mi"
             hugepages-2Mi: "1Gi"
         volumeMounts:
           - name: huge-pages
             mountPath: /hugepages
     volumes:
       - name: huge-pages
         emptyDir:
           medium: HugePages-2Mi
   ```

2. Deploy the Pod in your workload Namespace. Replace `NAMESPACE` with the Namespace name:

   ```bash theme={"system"}
   kubectl apply -n NAMESPACE -f huge-pages-pod.yaml
   ```

3. Wait for the Pod to become ready and inspect its placement and resource reservation:

   ```bash theme={"system"}
   kubectl wait -n NAMESPACE --for=condition=Ready pod/POD_NAME --timeout=120s
   kubectl get pod -n NAMESPACE POD_NAME -o wide
   kubectl describe pod -n NAMESPACE POD_NAME
   ```

   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:

   ```bash theme={"system"}
   kubectl delete pod -n NAMESPACE POD_NAME
   ```

For application-specific consumption and resource rules, see Kubernetes [Manage HugePages](https://kubernetes.io/docs/tasks/manage-hugepages/scheduling-hugepages/).
