Skip to content

About

NeuralTrust platform helm chart.

Topics

Resources

Contributing

Stars

5 stars

Watchers

0 watching

Forks

Latest commit

 

History

709 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

NeuralTrust Platform

Deploy NeuralTrust on Kubernetes with one Helm umbrella chart.

Choose a deployment mode

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.


Quick start (hybrid)

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.

1. Check prerequisites

  • 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 — see docs/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 (eu default, us for Americas), plus inbound from the NeuralTrust source IP — docs/hybrid-network.md
  • Credentials for the NeuralTrust image registry

2. Create the namespace and image pull secret

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 neuraltrust

This 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.

3. Create the operator-supplied Secrets

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.

4. Write your values file

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: true to your values before upgrading; otherwise supply TrustGuard's firewall JWT as above. With neither, helm upgrade fails 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).

5. Install

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.yaml

Validate first with helm template if you want to inspect the manifests:

helm template neuraltrust-platform <chart> \
  --namespace neuraltrust -f values-required.yaml > /tmp/rendered.yaml

6. Verify

kubectl get pods -n neuraltrust
kubectl get ingress -n neuraltrust

With 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.

Install fails? Common causes

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

What hybrid deploys

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 key agentgateway:; Kubernetes names stay agentgateway-*)
  • TrustGuard runtime, calling the NeuralTrust-hosted Firewall by default (global.firewall.deploy: true runs 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.

Deployment modes

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

Cluster sizing (defaults)

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.

Datastores

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: false

For 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.

Platform and ingress

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.

Optional components

  • umbrella OTel Collector: portable cluster observability
  • AlertEngine: external-mode alert evaluation and SIEM/integration forwarding (alertengine.enabled: false to 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.

Values examples

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.

Further reading

In this repo:

Public documentation at docs.neuraltrust.ai:

License

Apache License 2.0


Looking for v1? The legacy TrustGate/Kafka line ended at v1.14.16 — install it with --version ~1.14.0.

About

NeuralTrust platform helm chart.

Topics

Resources

Contributing

Stars

5 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages