Onebox Deployment Guide

This document outlines the recommended installation steps for a Onebox deployment to the OneTrust Data Discovery scanner.

Prerequisites

  • Supported:

    • Ubuntu 22.04 (Recommended)

    • RHEL 7.6-7.9; 8.1-8.5, 9.+

      • CIS RHEL 7 Level 1

      • CIS RHEL 8 Level 1

    • CentOS 7.7-7.9; 8.1-8.4,

      • CIS CentOS 7

      • CIS CentOS 8

      • CentOS Stream 8

      • CentOS Stream 9

  • Installed K3S (default) or Microkubernetes

  • VM service account for sudo access with admin privileges

  • Latest version of kubectl, with a minimum version of 1.30

  • Firewall rule for server open inbound on port 8200. This will permit vault web UI access. You can restrict to needed source IPs.

Hardware Requirements

Hardware

Minimum

Recommended

vCPUs

16

32

RAM

64GB

128GB

DISK

512GB

1TB*
Note:

*1TB shall be allocated to the /var directory.

  • If the VM is partitioned to use a separate filesystem mounted for the /var directory, the storage of snap, microk8s and the persistent volume created by Onebox installer uses that space.

  • Alternatively, if a VM is partitioned in a different manner, then all of the disk space shall be allocated on the / (root) path as there is no separate mount path for /var. All the disk space going into /var directory will use the / (root) path's disk space.

K3s Deployment Approach

For Onebox deployments, K3s is OneTrust's recommended Kubernetes distribution method due to its lightweight footprint and ease of install. In the Advanced options section when creating the worker node via guided installation, you will need to select the Enable K3S setting.

Ensure the following settings are disabled:

  • Enable Micro K8s Auto-Upgrade (not applicable for K3s)

  • Airgapped worker node install (unless deploying in a fully air-gapped environment)



Download and Extract Installer

Once you have obtained the curl command from the created worker node, follow these steps:

  1. SSH into your Linux VM where the worker node will be deployed:

    CODE 
    ssh user@your-vm-hostname

  2. Create a working directory (optional):

    CODE 
    mkdir -p ~/onetrust-installer
cd ~/onetrust-installer

  3. Paste and run the curl command:

    CODE 
    curl -o 'installer.sh' -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6Ik...' 'https://app.onetrust.com/api/discovery-scan-config/...'

  4. Verify the download using:

    CODE 
    ls -lh installer.sh

  5. Run the extraction command:

    CODE 
    bash installer.sh extract-zip

  6. When prompted, enter the PIN you created during the guided installation:

    CODE 
    Enter the PIN that was created in the application during the worker node creation.
PIN: ****

  7. The installer will extract to a named directory:

    CODE 
    /home/<user>/onetrust-dd-installer-onebox-<worker-node-name>-<version>/

  8. To verify, navigate to the Onebox deployment directory:

    CODE 
    cd /home/<user>/onetrust-dd-installer-onebox-<worker-node-name>-<version>/data-discovery/onebox-deployment

  9. List the contents using:

    CODE 
    ls -la

  10. You should observe the following:

    • deploy.sh - main installation script

    • inventory/ - configuration directory

    • utils/ - helper scripts

    • prerequisite-script/ - prerequisite installation scripts

    • README.md - installation documentation

Enable Configuration Flags

  1. Open the guided environment configuration file using:

    CODE 
    vi inventory/.guided-envs

    Alternatively, you can use your preferred editor:

    CODE 
    nano inventory/.guided-envs

  2. Hardened Images will be enabled by default for new worker nodes. To check they are enabled run:

    CODE 
    grep IS_HARDENED_IMAGE_ENABLED inventory/.guided-envs

Expected: 
export IS_HARDENED_IMAGE_ENABLED='true'

  3. To enable RWX Storage class, run:

    CODE 
    grep EXTLIB_SHARED_STORAGE_NAME inventory/.guided-envs

