Skip to content

Latest commit

 

History

History
171 lines (127 loc) · 5.79 KB

installation.md

File metadata and controls

171 lines (127 loc) · 5.79 KB

Trino Gateway documentation

Installation

Trino Gateway is distributed as an executable JAR file. The release notes contain links to download specific versions. Alternatively, you can look at the development instructions to build the JAR file or use the TrinoGatewayRunner for local testing. The quickstart guide contains instructions for running the application locally.

Following are instructions for installing Trino Gateway for production environments.

Requirements

Consider the following requirements for your Trino Gateway installation.

Java

Trino Gateway requires a Java 21 runtime. Older versions of Java can not be used. Newer versions might work but are not tested.

Verify the Java version on your system with java -version.

Operating system

No specific operating system is required. All testing and development is performed with Linux and MacOS.

Processor architecture

No specific processor architecture is required, as long as a suitable Java distribution is installed.

Backend database

Trino Gateway requires a MySQL or PostgreSQL database.

Use the following scripts to initialize the database:

The files are also included in the JAR file.

Trino clusters

The proxied Trino clusters behind the Trino Gateway must support the Trino JDBC driver and the Trino REST API for cluster and node health information. Typically, this means that Trino versions 354 and higher should work, however newer Trino versions are strongly recommended.

Trino-derived projects and platforms may work if the Trino JDBC driver and the REST API are supported. For example, Starburst Galaxy and Starburst Enterprise are known to work. Trino deployments with the Helm chart and other means on various cloud platforms, such as Amazon EKS also work. However Amazon Athena does not work since it uses alternative, custom protocols and lacks the concept of individual clusters.

Trino configuration

From a users perspective Trino Gateway acts as a transparent proxy for one or more Trino clusters. The following Trino configuration tips should be taken into account for all clusters behind the Trino Gateway.

Process forwarding must be enabled:

http-server.process-forwarded=true

Without this setting, first requests go from the user to Trino Gateway and then to Trino correctly. However, the URL for subsequent next URIs for more results in a query provided by Trino is then using the local URL of the Trino cluster, and not the URL of the Trino Gateway. This circumvents the Trino Gateway for all these requests, and is contrary to the purpose of using the Trino Gateway. In scenarios, where the local URL of the Trino cluster is private to the Trino cluster on the DNS/network level, these following calls might not work at all for users.

This setting is also required for Trino to authenticate in the case TLS is terminated at the Trino Gateway. Normally it refuses to authenticate plain HTTP requests, but if http-server.process-forwarded=true it authenticates over HTTP if the request includes X-Forwarded-Proto: HTTPS.

Configuration

After downloading or building the JAR, rename it to gateway-ha.jar, and place it in a directory with read and write access such as /opt/trinogateway.

Copy the example config file gateway-ha-config.yml into the same directory, and update the configuration as needed.

Each component of the Trino Gateway has a corresponding node in the configuration YAML file.

Configure routing rules

Find more information in the routing rules documentation.

Configure logging

Path to log.properties must be set via log.levels-file JVM options like -Dlog.levels-file=etc/log.properties.

Use the log.* properties from the Trino logging properties documentation for further configuration.

Proxying additional paths

By default, Trino Gateway only proxies requests to paths starting with /v1/statement, /v1/query, /ui, /v1/info, /v1/node, /ui/api/stats and /oauth.

If you want to proxy additional paths, you can add them by adding the extraWhitelistPaths node to your configuration YAML file:

extraWhitelistPaths:
  - "/ui/insights"
  - "/api/v1/biac"
  - "/api/v1/dataProduct"
  - "/api/v1/dataproduct"
  - "/ext/faster"

Running Trino Gateway

Start Trino Gateway with the following java command in the directory of the JAR and YAML files:

java -XX:MinRAMPercentage=50 -XX:MaxRAMPercentage=80 \
    --add-opens=java.base/java.lang=ALL-UNNAMED \
    --add-opens=java.base/java.net=ALL-UNNAMED \
    -jar gateway-ha.jar server gateway-config.yml