sbernauer · Oct 6, 2026 · Oct 8, 2026 · Oct 8, 2026 · Oct 8, 2026 · Oct 8, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -12,6 +12,8 @@ All notable changes to this project will be documented in this file.
 - Add `/ready` endpoint to the operator Deployment, which reports the CRD installation status ([#949]).
 - Coordinators now have a default affinity to the OPA Pods when OPA authorization is configured ([#924]).
 - Add support for 483 ([#956]).
+- Support configuring an Iceberg REST catalog in the Iceberg connector, optionally authenticated
+  using OAuth2 client credentials or a bearer token ([#950]).
 
 ### Changed
 
@@ -48,6 +50,11 @@ All notable changes to this project will be documented in this file.
 - Support Vector 0.58.0 ([#953], [#959], [#960]).
 - test: Bump hive to 4.2.1 ([#961]).
 - The operator Deployment runs with a restricted security context and a read-only root filesystem, so it can be deployed into namespaces that enforce the `restricted` Pod Security Standard ([#963]).
+- Add `TrinoCatalog` version `v1alpha2`, which is now the storage version. `v1alpha1` objects are
+  converted automatically by the conversion webhook, which requires the operator to maintain its
+  CRDs (the default). In `v1alpha2`, the optional `spec.connector.iceberg.metastore` is replaced
+  by the required `spec.connector.iceberg.catalog`, which is one of `rest`, `hiveMetastore` or
+  `userProvided` ([#950]).
 
 ### Fixed
 
@@ -82,6 +89,7 @@ All notable changes to this project will be documented in this file.
 [#944]: https://github.com/stackabletech/trino-operator/pull/944
 [#945]: https://github.com/stackabletech/trino-operator/pull/945
 [#949]: https://github.com/stackabletech/trino-operator/pull/949
+[#950]: https://github.com/stackabletech/trino-operator/pull/950
 [#953]: https://github.com/stackabletech/trino-operator/pull/953
 [#956]: https://github.com/stackabletech/trino-operator/pull/956
 [#957]: https://github.com/stackabletech/trino-operator/pull/957

diff --git a/Cargo.lock b/Cargo.lock
diff --git a/Cargo.nix b/Cargo.nix
diff --git a/deploy/helm/trino-operator/Chart.yaml b/deploy/helm/trino-operator/Chart.yaml
@@ -43,7 +43,7 @@ annotations:
       displayName: TrinoCluster
       description: A Trino cluster stacklet. This resource is managed by the Stackable operator for Trino.
     - kind: TrinoCatalog
-      version: v1alpha1
+      version: v1alpha2
       name: trinocatalogs.trino.stackable.tech
       displayName: TrinoCatalog
       description: The TrinoCatalog resource can be used to define catalogs in Kubernetes objects.
diff --git a/docs/modules/trino/examples/usage-guide/fault-tolerant-execution.yaml b/docs/modules/trino/examples/usage-guide/fault-tolerant-execution.yaml
@@ -96,7 +96,7 @@ stringData:
   accessKey: minio-access-key
   secretKey: minio-secret-key
 ---
-apiVersion: trino.stackable.tech/v1alpha1
+apiVersion: trino.stackable.tech/v1alpha2
 kind: TrinoCatalog
 metadata:
   name: tpch

diff --git a/docs/modules/trino/examples/usage-guide/trino-insecure.yaml b/docs/modules/trino/examples/usage-guide/trino-insecure.yaml
@@ -1,5 +1,5 @@
 ---
-apiVersion: trino.stackable.tech/v1alpha1
+apiVersion: trino.stackable.tech/v1alpha2
 kind: TrinoCatalog
 metadata:
   name: hive

diff --git a/docs/modules/trino/examples/usage-guide/trino-secure-internal-tls.yaml b/docs/modules/trino/examples/usage-guide/trino-secure-internal-tls.yaml
@@ -1,5 +1,5 @@
 ---
-apiVersion: trino.stackable.tech/v1alpha1
+apiVersion: trino.stackable.tech/v1alpha2
 kind: TrinoCatalog
 metadata:
   name: hive

diff --git a/docs/modules/trino/examples/usage-guide/trino-secure-tls-only.yaml b/docs/modules/trino/examples/usage-guide/trino-secure-tls-only.yaml
@@ -1,5 +1,5 @@
 ---
-apiVersion: trino.stackable.tech/v1alpha1
+apiVersion: trino.stackable.tech/v1alpha2
 kind: TrinoCatalog
 metadata:
   name: hive

diff --git a/docs/modules/trino/examples/usage-guide/trino-secure-tls.yaml b/docs/modules/trino/examples/usage-guide/trino-secure-tls.yaml
@@ -1,5 +1,5 @@
 ---
-apiVersion: trino.stackable.tech/v1alpha1
+apiVersion: trino.stackable.tech/v1alpha2
 kind: TrinoCatalog
 metadata:
   name: hive

diff --git a/docs/modules/trino/pages/index.adoc b/docs/modules/trino/pages/index.adoc
@@ -5,7 +5,7 @@
 :github: https://github.com/stackabletech/trino-operator/
 :crd: {crd-ref}{crd-ref-release}&operator=trino-operator
 :crd-trinocluster: {crd-ref}/trino.stackable.tech/v1alpha1/trinocluster{crd-ref-release}
-:crd-trinocatalog: {crd-ref}/trino.stackable.tech/v1alpha1/trinocatalog{crd-ref-release}
+:crd-trinocatalog: {crd-ref}/trino.stackable.tech/v1alpha2/trinocatalog{crd-ref-release}
 :feature-tracker: https://features.stackable.tech/unified
 :k8s-crs: https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/
 

diff --git a/docs/modules/trino/pages/usage-guide/catalogs/black-hole.adoc b/docs/modules/trino/pages/usage-guide/catalogs/black-hole.adoc
@@ -7,7 +7,7 @@ It works like the `/dev/null` device on Unix-like operating systems for data wri
 
 [source,yaml]
 ----
-apiVersion: trino.stackable.tech/v1alpha1
+apiVersion: trino.stackable.tech/v1alpha2
 kind: TrinoCatalog
 metadata:
   # The name of the catalog as it will appear in Trino

diff --git a/docs/modules/trino/pages/usage-guide/catalogs/delta-lake.adoc b/docs/modules/trino/pages/usage-guide/catalogs/delta-lake.adoc
@@ -7,7 +7,7 @@ It depends on a Hive metastore being present and makes use of the same metastore
 
 [source,yaml]
 ----
-apiVersion: trino.stackable.tech/v1alpha1
+apiVersion: trino.stackable.tech/v1alpha2
 kind: TrinoCatalog
 metadata:
   # The name of the catalog as it will appear in Trino

diff --git a/docs/modules/trino/pages/usage-guide/catalogs/generic.adoc b/docs/modules/trino/pages/usage-guide/catalogs/generic.adoc
@@ -11,7 +11,7 @@ This is how you can e.g. use the {trino-psql-connector}[PostgreSQL connector]:
 
 [source,yaml]
 ----
-apiVersion: trino.stackable.tech/v1alpha1
+apiVersion: trino.stackable.tech/v1alpha2
 kind: TrinoCatalog
 metadata:
   # The name of the catalog as it appears in Trino

diff --git a/docs/modules/trino/pages/usage-guide/catalogs/google-sheets.adoc b/docs/modules/trino/pages/usage-guide/catalogs/google-sheets.adoc
@@ -9,7 +9,7 @@ Consult the {trino-google-sheets-connector}[official documentation] on how to us
 
 [source,yaml]
 ----
-apiVersion: trino.stackable.tech/v1alpha1
+apiVersion: trino.stackable.tech/v1alpha2
 kind: TrinoCatalog
 metadata:
   name: gsheet

diff --git a/docs/modules/trino/pages/usage-guide/catalogs/hive.adoc b/docs/modules/trino/pages/usage-guide/catalogs/hive.adoc
@@ -8,7 +8,7 @@ Deploy a Hive Stacklet with the xref:hive:index.adoc[].
 
 [source,yaml]
 ----
-apiVersion: trino.stackable.tech/v1alpha1
+apiVersion: trino.stackable.tech/v1alpha2
 kind: TrinoCatalog
 metadata:
   name: hive-catalog  # <1>
@@ -143,7 +143,7 @@ To use the unmanaged Hive metastore we define a TrinoCatalog object in the same
 
 [source,yaml]
 ----
-apiVersion: trino.stackable.tech/v1alpha1
+apiVersion: trino.stackable.tech/v1alpha2
 kind: TrinoCatalog
 metadata:
   name: clouderahive

diff --git a/docs/modules/trino/pages/usage-guide/catalogs/iceberg.adoc b/docs/modules/trino/pages/usage-guide/catalogs/iceberg.adoc
@@ -1,15 +1,104 @@
 = Apache Iceberg
 
 Apache Iceberg is a format for huge analytic tables designed to address some of the scaling issues with traditional Hive tables.
-Iceberg depends on a Hive metastore being present and makes use of the same metastore ConfigMap used by the Hive connector.
+Iceberg stores table metadata in a metadata catalog, which is configured in `spec.connector.iceberg.catalog`.
+The following catalogs are supported:
 
-You can deploy a Hive Metastore Stacklet with the xref:hive:index.adoc[].
+* `rest`: An https://trino.io/docs/current/object-storage/metastores.html#rest-catalog[Iceberg REST catalog]
+* `hiveMetastore`: A Hive metastore, using the same metastore ConfigMap as the xref:usage-guide/catalogs/hive.adoc[] connector
+* `userProvided`: The operator doesn't configure a catalog, you need to configure it yourself using `configOverrides`
+
+== Example Iceberg REST catalog configuration
 
-== Example Iceberg catalog configuration
+[source,yaml]
+----
+apiVersion: trino.stackable.tech/v1alpha2
+kind: TrinoCatalog
+metadata:
+  name: iceberg  # <1>
+  labels:
+    trino: simple-trino
+spec:
+  connector:
+    iceberg:
+      catalog:
+        rest:
+          hostname: iceberg-rest-catalog.example.com  # <2>
+          port: 9001  # <3>
+          path: /catalog  # <4>
+          tls:  # <5>
+            verification:
+              server:
+                caCert:
+                  secretClass: tls
+          authentication:  # <6>
+            oAuth2:
+              server:  # <7>
+                hostname: idp.example.com
+                path: /oauth2/token
+              clientCredentials:  # <8>
+                secretName: trino-iceberg-client  # <9>
+                scopes:  # <10>
+                  - lakehouse
+      s3:
+        inline:
+          host: test-minio
+          port: 9000
+          accessStyle: Path
+          credentials:
+            secretClass: minio-credentials
+---
+apiVersion: v1
+kind: Secret
+metadata:
+  name: trino-iceberg-client
+stringData:
+  clientId: trino
+  clientSecret: my-client-secret
+----
+<1> The name of the catalog as it will appear in Trino
+<2> The hostname of the REST catalog server
+<3> Optional, defaults to 443 if TLS is used and to 80 otherwise
+<4> Optional, defaults to `/`
+<5> Optional, uses the same TLS configuration as xref:usage-guide/s3.adoc#tls[S3 connections].
+    If not specified, TLS is used and the server certificate is verified against the web PKI (`webPki`).
+    Set `tls: null` to connect without TLS. Disabling the TLS verification (`verification.none`) is not supported.
+    `tls: null` is kept when creating or replacing a TrinoCatalog, but `kubectl apply` and server-side apply remove it from an existing TrinoCatalog, which brings back the `webPki` default.
+    Use `kubectl replace` or recreate the TrinoCatalog to switch an existing catalog to a connection without TLS.
+<6> Optional, defaults to no authentication
+<7> The token endpoint of the OAuth2 server, see <<oauth2-server>>.
+    It takes the same `hostname`, `port`, `path` and `tls` fields as the REST catalog, so it uses TLS with `webPki` verification by default.
+<8> The client credentials are exchanged for a token using the OAuth2 client credentials flow.
+    Alternatively, use `token.secretName` to pass a Secret containing a static bearer token in the `token` key.
+<9> Name of a Secret containing the `clientId` and `clientSecret` keys
+<10> Optional, the scopes to request from the OAuth2 server.
+     If not specified, the `catalog` scope is requested. Specifying scopes replaces this default.
+
+The operator only supports a subset of the https://trino.io/docs/current/object-storage/metastores.html#rest-catalog[REST catalog properties].
+Use `configOverrides` to set additional ones.
+
+[#oauth2-server]
+=== OAuth2 server
+
+`oAuth2.server` points to the token endpoint of the OAuth2 server.
+What it is used for depends on the credential:
+
+* `clientCredentials`: Trino fetches its token from this endpoint on startup and refreshes it there before it expires.
+* `token`: Trino uses the token as is.
+  If the token is a JWT with an `exp` claim, Trino tries to refresh it before it expires by exchanging it at this endpoint (OAuth2 token exchange).
+  If the refresh fails, Trino logs a warning and keeps using the current token.
+  A token that isn't a JWT is never refreshed, so the endpoint is never called.
+
+The OAuth2 server is required even for tokens that are never refreshed.
+Without it, the Iceberg client used by Trino would fall back to the deprecated `/v1/oauth/tokens` endpoint of the REST catalog, which is planned to be removed (see https://github.com/apache/iceberg/issues/10537[apache/iceberg#10537]).
+
+== Example Iceberg Hive metastore configuration
+
+You can deploy a Hive Metastore Stacklet with the xref:hive:index.adoc[].
 
 [source,yaml]
 ----
-apiVersion: trino.stackable.tech/v1alpha1
+apiVersion: trino.stackable.tech/v1alpha2
 kind: TrinoCatalog
 metadata:
   name: iceberg  # <1>
@@ -19,8 +108,9 @@ spec:
   connector:
     # Specify iceberg here when defining a iceberg catalog
     iceberg:
-      metastore:
-        configMap: simple-hive  # <2>
+      catalog:
+        hiveMetastore:
+          configMap: simple-hive  # <2>
       s3:
         inline:
           host: test-minio

diff --git a/docs/modules/trino/pages/usage-guide/catalogs/index.adoc b/docs/modules/trino/pages/usage-guide/catalogs/index.adoc
@@ -14,7 +14,7 @@ You can create a catalog using the `TrinoCatalog` object as follows.
 
 [source,yaml]
 ----
-apiVersion: trino.stackable.tech/v1alpha1
+apiVersion: trino.stackable.tech/v1alpha2
 kind: TrinoCatalog
 metadata:
   name: hive-catalog
@@ -33,7 +33,7 @@ spec:
           credentials:
             secretClass: minio-credentials
 ---
-apiVersion: trino.stackable.tech/v1alpha1
+apiVersion: trino.stackable.tech/v1alpha2
 kind: TrinoCatalog
 metadata:
   name: iceberg
@@ -42,8 +42,9 @@ metadata:
 spec:
   connector:
     iceberg:
-      metastore:
-        configMap: simple-hive
+      catalog:
+        hiveMetastore:
+          configMap: simple-hive
       s3:
         inline:
           host: test-minio
@@ -70,7 +71,7 @@ This example illustrates how to use config overrides and config removals
 
 [source,yaml]
 ----
-apiVersion: trino.stackable.tech/v1alpha1
+apiVersion: trino.stackable.tech/v1alpha2
 kind: TrinoCatalog
 spec:
   # Add some properties
@@ -118,6 +119,7 @@ The Trino catalog will be called `my_postgres`:
 
 [source,yaml]
 ----
+apiVersion: trino.stackable.tech/v1alpha2
 kind: TrinoCatalog
 metadata:
   name: my-postgres

diff --git a/docs/modules/trino/pages/usage-guide/catalogs/postgresql.adoc b/docs/modules/trino/pages/usage-guide/catalogs/postgresql.adoc
@@ -6,7 +6,7 @@ The https://trino.io/docs/current/connector/postgresql.html[PostgreSQL connector
 
 [source,yaml]
 ----
-apiVersion: trino.stackable.tech/v1alpha1
+apiVersion: trino.stackable.tech/v1alpha2
 kind: TrinoCatalog
 metadata:
   # The name of the catalog as it will appear in Trino

diff --git a/docs/modules/trino/pages/usage-guide/catalogs/tpcds.adoc b/docs/modules/trino/pages/usage-guide/catalogs/tpcds.adoc
@@ -7,7 +7,7 @@ This is not a stored data set and is instead a virtual data set generated at que
 
 [source,yaml]
 ----
-apiVersion: trino.stackable.tech/v1alpha1
+apiVersion: trino.stackable.tech/v1alpha2
 kind: TrinoCatalog
 metadata:
   # The name of the catalog as it will appear in Trino

diff --git a/docs/modules/trino/pages/usage-guide/catalogs/tpch.adoc b/docs/modules/trino/pages/usage-guide/catalogs/tpch.adoc
@@ -7,7 +7,7 @@ This is not a stored data set and is instead a virtual data set generated at que
 
 [source,yaml]
 ----
-apiVersion: trino.stackable.tech/v1alpha1
+apiVersion: trino.stackable.tech/v1alpha2
 kind: TrinoCatalog
 metadata:
   # The name of the catalog as it will appear in Trino

diff --git a/docs/modules/trino/partials/nav.adoc b/docs/modules/trino/partials/nav.adoc
@@ -34,7 +34,7 @@
 * xref:trino:reference/index.adoc[]
 ** xref:trino:reference/crds.adoc[]
 *** {crd-ref}/trino.stackable.tech/v1alpha1/trinocluster{crd-ref-release}[TrinoCluster {external-link-icon}^]
-*** {crd-ref}/trino.stackable.tech/v1alpha1/trinocatalog{crd-ref-release}[TrinoCatalog {external-link-icon}^]
+*** {crd-ref}/trino.stackable.tech/v1alpha2/trinocatalog{crd-ref-release}[TrinoCatalog {external-link-icon}^]
 ** xref:trino:reference/security.adoc[]
 ** xref:trino:reference/commandline-parameters.adoc[]
 ** xref:trino:reference/environment-variables.adoc[]