> ## Documentation Index
> Fetch the complete documentation index at: https://docs.neuraltrust.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenShift — Hybrid deployment

> Complete walkthrough for deploying the NeuralTrust Data Plane on Red Hat OpenShift with the Control Plane on NeuralTrust SaaS. Covers project setup, SCC, image pull secret linking, full values overlay, Routes, enrollment, and verification.

This guide walks you end-to-end through a **hybrid deployment** on OpenShift — the Data Plane, TrustGate, and Firewall run in your OpenShift cluster; the Control Plane UI, API, and Scheduler run on NeuralTrust SaaS.

For the full-stack alternative, see [OpenShift self-hosted](./self-hosted).

## What you'll end up with

| Component                             | Location                             | Replicas |
| ------------------------------------- | ------------------------------------ | -------- |
| Data Plane API, worker, Kafka Connect | Your OpenShift cluster               | 2, 1, 1  |
| TrustGate admin / gateway / actions   | Your OpenShift cluster               | 2 each   |
| Firewall gateway + 5 workers          | Your OpenShift cluster               | 2 + 5    |
| ClickHouse, Kafka, PostgreSQL, Redis  | Your OpenShift cluster (or external) | 1 each   |
| Control Plane API, UI, Scheduler      | **NeuralTrust SaaS**                 | —        |

See [Image catalog](../images) for the full inventory.

## Prerequisites

| Resource                                | Recommended                                                                                                 |
| --------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| OpenShift version                       | 4.10+                                                                                                       |
| CPU pool node spec                      | 8 vCPU / 32 GiB                                                                                             |
| Min CPU nodes                           | **≥ 4** across 3 AZs. Drop to 3 if Firewall workers run on GPU nodes.                                       |
| GPU pool *(optional, for GPU Firewall)* | 4 vCPU / 16 GiB + 1 × NVIDIA GPU — 5 nodes (one per default Firewall worker). Requires NVIDIA GPU Operator. |
| Storage                                 | Cluster default; for ROSA, `gp3-csi`; for ARO, `managed-premium`; for ODF, `ocs-storagecluster-ceph-rbd`    |
| DNS                                     | OpenShift wildcard or custom domain (e.g. `platform.example.com`)                                           |
| Certificates                            | Router default cert, custom Route TLS, or cert-manager + Routes                                             |
| Image pull                              | `gcr-keys.json` from NeuralTrust                                                                            |
| NeuralTrust tenant                      | A SaaS Control Plane tenant — request from [support@neuraltrust.ai](mailto:support@neuraltrust.ai)          |

Sizing baseline: \~20.5 vCPU / 58.5 GiB requests / 80 GiB PVC (defaults with CPU Firewall).

## Step 1 — Create the project

```bash theme={null}
oc login -u <user> -p <password> https://api.<cluster>.openshift.com:6443
oc new-project neuraltrust
```

## Step 2 — Create and link the image pull secret

```bash theme={null}
oc create secret docker-registry gcr-secret \
  --docker-server=europe-west1-docker.pkg.dev \
  --docker-username=_json_key \
  --docker-password="$(cat path/to/gcr-keys.json)" \
  --docker-email=admin@neuraltrust.ai \
  -n neuraltrust

# Pre-link to default + builder service accounts
oc secrets link default gcr-secret --for=pull -n neuraltrust
oc secrets link builder gcr-secret --for=pull -n neuraltrust
```

