DataCore Puls8 Automatic Prerequisites Setup (Prerequisites Handler)

Explore this Page

Overview

The Prerequisites Handler is a DataCore Puls8 system component that automatically prepares Kubernetes nodes to run Replicated PV Mayastor io-engine and CSI node workloads. It ensures that each node has the required system-level dependencies, eliminating the need for administrators to manually configure the host.

The Prerequisites Handler automatically prepares:

  • HugePages (2MiB) for io-engine
  • NVMe and NVMe-TCP kernel modules for CSI Node
  • RDMA libraries (rdma-core) on Debian/Ubuntu hosts when required

These checks and configurations run automatically in the background whenever DataCore Puls8 is installed or when nodes restart.

Automatic prerequisite setup including HugePages configuration, NVMe/NVMe-TCP kernel-module installation, and RDMA package installation is supported only on recent systemd-based Debian/Ubuntu operating systems. TalOS and other non-Debian/Ubuntu systems require manual configuration.

Enablement Requirement

The Prerequisites Handler is disabled by default. To enable automatic prerequisite setup, you must explicitly enable the Prerequisites Handler during DataCore Puls8 installation by setting the following Helm value:

Copy
Enable Prerequisites Handler
--set prereqHandler.enabled=true

If the Prerequisites Handler is not enabled, all prerequisite configuration must be performed manually.

HugePages Setup

Replicated PV Mayastor io-engine requires 2GiB of 2MiB HugePages to run.

The Prerequisites Handler on supported systems:

  • Detects when HugePages are insufficient on a node
  • Automatically sets up the required HugePages
  • Refreshes node capacity information
  • Applies persistence when enabled

The Prerequisites Handler attempts to configure 1024 HugePages of 2MiB size (2 GiB total) for Replicated PV Mayastor io-engine Pods. In some environments, the operating system may be unable to allocate the required number of HugePages due to system constraints. When this occurs, the io-engine Pods may remain in a Pending state until sufficient HugePages are available.

The process is fully automated and requires no user intervention unless the HugePages setup is intentionally disabled. To disable HugePages setup:

Copy
Disable HugePages Setup
prereqHandler.controller.hugepages.enabled=false

Automatic HugePages configuration is supported only on recent systemd-based Debian/Ubuntu hosts. On TalOS or other operating systems, HugePages must be verified, configured, and persisted manually.

NVMe and NVMe-TCP Kernel Module Setup

Replicated PV MayastorCSI Node requires the nvme and nvme_tcp kernel modules.

On supported Debian/Ubuntu environments, the Prerequisites Handler:

  • Detects whether these modules are present on each node
  • Installs required packages on Debian/Ubuntu if they are missing
  • Loads the modules into the kernel
  • Persists module loading across system reboots

The process is fully automated and requires no user intervention unless the kernel module setup is intentionally disabled. To disable kernel module setup:

Copy
Disable Kernel Module Setup
prereqHandler.controller.kmods.enabled=false

Automatic detection, installation, and loading of kernel modules is supported only on Debian/Ubuntu hosts. On TalOS, kernel-module automation including all detection and installation logic is fully disabled. You must install, load, and persist the required modules manually on TalOS.

RDMA Core Package Setup

Some environments require RDMA support for advanced NVMe-oF or network configurations.

When needed, the Prerequisites Handler:

  • Installs the rdma-core package on Debian/Ubuntu hosts
  • Ensures the required libraries and utilities are available

RDMA prerequisites setup is disabled by default. When Replicated PV Mayastor RDMA is enabled, the Prerequisites Handler automatically installs the required rdma-core package on supported systems. You can explicitly enable or disable this behavior by using the following Helm value:

Copy
Enable or Disable RDMA Prerequisites Setup
prereqHandler.controller.rdma.enabled= <true|false>

On TalOS, RDMA automation is disabled, and all required RDMA components must be installed and validated manually.

Verifying Node Readiness

After the setup is complete, you can verify that nodes have been prepared:

  • Check HugePages (Automatic on Debian/Ubuntu and manual on TalOS). Look for allocatable.hugepages-2Mi ≥ 2048Mi.
    • Copy
    Verify HugePages
    kubectl describe node <node-name>
  • Check NVMe modules (Automatic on Debian/Ubuntu and manual on TalOS).
    • Copy
    Verify NVMe Modules
    lsmod | grep nvme
    lsmod | grep nvme_tcp
  • Check RDMA package (Debian/Ubuntu).
    • Copy
    Verify RDMA Package
    dpkg -l | grep rdma-core

    On TalOS, NVMe/NVMe-TCP and RDMA validation must be performed manually because automated detection is disabled.

Troubleshooting

  • If an io-engine pod remains in Pending, verify HugePages availability.
  • If CSI Node encounters issues, check NVMe module presence.
  • Ensure your nodes are running supported operating systems (Debian 12 and Ubuntu 22.04/24.04).
  • For air-gapped environments, disable module installation or ensure required packages are available in the node’s repository.
  • If you need to troubleshoot prerequisite operations, you may want the Prerequisites Handler helper Pods to remain in the cluster longer. By default, these Pods are cleaned up automatically. You can disable automatic cleanup using the following Helm value:
    • Copy
    Disable Prerequisites Handler Helper Pod Cleanup
    prereqHandler.controller.janitor.enabled=false

Learn More