From 53650ffe3d5e605b9dca57ecb1bd7b225f27518d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Florian=20M=C3=BCller?= Date: Tue, 28 Jul 2026 12:55:22 +0200 Subject: [PATCH 1/2] fix(docs): Add required TLS and fix stale fields in S3 examples --- .../usage-guide/catalogs/delta-lake.adoc | 10 +++++- .../pages/usage-guide/catalogs/hive.adoc | 17 +++++++-- .../pages/usage-guide/catalogs/iceberg.adoc | 6 ++++ docs/modules/trino/pages/usage-guide/s3.adoc | 36 +++++++++++++------ 4 files changed, 56 insertions(+), 13 deletions(-) diff --git a/docs/modules/trino/pages/usage-guide/catalogs/delta-lake.adoc b/docs/modules/trino/pages/usage-guide/catalogs/delta-lake.adoc index ba1661148..e2441e091 100644 --- a/docs/modules/trino/pages/usage-guide/catalogs/delta-lake.adoc +++ b/docs/modules/trino/pages/usage-guide/catalogs/delta-lake.adoc @@ -1,6 +1,6 @@ = Delta Lake -[Delta Lake](https://delta.io/) is an open-source storage framework that enables building a Lakehouse architecture with support for multiple compute engines. +https://delta.io/[Delta Lake] is an open-source storage framework that enables building a Lakehouse architecture with support for multiple compute engines. It depends on a Hive metastore being present and makes use of the same metastore ConfigMap used by the Hive connector. == Example Delta Lake catalog configuration @@ -27,8 +27,16 @@ spec: accessStyle: Path credentials: secretClass: minio-credentials + # TLS is required for S3 connections, see the note below + tls: + verification: + server: + caCert: + secretClass: minio-tls-certificates ---- +IMPORTANT: The `tls` section is required, see xref:usage-guide/s3.adoc#tls-required[Connecting Trino to S3]. + == Connect to S3 store or HDFS The Delta Lake connector connects to S3 or HDFS in the same way the xref:usage-guide/catalogs/hive.adoc[] connector does. diff --git a/docs/modules/trino/pages/usage-guide/catalogs/hive.adoc b/docs/modules/trino/pages/usage-guide/catalogs/hive.adoc index db3de6ac2..f671d8f3d 100644 --- a/docs/modules/trino/pages/usage-guide/catalogs/hive.adoc +++ b/docs/modules/trino/pages/usage-guide/catalogs/hive.adoc @@ -26,13 +26,19 @@ spec: accessStyle: Path credentials: secretClass: minio-credentials - configOverrides: # <4> + tls: # <4> + verification: + server: + caCert: + secretClass: minio-tls-certificates + configOverrides: # <5> hive.metastore.username: trino ---- <1> The name of the catalog as it will appear in Trino <2> TrinoCluster can use these labels to select which catalogs to include <3> The name of your Hive Stacklet -<4> Use `configOverrides` to add arbitrary properties to the Trino catalog configuration +<4> TLS is required for S3 connections, see xref:usage-guide/s3.adoc#tls-required[Connecting Trino to S3] +<5> Use `configOverrides` to add arbitrary properties to the Trino catalog configuration == Connect to S3 store @@ -50,11 +56,18 @@ spec: accessStyle: Path credentials: secretClass: minio-credentials + tls: + verification: + server: + caCert: + secretClass: minio-tls-certificates # OR s3: reference: my-minio ---- +IMPORTANT: The `tls` section is required, see xref:usage-guide/s3.adoc#tls-required[Connecting Trino to S3]. + See xref:concepts:s3.adoc[] for details about S3 connections. IMPORTANT: Make sure that the underlying Hive metastore also has access to the S3 store, because it will e.g. check if the directory exists when creating tables. diff --git a/docs/modules/trino/pages/usage-guide/catalogs/iceberg.adoc b/docs/modules/trino/pages/usage-guide/catalogs/iceberg.adoc index f898a812b..a37c35440 100644 --- a/docs/modules/trino/pages/usage-guide/catalogs/iceberg.adoc +++ b/docs/modules/trino/pages/usage-guide/catalogs/iceberg.adoc @@ -28,9 +28,15 @@ spec: accessStyle: Path credentials: secretClass: minio-credentials + tls: # <3> + verification: + server: + caCert: + secretClass: minio-tls-certificates ---- <1> The name of the catalog as it will appear in Trino <2> This is the name of your Hive Stacklet +<3> TLS is required for S3 connections, see xref:usage-guide/s3.adoc#tls-required[Connecting Trino to S3] == Connect to S3 store or HDFS The Iceberg connector can connect to S3 or HDFS in the same way the xref:usage-guide/catalogs/hive.adoc[] connector does. diff --git a/docs/modules/trino/pages/usage-guide/s3.adoc b/docs/modules/trino/pages/usage-guide/s3.adoc index 142cc99d8..cbea228ed 100644 --- a/docs/modules/trino/pages/usage-guide/s3.adoc +++ b/docs/modules/trino/pages/usage-guide/s3.adoc @@ -2,7 +2,16 @@ :description: Configure S3 connections in Trino either inline within the TrinoCatalog or via an external S3Connection resource for centralized management. You can specify S3 connection details directly inside the TrinoCatalog specification or by referring to an external S3Connection custom resource. -This mechanism used used across the whole Stackable Data Platform, read the xref:concepts:s3.adoc[S3 concepts page] to learn more. +This mechanism is used across the whole Stackable Data Platform, read the xref:concepts:s3.adoc[S3 concepts page] to learn more. + +[#tls-required] +IMPORTANT: Every S3 connection must contain a `tls` section, because Trino uses the native S3 client, which requires TLS. +The operator rejects a connection without it, and reconciliation of the entire TrinoCluster fails. +No configuration change is applied until the connection is fixed, including changes unrelated to S3. +The Stacklet keeps running with its previous configuration and still reports the `Available` condition as `True`, and no Kubernetes event is emitted. +Check the logs of the Trino operator if a catalog or a configuration change appears to have no effect. +Adding the missing `tls` section is enough to recover; the pending changes are applied within seconds. +This applies to both of the forms shown below. == Inline @@ -14,22 +23,24 @@ s3: # <1> inline: host: test-minio # <2> port: 9000 # <3> - pathStyleAccess: true # <4> - secretClass: minio-credentials # <5> - tls: + accessStyle: Path # <4> + credentials: + secretClass: minio-credentials # <5> + tls: # <6> verification: server: caCert: - secretClass: minio-tls-certificates #<6> + secretClass: minio-tls-certificates ---- <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. +<4> Optional access style, either `Path` or `VirtualHosted`; This defaults to + `VirtualHosted`, which means virtual hosted-style URLs are used. +<5> Name of the SecretClass providing the credentials. The Secret behind it is expected + to contain the following keys: `accessKey` and `secretKey` +<6> TLS settings for encrypted traffic. The `secretClass` can be provided by the Secret Operator or yourself. + This section is required, see <>. A self provided S3 TLS secret can be specified like this: @@ -84,6 +95,11 @@ spec: accessStyle: Path credentials: secretClass: minio-credentials + tls: + verification: + server: + caCert: + secretClass: minio-tls-certificates ---- This has the advantage that the connection configuration is configured in a single place and can be shared across applications, reducing the cost of updating these details. From e59e1c3ce2038cdd0b89797e49f1ff7d941c3412 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Florian=20M=C3=BCller?= Date: Tue, 28 Jul 2026 17:21:06 +0200 Subject: [PATCH 2/2] fix(docs): focus tls remark --- docs/modules/trino/pages/usage-guide/s3.adoc | 6 ------ 1 file changed, 6 deletions(-) diff --git a/docs/modules/trino/pages/usage-guide/s3.adoc b/docs/modules/trino/pages/usage-guide/s3.adoc index cbea228ed..b9ef07516 100644 --- a/docs/modules/trino/pages/usage-guide/s3.adoc +++ b/docs/modules/trino/pages/usage-guide/s3.adoc @@ -6,12 +6,6 @@ This mechanism is used across the whole Stackable Data Platform, read the xref:c [#tls-required] IMPORTANT: Every S3 connection must contain a `tls` section, because Trino uses the native S3 client, which requires TLS. -The operator rejects a connection without it, and reconciliation of the entire TrinoCluster fails. -No configuration change is applied until the connection is fixed, including changes unrelated to S3. -The Stacklet keeps running with its previous configuration and still reports the `Available` condition as `True`, and no Kubernetes event is emitted. -Check the logs of the Trino operator if a catalog or a configuration change appears to have no effect. -Adding the missing `tls` section is enough to recover; the pending changes are applied within seconds. -This applies to both of the forms shown below. == Inline