kernel
settings.kernel.*)Topic list
Setting list for settings.kernel
settings.kernel.drivers.nvidia.branchsettings.kernel.hugepages.static.<size>.countsettings.kernel.hugepages.static.essentialsettings.kernel.hugepages.transparent.defragsettings.kernel.hugepages.transparent.enabledsettings.kernel.lockdownsettings.kernel.modules.<name>.allowedsettings.kernel.modules.<name>.autoloadsettings.kernel.sysctl
Topics
Huge pages
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. Bottlerocket exposes two independent families undersettings.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.
Static reservations are applied once during early boot and require a reboot to change.[settings.kernel.hugepages.static]
essential = true
"2Mi" = { count = "512" }
"1Gi" = { count = "4" }
[settings.kernel.hugepages.transparent]
enabled = "always"
defrag = "defer+madvise"
apiclient set \
settings.kernel.hugepages.static.essential=true \
settings.kernel.hugepages.static.2Mi.count="512" \
settings.kernel.hugepages.static.1Gi.count="4" \
settings.kernel.hugepages.transparent.enabled="always" \
settings.kernel.hugepages.transparent.defrag="defer+madvise"
Settings
NVIDIA driver branch selection
The aws-k8s-1.37+ NVIDIA variants include two NVIDIA driver branches: the long-term support branch (lts) and the product branch (pb).
At boot, the nvidia-select-branch.service unit selects one branch, and Bottlerocket loads only the drivers from that branch.
The unit selects the branch in this order:
- If
settings.kernel.drivers.nvidia.branchisltsorpb, the unit uses that branch. - If the setting is unset, the unit uses
pbwhen a GPU on the host requires the product branch. - In all other cases, the unit uses
lts.
If the unit cannot read the setting from the Bottlerocket API, the unit fails and Bottlerocket does not load an NVIDIA driver. Bottlerocket does not fall back to GPU detection in this case, because detection can select a different branch than the one that you set.
Settings
Full Reference
settings.kernel.drivers.nvidia.branch
Selects the NVIDIA driver branch that Bottlerocket activates at boot on dual-branch variants. A dual-branch variant includes two NVIDIA driver branches in one image. If you do not set this setting, Bottlerocket selects the branch from the NVIDIA GPUs that it finds on the host.
Warning
If you set this setting, Bottlerocket does not do GPU detection.
Default: unset. Bottlerocket selects the branch from the NVIDIA GPUs on the host.
Accepted values:lts: the long-term support branch.pb: the product branch.
Note
This setting has an effect only on the aws-k8s-1.37+ NVIDIA variants.
Other NVIDIA variants include one driver branch and ignore this setting.
Bottlerocket reads this setting once per boot, before it loads the NVIDIA drivers.
If you change the setting on a running host, reboot the host to apply the change.
To use a branch from the first boot, put the setting in user data.
# Use the product branch on every boot.
[settings.kernel.drivers.nvidia]
branch = "pb"
apiclient set settings.kernel.drivers.nvidia.branch="pb"
settings.kernel.hugepages.static.<size>.count
Reserves a pool of huge pages of the given <size> at boot time.
<size> is the huge page size and count is the number of pages to reserve.
Changes to this setting only take effect on boot.
Note
<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.
The size must also be supported by the kernel and CPU architecture; unsupported sizes cause the reservation to fail.
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.
Larger page sizes are reserved before smaller ones to reduce the chance of memory fragmentation preventing allocation.
# Reserve 512 pages of 2 MiB (1 GiB total) across all NUMA nodes.
[settings.kernel.hugepages.static]
"2Mi" = { count = "512" }
# Reserve 1 GiB pages per NUMA node: 2 pages on node 0 and 2 pages on node 1.
[settings.kernel.hugepages.static]
"1Gi" = { count = "0:2,1:2" }
apiclient apply <<EOF
[settings.kernel.hugepages.static."2Mi"]
count="512"
EOF
apiclient apply <<EOF
[settings.kernel.hugepages.static."1Gi"]
count = "0:2,1:2"
EOF
settings.kernel.hugepages.static.essential
Controls whether a shortfall in the requested static huge page reservation is fatal at boot.
Warning
When set to true, the host fails to boot if the full number of requested huge pages cannot be reserved.
Default: false
truefalse
Note
When false, an unmet reservation is logged as a warning and boot continues with however many pages could be reserved.
Errors other than a reservation shortfall (such as an unsupported page size or NUMA node) always fail the boot regardless of this setting.
# Require the full reservation; fail to boot otherwise.
[settings.kernel.hugepages.static]
essential = true
"1Gi" = { count = "4" }
apiclient apply <<EOF
[settings.kernel.hugepages.static]
essential = true
"1Gi" = { count = "4" }
EOF
settings.kernel.hugepages.transparent.defrag
Controls how much effort the kernel spends defragmenting memory to satisfy a transparent huge page allocation.
Default: derived from hugepages.transparent.enabled, which defaults to madvise
always: stall the allocating task until huge pages are available.defer: wake the background reclaim/compaction daemons and fall back to smaller pages for now.defer+madvise: behave likedefer, but stall for regions that usedmadvise(MADV_HUGEPAGE).madvise: stall only for regions that usedmadvise(MADV_HUGEPAGE).never: do not defragment for transparent huge pages.
Note
When unset, the defrag policy is derived from hugepages.transparent.enabled (always and madvise map to madvise, never maps to never).
[settings.kernel.hugepages.transparent]
enabled = "always"
defrag = "defer+madvise"
apiclient set settings.kernel.hugepages.transparent.enabled="always"
apiclient set settings.kernel.hugepages.transparent.defrag="defer+madvise"
settings.kernel.hugepages.transparent.enabled
Sets the Transparent Huge Pages (THP) policy, which controls when the kernel automatically backs memory with huge pages.
Default: madvise
always: the kernel tries to use transparent huge pages for all eligible memory.madvise: the kernel uses transparent huge pages only for memory regions that request them viamadvise(MADV_HUGEPAGE).never: disables transparent huge pages.
[settings.kernel.hugepages.transparent]
enabled = "always"
apiclient set settings.kernel.hugepages.transparent.enabled="always"
settings.kernel.lockdown
Sets the mode for the lockdown Linux security module.
Warning
Changing this setting from confidentiality to integrity or integrity to none requires a reboot to take effect.
Default: integrity except for nvidia and dev variant flavours which use none
confidentiality: blocks most methods of reading kernel memory from userspace. Tools that rely on reading kernel memory may not work in this mode.integrity: blocks most methods for overwriting kernel memory or modifying kernel code. This mode prevents unsigned kernel modules from loading.none: disables protection by the Lockdown security module.
settings.kernel.modules.<name>.allowed
Allows (true) or disallows (false) the loading of kernel module <name>.
Warning
This setting only affects loading of kernel modules at boot time. Changing the setting of already loaded (running) kernel modules to false has no affect until reboot.
truefalse
Note
Use settings.boot.kernel-parameters to set module parameters through the kernel command line.
[settings.kernel.modules.sctp]
allowed = false
[settings.kernel.modules.udf]
allowed = true
apiclient set settings.kernel.modules.sctp.allowed=false
apiclient set settings.kernel.modules.udf.allowed=true
settings.kernel.modules.<name>.autoload
If true, the kernel <name> module loads automatically on boot.
truefalse
Note
You must use this setting in conjuction with settings.kernel.modules.<name>.allowed on the same module.
This ensures that the OS doesn’t auto-load a blocked module.
Use settings.boot.kernel-parameters to set module parameters through the kernel command line.
[settings.kernel.modules.ip_vs_lc]
allowed = true
autoload = true
apiclient set settings.kernel.modules.ip_vs_lc.allowed=true settings.kernel.modules.ip_vs_lc.autoload=true
settings.kernel.sysctl
Sets kernel parameters.
Note
Add quotes (") around keys as they often contain dots (.) as well as around values.
[settings.kernel.sysctl]
"user.max_user_namespaces" = "16384"
"vm.max_map_count" = "262144"