Prepare Ubuntu - Poolside

Complete these steps on an Ubuntu host before you run the on-premises installation. For requirements that apply to every host, see On-premises installation prerequisites.

Supported versions and architectures

Item	Supported values
Operating system	Ubuntu 22.04 LTS, Ubuntu 24.04 LTS
CPU architecture	`amd64` (`x86_64`), `arm64` (`aarch64`)

The steps on this page apply to both Ubuntu 22.04 LTS and Ubuntu 24.04 LTS.

Step 1: Install required tools

Install kubectl using sudo snap install kubectl --classic
Install jq using sudo apt install -y jq
Install yq (version v4.49.2 or later) from the yq releases page
- Download yq_linux_amd64.tar.gz or yq_linux_arm64.tar.gz and install it to /usr/local/bin/yq
Install terraform (version 1.8.5) from the Terraform 1.8.5 releases page
- Download terraform_1.8.5_linux_amd64.zip or terraform_1.8.5_linux_arm64.zip and install the binary to /usr/local/bin/terraform
- unzip is required to extract the Terraform binary
Install skopeo (version v1.18 or later) from the skopeo-binary releases page
- Download skopeo-linux-amd64 or skopeo-linux-arm64 and install it to /usr/local/bin/skopeo

Step 2: Configure the containers trust policy

Ensure the containers trust policy at /etc/containers/policy.json allows skopeo to access the RKE2 registry with the minimum required permissions. Replace <installation-bundle-path> with the fully qualified path to the root of the unpacked installation bundle. This allows the bundled images to be loaded into the local RKE2 registry during Step 2 of the on-premises installation.

{
  "default": [
    {
      "type": "reject"
    }
  ],
  "transports": {
    "docker": {
      "localhost:30500": [{"type": "insecureAcceptAnything"}]
    },
    "dir": {
      "<installation-bundle-path>": [{"type": "insecureAcceptAnything"}]
    }
  }
}

Step 3: Configure kernel parameters

Poolside file watchers can exceed the Ubuntu default for inotify instances. Set the following parameter to 65535 or higher:

fs.inotify.max_user_instances = 65535

To apply the setting, add the parameter under /etc/sysctl.d/ and reload:

echo "fs.inotify.max_user_instances = 65535" | sudo tee /etc/sysctl.d/99-poolside.conf
sudo sysctl --system

Step 4: Disable the `nouveau` driver

Confirm that the nouveau graphics driver is not loaded. For instructions, see Disable the nouveau driver in the NVIDIA documentation. Run the following command to check whether the nouveau driver is loaded. If the command returns output, follow the next steps to turn off the driver and reboot.

lsmod | grep nouveau

If the nouveau driver is loaded:

cat <<EOF | sudo tee /etc/modprobe.d/blacklist-nouveau.conf
blacklist nouveau
options nouveau modeset=0
EOF

# Regenerate the kernel initramfs.
sudo update-initramfs -u

# Reboot your system:
sudo reboot

# After reboot, confirm that nouveau is not loaded.
lsmod | grep nouveau

Step 5: Choose a GPU driver installation method

When no NVIDIA driver is installed on the host, the GPU Operator compiles and installs one from its driver container. The container needs the packages for the running kernel from external Ubuntu repositories, an internal APT mirror, or the host APT cache.

The driver compiled by the GPU Operator is not signed and is not compatible with Secure Boot. If you require Secure Boot, preinstall the driver on the host.

Use external Ubuntu package repositories

If the host can reach the Ubuntu package repositories and Secure Boot is disabled, do not preinstall an NVIDIA driver. The GPU Operator installs the driver during Step 2 of the on-premises installation.

Use the host APT cache

On an air-gapped host, the GPU Operator can compile the driver if you ran apt update before disconnecting the host and the APT cache contains these packages for the kernel version reported by uname -r:

linux-headers-<kernel-version>
linux-image-<kernel-version>
linux-modules-<kernel-version>

If the cache does not contain all required packages, use an internal APT mirror or preinstall the driver.

Use an internal APT mirror

If the host can reach an internal APT mirror, configure the GPU Operator driver container to use it. Before you run Step 2 of the installation, add the following configuration to 02-infra-services/terraform.tfvars:

gpu_operator_driver_container_config = {
  package_repository_config_b64 = "<base64-encoded-apt-configuration>"
  ca_certificate_config_b64     = ""
  environment_variables         = {}
}

package_repository_config_b64: A base64-encoded APT repository configuration in the format described in NVIDIA’s air-gapped GPU Operator documentation
ca_certificate_config_b64: An optional base64-encoded CA chain, including intermediate certificates, when the mirror uses a TLS certificate signed by an internal CA
environment_variables: An optional map of NAME = VALUE environment variables passed to the driver container, such as PROXY and NO_PROXY

Preinstall the NVIDIA driver

Preinstall the driver if you require Secure Boot or the GPU Operator cannot access the required kernel packages. Follow the NVIDIA driver installation instructions for Ubuntu. Install NVIDIA driver version , which is the version fully validated with this installation bundle. Earlier driver versions are not supported. Later versions might work, but can cause compatibility issues because they have not been validated against this bundle. After you install the driver, run nvidia-smi and confirm that it reports the host GPUs. During installation, the GPU Operator detects the host driver and skips driver compilation.

Step 6: Verify prerequisites

Your host is ready when the following checks pass:

Confirm that the required tools are installed and on the path:

kubectl version --client
jq --version
/usr/local/bin/yq --version
/usr/local/bin/terraform version
/usr/local/bin/skopeo --version

Confirm that the nouveau driver is not loaded. This command returns no output:
lsmod | grep nouveau

Next steps

Install on-premises

​Supported versions and architectures

​Step 1: Install required tools

​Step 2: Configure the containers trust policy

​Step 3: Configure kernel parameters

​Step 4: Disable the nouveau driver

​Step 5: Choose a GPU driver installation method

​Use external Ubuntu package repositories

​Use the host APT cache

​Use an internal APT mirror

​Preinstall the NVIDIA driver

​Step 6: Verify prerequisites

​Next steps

​Related resources

Supported versions and architectures

Step 1: Install required tools

Step 2: Configure the containers trust policy

Step 3: Configure kernel parameters

Step 4: Disable the `nouveau` driver

Step 5: Choose a GPU driver installation method

Use external Ubuntu package repositories

Use the host APT cache

Use an internal APT mirror

Preinstall the NVIDIA driver

Step 6: Verify prerequisites

Next steps

Related resources