Expected: 
export EXTLIB_SHARED_STORAGE_NAME='nfs-pod-onetrust-dd'
    Important:

    Read Write Many storage class is used for copying and loading custom libraries, jars, or files required for datasource connections. This is also used to write Java info like heapdumps and threaddumps during failures.

    nfs-pod-onetrust-dd will use a nfs-provisioner type RWX storage, which will be installed and enabled during installation. Note that deployment will attempt to install nfs utils and other dependent nfs mount libraries , this install could fail in airgapped and firewalled environments. Revert to none to continue with installation or allow outbound connection to install required nfs plugins.

  4. To configure the data directory for K3s, you can set the K3S_DATA_DIR flag. This allows you to specify a custom directory where K3s will store its data. Default value is /var/lib/rancher/k3s

    CODE 
    export K3S_DATA_DIR='/opt/k3s'
    Important:

    If SELinux is enabled on your system, this flag may not be honored or may not work as expected. For more information on enabling SELinux enforcement, refer to the K3s documentation here.

    Make sure to verify the configurations and ensure that the specified directory has the appropriate permissions for K3s to operate correctly.

  5. To configure the installation of CLI tools and plugins from OneTrust URLs instead of using the internet, you can set the f flag. This is particularly useful in firewalled and airgapped environments that only allow access to OneTrust URLs.

    CODE 
    export AIRGAPPED_CLI_INSTALL='true'
    Important:

    Important: Enabling this flag will ensure that the installer pulls and installs CLI tools, plugins, and prerequisites directly from OneTrust's URLs, bypassing the need for general internet access. Tools installed are kubectl, helm, jq, curl, k9s, perl, unzip, yq, zip, busybox

  6. The AIRGAPPED_WN_INSTALL flag enables airgapped installation mode for workernode container images in K3S environments. When enabled, the installer downloads all required workernode Docker images as compressed tar files from the OneTrust Cloud API and imports them directly into the K3S cluster's local image registry. Default value will be set to false.

    CODE 
    export AIRGAPPED_WN_INSTALL="true"

    When to use Airgapped Installs:

    • Environments with no direct internet access or restricted outbound connectivity

    • Environments where pulling images from external registries docker.onetrust.io (OneTrust’s Azure ACR) or docker.io/otcr (OneTrust’s DockerHub) is blocked by firewall rules.

    • Air-gapped or highly secured production environments

    • Environments requiring all container images to be pre-loaded locally

    CAUTION:

    Note that the Airgapped option serves as a workaround for initial installs or when clients use custom Docker Registry settings (Internal Artifactory) instead of OneTrust Docker registries and their automated release cadence. Clients using OneTrust Docker registries must safelist the required URLs after the initial install to enable ongoing upgrades.

    Disk Space Requirements for Airgapped Installs:

    • Minimum: 35 GB free space in /tmp (or custom temp directory)

    • Recommended: 50+ GB to accommodate image downloads, extraction, and import operations

    • Images are cleaned up automatically after successful import

Install & Verification

Important:

For OneBox deployments, prefix all kubectl commands with microk8s.

  • Example: microk8s kubectl

  1. Run the following to start the installation script:

    CODE 
    ./deploy.sh install

  2. The installer will perform the following steps:

    1. System Checks (~1 minute)

      • Verify system requirements

      • Check available resources

      • Validate network connectivity

    2. K3s Installation (~3-5 minutes)

      • Download and install K3s

      • Configure K3s as systemd service

      • Set up kubectl access

    3. Prerequisites Installation (~2-3 minutes)

      • Install required command-line tools

      • Configure storage classes

      • Set up DNS resolution

    4. Worker Node Deployment (~10-15 minutes)

      • Pull Docker images (hardened versions)

      • Deploy StatefulSets (Postgres, Kafka, Elasticsearch, Vault)

      • Deploy application services (scanners, job managers, ops services)

      • Configure networking and ingress

      • Initialize databases and message queues

  3. Verify K3s cluster is running with:

    CODE 
    sudo k3s kubectl get nodes

Expected: 
NAME       STATUS   ROLES                  AGE   VERSION
hostname   Ready    control-plane,master   10m   v1.28.x+k3s1

  4. Check the worker node namespace with:

    CODE 
    sudo k3s kubectl get namespaces | grep test-onebox-demo

  5. List all pods in the worker node namespace with:

    CODE 
    sudo k3s kubectl get pods -n test-onebox-demo

    All pods should show Running status after 20-30 minutes.

K3s Troubleshooting

About K3s PATH

K3s installs its binaries here:

CODE 
/usr/local/bin/k3s
/usr/local/bin/k3s-killall.sh
/usr/local/bin/k3s-uninstall.sh

sudo does not include /usr/local/bin in its default PATH on RHEL/SUSE-like distros, so commands like this fail:

CODE 
sudo k3s kubectl get nodes
# sudo: k3s: command not found

OneTrust recommends using these two safe patterns throughout your troubleshooting:

  • For scripts and documentation:

    CODE 
    sudo /usr/local/bin/k3s kubectl get nodes
