Self-host Kuery

Prerequisites

You need a Kubernetes runtime you administer, Helm, network access from the provider runtime to the hub and advertised virtual-workspace endpoints, and permission to onboard this provider. Use the common provider flow to obtain the workspace kubeconfig. The examples below use a Secret named railgrid-provider-kubeconfig with data key kubeconfig.

For production, a Postgres database and its connection string.

Install

kubectl create namespace railgrid-provider-kuery
kubectl --namespace railgrid-provider-kuery create secret generic railgrid-provider-kubeconfig \
  --from-file=kubeconfig=./kuery.kubeconfig

kuery-values.yaml with Postgres:

replicaCount: 2
hub:
  url: https://railgrid-hub.railgrid-system.svc.cluster.local:9443
  tokenSecretRef:
    name: ""
catalogEntry:
  enabled: true
store:
  driver: postgres
  persistence:
    enabled: false
  # dsn: set at install time, not in this file

The chart has no Secret reference for the DSN; store.dsn is a plain value. Keep it out of committed values files: pass it on the command line from a Secret, or, with Flux, inject it with valuesFrom from a Secret key into store.dsn.

helm upgrade --install kuery oci://ghcr.io/railgrid/charts/railgrid-kuery-provider --version CHART_VERSION \
  --namespace railgrid-provider-kuery --values kuery-values.yaml \
  --set-string store.dsn="$(kubectl -n railgrid-provider-kuery get secret kuery-dsn -o jsonpath='{.data.dsn}' | base64 -d)"

The chart README contains the matching values table for the deployed version: chart instructions .

Provider requirements

SQLite on the chart’s PVC is the default and pins the provider to one replica; it is not a multi-replica production store. With store.driver: postgres, extra replicas buy availability: every replica serves queries, MCP, and the portal from the shared store, while the sync controllers are singletons behind a Lease in the provider workspace. Size resources for the number of engaged edges; the sync engine holds informer caches for every one. Review sync.whitelist and sync.blacklist before enabling inventory sync, since edge links are often bandwidth-constrained.

Postgres over a private network with sslmode=require in the DSN is what Railgrid runs; the database is the provider’s only state.

Verify

Run kubectl -n railgrid-provider-kuery get pods and wait for Ready and a fresh heartbeat. A fresh provider stays unready until a workspace enables it; see the common flow . Enable Kuery in a test workspace, connect a disposable edge, and verify engagement, whitelist behavior, and synchronization using the Kuery quickstart .

Recover

For a failed rollout, preserve the SQLite PVC or Postgres data before changing storage settings. Inspect edge engagement and sync logs, restore the original driver/DSN, and verify one edge’s inventory before expanding the fleet.

Configuration reference

Chart values are authoritative for this source baseline. Keep the deployed image and chart versions recorded together.