Runtime Model

The preferred terminology is runtime.

An XTrinode runtime is the platform identity for a Trino compute unit. It owns or references the pieces needed to run SQL safely in a shared Kubernetes environment:

• Trino coordinator;
• Trino workers;
• catalog selection;
• route identity;
• lifecycle state;
• scaling policy;
• status conditions;
• optional per-runtime node-pool intent.

Runtime Resource

apiVersion: analytics.xtrinode.io/v1
kind: XTrinode
metadata:
  name: analytics
  namespace: team-a
spec:
  size: m
  minWorkers: 0
  maxWorkers: 8
  suspended: false
  routing:
    hostnameDomain: trino.example.com

Lifecycle Intent

The suspended field expresses desired runtime lifecycle state.

• suspended: false means the runtime should be available.
• suspended: true means compute can be scaled down and kept out of normal query routing.
• Gateway demand or API server calls can initiate resume behavior.

The API server coordinates resume and suspend operations with Kubernetes leases so parallel callers do not trigger duplicate lifecycle work.

Sizing And Workers

Runtimes can use fixed worker counts or KEDA-managed scaling.

Fixed workers are simpler and predictable:

spec:
  minWorkers: 2
  maxWorkers: 2

Elastic workers are useful for runtime demand that changes over time:

spec:
  minWorkers: 0
  maxWorkers: 8
  keda:
    enabled: true
    scalerType: prometheus
    scalingMetric: query
    prometheusServer: http://prometheus-operated.monitoring.svc.cluster.local:9090

enabled: true by itself is not enough to create a runtime worker ScaledObject; the controller also requires scaler configuration such as a scaler type, metric, Prometheus server/query, or HTTP endpoint.

Sizing is layered. spec.size chooses the preset, spec.nodePool changes provider capacity such as machine type and node bounds, and privileged spec.valuesOverlay handles advanced pod, image, scheduling, service, Trino config, and worker-HPA settings. See Sizing and overrides before using low-level overlays.

Routing Identity

Runtimes can be selected by hostname, header, default route, or shared routing group.

spec:
  routing:
    header: X-Trino-XTrinode=team-a/analytics
    hostnameDomain: trino.example.com

When hostnameDomain is used without an explicit hostname, the generated host is <routing-group>.<domain>. The default dedicated routing group is namespace--name, such as team-a--analytics.

Catalog Attachment

Catalogs are selected from the runtime spec, usually by label:

spec:
  catalogSelector:
    matchLabels:
      team: analytics

The catalog controller renders Trino catalog ConfigMaps and secret-backed environment references. Runtime pods receive the selected catalog configuration.

Node Pools

For stronger isolation or chargeback, a runtime can request a provider-managed node pool. GCP/GKE/CAPG is the fully exercised checked-in cloud path for live node-pool behavior. AWS and Azure provider resource generation exists, while live CAPA/CAPZ parity is tracked separately.

spec:
  nodePool:
    name: analytics-nodes
    provider: gcp
    providerMode: managed
    clusterName: xtrinode-gke-test
    kubernetesVersion: v1.35.3
    gcp:
      machineType: e2-standard-2

Use per-runtime node pools only when the operational or cost boundary is worth the additional cloud infrastructure.