After the chart install, link `gcr-secret` to the component-specific service accounts as well (see [Step 7](#step-7-link-pull-secret-to-component-service-accounts)).

## Step 3 — Write your values overlay

Save as `my-values.yaml`:

```yaml theme={null}
# Hybrid deployment on OpenShift
global:
  platform: "openshift"
  domain: "apps.<cluster>.openshift.com"   # OpenShift wildcard
  # or domain: "platform.example.com"      # for a custom domain
  storageClass: ""                          # use cluster default
  autoGenerateSecrets: true
  security:
    allowInsecureImages: true               # required for some upstream images on OpenShift

# Control Plane disabled — runs on NeuralTrust SaaS
neuraltrust-control-plane:
  controlPlane:
    enabled: false
  infrastructure:
    postgresql:
      deploy: true        # for TrustGate admin metadata

# Data Plane in your cluster
neuraltrust-data-plane:
  dataPlane:
    enabled: true

# TrustGate
trustgate:
  enabled: true
  global:
    env:
      SERVER_BASE_DOMAIN: "apps.<cluster>.openshift.com"

# Firewall in-cluster
neuraltrust-firewall:
  firewall:
    enabled: true

# Infrastructure
infrastructure:
  clickhouse:
    deploy: true
  kafka:
    deploy: true
```

<Tip>
  For OpenShift, the chart creates **Routes**, not Ingresses, when `global.platform: "openshift"`. Route hostnames follow the long pattern: `data-plane-api.<domain>`, `trustgate-admin.<domain>`, `trustgate-gateway.<domain>`, `trustgate-actions.<domain>`.
</Tip>

### Using external managed services

```yaml theme={null}
infrastructure:
  clickhouse:
    deploy: false
    external:
      host: "your-tenant.clickhouse.cloud"
      port: "8443"
      user: "neuraltrust"
      password: ""
      database: "neuraltrust"
  kafka:
    deploy: false
    external:
      bootstrapServers: "<bootstrap>:9092"

neuraltrust-control-plane:
  infrastructure:
    postgresql:
      deploy: false
  controlPlane:
    components:
      postgresql:
        secrets:
          host: "<rds-or-aro-postgres>.example.com"
          port: "5432"
          user: "neuraltrust"
          password: ""
          database: "neuraltrust"
```

For ROSA, RDS or Aurora is the natural choice; for ARO, Azure Database for PostgreSQL Flexible Server fits. For ClickHouse Cloud, see the [native-port caveat](../feature-flags#required-clickhouse-cloud-caveat) before installing.

## Step 4 — Install

```bash theme={null}
helm upgrade --install neuraltrust-platform \
  oci://europe-west1-docker.pkg.dev/neuraltrust-app-prod/helm-charts/neuraltrust-platform \
  --version <VERSION> \
  --namespace neuraltrust \
  -f my-values.yaml
```

## Step 5 — Check Routes and DNS

```bash theme={null}
oc get route -n neuraltrust
```

You should see Routes for:

| Route               | Host                         |
| ------------------- | ---------------------------- |
| `data-plane-api`    | `data-plane-api.<domain>`    |
| `trustgate-admin`   | `trustgate-admin.<domain>`   |
| `trustgate-gateway` | `trustgate-gateway.<domain>` |
| `trustgate-actions` | `trustgate-actions.<domain>` |

If you're using the OpenShift wildcard DNS (`*.apps.<cluster>...`), Routes are reachable immediately. For a custom domain, add CNAME records pointing to your router's canonical hostname.

## Step 6 — Custom TLS for Routes (optional)

By default, Routes use the OpenShift router's wildcard certificate. To bring your own cert, attach it to each Route:

```yaml theme={null}
trustgate:
  ingress:
    controlPlane:
      route:
        tls:
          termination: edge
          certificate: |
            -----BEGIN CERTIFICATE-----
            ...
          key: |
            -----BEGIN PRIVATE KEY-----
            ...
```

Prefer storing certs in OpenShift Secrets and templating values from there.

## Step 7 — Link pull secret to component service accounts

After install, ensure every component service account can pull from the private registry:

```bash theme={null}
for sa in \
  data-plane-api data-plane-worker kafka-connect \
  trustgate-control-plane trustgate-data-plane trustgate-actions \
  firewall ; do
    oc secrets link "$sa" gcr-secret --for=pull -n neuraltrust
done
```

(Service-account names may vary slightly — check `oc get sa -n neuraltrust`.)

## Step 8 — Enroll the Data Plane with NeuralTrust SaaS

<Steps>
  <Step title="Get the Data Plane JWT secret">
    ```bash theme={null}
    oc get secret data-plane-jwt-secret -n neuraltrust \
      -o jsonpath='{.data.DATA_PLANE_JWT_SECRET}' | base64 -d
    ```
  </Step>

  <Step title="Open the NeuralTrust portal">
    Log in at the URL provided by NeuralTrust.
  </Step>

  <Step title="Connect the Data Plane">
    **Team Settings → Advanced → Connect Data Plane**. Provide the Data Plane Route URL (`https://data-plane-api.<domain>`), the JWT secret, and the region. See [Platform › Advanced](/platform/advanced).
  </Step>

  <Step title="Verify connectivity">
    On success, your data plane shows as **Connected** in the portal.
  </Step>
</Steps>

## Step 9 — Send traffic through TrustGate

Point your AI applications at the TrustGate Route: `https://trustgate-gateway.<domain>`. For gateway / route / plugin configuration, see [TrustGate › Getting started](/trustgate/overview).

## Verification

```bash theme={null}
oc get pods -n neuraltrust
oc get route -n neuraltrust

curl https://data-plane-api.<domain>/health
curl https://trustgate-gateway.<domain>/__health
```

In the NeuralTrust portal: Data Plane status **Connected**, TrustGate receiving traffic, Firewall classifying (if enabled).

## Upgrading

```bash theme={null}
helm upgrade neuraltrust-platform \
  oci://europe-west1-docker.pkg.dev/neuraltrust-app-prod/helm-charts/neuraltrust-platform \
  --version <NEW_VERSION> \
  --namespace neuraltrust \
  -f my-values.yaml
```

## Migration to self-hosted

```yaml theme={null}
neuraltrust-control-plane:
  controlPlane:
    enabled: true
```

The chart adds Routes for `control-plane-api.<domain>`, `control-plane-app.<domain>`, `control-plane-scheduler.<domain>`. See [Self-hosted on OpenShift](./self-hosted) for the full picture.

## Troubleshooting

| Symptom                               | Likely cause                      | Fix                                                                    |
| ------------------------------------- | --------------------------------- | ---------------------------------------------------------------------- |
| Pods stuck `ImagePullBackOff`         | `gcr-secret` not linked to the SA | `oc secrets link <sa> gcr-secret --for=pull -n neuraltrust`            |
| Route returns 503                     | Backend pods not Ready            | `oc get pods` — check readiness probes                                 |
| Pod SCC error                         | Custom UID conflicts              | Verify you haven't overridden `podSecurityContext` to a fixed UID      |
| ClickHouse `Permission denied` on PVC | UID/GID conflict                  | The chart sets OpenShift-aware SCC; check that you haven't disabled it |
| TrustGate can't reach Firewall        | Service name mismatch             | Default is `http://firewall:80`                                        |

## Related guides

* [Self-hosted deployment on OpenShift](./self-hosted) — Control Plane in your cluster
* [OpenShift overview](./overview) — cluster prerequisites and OpenShift-specific defaults
* [Deployment models](../deployment-models) — hybrid vs self-hosted comparison
* [Image catalog](../images) — what runs in hybrid mode
* [Secrets management](../secrets) — auto-generation, External Secrets Operator
* [Firewall deployment](../firewall) — GPU workers on OpenShift