repository·main·Indexed 42 days ago
https://github.com/trinodb/trino-gatewayA specialized proxy and load balancer for Trino environments that provides a centralized entry point to route queries across multiple Trino clusters based on configurable rules. It includes a web application built with React and TypeScript, and supports deployment via Docker and Kubernetes.
Each Trino cluster configured in the Gateway has two distinct URL types:
proxyTo URL: Used internally by the Trino Gateway to route requests based on routing rules and query identifiers. This is typically a service-to-service address (e.g., a Kubernetes service).externalURL: A publicly reachable or UI-accessible address. This is used by users to access the Trino Web UI.Example (Kubernetes):
proxyTo: trino-backend-service.trino-namespace.svc.cluster.local:8083externalURL: trino.domain.comTrino Gateway is used to solve several common Trino management challenges:
When rulesType is set to EXTERNAL, Trino Gateway sends a POST request to the configured urlPath. The body contains a map of all request headers (excluding those in excludeHeaders). If requestAnalyzerConfig.analyzeRequest is true, the body also includes TrinoRequestUser and TrinoQueryProperties data.
Included HTTP Information:
remoteUser, method, requestURI, queryString, session, remoteAddr, remoteHost, parameterMap.External Service Response Requirements:
200 OK.routingGroup.errors field is not null, the query is routed to the default group.Dynamic Header Modification:
The service can return an externalHeaders map to inject or modify headers (like session properties or client tags) before the request reaches the Trino cluster.
{
"routingGroup": "test-group",
"errors": [
"Error1",
"Error2",
"Error3"
],
"externalHeaders": {
"x-trino-client-tags": "['etl']",
"x-trino-session": "query_max_memory=50GB,optimize_metadata_queries=false"
}
}Trino Gateway determines how to route incoming requests using two main approaches:
Note: Only healthy clusters are eligible for routing.
Trino Gateway provides two entry-level routers that make decisions based on cluster load reported in ClusterStats.
When using client certificates, you must define how the certificate identity is extracted via requestAnalyzerConfig.clientCertificateIdentityField.
SUBJECT_DN: Matches Trino's native certificate authentication by mapping the whole subject DN. Use this if you want to copy existing Trino user-mapping rules (http-server.authentication.certificate.user-mapping.*) directly to the gateway.CN, OU): The gateway extracts the specific RDN value from the subject DN. Note: Rules written for Trino (which expect a full DN) will not work in this mode. You must rewrite your mapping rules to match the extracted value instead of the full DN.Constraint: If your mapping file contains rules with "allow": false, you must use clientCertificateIdentityField: SUBJECT_DN.
Trino Gateway acts as a transparent proxy. To ensure correct routing and authentication (especially when TLS is terminated at the Gateway), you must configure the proxied Trino clusters:
http-server.process-forwarded=true. This ensures subsequent requests use the Gateway's URL instead of the cluster's local URL.X-Forwarded-* and Forwarded headers, set routing.forwardedHeadersEnabled: false in the Gateway configuration.# In Trino cluster configuration
http-server.process-forwarded=true# In Trino Gateway configuration
routing:
forwardedHeadersEnabled: falseTrino Gateway performs periodic health checks to maintain an in-memory TrinoStatus for each backend. If a backend fails a check, it is marked as UNHEALTHY and routing stops.
Note: TrinoStatus (programmatic health) is distinct from the active/inactive state (manual toggle).
Rules are evaluated in order. If multiple rules match, the last one to execute its result.put("routingGroup", ...) action wins. To manage complex logic, use these two mechanisms:
priority to a rule. Lower integers fire earlier. Use higher priorities for more specific rules that should override general rules.state object to store information in an early rule (e.g., state.put("is_airflow", true)) and check it in a later rule (e.g., condition: 'state.get("is_airflow") == true').Example: Using Priority and State
---
name: "initialize state"
priority: 0
condition: "true"
actions:
- |
state.put("triggeredRules", new HashSet())
---
name: "airflow"
priority: 1
condition: |
request.getHeader("X-Trino-Source") == "airflow"
actions:
- |
result.put("routingGroup", "etl")
- |
state.get("triggeredRules").add("airflow")
---
name: "airflow special"
priority: 2
condition: |
state.get("triggeredRules").contains("airflow") && request.getHeader("X-Trino-Client-Tags") contains "label=special"
actions:
- 'result.put("routingGroup", "etl-special")'When Trino Gateway forwards a request to a Trino cluster, it follows these steps:
X-Forwarded-* proxy headers.routing.forwardedHeadersEnabled to false in the ProxyRequestHandler configuration, the Gateway will case-insensitively strip all client-provided legacy (X-Forwarded-*) and modern (Forwarded) headers. It will also skip adding its own proxy headers. This configuration is useful when you want Trino backend responses (like nextUri values) to point directly to the backend rather than back through the Gateway or load balancer.queryId from a Trino response or setting session cookies for OIDC compatibility in the web UI.airlift.jaxrs.AsyncResponseHandler.In versions 10+, multiple service ports have been merged into a single HTTP port (default 8080).
Port Consolidation:
Admin Service & JMX:
/v1/jmx.WebUI Path Change:
/ to /trino-gateway./ redirects to /trino-gateway./ directly to Trino instead of the WebUI, add / to extraWhitelistPaths using regex format.