Updated on 2025-08-12 GMT+08:00

Configuring Transparent Huge Pages

Scenario

Transparent Huge Pages (THP) is a memory management feature in the Linux kernel. It is designed to compact multiple small pages (usually 4 KB) into huge pages (usually 2 MB). THP dynamically adjusts the page size to optimize memory management and reduces the number of page table lookups and Translation Lookaside Buffer (TLB) misses to reduce memory access latency. However, if there is memory fragmentation or high overhead of background processes, THP may increase memory usage.

Advantages of THP

  • Reduced TLB misses

    THP compacts multiple small pages (usually 4 KB) into huge pages (usually 2 MB), significantly reducing TLB misses. TLB misses cause the processor to access the page table for address translation, increasing the memory access latency. For memory-intensive applications, THP reduces the memory access latency and significantly improves application performance.

  • Reduced resource consumption for memory management by kernel

    When the size of a memory page increases, the number of pages to be maintained in the same physical memory is greatly reduced. This reduces the resource consumption for the kernel to manage memory and the time of page table queries. The page table query time is proportional to the page table hierarchy and the number of pages. The decrease in the number of pages improves the query efficiency and the overall system performance.

Disadvantages of THP

  • Higher memory usage

    In an environment where memory is frequently allocated and released, THP may cause memory fragmentation, which increases the memory usage. When there are a large number of small pages that cannot be compacted into huge pages, THP may not work effectively. As a result, memory allocation fails or performance deteriorates. Memory fragmentation is more obvious in memory-intensive workloads.

  • Potential OOM error

    The resource allocation of THP may cause the actual memory usage to be inconsistent with the application requirements. For example, an application requires only 8 KB of memory (two small pages), but the kernel may allocate 2 MB of memory (a transparent huge page). When the system memory is insufficient, the extra memory usage may trigger an out of memory (OOM) error, affecting system stability.

THP Configuration Suggestions

  • When an application frequently requests and releases small memory blocks (for example, 4-KB pages), THP may frequently attempt to merge and split pages. This dynamic management process requires additional compute resources, which may significantly increase the memory management overhead. In addition, frequent merging and splitting operations may cause memory fragmentation, further reducing memory utilization. For this reason, you are advised not to enable THP in this scenario to avoid performance deterioration.
  • If the application does not have high performance requirements and the system memory is insufficient, you can disable THP to reduce memory usage. The resource allocation of THP may cause the actual memory usage to be inconsistent with the application requirements, and the resident set size (RSS) increases. After THP is disabled, the system uses small 4-KB pages for management. Although the number of TLB misses may increase, there is less memory fragmentation, and the memory usage can be reduced. This avoids the OOM error caused by insufficient memory.

Constraints

  • CCI 2.0 allows you to configure THP policies by using annotations when creating a workload. If you modify the THP policy by editing the YAML file for the Deployment, the pods will be recreated.
  • If THP policies are enabled:
    • The default value of transparent_hugepage/defrag is madvise. The memory is only reclaimed from the area specified by madvise (MADV_HUGEPAGE).
    • The default value of transparent_hugepage/khugepaged/defrag is 1, indicating that khugepaged for memory defragmentation is enabled by default.

Procedure

  1. Log in to the CCI 2.0 console.
  2. In the navigation pane, choose Workloads. On the Deployments tab, click Create from YAML.
  1. Define the Deployment. The following is an example YAML file:
    kind: Deployment
    apiVersion: cci/v2
    metadata:
      name: deploy-example
      namespace: test-namespace
    spec:
      replicas: 1
      selector:
        matchLabels:
          app: deploy-example
      template:
        metadata:
          labels:
            app: deploy-example
          annotations:
            system.cci.io/transparent_hugepage.enabled: never
        spec:
          containers:
            - name: deploy-example
              image: nginx
              resources:
                limits:
                  cpu: 500m
                  memory: 1Gi
                requests:
                  cpu: 500m
                  memory: 1Gi
          dnsPolicy: Default
          imagePullSecrets:
            - name: imagepull-secret
      strategy:
        type: RollingUpdate
        rollingUpdate:
          maxUnavailable: 0
          maxSurge: 100%
    Table 1 Description of key fields

    Field

    Type

    Description

    system.cci.io/transparent_hugepage.enabled

    String

    • always (default): enables THP globally.
    • madvise: enables THP globally only in the area specified by madvise (MADV_HUGEPAGE).
    • never: disables THP globally.
  2. Click OK.