sudo /usr/local/bin/k3s crictl ps
sudo /usr/local/bin/k3s kubectl get pods -A

  • For cleaner, more temporary commands

    CODE 
    export PATH=/usr/local/bin:$PATH
sudo env "PATH=$PATH" k3s kubectl get node

Basic Health Checks

CODE 
sudo systemctl status k3s
sudo journalctl -u k3s -n 200 --no-pager
sudo /usr/local/bin/k3s kubectl get nodes -o wide
sudo /usr/local/bin/k3s kubectl get pods -A

Restart and watch logs:

CODE 
sudo systemctl restart k3s
sudo journalctl -u k3s -f

Verify OS / Kernel Support

CODE 
sudo /usr/local/bin/k3s check-config

If this reports missing cgroup or kernel features, fix them before debugging anything else.

API Flakiness/Pods Not Reconciling

CODE 
sudo /usr/local/bin/k3s kubectl get ns
sudo /usr/local/bin/k3s kubectl get --raw='/readyz?verbose'

Check node pressure:

CODE 
top
df -h

K3s logs:

CODE 
sudo journalctl -u k3s -n 300 --no-pager | egrep -i 'timeout|etcd|db|panic'

Disk Usage ISsues in /var/lib/rancher/k3s

CODE 
sudo du -sh /var/lib/rancher/k3s/*

Ctr commands, use pruning carefully

CODE 
sudo /usr/local/bin/k3s ctr images list
sudo /usr/local/bin/k3s ctr images --prune

Standard Uninstall

Always try this approach before deep cleaning. This will delete PVC data, do not run if Vault, Elasticsearch and critical data is needed. This removes binaries, systemd services, and most data — but can leave mounts/locks if K3s died badly.

CODE 
sudo /usr/local/bin/k3s-uninstall.sh

Deep Clean for .lock erros, state mounts, failed reinstalls

CODE 
sudo mount --make-rprivate /
sudo pkill -9 -f "k3s|kubelet|containerd|containerd-shim|runc" || true

for TREE in /var/lib/rancher/k3s /app/k3s; do
  sudo awk '$5 ~ /^'${TREE//\//\\/}'(\/|$)/ {print $5}' /proc/self/mountinfo \
    | sort -r \
    | xargs -r -n1 sudo umount -l
done

mount | grep -E '/var/lib/rancher/k3s|/app/k3s' || echo "No mounts left under k3s trees"
sudo rm -rf /var/lib/rancher/k3s /app/k3s

Automating Microkubernetes Upgrades

Automate and secure Microkubernetes upgrades that keep clusters aligned with our latest platform version. This helps you reduce the maintenance burden and minimize compatibility and security risks with Onebox deployments.

  1. On the Data Discovery menu, select Settings. The Data Discovery section in the Global Settings screen appears.

  2. Go the General menu. The Worker Node Settings screen appears.

  3. Enable the setting Enable Microkubernetes Auto-Upgrade.



  4. Click the Save button.

  5. During installation, ensure the environment variable, export IS_GOAGENT_ENABLED, is set to true.



  6. This variable will communicate with the OneTrust cloud to confirm which version is currently operating and identify if an update is needed.



  7. If there are multiple available versions listed, each one will be upgraded to order to proceed to the most current.



Credential Vault Configuration

The "Internal" option deploys HashiCorp Vault as part of the worker node installation. This is recommended for Onebox deployments.

For more information on configuring credential vaults and the supported providers, please reference Credential Vault Options for Data Sources.

Validating Microkubernetes Installation

Note:

For customers using an internal DNS server, ensure the internal VM IP address is not included in the CIDR range used by Microkubernetes to avoid collision. By default, Microkubernetes uses 10.1.0.0.

To change pods and to learn more about CIDR in clusters, please refer to Microkubernetes install documentation.

  1. Check if ufw (Uncomplicated Firewall) is installed by running the following command:

    CODE 
    sudo ufw status

  2. If not installed, install by running the following:

    CODE 
    sudo yum install epel-release -y
sudo yum install --enablerepo="epel" ufw -y

sudo ufw enable

  3. To allow traffic on vxlan.calico, run the following:

    CODE 
    sudo ufw allow in on vxlan.calico && sudo ufw allow out on vxlan.calico

  4. To allow pods to communicate with each other and outside, run the following:

    CODE 
    sudo ufw default allow routed

  5. To check the installation and confirm no warnings, run the following:

    CODE 
    microk8s inspect