Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

 
ON THIS PAGE
 

Configure Huge Pages

Learn how to configure huge pages for the Cloud-Native Router vRouter.

Huge pages make memory accesses more efficient by reducing the number of TLB (translation lookaside buffer) misses and are instrumental in getting the best performance from your Cloud-Native Router vRouter installation.

Starting with Cloud-Native Router Release 26.2, you can configure the vRouter to use either 1G or 2MB hugepages. The default hugepage size is 1G. Use 2MB hugepages in deployments where memory resources are limited, such as RAN (Radio Access Network) nodes where the Cloud-Native Router vRouter coexists with memory-intensive workloads.

Configuring huge pages is a two-part procedure. First, specify the number and size of huge pages that you want the node to make available (Configure the Number of Huge Pages Available on a Node) and then configure the Cloud-Native Router vRouter to use these huge pages (Configure the Number of Huge Pages to Use) by setting the hugepage_sz parameter in the values.yaml file.

By default, the Cloud-Native Router vRouter uses 1G hugepages and does not require the hugepage_sz parameter to be set. Set this parameter only if you want to change the hugepage size.

Configure the Number of Huge Pages Available on a Node

Use this procedure to specify the number and size of huge pages that you want to make available on a node.

Note:

This procedure does not apply to a Red Hat OpenShift or a Wind River Cloud Platform deployment.
  1. Log in as root to the cluster node where you want to configure huge pages.
  2. Configure GRUB to boot up the node with the desired number of huge pages.

    Add GRUB_CMDLINE_LINUX_DEFAULT values in /etc/default/grub.

    For example, the following configures the node to boot up with 10 x 1 GB huge pages (and SR-IOV pass-through support):

    To configure the node for 2MB hugepages instead, use the following GRUB_CMDLINE_LINUX_DEFAULT values. The following example configures the node to boot with 1536 x 2MB hugepages (3 Gi):

    Note:

    1536 is the minimum number of 2MB hugepages required for Cloud-Native Router (1536 x 2 MB = 3 Gi). Adjust this value based on your memory requirements.
  3. Update GRUB.
  4. Reboot.
  5. Log back in to the node.
  6. Verify that the node has acquired the requested number of huge pages.
    Look at the output to confirm that GRUB has been configured to request the desired number of huge pages:Look at the output to confirm that the node has successfully acquired and made available the desired number of huge pages:

Configure the Number of Huge Pages to Use

By default, the Cloud-Native Router vRouter is already configured to use huge pages. Use this procedure to change the number of huge pages that the Cloud-Native Router vRouter uses.

  1. On the host where you're running the Cloud-Native Router installation procedures, go to the Helm chart directory for the Cloud-Native Router vRouter.
  2. Configure the number of huge pages in the Cloud-Native Router vRouter values.yaml file.
    For 1G hugepages, change the default hugepages-1Gi value in limits and requests to the number of your choice:

    For example, to set huge pages to 10 GB:

    For 2MB hugepages, when hugepage_sz is set to "2MB" in the top-level values.yaml file, Cloud-Native Router automatically sets the resource type to hugepages-2Mi. Adjust the size as needed:

    Note:

    The number you specify here must not be greater than the number of huge pages you've made available on the node.

  3. Save and exit the file.

Configure 2MB Hugepages for Low Memory Deployments

Starting with Cloud-Native Router Release 26.2, the vRouter supports 2MB hugepages in addition to the default 1G hugepages. Use 2MB hugepages to reduce the Cloud-Native Router memory footprint in resource-constrained deployments, such as RAN nodes where Cloud-Native Router coexists with memory-intensive workloads.

Overview

By default, the Cloud-Native Router vRouter uses 1G hugepages, which require a minimum of 6 Gi of hugepage memory. With 2MB hugepages, the minimum hugepage allocation is 3 Gi, and the memory footprint can be reduced further by adjusting the DPDK mempool size using the dpdkCommandAdditionalArgs parameter. 1G hugepages provide better performance for high-throughput packet processing workloads due to reduced TLB pressure. 2MB hugepages are fully functional and suitable for deployments where minimizing the memory footprint is the primary requirement.

Note:

NOTE: 2MB hugepages are supported for the DPDK dataplane variant of Cloud-Native Router only. This feature does not apply to the eBPF XDP dataplane.

Prerequisites

Before configuring 2MB hugepages, ensure the following:

  • The host node has 2MB hugepages configured and available. The minimum required is 1536 x 2MB hugepages (3 Gi) per NUMA socket.

  • For bare metal, EKS, GCP, and Azure deployments, configure 2MB hugepages in GRUB as described in the Configure the Number of Huge Pages Available on a Node section.

  • For Red Hat OpenShift deployments, configure 2MB hugepages using the Tuned profile and MachineConfigPool as described in Resource Requirements for OCP.

  • For Wind River Cloud Platform deployments, configure 2MB hugepages using the system host-memory-modify commands as described in Resource Requirements on a Wind River Deployment.

  • Verify that 2MB hugepages are available on the node:

    Confirm that the output shows: Hugepagesize: 2048 kB

Configure 2MB Hugepages

Set the hugepage_sz parameter in the jcnr-vrouter section of the values.yaml file and deploy Cloud-Native Router:

Cloud-Native Router automatically configures the following when hugepage_sz is set to "2MB":

  • Kubernetes resource type: hugepages-2Mi

  • Resource limit: 3 Gi

  • Socket memory: 512 MB per NUMA socket (--socket-mem=512,512 on dual-NUMA)

Note:

If hugepage_sz is not specified in values.yaml, Cloud-Native Router uses 1G hugepages by default. Existing deployments continue to work without any configuration change.

To reduce the memory footprint further, override the default socket memory and mempool settings using dpdkCommandAdditionalArgs. The following example achieves a total vRouter memory consumption of approximately 520 MB on a dual-NUMA system:

Note:

Reducing the mempool size and flow table entries limits the maximum number of concurrent flows and bridge entries the vRouter can handle. Configure these values based on your traffic and scale requirements.

Memory Profiles

The following table shows memory consumption for different hugepage configurations.

Verify the Hugepage Configuration

After deploying Cloud-Native Router with 2MB hugepages, verify the configuration using the following methods.

  1. Method 1 — Check the hugepage mount point on the host:

    With 2MB hugepages, the output shows multiple smaller hugepage files (typically 2M–154M each) rather than the single large 1024M files seen with 1G hugepages. For example:

  2. Method 2 — Verify the hugepage size using the dpdkinfo utility:

    From inside the contrail-vrouter-agent-dpdk container, run:

    In the output, the HugepageSz column confirms the hugepage size in use. For 2MB hugepages, the column shows "2M" for all zones. For example:

    For 1G hugepages, the HugepageSz column shows "1G".

  3. Method 3 — Verify hugepage size from /proc/meminfo:

    For 2MB hugepages, the output includes: Hugepagesize: 2048 kB

    For 1G hugepages, the output includes: Hugepagesize: 1048576 kB

Note:

Only one hugepage size can be active per vRouter at a time. A node can have both 1G and 2MB hugepages configured at the host level, but Cloud-Native Router uses only the hugepage size specified by hugepage_sz. When hugepage_sz is not set, Cloud-Native Router uses 1G hugepages.