diff --git a/docs/modules/trino/images/.$trino_overview.drawio.svg.bkp b/docs/modules/trino/images/.$trino_overview.drawio.svg.bkp
new file mode 100644
index 00000000..c9cb3649
--- /dev/null
+++ b/docs/modules/trino/images/.$trino_overview.drawio.svg.bkp
@@ -0,0 +1,4 @@
+
+
+
+
\ No newline at end of file
diff --git a/docs/modules/trino/images/trino_overview.drawio.svg b/docs/modules/trino/images/trino_overview.drawio.svg
new file mode 100644
index 00000000..623dccb9
--- /dev/null
+++ b/docs/modules/trino/images/trino_overview.drawio.svg
@@ -0,0 +1,4 @@
+
+
+
+
\ No newline at end of file
diff --git a/docs/modules/trino/pages/concepts.adoc b/docs/modules/trino/pages/concepts.adoc
index 0f9e5225..643492fd 100644
--- a/docs/modules/trino/pages/concepts.adoc
+++ b/docs/modules/trino/pages/concepts.adoc
@@ -1,13 +1,13 @@
= Concepts
-== Connectors
+== [[connectors]]Connectors
-https://trino.io/docs/current/overview/use-cases.html#what-trino-is[Trino] is a tool designed to efficiently query vast amounts of data using distributed queries. It is not a database with its own store but rather interacts with many types of store. Trino connects to these stores - or data sources - via https://trino.io/docs/current/connector.html[connectors].
-Each connector enables access to a specific underlying datasource such as a Hive warehouse, a PostgreSQL database or a Druid instance.
+https://trino.io/docs/current/overview/use-cases.html#what-trino-is[Trino] is a tool designed to efficiently query vast amounts of data using distributed queries. It is not a database with its own storage but rather interacts with many different data stores. Trino connects to these data stores - or data sources - via https://trino.io/docs/current/connector.html[connectors].
+Each connector enables access to a specific underlying data source such as a Hive warehouse, a PostgreSQL database or a Druid instance.
A Trino cluster comprises two roles: the Coordinator, responsible for managing and monitoring work loads, and the Worker, which is responsible for executing specific tasks that together make up a work load. The workers fetch data from the connectors, execute tasks and share intermediate results. The coordinator collects and consolidates these results for the end-user.
-== Catalogs
+== [[catalogs]]Catalogs
An instance of a connector is called a catalog.
Think of a setup containing a large Hive warehouse running on HDFS.
diff --git a/docs/modules/trino/pages/getting_started/first_steps.adoc b/docs/modules/trino/pages/getting_started/first_steps.adoc
index c7a7bd8c..c9606547 100644
--- a/docs/modules/trino/pages/getting_started/first_steps.adoc
+++ b/docs/modules/trino/pages/getting_started/first_steps.adoc
@@ -123,4 +123,4 @@ include::example$getting_started/code/getting_started.sh[tag=cleanup-trino-cli]
== What's next
-Have a look at the xref:usage_guide/cluster.adoc[] to find out more about how to configure a Trino cluster.
+Have a look at the xref:usage_guide/index.adoc[] to find out more about how to configure a Trino cluster.
diff --git a/docs/modules/trino/pages/index.adoc b/docs/modules/trino/pages/index.adoc
index 8afe6b63..5509d8fe 100644
--- a/docs/modules/trino/pages/index.adoc
+++ b/docs/modules/trino/pages/index.adoc
@@ -1,18 +1,42 @@
= Stackable Operator for Trino
+:description: The Stackable Operator for Trino is a Kubernetes operator that can manage Trino clusters. Learn about its features, resources, dependencies and demos, and see the list of supported Trino versions.
+:keywords: Stackable Operator, Trino, Kubernetes, k8s, operator, data science, data exploration, SQL, engineer, big data, CRD, StatefulSet, ConfigMap, Service, Druid, Trino, S3, Superset
This is an operator for Kubernetes that can manage https://https://trino.io/[Trino] clusters.
+Trino is an open-source distributed SQL query engine that enables high-speed analytics of large datasets from multiple data sources using SQL queries. This operator enables you to manage your Trino instances on Kubernetes efficiently.
+
+== Getting started
+
+Follow the xref:getting_started/index.adoc[Getting started guide] to start using the Stackable Operator for Trino on your Kubernetes cluster. It will guide you through the installation process and help you run your first Trino queries on Kubernetes.
+
+== Operator model
+
+The Operator manages Kubernetes resources in sync with https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/[custom resources] defined by you, the user.
+
+=== Custom resources
+
+The Trino Operator manages two custom resources: The _TrinoCluster_ and xref:concepts.adoc#catalogs[_TrinoCatalogs_]. The TrinoCluster resource allows for the specification of a Trino cluster. Two xref:concepts:roles-and-role-groups.adoc[roles] are defined: `coordinators` and `workers`.
+
+To connect to data sources the TrinoCatalogs are used. Have a look at the xref:usage_guide/catalogs/index.adoc[catalog overview] to find out which types of data sources are supported by the Stackable platform.
+
+=== Resources
+
+To run the cluster on Kubernetes the Operator creates Kubernetes resources such as ConfigMaps, StatefulSets and Services.
+
+image::trino_overview.drawio.svg[A diagram depicting the Kubernetes resources created by the operator]
+
+== Demos
+
+The xref:stackablectl::demos/trino-taxi-data.adoc[] demo uses Trino together with xref:hive:index.adoc[Apache Hive] to access the prominent New York Taxi dataset. xref:superset:index.adoc[Apache Superset] is then used to read the data from the Trino instance via SQL and visualize it.
+
+The xref:stackablectl::demos/data-lakehouse-iceberg-trino-spark.adoc[] demo showcases a data Lakehouse with multiple datasets. Again Trino is used to enable SQL acces to the data. The xref:stackablectl::demos/trino-iceberg.adoc[] demo is a subset of the Lakehouse demo, focusing just on Apache Iceberg integration.
+
+The xref:stackablectl::demos/spark-k8s-anomaly-detection-taxi-data.adoc[] also uses Trino to enable SQL access to data but also shows xref:opa:index.adoc[OpenPolicyAgent] integration for xref:usage_guide/security.adoc#authorization[authorization].
+
-WARNING: This operator only works with images from the https://repo.stackable.tech/#browse/browse:docker:v2%2Fstackable%2Ftrino[Stackable] repository
== Supported Versions
The Stackable Operator for Trino currently supports the following versions of Trino:
include::partial$supported-versions.adoc[]
-
-== Get Docker image
-
-[source]
-----
-docker pull docker.stackable.tech/stackable/trino:
-----
diff --git a/docs/modules/trino/pages/usage_guide/cluster.adoc b/docs/modules/trino/pages/usage_guide/cluster.adoc
deleted file mode 100644
index e49b1b4c..00000000
--- a/docs/modules/trino/pages/usage_guide/cluster.adoc
+++ /dev/null
@@ -1,221 +0,0 @@
-= Creating a Trino cluster
-
-== Define an insecure cluster (testing)
-
-Create an insecure single node Trino cluster for testing. This can be accessed with the UI/CLI via http without either user/password credentials or authorization.
-
-For testing purposes we use the https://trino.io/docs/current/installation/cli.html[Trino CLI].
-
-First, ensure all necessary operator have been deployed:
-
-[source]
-----
-stackablectl operator install \
- secret commons hive trino
-----
-
-The Trino cluster can now be deployed:
-
-[source,yaml]
-----
-include::example$usage_guide/trino-insecure.yaml[]
-----
-
-We have defined a single catalog - Hive - which uses an embedded database (derby).
-
-To interact with Trino, first obtain the host and port for the Trino coordinator service (in this and following examples, https://172.18.0.3:31748):
-
-[source]
-----
-stackablectl services list
-
- PRODUCT NAME NAMESPACE ENDPOINTS EXTRA INFOS
-
- hive simple-hive-derby default hive 172.18.0.4:32186
- metrics 172.18.0.4:30109
-
- trino simple-trino default coordinator-metrics 172.18.0.3:32123
- coordinator-https https://172.18.0.3:31748
-----
-
-Next, download the Trino CLI tool (this can be obtained from the Stackable repository, as shown below):
-
-[source]
-----
-curl --output trino.jar https://repo.stackable.tech/repository/packages/trino-cli/trino-cli-396-executable.jar
-----
-
-Execute some CLI commands to verify operation, such as returning the names of all catalogs. Note that an insecure connection is specified:
-[source]
-----
-./trino.jar --insecure --debug --server https://172.18.0.3:31748 --user=admin --execute "SHOW CATALOGS" --output-format=CSV_UNQUOTED
-
-hive
-system
-----
-
-== Define a secure cluster (production)
-
-For secure connections the following steps must be taken:
-
-1. Enable authentication
-2. Enable TLS between the clients and coordinator
-3. Enable internal TLS for communication between coordinators and workers
-
-=== Via authentication
-
-If authentication is enabled, https://trino.io/docs/current/security/tls.html[TLS] for the coordinator as well as a shared secret for https://trino.io/docs/current/security/internal-communication.html[internal communications] (this is base64 and not encrypted) must be configured.
-
-Securing the Trino cluster will disable all HTTP ports and disable the web interface on the HTTP port as well. In the definition below the authentication is directed to use the `trino-users` secret and TLS communication will use a certificate signed by the Secret Operator (indicated by `autoTls`).
-
-[source,yaml]
-----
-include::example$usage_guide/trino-secure-tls.yaml[]
-----
-
-<1> The name of (and reference to) the `SecretClass`
-<2> The name of (and reference to) the `Secret`
-<3> `TrinoCatalog` reference
-<4> TLS mechanism
-
-The CLI now requires that a path to the keystore and a password be provided:
-
-[source]
-----
-./trino.jar --debug --server https://172.18.0.3:31748
---user=admin --keystore-path= --keystore-password=
-----
-
-=== Via TLS only
-
-This will disable the HTTP port and UI access and encrypt client-server communications.
-
-[source,yaml]
-----
-include::example$usage_guide/trino-secure-tls-only.yaml[]
-----
-
-<1> The name of (and reference to) the `SecretClass`
-<2> `TrinoCatalog` reference
-<3> TLS mechanism
-
-CLI callout:
-
-[source]
-----
-./trino.jar --debug --server https://172.18.0.3:31748 --keystore-path= --keystore-password=
-----
-
-=== Via internal TLS
-
-Internal TLS is for encrypted and authenticated communications between coordinators and workers. Since this applies to all the data send and processed between the processes, this may reduce the performance significantly.
-
-[source,yaml]
-----
-include::example$usage_guide/trino-secure-internal-tls.yaml[]
-----
-
-<1> The name of (and reference to) the `SecretClass`
-<2> The name of (and reference to) the `Secret`
-<3> TLS mechanism
-
-Since Trino has internal and external communications running over a single port, this will enable the HTTPS port but not expose it. Cluster access is only possible via HTTP.
-
-[source]
-----
-./trino.jar --debug --server http://172.18.0.3:31748 --user=admin
-----
-
-== S3 connection specification
-
-You can specify S3 connection details directly inside the `TrinoCatalog` specification
-or by referring to an external `S3Connection` custom resource.
-
-To specify S3 connection details directly as part of the `TrinoCatalog` resource, you
-add an inline connection configuration as shown below:
-
-[source,yaml]
-----
-s3: # <1>
- inline:
- host: test-minio # <2>
- port: 9000 # <3>
- pathStyleAccess: true # <4>
- secretClass: minio-credentials # <5>
- tls:
- verification:
- server:
- caCert:
- secretClass: minio-tls-certificates #<6>
-----
-<1> Entry point for the connection configuration
-<2> Connection host
-<3> Optional connection port
-<4> Optional flag if path-style URLs should be used; This defaults to `false`
- which means virtual hosted-style URLs are used.
-<5> Name of the `Secret` object expected to contain the following keys:
- `accessKey` and `secretKey`
-<6> Optional TLS settings for encrypted traffic. The `secretClass` can be provided by the Secret Operator or yourself.
-
-A self provided S3 TLS secret can be specified like this:
-
-[source,yaml]
-----
----
-apiVersion: secrets.stackable.tech/v1alpha1
-kind: SecretClass
-metadata:
- name: minio-tls-certificates
-spec:
- backend:
- k8sSearch:
- searchNamespace:
- pod: {}
----
-apiVersion: v1
-kind: Secret
-metadata:
- name: minio-tls-certificates
- labels:
- secrets.stackable.tech/class: minio-tls-certificates
-data:
- ca.crt:
- tls.crt:
- tls.key:
-----
-
-It is also possible to configure the bucket connection details as a separate
-Kubernetes resource and only refer to that object from the `TrinoCatalog` specification
-like this:
-
-[source,yaml]
-----
-s3:
- reference: my-connection-resource # <1>
-----
-<1> Name of the connection resource with connection details
-
-The resource named `my-connection-resource` is then defined as shown below:
-
-[source,yaml]
-----
----
-apiVersion: s3.stackable.tech/v1alpha1
-kind: S3Connection
-metadata:
- name: my-connection-resource
-spec:
- host: test-minio
- port: 9000
- accessStyle: Path
- credentials:
- secretClass: minio-credentials
-----
-
-This has the advantage that the connection configuration can be shared across
-applications and reduces the cost of updating these details.
-
-
-
-
-
diff --git a/docs/modules/trino/pages/usage_guide/connect_to_trino.adoc b/docs/modules/trino/pages/usage_guide/connect_to_trino.adoc
index 09f756ec..a6738121 100644
--- a/docs/modules/trino/pages/usage_guide/connect_to_trino.adoc
+++ b/docs/modules/trino/pages/usage_guide/connect_to_trino.adoc
@@ -5,7 +5,7 @@ An https://trino.io/docs/current/client/jdbc.html[open source JDBC driver] does
Multiple SQL clients can be used to connect to Trino as described below.
-== Perquisites
+== Prerequisites
The Trino server must be reachable from your local computer.
It is typically secured via HTTPS with a certificated provided by a xref:secret-operator:secretclass.adoc[SecretClass].
diff --git a/docs/modules/trino/pages/usage_guide/index.adoc b/docs/modules/trino/pages/usage_guide/index.adoc
index 5795b2d4..2e2de99b 100644
--- a/docs/modules/trino/pages/usage_guide/index.adoc
+++ b/docs/modules/trino/pages/usage_guide/index.adoc
@@ -6,8 +6,8 @@ This section will help you to use the Trino Stackable Operator. It will show you
The following guides are available here:
-* xref:usage_guide/cluster.adoc[]
* xref:usage_guide/catalogs/index.adoc[]
+* xref:usage_guide/s3.adoc[]
* xref:usage_guide/configuration.adoc[]
* xref:usage_guide/security.adoc[]
* xref:usage_guide/monitoring.adoc[]
diff --git a/docs/modules/trino/pages/usage_guide/s3.adoc b/docs/modules/trino/pages/usage_guide/s3.adoc
new file mode 100644
index 00000000..4922ecbf
--- /dev/null
+++ b/docs/modules/trino/pages/usage_guide/s3.adoc
@@ -0,0 +1,88 @@
+= S3 connection specification
+
+You can specify S3 connection details directly inside the TrinoCatalog specification
+or by referring to an external S3Connection custom resource.
+
+To specify S3 connection details directly as part of the TrinoCatalog resource, you
+add an inline connection configuration as shown below:
+
+[source,yaml]
+----
+s3: # <1>
+ inline:
+ host: test-minio # <2>
+ port: 9000 # <3>
+ pathStyleAccess: true # <4>
+ secretClass: minio-credentials # <5>
+ tls:
+ verification:
+ server:
+ caCert:
+ secretClass: minio-tls-certificates #<6>
+----
+<1> Entry point for the connection configuration
+<2> Connection host
+<3> Optional connection port
+<4> Optional flag if path-style URLs should be used; This defaults to `false`
+ which means virtual hosted-style URLs are used.
+<5> Name of the Secret object expected to contain the following keys:
+ `accessKey` and `secretKey`
+<6> Optional TLS settings for encrypted traffic. The `secretClass` can be provided by the Secret Operator or yourself.
+
+A self provided S3 TLS secret can be specified like this:
+
+[source,yaml]
+----
+---
+apiVersion: secrets.stackable.tech/v1alpha1
+kind: SecretClass
+metadata:
+ name: minio-tls-certificates
+spec:
+ backend:
+ k8sSearch:
+ searchNamespace:
+ pod: {}
+---
+apiVersion: v1
+kind: Secret
+metadata:
+ name: minio-tls-certificates
+ labels:
+ secrets.stackable.tech/class: minio-tls-certificates
+data:
+ ca.crt:
+ tls.crt:
+ tls.key:
+----
+
+It is also possible to configure the bucket connection details as a separate
+Kubernetes resource and only refer to that object from the TrinoCatalog specification
+like this:
+
+[source,yaml]
+----
+s3:
+ reference: my-connection-resource # <1>
+----
+<1> Name of the connection resource with connection details
+
+The resource named `my-connection-resource` is then defined as shown below:
+
+[source,yaml]
+----
+---
+apiVersion: s3.stackable.tech/v1alpha1
+kind: S3Connection
+metadata:
+ name: my-connection-resource
+spec:
+ host: test-minio
+ port: 9000
+ accessStyle: Path
+ credentials:
+ secretClass: minio-credentials
+----
+
+This has the advantage that the connection configuration can be shared across
+applications and reduces the cost of updating these details.
diff --git a/docs/modules/trino/pages/usage_guide/security.adoc b/docs/modules/trino/pages/usage_guide/security.adoc
index 1685a359..0e3c6246 100644
--- a/docs/modules/trino/pages/usage_guide/security.adoc
+++ b/docs/modules/trino/pages/usage_guide/security.adoc
@@ -2,7 +2,7 @@
This page covers <> and <>.
-== Authentication
+== [[authentication]]Authentication
Trino supports several https://trino.io/docs/current/security/authentication-types.html[authentication types].
@@ -53,7 +53,7 @@ include::example$usage_guide/trino-ldap-auth-snippet.yaml[tag=trino]
In the Trino CLI and web interface, LDAP users can now be used to log in.
-== Authorization
+== [[authorization]]Authorization
In order to authorize Trino via OPA, a `ConfigMap` containing Rego rules for Trino has to be applied. The following example is an all-access Rego rule for testing with the user `admin`. Do not use it in production!
@@ -62,4 +62,76 @@ In order to authorize Trino via OPA, a `ConfigMap` containing Rego rules for Tri
include::example$usage_guide/opa-bundle-trino-cm.yaml[]
----
-Users should write their own rego rules for more complex OPA authorization.
\ No newline at end of file
+Users should write their own rego rules for more complex OPA authorization.
+
+== Define a secure cluster
+
+For secure connections the following steps must be taken:
+
+1. Enable authentication
+2. Enable TLS between the clients and coordinator
+3. Enable internal TLS for communication between coordinators and workers
+
+=== Via authentication
+
+If authentication is enabled, https://trino.io/docs/current/security/tls.html[TLS] for the coordinator as well as a shared secret for https://trino.io/docs/current/security/internal-communication.html[internal communications] (this is base64 and not encrypted) must be configured.
+
+Securing the Trino cluster will disable all HTTP ports and disable the web interface on the HTTP port as well. In the definition below the authentication is directed to use the `trino-users` secret and TLS communication will use a certificate signed by the Secret Operator (indicated by `autoTls`).
+
+[source,yaml]
+----
+include::example$usage_guide/trino-secure-tls.yaml[]
+----
+
+<1> The name of (and reference to) the `SecretClass`
+<2> The name of (and reference to) the `Secret`
+<3> `TrinoCatalog` reference
+<4> TLS mechanism
+
+The CLI now requires that a path to the keystore and a password be provided:
+
+[source]
+----
+./trino.jar --debug --server https://172.18.0.3:31748
+--user=admin --keystore-path= --keystore-password=
+----
+
+=== Via TLS only
+
+This will disable the HTTP port and UI access and encrypt client-server communications.
+
+[source,yaml]
+----
+include::example$usage_guide/trino-secure-tls-only.yaml[]
+----
+
+<1> The name of (and reference to) the `SecretClass`
+<2> `TrinoCatalog` reference
+<3> TLS mechanism
+
+CLI callout:
+
+[source]
+----
+./trino.jar --debug --server https://172.18.0.3:31748 --keystore-path= --keystore-password=
+----
+
+=== Via internal TLS
+
+Internal TLS is for encrypted and authenticated communications between coordinators and workers. Since this applies to all the data send and processed between the processes, this may reduce the performance significantly.
+
+[source,yaml]
+----
+include::example$usage_guide/trino-secure-internal-tls.yaml[]
+----
+
+<1> The name of (and reference to) the `SecretClass`
+<2> The name of (and reference to) the `Secret`
+<3> TLS mechanism
+
+Since Trino has internal and external communications running over a single port, this will enable the HTTPS port but not expose it. Cluster access is only possible via HTTP.
+
+[source]
+----
+./trino.jar --debug --server http://172.18.0.3:31748 --user=admin
+----
diff --git a/docs/modules/trino/partials/nav.adoc b/docs/modules/trino/partials/nav.adoc
index af0ea4e7..d777e92a 100644
--- a/docs/modules/trino/partials/nav.adoc
+++ b/docs/modules/trino/partials/nav.adoc
@@ -4,15 +4,15 @@
* xref:trino:configuration.adoc[]
* xref:trino:concepts.adoc[]
* xref:trino:usage_guide/index.adoc[]
-** xref:trino:usage_guide/cluster.adoc[]
+** xref:trino:usage_guide/pod_placement.adoc[]
+** xref:trino:usage_guide/cluster_operations.adoc[]
** xref:trino:usage_guide/connect_to_trino.adoc[]
** xref:trino:usage_guide/configuration.adoc[]
+** xref:trino:usage_guide/s3.adoc[]
** xref:trino:usage_guide/security.adoc[]
** xref:trino:usage_guide/monitoring.adoc[]
** xref:trino:usage_guide/log_aggregation.adoc[]
** xref:trino:usage_guide/query.adoc[]
-** xref:trino:usage_guide/pod_placement.adoc[]
-** xref:trino:usage_guide/cluster_operations.adoc[]
** xref:trino:usage_guide/catalogs/index.adoc[]
*** xref:trino:usage_guide/catalogs/black-hole.adoc[]
*** xref:trino:usage_guide/catalogs/google-sheets.adoc[]