Configuring kernel parameters lets AlloyDB Omni use system memory and IO resources more efficiently when handling heavy workloads.
Prerequisite
Before you start, make sure your Kubernetes nodes run Linux kernel 6.1 or higher, specifically a kernel that supports the MADV_COLLAPSE and MADV_POPULATE_WRITE flags. For more information about these flags, see Linux madwise documentation.
Apply recommended kernel settings to Kubernetes nodes
The following table lists required kernel parameters and their corresponding values for Kubernetes nodes that run database cluster pods:
File
Value
/sys/kernel/mm/transparent_hugepage/shmem_enabled For information about shared memory, see Transparent Hugepage Support
within_size or always
/proc/sys/vm/max_map_count For information about the number of memory map areas a process can create, see Documentation for /proc/sys/vm
Greater than or equal to 1073741824
To configure the kernel parameters on your Kubernetes nodes using a DaemonSet, do the following:
Apply labels to the nodes where you plan to run database clusters using instructions in Add a label to a node.
To set the kernel parameters on the nodes labeled LABEL_KEY=LABEL_VALUE, create a DaemonSet:
DS_NAMESPACE: the namespace where you want to deploy the DaemonSet—for example, default.
LABEL_KEY: the identifier for the label—for example, workload.
LABEL_VALUE: the data associated with the identifier for the label—for example, database.
INIT_IMAGE: the name of the image used for the init container.
MAX_MAP_COUNT: the maximum number of memory map areas a process can create—for example, 1073741824.
CONTAINER_NAME: the name of the main container—for example, main.
CONTAINER_IMAGE: the name of the image used for the main container—for example, latest.
After deploying the DaemonSet, to verify that all pods in your Kubernetes cluster are in the Running state and that you have one pod for each node with the label LABEL_KEY=LABEL_VALUE, use the following command:
kubectlgetpods-lLABEL_KEY=LABEL_VALUE
An example output looks as follows:
NAME READY STATUS RESTARTS AGE
alloydb-omni-kernel-tuning-2dkwh 1/1 Running 0 22s
alloydb-omni-kernel-tuning-pgkbj 1/1 Running 0 19s
To verify the kernel flag is successfully applied, for each of the pods identified after deploying the DaemonSet, run the following command:
kubectllogsPOD_NAME
Replace POD_NAME with the name of the pod you want to examine the logs of.
An example output looks as follows:
always [within_size] advise never deny force
Run database clusters on Kubernetes nodes with recommended kernel parameters
To deploy database clusters on Kubernetes nodes with recommended kernel parameters, add a nodeAffinity section to one of the following sections of your database cluster manifest:
primarySpec.schedulingConfig for primary instances
To verify kernel parameters are applied to database pods, do the following:
If high availability is enabled, specifically spec.availability.numberOfStandbys is set to a value greater than zero, verify that the database custom resource shows DBClusterReady in the DBCLUSTERPHASE column and True in the HAREADYSTATUS column.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-08-28 UTC."],[[["\u003cp\u003eThis page outlines the necessary steps to configure Kubernetes nodes for optimal performance of AlloyDB Omni database clusters, emphasizing kernel parameter settings.\u003c/p\u003e\n"],["\u003cp\u003ePrior to configuration, ensure your Kubernetes nodes are running Linux kernel 6.1 or higher to support specific memory management flags like \u003ccode\u003eMADV_COLLAPSE\u003c/code\u003e and \u003ccode\u003eMADV_POPULATE_WRITE\u003c/code\u003e.\u003c/p\u003e\n"],["\u003cp\u003eKernel parameters like \u003ccode\u003e/sys/kernel/mm/transparent_hugepage/shmem_enabled\u003c/code\u003e (set to \u003ccode\u003ewithin_size\u003c/code\u003e or \u003ccode\u003ealways\u003c/code\u003e) and \u003ccode\u003e/proc/sys/vm/max_map_count\u003c/code\u003e (set to \u003ccode\u003e1073741824\u003c/code\u003e or higher) need to be applied to the Kubernetes nodes hosting the database clusters.\u003c/p\u003e\n"],["\u003cp\u003eA DaemonSet is provided to apply the recommended kernel settings automatically to labeled nodes, and instructions are given to deploy this DaemonSet to your Kubernetes cluster.\u003c/p\u003e\n"],["\u003cp\u003eAfter deploying database clusters, you must verify that the kernel parameters are correctly applied to the database pods, which can be checked by examining the shared memory information within the pods.\u003c/p\u003e\n"]]],[],null,["# Configure kernel parameters for AlloyDB Omni on Kubernetes\n\nSelect a documentation version: 15.7.1keyboard_arrow_down\n\n- [Current (16.8.0)](/alloydb/omni/current/docs/optimize-database-performance-configure-kernel-kubernetes)\n- [16.8.0](/alloydb/omni/16.8.0/docs/optimize-database-performance-configure-kernel-kubernetes)\n- [16.3.0](/alloydb/omni/16.3.0/docs/optimize-database-performance-configure-kernel-kubernetes)\n- [15.12.0](/alloydb/omni/15.12.0/docs/optimize-database-performance-configure-kernel-kubernetes)\n- [15.7.1](/alloydb/omni/15.7.1/docs/optimize-database-performance-configure-kernel-kubernetes)\n- [15.7.0](/alloydb/omni/15.7.0/docs/optimize-database-performance-configure-kernel-kubernetes)\n\n\u003cbr /\u003e\n\nThis page provides information about setting up Kubernetes nodes that host AlloyDB Omni database clusters for the optimal performance of the AlloyDB Omni Kubernetes operator and the AlloyDB Omni database engine.\n\n\u003cbr /\u003e\n\nConfiguring kernel parameters lets AlloyDB Omni use system memory and IO resources more efficiently when handling heavy workloads.\n\nPrerequisite\n------------\n\nBefore you start, make sure your Kubernetes nodes run Linux kernel 6.1 or higher, specifically a kernel that supports the `MADV_COLLAPSE` and `MADV_POPULATE_WRITE` flags. For more information about these flags, see [Linux `madwise` documentation](https://man7.org/linux/man-pages/man2/madvise.2.html).\n\nApply recommended kernel settings to Kubernetes nodes\n-----------------------------------------------------\n\nThe following table lists required kernel parameters and their corresponding values for Kubernetes nodes that run database cluster pods:\n\nTo configure the kernel parameters on your Kubernetes nodes using a [DaemonSet](https://kubernetes.io/docs/concepts/workloads/controllers/daemonset/), do the following:\n\n1. Apply labels to the nodes where you plan to run database clusters using instructions in [Add a label to a node](https://kubernetes.io/docs/tasks/configure-pod-container/assign-pods-nodes/#add-a-label-to-a-node).\n\n2. To set the kernel parameters on the nodes labeled `LABEL_KEY=LABEL_VALUE`, create a DaemonSet:\n\n cat \u003c\u003c EOF | kubectl apply -f -\n apiVersion: apps/v1\n kind: DaemonSet\n metadata:\n name: alloydb-omni-kernel-tuning\n namespace: \u003cvar translate=\"no\"\u003e\u003cspan class=\"devsite-syntax-l devsite-syntax-l-Scalar devsite-syntax-l-Scalar-Plain\"\u003eDS_NAMESPACE\u003c/span\u003e\u003c/var\u003e\n spec:\n selector:\n matchLabels:\n name: alloydb-omni-kernel-tuning\n template:\n metadata:\n labels:\n name: alloydb-omni-kernel-tuning\n spec:\n volumes:\n - name: host-sys\n hostPath:\n path: /sys\n nodeSelector:\n \u003cvar translate=\"no\"\u003e\u003cspan class=\"devsite-syntax-nt\"\u003eLABEL_KEY\u003c/span\u003e\u003c/var\u003e: \"\u003cvar translate=\"no\"\u003eLABEL_VALUE\u003c/var\u003e\"\n restartPolicy: Always\n terminationGracePeriodSeconds: 1\n initContainers:\n - name: enable-thp-mmc\n image: \u003cvar translate=\"no\"\u003e\u003cspan class=\"devsite-syntax-l devsite-syntax-l-Scalar devsite-syntax-l-Scalar-Plain\"\u003eINIT_IMAGE\u003c/span\u003e\u003c/var\u003e\n volumeMounts:\n - name: host-sys\n mountPath: /sys\n securityContext:\n privileged: true\n command: [\"sh\", \"-c\", \"sysctl -w vm.max_map_count=\u003cvar translate=\"no\"\u003eMAX_MAP_COUNT\u003c/var\u003e && echo within_size \u003e/sys/kernel/mm/transparent_hugepage/shmem_enabled\"]\n containers:\n - name: \u003cvar translate=\"no\"\u003e\u003cspan class=\"devsite-syntax-l devsite-syntax-l-Scalar devsite-syntax-l-Scalar-Plain\"\u003eCONTAINER_NAME\u003c/span\u003e\u003c/var\u003e\n image: \u003cvar translate=\"no\"\u003e\u003cspan class=\"devsite-syntax-l devsite-syntax-l-Scalar devsite-syntax-l-Scalar-Plain\"\u003eCONTAINER_IMAGE\u003c/span\u003e\u003c/var\u003e\n command: [\"watch\", \"-n\", \"600\", \"cat\", \"/sys/kernel/mm/transparent_hugepage/shmem_enabled\"]\n EOF\n\n Replace the following:\n - \u003cvar translate=\"no\"\u003eDS_NAMESPACE\u003c/var\u003e: the namespace where you want to deploy the DaemonSet---for example, `default`.\n - \u003cvar translate=\"no\"\u003eLABEL_KEY\u003c/var\u003e: the identifier for the label---for example, `workload`.\n - \u003cvar translate=\"no\"\u003eLABEL_VALUE\u003c/var\u003e: the data associated with the identifier for the label---for example, `database`.\n - \u003cvar translate=\"no\"\u003eINIT_IMAGE\u003c/var\u003e: the name of the image used for the init container.\n - \u003cvar translate=\"no\"\u003eMAX_MAP_COUNT\u003c/var\u003e: the maximum number of memory map areas a process can create---for example, `1073741824`.\n - \u003cvar translate=\"no\"\u003eCONTAINER_NAME\u003c/var\u003e: the name of the main container---for example, `main`.\n - \u003cvar translate=\"no\"\u003eCONTAINER_IMAGE\u003c/var\u003e: the name of the image used for the main container---for example, `latest`.\n3. After deploying the DaemonSet, to verify that all pods in your Kubernetes cluster are in the `Running` state and that you have one pod for each node with the label \u003cvar translate=\"no\"\u003eLABEL_KEY\u003c/var\u003e`=`\u003cvar translate=\"no\"\u003eLABEL_VALUE\u003c/var\u003e, use the following command:\n\n kubectl get pods -l \u003cvar translate=\"no\"\u003e\u003cspan class=\"devsite-syntax-nv\"\u003eLABEL_KEY\u003c/span\u003e\u003c/var\u003e=\u003cvar translate=\"no\"\u003eLABEL_VALUE\u003c/var\u003e\n\n An example output looks as follows: \n\n NAME READY STATUS RESTARTS AGE\n alloydb-omni-kernel-tuning-2dkwh 1/1 Running 0 22s\n alloydb-omni-kernel-tuning-pgkbj 1/1 Running 0 19s\n\n4. To verify the kernel flag is successfully applied, for each of the pods identified after deploying the DaemonSet, run the following command:\n\n kubectl logs \u003cvar translate=\"no\"\u003ePOD_NAME\u003c/var\u003e\n\n Replace \u003cvar translate=\"no\"\u003ePOD_NAME\u003c/var\u003e with the name of the pod you want to examine the logs of.\n\n An example output looks as follows: \n\n always [within_size] advise never deny force\n\nRun database clusters on Kubernetes nodes with recommended kernel parameters\n----------------------------------------------------------------------------\n\nTo deploy database clusters on Kubernetes nodes with recommended kernel parameters, add a `nodeAffinity` section to one of the following sections of your database cluster manifest:\n\n- `primarySpec.schedulingConfig` for primary instances\n- `spec.schedulingConfig` for read pool instances\n\n nodeaffinity:\n requiredDuringSchedulingIgnoredDuringExecution:\n nodeSelectorTerms:\n - matchExpressions:\n - key: \u003cvar translate=\"no\"\u003e\u003cspan class=\"devsite-syntax-l devsite-syntax-l-Scalar devsite-syntax-l-Scalar-Plain\"\u003eLABEL_KEY\u003c/span\u003e\u003c/var\u003e\n operator: In\n values:\n - \"\u003cvar translate=\"no\"\u003eLABEL_VALUE\u003c/var\u003e\"\n\nFor more information about running database clusters on specific Kubernetes nodes, see [Assign nodes to a database cluster using scheduling](/alloydb/omni/15.7.1/docs/assign-nodes-cluster-scheduling).\n\n### Verify the application of kernel parameters\n\nTo verify kernel parameters are applied to database pods, do the following:\n\n1. If high availability is enabled, specifically `spec.availability.numberOfStandbys` is set to a value greater than zero, verify that the database custom resource shows `DBClusterReady` in the **DBCLUSTERPHASE** column and `True` in the **HAREADYSTATUS** column.\n\n kubectl get dbcluster -n \u003cvar translate=\"no\"\u003eDBCLUSTER_NAMESPACE\u003c/var\u003e \u003cvar translate=\"no\"\u003eDBCLUSTER_NAME\u003c/var\u003e\n\n Replace the following:\n - \u003cvar translate=\"no\"\u003eDBCLUSTER_NAME\u003c/var\u003e: the name of the database cluster you verify.\n - \u003cvar translate=\"no\"\u003eDBCLUSTER_NAMESPACE\u003c/var\u003e: the name of the specific namespace where your database cluster resides.\n\n An example output looks as follows: \n\n NAME PRIMARYENDPOINT PRIMARYPHASE DBCLUSTERPHASE HAREADYSTATUS HAREADYREASON\n dbcluster-sample 10.29.21.240 Ready DBClusterReady True Ready\n\n2. List Kubernetes pods that belong to the database cluster:\n\n kubectl get pods -n \u003cvar translate=\"no\"\u003eDBCLUSTER_NAMESPACE\u003c/var\u003e -l alloydbomni.internal.dbadmin.goog/dbcluster=\u003cvar translate=\"no\"\u003eDBCLUSTER_NAME\u003c/var\u003e\n\n3. To check shared memory information, run the following command:\n\n kubectl exec -n \u003cvar translate=\"no\"\u003eDBCLUSTER_NAMESPACE\u003c/var\u003e \u003cvar translate=\"no\"\u003ePOD_NAME\u003c/var\u003e -- grep Shmem /proc/meminfo\n\n4. The output must contain numbers other than zero in all of the entries.\n\n An example output looks as follows: \n\n Shmem: 126255872 kB\n ShmemHugePages: 18403328 kB\n ShmemPmdMapped: 2961408 kB\n\n If you see `0 kB` shows in any of the entries, restart the corresponding pod: \n\n kubectl delete pod -n \u003cvar translate=\"no\"\u003eDBCLUSTER_NAMESPACE\u003c/var\u003e \u003cvar translate=\"no\"\u003ePOD_NAME\u003c/var\u003e\n\n5. Repeat steps 1 through 5 after the pod is in the `Running` state."]]