|
| 1 | +# Huge pages settings, introduced in Bottlerocket v1.64.0 |
| 2 | +# (bottlerocket-core-kit v14.9.0 / bottlerocket-settings-models 0.25.0). |
| 3 | +# These entries are merged on top of the earlier kernel settings via version |
| 4 | +# inheritance, so only the newly added settings are defined here. |
| 5 | + |
| 6 | +[[docs.ref.hugepages_static_count]] |
| 7 | +name_override = "hugepages.static.<size>.count" |
| 8 | +tags = [ |
| 9 | + "hugepages" |
| 10 | +] |
| 11 | +description = """ |
| 12 | +Reserves a pool of huge pages of the given `<size>` at boot time. |
| 13 | +`<size>` is the huge page size and `count` is the number of pages to reserve. |
| 14 | +Changes to this setting only take effect on boot. |
| 15 | +""" |
| 16 | +note = """ |
| 17 | +`<size>` must be a positive integer followed by an IEC binary unit (`Ki`, `Mi`, `Gi`, or `Ti`) whose byte value is a power of two, for example `2Mi` or `1Gi`. |
| 18 | +The size must also be supported by the kernel and CPU architecture; unsupported sizes cause the reservation to fail. |
| 19 | +`count` is a string that is either a single non-negative integer (a global total) or a comma-separated list of `<node>:<pages>` pairs to allocate per NUMA node. |
| 20 | +Larger page sizes are reserved before smaller ones to reduce the chance of memory fragmentation preventing allocation. |
| 21 | +""" |
| 22 | +see = [ |
| 23 | + [ "settings", "kernel", "hugepages_static_essential" ], |
| 24 | + [ "settings", "kernel", "hugepages_transparent_enabled" ], |
| 25 | + ["[HugeTLB Pages (Linux kernel documentation)](https://docs.kernel.org/admin-guide/mm/hugetlbpage.html)"] |
| 26 | +] |
| 27 | +[[docs.ref.hugepages_static_count.example]] |
| 28 | +comment = "Reserve 512 pages of 2 MiB (1 GiB total) across all NUMA nodes." |
| 29 | +direct_toml = """ |
| 30 | +[settings.kernel.hugepages.static] |
| 31 | +"2Mi" = { count = "512" } |
| 32 | +""" |
| 33 | +direct_shell = """ |
| 34 | +apiclient apply <<EOF |
| 35 | +[settings.kernel.hugepages.static."2Mi"] |
| 36 | +count="512" |
| 37 | +EOF |
| 38 | +""" |
| 39 | +[[docs.ref.hugepages_static_count.example]] |
| 40 | +comment = "Reserve 1 GiB pages per NUMA node: 2 pages on node 0 and 2 pages on node 1." |
| 41 | +direct_toml = """ |
| 42 | +[settings.kernel.hugepages.static] |
| 43 | +"1Gi" = { count = "0:2,1:2" } |
| 44 | +""" |
| 45 | +direct_shell = """ |
| 46 | +apiclient apply <<EOF |
| 47 | +[settings.kernel.hugepages.static."1Gi"] |
| 48 | +count = "0:2,1:2" |
| 49 | +EOF |
| 50 | +""" |
| 51 | + |
| 52 | +[[docs.ref.hugepages_static_essential]] |
| 53 | +name_override = "hugepages.static.essential" |
| 54 | +tags = [ |
| 55 | + "hugepages" |
| 56 | +] |
| 57 | +description = """ |
| 58 | +Controls whether a shortfall in the requested static huge page reservation is fatal at boot. |
| 59 | +""" |
| 60 | +warning = "When set to `true`, the host fails to boot if the full number of requested huge pages cannot be reserved." |
| 61 | +note = """ |
| 62 | +When `false`, an unmet reservation is logged as a warning and boot continues with however many pages could be reserved. |
| 63 | +Errors other than a reservation shortfall (such as an unsupported page size or NUMA node) always fail the boot regardless of this setting. |
| 64 | +""" |
| 65 | +accepted_values = [ |
| 66 | + "`true`", |
| 67 | + "`false`" |
| 68 | +] |
| 69 | +default = "`false`" |
| 70 | +see = [ |
| 71 | + [ "settings", "kernel", "hugepages_static_count" ] |
| 72 | +] |
| 73 | +[[docs.ref.hugepages_static_essential.example]] |
| 74 | +comment = "Require the full reservation; fail to boot otherwise." |
| 75 | +direct_toml = """ |
| 76 | +[settings.kernel.hugepages.static] |
| 77 | +essential = true |
| 78 | +"1Gi" = { count = "4" } |
| 79 | +""" |
| 80 | +direct_shell = """ |
| 81 | +apiclient apply <<EOF |
| 82 | +[settings.kernel.hugepages.static] |
| 83 | +essential = true |
| 84 | +"1Gi" = { count = "4" } |
| 85 | +EOF |
| 86 | +""" |
| 87 | + |
| 88 | +[[docs.ref.hugepages_transparent_enabled]] |
| 89 | +name_override = "hugepages.transparent.enabled" |
| 90 | +tags = [ |
| 91 | + "hugepages" |
| 92 | +] |
| 93 | +description = """ |
| 94 | +Sets the Transparent Huge Pages (THP) policy, which controls when the kernel automatically backs memory with huge pages. |
| 95 | +""" |
| 96 | +accepted_values = [ |
| 97 | + "`always` : the kernel tries to use transparent huge pages for all eligible memory.", |
| 98 | + "`madvise` : the kernel uses transparent huge pages only for memory regions that request them via `madvise(MADV_HUGEPAGE)`.", |
| 99 | + "`never` : disables transparent huge pages." |
| 100 | +] |
| 101 | +default = "`madvise`" |
| 102 | +see = [ |
| 103 | + [ "settings", "kernel", "hugepages_transparent_defrag" ], |
| 104 | + ["[Transparent Hugepage Support (Linux kernel documentation)](https://docs.kernel.org/admin-guide/mm/transhuge.html)"] |
| 105 | +] |
| 106 | +[[docs.ref.hugepages_transparent_enabled.example]] |
| 107 | +direct_toml = """ |
| 108 | +[settings.kernel.hugepages.transparent] |
| 109 | +enabled = "always" |
| 110 | +""" |
| 111 | +direct_shell = """ |
| 112 | +apiclient set settings.kernel.hugepages.transparent.enabled="always" |
| 113 | +""" |
| 114 | + |
| 115 | +[[docs.ref.hugepages_transparent_defrag]] |
| 116 | +name_override = "hugepages.transparent.defrag" |
| 117 | +tags = [ |
| 118 | + "hugepages" |
| 119 | +] |
| 120 | +description = """ |
| 121 | +Controls how much effort the kernel spends defragmenting memory to satisfy a transparent huge page allocation. |
| 122 | +""" |
| 123 | +note = "When unset, the defrag policy is derived from `hugepages.transparent.enabled` (`always` and `madvise` map to `madvise`, `never` maps to `never`)." |
| 124 | +accepted_values = [ |
| 125 | + "`always` : stall the allocating task until huge pages are available.", |
| 126 | + "`defer` : wake the background reclaim/compaction daemons and fall back to smaller pages for now.", |
| 127 | + "`defer+madvise` : behave like `defer`, but stall for regions that used `madvise(MADV_HUGEPAGE)`.", |
| 128 | + "`madvise` : stall only for regions that used `madvise(MADV_HUGEPAGE)`.", |
| 129 | + "`never` : do not defragment for transparent huge pages." |
| 130 | +] |
| 131 | +default = "derived from `hugepages.transparent.enabled`, which defaults to `madvise`" |
| 132 | +see = [ |
| 133 | + [ "settings", "kernel", "hugepages_transparent_enabled" ] |
| 134 | +] |
| 135 | +[[docs.ref.hugepages_transparent_defrag.example]] |
| 136 | +direct_toml = """ |
| 137 | +[settings.kernel.hugepages.transparent] |
| 138 | +enabled = "always" |
| 139 | +defrag = "defer+madvise" |
| 140 | +""" |
| 141 | +direct_shell = """ |
| 142 | +apiclient set settings.kernel.hugepages.transparent.enabled="always" |
| 143 | +apiclient set settings.kernel.hugepages.transparent.defrag="defer+madvise" |
| 144 | +""" |
| 145 | + |
| 146 | +[[docs.tag.hugepages]] |
| 147 | +heading = "Huge pages" |
| 148 | +description = """ |
| 149 | +Huge pages let the kernel manage memory in larger blocks than the default page size, reducing translation lookaside buffer (TLB) pressure for memory-intensive workloads. |
| 150 | +Bottlerocket exposes two independent families under `settings.kernel.hugepages`: `static` reserves a fixed pool of HugeTLB pages at boot, while `transparent` tunes the kernel's Transparent Huge Pages (THP) behavior at runtime. |
| 151 | +Static reservations are applied once during early boot and require a reboot to change. |
| 152 | +""" |
| 153 | +[[docs.tag.hugepages.example]] |
| 154 | +tab = "TOML" |
| 155 | +type = "toml" |
| 156 | +source = """ |
| 157 | +[settings.kernel.hugepages.static] |
| 158 | +essential = true |
| 159 | +"2Mi" = { count = "512" } |
| 160 | +"1Gi" = { count = "4" } |
| 161 | +
|
| 162 | +[settings.kernel.hugepages.transparent] |
| 163 | +enabled = "always" |
| 164 | +defrag = "defer+madvise" |
| 165 | +""" |
| 166 | +[[docs.tag.hugepages.example]] |
| 167 | +tab = "apiclient" |
| 168 | +type = "shell" |
| 169 | +source = """ |
| 170 | +apiclient set \\ |
| 171 | + settings.kernel.hugepages.static.essential=true \\ |
| 172 | + settings.kernel.hugepages.static.2Mi.count="512" \\ |
| 173 | + settings.kernel.hugepages.static.1Gi.count="4" \\ |
| 174 | + settings.kernel.hugepages.transparent.enabled="always" \\ |
| 175 | + settings.kernel.hugepages.transparent.defrag="defer+madvise" |
| 176 | +""" |
0 commit comments