XTrinode Documentation

XTrinode is a Kubernetes-native Trino control plane: an operator, API server, and gateway for managing elastic Trino compute runtimes.

Use these docs to understand how a team requests an XTrinode runtime, how the operator reconciles it, how the gateway routes SQL traffic, how catalogs are mounted, how runtimes scale and fail, and how releases are versioned and packaged.

Documentation Map

• Getting started gives the shortest orientation path.
• Comparison shows where XTrinode fits against vanilla Trino, Trino Gateway, and other Trino operator models.
• Versioning lists the current release, image tags, and included feature set.
• Compatibility records toolchain, Kubernetes, KEDA, chart, and Trino runtime version pins.
• Runtime model explains the XTrinode custom resource, lifecycle, scaling, catalogs, and node-pool shape.
• Architecture explains the operator, API server, gateway, runtime state, and failure boundaries.
• Deployment covers local, generic Kubernetes, GCP, AWS, and Azure deployment paths.
• Routing explains hostnames, headers, default routes, shared pools, and resume behavior.
• Catalogs covers reusable catalog declarations and secret-backed configuration.
• Scaling covers fixed workers, KEDA query scaling, scale-from-zero, node pools, and gateway/API server replicas.
• Sizing and overrides explains presets, node-pool machine types, and privileged valuesOverlay settings.
• Observability covers Kubernetes events, Prometheus metrics, gateway query signals, Vector logs, and incident checks.
• Security and networking covers namespace separation, gateway boundaries, secrets, Redis, auth, and privileged overlays.
• Troubleshooting gives commands for runtime, gateway, KEDA, catalog, and node-pool failures.
• GCP explains the fully exercised GCP/GKE/CAPG integration path.
• AWS summarizes the current EKS/ECR material and pending live CAPA validation.
• Azure summarizes the current AKS/ACR material and pending live CAPZ validation.
• Packaging covers GHCR images, Helm chart version alignment, and the Trino runtime image pin.

Minimal Runtime

apiVersion: analytics.xtrinode.io/v1
kind: XTrinode
metadata:
  name: runtime-a
  namespace: team-a
spec:
  size: s
  minWorkers: 0
  maxWorkers: 2
  suspended: false
  routing:
    header: X-Trino-XTrinode=team-a/runtime-a

Release And Platform Position

See Versioning for the current release line, component image tags, and included feature set.

Area	Status
Control-plane images	GitHub Container Registry (ghcr.io/xtrinode/...)
Trino runtime image	Pinned separately from the XTrinode release
GCP integration	Fully exercised path for GKE, Terraform, Helm, CAPG bootstrap, managed node pools, and KEDA/resume smoke coverage
AWS and Azure	Experimental provider-validation paths with Terraform, registry/deploy material, API auth wiring, and tested node-pool resource generation; live CAPA/CAPZ parity tracked separately