GroundX On-Prem on OpenShift | Documentation

Installing GroundX On-Prem on OpenShift

Install GroundX On-Prem on OpenShift, Red Hat’s container platform. This free, open source deployment includes the components needed to run retrieval augmented generation (RAG) in a controlled environment.

This guide adapts the AWS EKS installation guide for OpenShift.

See Choose Your GroundX Path to compare deployment options, including managing an on-prem instance with GroundX Agent Harness.

⚠️ Warning ⚠️

Resources created by this guide may incur charges. OpenShift experience is recommended.

Prerequisites

Before starting, ensure you have:

A running OpenShift cluster, on-premises or in a cloud provider.
Node Feature Discovery and the NVIDIA GPU Operator installed (link)

1) Defining the Infrastructure

Clone the repository:

git clone https://github.com/eyelevelai/groundx-on-prem.git

Create the configuration file:

cd groundx-on-prem/
cp operator/env.tfvars.example-openshift operator/env.tfvars

operator/env.tfvars defines the Terraform resources. The copied example uses the default OpenShift configuration. Edit it to suit your deployment.

2) Update admin information in env.tfvars

For security, we strongly recommend changing these values in operator/env.tfvars:

admin.api_key: Set a random UUID, generated with bin/uuid. This is the admin API key used for inter-service communication.
admin.username: Set a random UUID, generated with bin/uuid. This is the admin user ID used for inter-service communication.
admin.email: Set the admin account email address.

3) Update Persistent Volume Class Definition in env.tfvars

Many GroundX pods require persistent volumes (PVs). Define a storage class in the OpenShift cluster for these pods.

Set cluster.pv in operator/env.tfvars to use that storage class. The default is:

name = "eyelevel-pv"
type = "ocs-storagecluster-ceph-rbd"

4) Label Nodes

GroundX pods can use 1 to 5 node groups, depending on how you allocate resources for the 5 pod classes. By default, cluster.nodes in env.tfvars assigns a separate node group to each class:

nodes            = {
      cpu_memory     = "eyelevel-cpu-memory"
      cpu_only       = "eyelevel-cpu-only"
      gpu_layout     = "eyelevel-gpu-layout"
      gpu_ranker     = "eyelevel-gpu-ranker"
      gpu_summary    = "eyelevel-gpu-summary"
    }

The GPU node groups and resource needs in a default installation are:

gpu_layout
- 0.5 vCPU
- 2 GB RAM
- 8 GB of GPU memory
- ~10 GB hard disk space
gpu_ranker
- 1.5 vCPU
- 4 GB RAM
- 8 GB of GPU memory
- ~10 GB hard disk space
gpu_summary
- 1 vCPU
- 4 GB RAM
- 40 GB of GPU memory
- ~40 GB hard disk space

The CPU node groups and resource needs in a default installation are:

cpu_memory
- 3.2 vCPU
- 2.5 GB RAM
- ~10 GB hard disk space
cpu_only
- 3.5 vCPU
- 7 GB RAM
- ~120 GB hard disk space

To use 1 node group with enough resources for all 5 pod classes, set the labels in cluster.nodes within env.tfvars to:

nodes            = {
      cpu_memory     = "eyelevel-node"
      cpu_only       = "eyelevel-node"
      gpu_layout     = "eyelevel-node"
      gpu_ranker     = "eyelevel-node"
      gpu_summary    = "eyelevel-node"
    }

To use separate CPU and GPU node groups with enough resources for all 5 pod classes, set the labels to:

nodes            = {
      cpu_memory     = "eyelevel-cpu"
      cpu_only       = "eyelevel-cpu"
      gpu_layout     = "eyelevel-gpu"
      gpu_ranker     = "eyelevel-gpu"
      gpu_summary    = "eyelevel-gpu"
    }

5) Deploying GroundX

Deploy GroundX with the saved configuration:

./operator/setup

This deploys GroundX On-Prem to the configured OpenShift cluster.

6) Setting Up A Client To Talk TO GroundX On-Prem

Run kubectl -n eyelevel get route to find the API endpoint for the SDK. Use the address associated with the GroundX load balancer.

Example address:

EXTERNAL-IP
groundx-service-eyelevel.apps.ocp.psdc.lan

Configure the SDK with that API endpoint and the admin.api_key from step 2:

from groundx import GroundX
external_ip = "groundx-service-eyelevel.apps.ocp.psdc.lan"
api_key="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
client = GroundX(api_key=api_key, base_url=f"http://{external_ip}/api")

The client works similarly to a client connected to hosted GroundX. See the API Documentation for endpoint details and tutorials.

Protected file prerequisites

Follow File Access and Sharing using the deployment’s local API, file gateway, and signing endpoints. Before ingesting protected files, verify:

Private storage origins.
Compatible API, processor, and gateway images.
Policy, cache, and database readiness.
Protection for existing files.

Test each advertised storage backend and TLS certificate trust path at pinned versions. S3 compatibility alone does not establish vendor support. Verify local MCP transport authentication; do not assume it uses hosted OAuth.