diff --git a/.github/workflows/build.yaml b/.github/workflows/build.yaml index 99179cf..8bfcd47 100644 --- a/.github/workflows/build.yaml +++ b/.github/workflows/build.yaml @@ -8,7 +8,7 @@ env: jobs: test: - name: Run test + name: Run tests runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 diff --git a/README.md b/README.md index 0c8b6d5..8ee8831 100644 --- a/README.md +++ b/README.md @@ -8,3 +8,58 @@ A highly available load balancer with support for queueing, routing and auto-sca * [PythonScriptRouter](./docs/routing/PythonScriptRouter.md) * [Scaling](./docs/scaling/index.md) * [Stackable](./docs/scaling/stackable.md) + +## Try it out locally +The easiest way to use trino-ls is by using the available container image. +Make sure you clone this repo and run the following command from the root directory of it. + +### Without Trino clusters +In case you don't have any Trino cluster at hand you can start trino-lb without any Trino cluster as follows: + +```bash +docker run -p 8080:8080 -v ./example-configs/simple-no-trino.yaml:/etc/trino-lb-config.yaml --rm oci.stackable.tech/stackable/trino-lb:dev +``` + +This starts trino-lb listening on http://127.0.0.1:8080. + +You can submit a test-query using [trino-cli](https://trino.io/docs/current/client/cli.html) by calling the following command and entering `show catalogs`: + +```bash +java -jar ~/Downloads/trino-cli-435-executable.jar --server http://127.0.0.1:8080 +trino> select 42; + +Query trino_lb_20240111_194610_ZI6zmb1d, QUEUED_IN_TRINO_LB, 0 nodes, 0 splits +``` + +As you can see by `QUEUED_IN_TRINO_LB`, the query is queued in trino-lb indefinitely, as no Trino clusters are configured - hence trino-ln has Trino cluster to hand the query to. + +### With Trino clusters + +Let's assume your Trino cluster is accessible at `https://127.0.0.1:8443` using the username `admin` and password `admin`. + +First check the config file `example-configs/simple-single-trino.yaml` and swap out the hostname and credentials corresponding to your Trino cluster. +Afterwards start trino-lb using the following command. +We are using self-signed certificates for testing purpose here. + +```bash +docker run -p 443:8443 -v ./example-configs/simple-single-trino.yaml:/etc/trino-lb-config.yaml -v ./example-configs/self-signed-certs/:/self-signed-certs/ --rm oci.stackable.tech/stackable/trino-lb:dev +``` + +> [!NOTE] +> We map the trino-lb port 8443 to 443 on our host, as the port 8443 is already taken by Trino. Keep that in mind when accessing trino-lb + +We can send queries to trino-lb and it will forward them to the configured Trino cluster. + +```bash +java -jar ~/Downloads/trino-cli-435-executable.jar --server https://127.0.0.1:443 --insecure --user admin --password +Password: +trino> select 42; + _col0 +------- + 42 +(1 row) +``` + +While this example seems a bit silly, keep in mind that trino-lb already keeps track of the number of queries running on the underlying Trino cluster and queues every query that would exceed the limit of allowed queries (a single query in this case). +You can test this out by executing multiple long running queries in parallel. +Also this is just the starting point without any routing, load-balancing or autoscaling. Read on the [design guide](./docs/design.md) on what trino-lb can do. diff --git a/self_signed_certs/cert.pem b/example-configs/self-signed-certs/cert.pem similarity index 100% rename from self_signed_certs/cert.pem rename to example-configs/self-signed-certs/cert.pem diff --git a/self_signed_certs/key.pem b/example-configs/self-signed-certs/key.pem similarity index 100% rename from self_signed_certs/key.pem rename to example-configs/self-signed-certs/key.pem diff --git a/example-configs/simple-no-trino.yaml b/example-configs/simple-no-trino.yaml new file mode 100644 index 0000000..910de3e --- /dev/null +++ b/example-configs/simple-no-trino.yaml @@ -0,0 +1,11 @@ +trinoLb: + externalAddress: http://127.0.0.1:8080 + persistence: + inMemory: {} +trinoClusterGroups: + default: + maxRunningQueries: 1 + trinoClusters: [] + +routers: [] +routingFallback: default diff --git a/example-configs/simple-single-trino.yaml b/example-configs/simple-single-trino.yaml new file mode 100644 index 0000000..e823aab --- /dev/null +++ b/example-configs/simple-single-trino.yaml @@ -0,0 +1,22 @@ +trinoLb: + externalAddress: https://127.0.0.1:443 + tls: + enabled: true + certPemFile: /self-signed-certs/cert.pem + keyPemFile: /self-signed-certs/key.pem + persistence: + inMemory: {} +trinoClusterGroups: + default: + maxRunningQueries: 1 + trinoClusters: + - name: trino-default-1 + endpoint: https://5.250.181.98:8443 # FIXME + credentials: + username: admin + password: adminadmin # FIXME +# Your Trino probably does not have a globally trusted certificate +trinoClusterGroupsIgnoreCert: true + +routers: [] +routingFallback: default