Deployment

The deployment flow usually moves through generated CRDs, infrastructure, images, and Helm releases.

The GCP/GKE/CAPG path is the current fully exercised cloud path. AWS/EKS and Azure/AKS are experimental provider-validation paths and should not be read as production-hardened or parity-tested yet.

make manifests
  -> terraform apply
  -> docker build and push
  -> helm dependency build
  -> helm upgrade --install
  -> gateway route ConfigMap hook

The gateway chart creates the route ConfigMap if it is missing. The operator then owns the runtime route entries inside that ConfigMap.

CRDs need special handling during upgrades. make manifests generates the CRDs into the operator chart, but Helm only installs CRDs on first install and does not upgrade existing CRDs automatically. The cloud deploy scripts apply CRDs explicitly before Helm so API shape changes are present before the operator, API server, and gateway are upgraded.

Support Status

Provider path	Status
Local k3d/Tilt	Development and validation path
Generic Kubernetes	Works when images, registry access, Helm, and CRDs are prepared
GCP/GKE/CAPG	Fully exercised cloud path, including Terraform, deployment automation, CAPG bootstrap, managed node-pool smoke coverage, and KEDA/resume smoke coverage
AWS/EKS/CAPA	Experimental provider-validation path with checked-in Terraform, registry/deploy material, API auth wiring, and unit-tested node-pool resource generation
Azure/AKS/CAPZ	Experimental provider-validation path with checked-in Terraform, registry/deploy material, API auth wiring, and unit-tested node-pool resource generation

Runtime Prerequisites

For platform deployments, prepare:

• kubectl;
• Helm 3;
• Docker or a CI image builder;
• Terraform when provisioning cloud infrastructure;
• registry access for XTrinode component images;
• KEDA when using event or metric-driven worker scaling;
• provider CLI and credentials for the cloud path you are deploying.

Images And Registry

XTrinode component images are versioned independently from the managed Trino runtime image.

Use the component image tags listed in Versioning, and keep the chart version and component image version aligned for the release you deploy. Public GHCR release images are currently linux/amd64; for arm64 clusters, publish a private arm64 image set or schedule the XTrinode control-plane components onto amd64 nodes.

The Trino runtime image is pinned separately. The current compatibility target in the XTrinode repository is Trino app tag 480.

Generic Install Shape

The generic path installs the operator, API server, gateway, and CRDs into Kubernetes namespaces such as xtrinode-system and xtrinode-gateway. Use the Makefile target from the main repository when possible:

make deploy

The equivalent Helm shape is:

make manifests
helm dependency build helm/xtrinode
helm upgrade --install xtrinode helm/xtrinode \
  --namespace xtrinode-system \
  --create-namespace \
  --set global.imageRegistry=ghcr.io/xtrinode

For manual upgrades, apply refreshed CRDs before the Helm upgrade. If the operator reports no matches for kind XTrinode, verify that the CRDs are installed and match the chart version you are deploying.

After deployment, verify:

kubectl get pods -n xtrinode-system
kubectl get pods -n xtrinode-gateway
kubectl get crd | grep xtrinode

GCP Integration

The fully exercised checked-in cloud path targets GKE. The repository includes GCP Terraform, Artifact Registry wiring, GKE deployment scripts, CAPI/CAPG material for runtime node pools, and live smoke coverage for managed node pools and KEDA/resume behavior.

For a first GCP deployment from scratch:

make gcp-management-up
make gcp-images-push
make gcp-control-plane-deploy

make gcp-management-up wraps the safer two-phase Terraform flow: create the GKE management cluster first, configure kubectl, then apply the Kubernetes and cloud add-ons. If infrastructure and images already exist, make deploy-gcp is the shorter control-plane redeploy path.

AWS And Azure Integration

AWS and Azure have provider-specific Terraform and deployment material, but they remain experimental provider-validation paths until live CAPA/CAPZ parity is proven. Treat the cloud-specific pages as status notes for auth posture, registry wiring, private cluster access, and provider caveats rather than as stable runbooks.

Current parity work tracks live validation for deploy, image pulls, gateway routing, API-server resume flow, KEDA scaling, teardown, and managed node-pool behavior on each provider.

AWS and Azure are documented with the same broad deployment shape, but remain marked experimental because they have not been live-smoke validated like GCP.

For CAPI/CAPG-managed GKE clusters, Terraform prepares infrastructure such as VPC, subnet, firewall, NAT, optional Postgres, Artifact Registry, and IAM. The XTrinode spec can then drive per-runtime node pools with spec.nodePool.

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

Runtime Deployment Checklist

Before debugging an individual runtime, confirm:

• CRDs are installed;
• operator, API server, and gateway pods are running;
• the gateway route ConfigMap exists;
• image pull secrets or registry access are valid;
• KEDA is installed when KEDA scaling is enabled;
• catalog secrets exist in the runtime namespace;
• GCP node-pool permissions are configured when spec.nodePool is used.

Cloud-specific status pages:

• GCP covers authenticated gcloud validation, Terraform, Artifact Registry, and CAPG.
• AWS summarizes the current EKS/ECR material and the remaining live CAPA validation caveats.
• Azure summarizes the current AKS/ACR material and the remaining live CAPZ validation caveats.

Site Deployment

This web site is separate from the XTrinode runtime platform.

Setting	Value
Framework preset	Astro
Build command	npm run build
Output directory	dist
Production branch	main
Domain	xtrinode.dev