Deploy NeuralTrust on Kubernetes with one Helm umbrella chart.
| Mode | Control plane | What runs in your cluster | Start here |
|---|---|---|---|
hybrid (default) |
Hosted by NeuralTrust | The data path: TrustGate, TrustGuard, data-plane API, one DataAgent per product; the Firewall is NeuralTrust-hosted by default | Quick start below |
external |
Yours | Everything, including the console, ClickHouse analytics, DataCore, and AlertEngine | README-EXTERNAL.md |
saas |
Yours, and it also serves data planes in other clusters | external plus DataBridge and a public telemetry ingest gateway |
docs/saas-mode.md |
On OpenShift, all modes work but ingress differs — use README-OPENSHIFT.md instead of the quick start below.
This produces a working full-product hybrid data plane. Every step is required. Step 3 is where most installs fail, because those four Secrets are never auto-generated by the chart.
- A Kubernetes cluster with an ingress controller, and Helm 3.8+ for OCI installs
- 3 nodes of 8 vCPU / 32 GiB (
m6i.2xlarge,Standard_D8s_v5,e2-standard-8) for all three products, with cluster autoscaling on — seedocs/sizing.md - A base domain you can point at the cluster ingress, for example
platform.example.com - Outbound TCP 443 to the NeuralTrust config-sync, DataBridge, and telemetry
hosts for your
global.saasRegion(eudefault,usfor Americas), plus inbound from the NeuralTrust source IP —docs/hybrid-network.md - Credentials for the NeuralTrust image registry
NeuralTrust images are private. NeuralTrust sends you a registry key (a JSON service-account key) when your account is provisioned — turn it into the pull Secret the chart references by default:
kubectl create namespace neuraltrust
GCR_KEY_FILE=./gcr-keys.json ./create-image-pull-secret.sh --namespace neuraltrustThis creates gcr-secret. Every component defaults to that name, so pulling
directly from the NeuralTrust registry needs no values changes.
If your cluster cannot reach that registry, mirror the images into your own and
set global.imageRegistry, keeping the repository names and tags, plus
global.imageRegistryScope: all so the OTel collector images move too. Confirm
with helm template ... | grep image:. Full guidance:
Container images.
Create TrustGate and TrustGuard in the NeuralTrust console first. Each product
issues a config-sync token and a DataAgent enrolment JWT, plus a
firewall JWT (FIREWALL_JWT) for the NeuralTrust-hosted firewall. The
console shows the firewall JWT only once. Full console walkthrough:
Console setup.
# Config-sync — pulls runtime configuration from the hosted control plane
kubectl create secret generic agentgateway-config-sync -n neuraltrust \
--from-literal=CONFIG_SYNC_TOKEN='<trustgate-config-sync-token>'
kubectl create secret generic trustguard-config-sync -n neuraltrust \
--from-literal=CONFIG_SYNC_TOKEN='<trustguard-config-sync-token>'
# DataAgent enrolment — powers DataBridge reads and product OTLP egress
kubectl create secret generic dataagent-enrolment-trustgate -n neuraltrust \
--from-literal=ENROLMENT_TOKEN='<trustgate-enrolment-jwt>'
kubectl create secret generic dataagent-enrolment-trustguard -n neuraltrust \
--from-literal=ENROLMENT_TOKEN='<trustguard-enrolment-jwt>'
# Firewall — TrustGuard's client for the NeuralTrust-hosted firewall
kubectl create secret generic trustguard-firewall -n neuraltrust \
--from-literal=FIREWALL_JWT='<trustguard-firewall-jwt>'To run the firewall in your own cluster instead, skip trustguard-firewall and
set global.firewall.deploy: true in step 4. TrustGate's firewall JWT is
optional (smart-routing complexity scoring); store it the same way as
agentgateway-firewall and set agentgateway.firewall.existingSecret.name.
The enrolment JWT already carries tenant_id and instance_id — do not
duplicate them in values. Every other secret (JWT signing keys, PostgreSQL
password, the config-sync CONFIG_SYNC_LKG_KEY cache key, and so on) is
generated on first install and reused on upgrade while
global.autoGenerateSecrets: true and global.preserveExistingSecrets: false.
Turn either off and creating those credentials becomes your job. See
SECRETS.md.
values-required.yaml is the tracked full-hybrid
preset and already matches the Secret names above. Copy it and change the two
cluster-specific lines:
global:
platform: "kubernetes" # aws | gcp | azure | openshift | kubernetes
domain: "platform.example.com"
products:
trustgate: true
trustguard: true
dataPlane: true
agentgateway:
configSync:
existingSecret:
name: "agentgateway-config-sync"
dataagent:
enrolment:
existingSecret:
name: "dataagent-enrolment-trustgate"
trustguard:
configSync:
existingSecret:
name: "trustguard-config-sync"
dataagent:
enrolment:
existingSecret:
name: "dataagent-enrolment-trustguard"
firewall:
jwtExistingSecret:
name: "trustguard-firewall"Upgrading an install that runs the Firewall in your cluster? Every mode now calls the NeuralTrust-hosted Firewall by default. To keep yours, add
global.firewall.deploy: trueto your values before upgrading; otherwise supply TrustGuard's firewall JWT as above. With neither,helm upgradefails and says so. See CHANGELOG.md.
Product flags default to off and at least one must be true. They are keyed
by product id, which for TrustGate is not the same as its values block:
global.products.trustgate selects it, agentgateway: configures it. Older
consoles emit global.products.agentgateway: true in the generated
values.yaml; rename that key to trustgate or the render fails with
global.products supports only trustgate, trustguard, and dataPlane.
For a subset, drop the flags you do not need and use the matching slice —
values-trustgate.yaml.example,
values-trustguard.yaml.example, or
values-red-teaming.yaml.example
(data-plane API only, no DataAgent or config-sync needed).
The chart registry is public — no helm registry login. Only the container
images are private, which is what the pull Secret from step 1 covers.
helm upgrade --install neuraltrust-platform \
oci://europe-west1-docker.pkg.dev/neuraltrust-app-prod/helm-charts/neuraltrust-platform \
--version <VERSION> \
--namespace neuraltrust --create-namespace \
-f values-required.yamlValidate first with helm template if you want to inspect the manifests:
helm template neuraltrust-platform <chart> \
--namespace neuraltrust -f values-required.yaml > /tmp/rendered.yamlkubectl get pods -n neuraltrust
kubectl get ingress -n neuraltrustWith all three products on you should see agentgateway-proxy,
agentgateway-mcp, trustguard-data-plane, data-plane-api, dataagent,
dataagent-trustguard, control-plane-postgresql, and redis — plus
firewall and its workers with global.firewall.deploy: true.
Default hostnames derive from global.domain:
| Service | Host |
|---|---|
| TrustGate LLM gateway | gateway.<domain> and *.llm.<domain> |
| TrustGate MCP | mcp.<domain> and *.mcp.<domain> |
| TrustGuard | trustguard.<domain> |
| data-plane API | data-plane-api.<domain> |
Point DNS at the ingress address, then finish the LLM and MCP URL setup in the console.
| Error | Fix |
|---|---|
v2 hybrid requires at least one product |
Set at least one global.products.* to true |
agentgateway config-sync requires CONFIG_SYNC_TOKEN |
Create the Secrets in step 3, or set configSync.enabled: false for Postgres-managed configuration |
hybrid trustgate/trustguard requires dataagent enrolment |
Create the enrolment Secrets in step 3 |
TrustGuard uses the NeuralTrust-hosted firewall by default and needs its firewall JWT |
Create trustguard-firewall in step 3, or set global.firewall.deploy: true to keep the firewall in your cluster |
global.clickstack.enabled is no longer supported |
Hybrid OTLP is mandatory. Use global.deploymentMode: external for air-gapped or local-only telemetry |
Hybrid keeps the control plane hosted and runs the data path in your cluster:
- TrustGate proxy and MCP runtimes (product flag
global.products.trustgate; values keyagentgateway:; Kubernetes names stayagentgateway-*) - TrustGuard runtime, calling the NeuralTrust-hosted Firewall by default
(
global.firewall.deploy: trueruns it in your cluster) - data-plane API, PostgreSQL-backed by default — no ClickHouse in hybrid
- in-cluster PostgreSQL and Redis by default
- one DataAgent per enabled product (TrustGate / TrustGuard)
Config-sync is on by default (mode-derived, enabled: null in subcharts).
Overlays set existingSecret.name only — do not restate enabled: true. Set
configSync.enabled: false only for Postgres-managed runtime configuration.
Product OTLP is mandatory when TrustGate or TrustGuard is enabled. Those
apps send plain OTLP to a local clickstack-egress-collector on the primary
DataAgent pod; the sidecar exchanges the DataAgent enrolment JWT for a
short-lived OTLP access token and exports to the hosted telemetry endpoint.
There is no direct ClickStack bearer on apps and no hybrid opt-out
(global.clickstack.enabled and global.clickstack.egress.enabled are
rejected). Air-gapped or local-only product telemetry requires
global.deploymentMode: external. A data-plane-only hybrid skips DataAgent
entirely.
Full contract: docs/architecture.md and
values-hybrid.yaml.example.
| Mode | Hosted control plane | Workloads in cluster | Analytics path |
|---|---|---|---|
hybrid (default) |
Yes | TrustGate / TrustGuard / data-plane-api via positive global.products (at least one); TrustGuard calls the NeuralTrust-hosted Firewall unless global.firewall.deploy: true; per-product DataAgent when TrustGate/TrustGuard is on |
Hosted analytics via enrolment-backed ClickStack OTLP. Raw payloads stay in Postgres for DataAgent. No in-cluster ClickHouse |
external |
No | Full product stack (opt out per product with global.products.<name>: false) plus control planes, product API/app, DataCore, AlertEngine; TrustGuard calls the NeuralTrust-hosted Firewall unless global.firewall.deploy: true |
ClickStack OTel Collector writes to ClickHouse; data-plane API reads ClickHouse |
saas |
No — this cluster is one, for hybrid clusters elsewhere |
Everything external renders, plus DataBridge (HA by default) and the ClickStack ingest gateway |
Local ClickHouse for central telemetry; DataCore runs RESIDENCY_BACKEND=hybrid and reaches remote data planes through DataBridge. Operator path: saas-mode quick start |
Kubernetes schedules pods by their resource requests, so the chart's defaults
set the smallest cluster a new installation can be scheduled on. Use these counts
as each node pool's minimum and enable cluster autoscaling to add capacity as
load grows — see docs/sizing.md.
| Scenario | Firewall on CPU | Firewall on GPU |
|---|---|---|
| Hybrid, all products or TrustGuard only, hosted firewall (default) | 2 × 8 vCPU / 16 GiB | — (no Firewall here) |
| Hybrid, all products, in-cluster firewall | 3 × 8 vCPU / 32 GiB | 2 × 8 vCPU / 16 GiB + 2 × L4 GPU nodes |
| Hybrid, TrustGuard only, in-cluster firewall | 3 × 8 vCPU / 16 GiB | 2 × 8 vCPU / 16 GiB + 2 × L4 GPU nodes |
| Hybrid, TrustGate only | 2 × 8 vCPU / 16 GiB | — |
| External or SaaS, hosted firewall (default) | 3 × 8 vCPU / 16 GiB | — (no Firewall here) |
| External or SaaS, in-cluster firewall | 4 × 8 vCPU / 32 GiB | 3 × 8 vCPU / 16 GiB + 2 × L4 GPU nodes |
8 vCPU / 32 GiB: AWS m6i.2xlarge, Azure Standard_D8s_v5, GCP
e2-standard-8. 8 vCPU / 16 GiB: AWS c6i.2xlarge, Azure Standard_F8s_v2,
GCP c4-highcpu-8. L4 GPU node (8 vCPU / 32 GiB, one L4, shared by four CUDA
MPS clients): AWS g6.2xlarge, GCP g2-standard-8.
PostgreSQL and Redis deploy in-cluster by default in both modes. In-cluster
ClickHouse renders only in external. Each can be replaced with a managed
service:
global:
postgresql:
deploy: false
redis:
deploy: false
# Where the managed ClickHouse actually is. Needed alongside deploy: false --
# every consumer resolves through here (see README-EXTERNAL.md).
clickhouse:
host: "clickhouse.example.com"
httpPort: "8443"
nativePort: "9440"
infrastructure:
clickhouse:
deploy: falseFor the complete endpoint and existing-secret pattern, use
values-hybrid.yaml.example in hybrid and
values-managed-datastores.yaml.example
in external.
In hybrid, AgentGateway, TrustGuard, DataAgent, and data-plane-api share
ONE PostgreSQL role owning ONE database, driven by global.postgresql
(defaults: user neuraltrust, database neuraltrust). The chart renders shared
postgresql-secrets and redis-secrets (from global.redis) for all of them.
Each stores one canonical name per fact — POSTGRES_*, REDIS_* — and the
chart maps those keys to whatever variable names a given container expects, so
do not expect DB_* or DATABASE_URL as keys inside a chart-managed Secret.
If instead you supply your own with global.postgresql.existingSecret.name, the
chart injects it verbatim and your keys must be the DB_* names the applications
read; see docs/architecture.md. There is no
chart-managed init Job — application migrations own their tables, so pre-create
the role and database when using a managed PostgreSQL.
In external, runtime services use per-service *.database / *.redis
overlays. global.postgresql still gates in-cluster PostgreSQL and feeds
control-plane postgresql-secrets for control-plane-api/app. See
docs/architecture.md for the full contract.
global.platform selects provider-specific ingress and security behavior. Left
empty (the default), the chart detects it: gcp when the cluster serves GKE's
BackendConfig API, otherwise kubernetes. An offline helm template cannot
see the cluster, so set gcp explicitly when rendering for GKE that way.
| Value | Target |
|---|---|
gcp |
GKE / GCE Ingress |
aws |
EKS / AWS Load Balancer Controller |
azure |
AKS / Application Gateway |
openshift |
OpenShift Routes or Ingress |
kubernetes |
Generic Kubernetes (detected default off GKE) |
Set global.domain to derive service hostnames. Set global.imageRegistry to
mirror all images into a private registry.
global.ingress.provider overrides the provider global.platform implies.
With gateway-api the chart renders Gateway API HTTPRoutes instead of
Ingresses: one per public surface, with the same hosts and backends, attached to
an existing Gateway named in global.ingress.gatewayApi.parentRefs. The Gateway
owns TLS. This works on any cluster that implements Gateway API, including GKE,
where the chart also adds a HealthCheckPolicy per backend. See
values-gateway-api.yaml.example.
Provider prerequisites (node shapes, load balancer, managed stores) are covered per cloud in the public docs: GKE · EKS · AKS · OpenShift · vanilla Kubernetes.
- umbrella OTel Collector: portable cluster observability
- AlertEngine: external-mode alert evaluation and SIEM/integration forwarding
(
alertengine.enabled: falseto omit it)
Firewall follows TrustGuard. Where it runs is global.firewall.deploy;
firewall.enabled, firewall.firewall.enabled, and trustguard.firewall.enabled
are no-ops. Unset, every mode calls the NeuralTrust-hosted firewall with
TrustGuard's FIREWALL_JWT: hybrid takes it from app.neuraltrust.ai, external
and saas ask NeuralTrust, which sends it over a secure channel.
deploy: true runs the firewall in-cluster; deploy: false with
global.firewall.baseURL and its JWT_SECRET points at a firewall you already
run. See
VALUES_SCENARIOS.md. In-cluster, its CPU workers are
the largest memory consumer in the data path, so size for them. Choose CPU or
GPU workers via
values-dataplane-gpu.yaml.example.
| File | Mode | Purpose |
|---|---|---|
values-required.yaml |
hybrid | Full-hybrid preset used by the quick start |
values-hybrid-reference.yaml.example |
hybrid | Annotated reference for every hybrid knob |
values-hybrid.yaml.example |
hybrid | Hybrid topology overlay with managed datastores |
values-trustgate.yaml.example |
hybrid | TrustGate-only slice |
values-trustguard.yaml.example |
hybrid | TrustGuard slice (hosted Firewall) |
values-red-teaming.yaml.example |
hybrid | data-plane-API-only slice |
values-dataplane-gpu.yaml.example |
hybrid | GPU Firewall workers |
values-openshift.yaml |
hybrid | OpenShift Routes |
values-gateway-api.yaml.example |
any | HTTPRoutes on an existing Gateway instead of Ingress |
values-external.yaml.example |
external | Minimal self-hosted external |
values-managed-datastores.yaml.example |
external | Managed PostgreSQL, Redis, and ClickHouse endpoints |
values-observability-self-hosted.yaml.example |
both | Local-only observability, hosted export off |
Scenario walkthroughs: VALUES_SCENARIOS.md.
In this repo:
- External (self-hosted) guide
saasmode — your own control plane for data planes in other clusters- OpenShift guide
- Deployment guide — step-by-step across both modes
- Secrets management
- Values scenarios
- Architecture and topology contract
- Cluster sizing
- Hybrid network allowlist
- Observability and self-healing
Public documentation at docs.neuraltrust.ai:
- Deployment models — SaaS vs hybrid vs external
- Console setup — obtaining the step 3 credentials
- External (self-hosted)
- Configuration and feature flags
- Network allowlist · Sizing · Secrets
- Firewall · High availability
Apache License 2.0
Looking for v1? The legacy TrustGate/Kafka line ended at v1.14.16 — install it with --version ~1.14.0.