Creating a Managed Service for Trino catalog

A Trino catalog defines a connection to an external data source. Each catalog is described using a TrinoCatalog resource and associated with a specific cluster via the spec.cluster field.

Supported catalog types:

• postgresql: PostgreSQL connection.
• clickhouse: ClickHouse® connection.
• iceberg: Apache Iceberg™ connection via the REST catalog.

Using the CLIUsing the CLI

1. Prepare a Secret containing credentials for connecting to the data source.

2. Create the TrinoCatalog resource file, e.g., using the touch trinocatalog.yaml command.

3. Open the file and paste the configuration for the appropriate catalog type:

   PostgreSQL

   Iceberg (REST catalog, S3)

   Iceberg (REST catalog, Object Storage)

   ---
   apiVersion: v1
   kind: Secret
   metadata:
     name: postgres-secret
   stringData:
     username: <username>
     password: <user_password>
   ---
   apiVersion: trino.stackland.yandex.cloud/v1alpha1
   kind: TrinoCatalog
   metadata:
     name: postgresql-test-trino-full
   spec:
     cluster: trino-full
     type: postgresql
     name: postgresql-test
     postgres:
       url: postgres.example.svc.cluster.local:5432/database
       credentialsSecretRef:
         name: postgres-secret
         usernameKey: username
         passwordKey: password
   

   Settings:

   • spec.cluster: Name of the Trino cluster you want to associate the catalog with.
   • spec.name: Catalog name in Trino (used in SQL queries, such as SELECT * FROM <catalog_name>.schema.table).
   • spec.postgres.url: PostgreSQL server address in host:port/database format.
   • spec.postgres.credentialsSecretRef: Reference to the Secret with credentials, and the names of usernameKey and passwordKey.

   -ClickHouse®

    {% include notitle [YAML-file](../../_includes/yamls/operations/trino/create-catalog-clickhouse-85b29321dd6b.md) %}
   
    Settings:
   
    * `spec.cluster`: Trino cluster name.
    * `spec.name`: Catalog name in Trino.
    * `spec.clickhouse.url`: ClickHouse® server address in `host:port/database` format.
    * `spec.clickhouse.credentialsSecretRef`: Reference to the Secret with credentials.
   

   Below is an example of an Iceberg catalog using a REST catalog, client credentials authentication, and storage in an S3-compatible bucket.

   ---
   apiVersion: v1
   kind: Secret
   metadata:
     name: iceberg-oauth2-secret
   stringData:
     client-id: <customer_ID>
     client-secret: <client_secret>
   ---
   apiVersion: v1
   kind: Secret
   metadata:
     name: iceberg-s3-secret
   stringData:
     access-key-id: <access_key_id>
     secret-access-key: <secret_access_key>
   ---
   apiVersion: trino.stackland.yandex.cloud/v1alpha1
   kind: TrinoCatalog
   metadata:
     name: iceberg-test-trino-full
   spec:
     cluster: trino-full
     type: iceberg
     name: iceberg-test
     iceberg:
       url: https://iceberg-rest.example.svc.cluster.local:8181
       catalogType: rest
       storageType: s3
       rest:
         warehouse: my-warehouse
         oauth2:
           clientCredentials:
             tokenEndpoint: https://auth.example.com/token
             credentialsSecretRef:
               name: iceberg-oauth2-secret
               clientIdKey: client-id
               clientSecretKey: client-secret
       s3:
         endpoint: https://storage.yandexcloud.net
         region: ru-central1
         credentialsSecretRef:
           name: iceberg-s3-secret
           accessKeyIdKey: access-key-id
           secretAccessKeyKey: secret-access-key
   

   Settings:

   • spec.iceberg.url: REST catalog URL.
   • spec.iceberg.storageType: Storage type. The possible values are s3 and stackland-storage.
   • spec.iceberg.rest.warehouse: REST catalog name.
   • spec.iceberg.rest.oauth2.clientCredentials: Client credentials authentication parameters: the authorization server URL (tokenEndpoint) and the Secret containing the client ID and client secret.
   • spec.iceberg.s3.endpoint, region: S3 storage settings.
   • spec.iceberg.s3.credentialsSecretRef: Secret with access-key-id and secret-access-key.

   For a static token, instead of clientCredentials, specify spec.iceberg.rest.oauth2.accessTokenSecretRef with a reference to the Secret containing the token.

   Below is an example of an Iceberg catalog with a Stackland managed object storage. It is only available for clusters with enabled Object Storage.

   apiVersion: trino.stackland.yandex.cloud/v1alpha1
   kind: TrinoCatalog
   metadata:
     name: iceberg-stackland-trino-full
   spec:
     cluster: trino-full
     type: iceberg
     name: iceberg-stackland
     iceberg:
       url: http://iceberg-rest-catalog.stackland-iceberg-rest-catalog.svc:8181/api/catalog
       catalogType: rest
       storageType: stackland-storage
       rest:
         warehouse: my-warehouse
         oauth2:
           clientCredentials:
             tokenEndpoint: http://iceberg-rest-catalog.stackland-iceberg-rest-catalog.svc:8181/api/catalog/v1/oauth/tokens
             credentialsSecretRef:
               name: <user_secret>
               clientIdKey: clientId
               clientSecretKey: clientSecret
       stacklandStorage:
         bucketRef: <bucket_name>
   

   Settings:

   • spec.iceberg.rest.oauth2.clientCredentials: Client credentials authentication parameters for the platform Iceberg REST Catalog: the authorization server URL (tokenEndpoint) and the secret containing clientId and clientSecret of the RestCatalogPrincipal user.
   • spec.iceberg.storageType: stackland-storage.
   • spec.iceberg.stacklandStorage.bucketRef: Reference to the Bucket resource in the current namespace.

   The operator automatically creates AccessKey and AccessBinding and populates the S3 connection parameters.

   Note

   This example targets the platform Iceberg REST Catalog connection. Insert the following values from the RestCatalog resource and the user secret:

   • spec.iceberg.url: status.endpoint value.
   • spec.iceberg.rest.oauth2.clientCredentials.tokenEndpoint: status.oauth2TokenEndpoint value.
   • spec.iceberg.rest.warehouse: RestCatalog resource name.
   • credentialsSecretRef: Secret containing clientId and clientSecret of the RestCatalogPrincipal user. For details, see Creating a catalog user.

   Tip

   Make sure the resource name (metadata.name) follows the <spec.name>-<spec.cluster> format as shown above. Otherwise, the operator will reject catalog creation.

4. Apply the manifest: kubectl apply -f trinocatalog.yaml -n <namespace>.

Using the management consoleUsing the management console

1. If you have not opened a project yet, select one.

2. Select the namespace the cluster was created in.

3. In the left-hand menu, select Trino → Clusters.

4. Select the cluster.

5. Open the Catalogs tab and click Create catalog.

6. Fill out the fields as follows:

   Basic settings

   • Name: Catalog name in Trino. It is defined in spec.name. The management console automatically uses the <catalog_name>-<cluster_name> format for the Kubernetes resource name (metadata.name).
   • Type: Connector type. Valid values: postgresql, clickhouse, iceberg.

   After selecting the type, the Catalog settings section appears.

   Catalog settings: PostgreSQL

   • URL: Server address in host:port/database format.
   • Username: PostgreSQL user.
   • Password: User password.

   Catalog settings: ClickHouse

   • URL: Server address in host:port/database format.
   • Username: ClickHouse® user.
   • Password: User password.

   Catalog settings: Iceberg (REST catalog)

   Connection:

   • URL: REST catalog URL.
   • Warehouse: REST catalog name. This is an optional setting.

   Authentication (optional subsection):

   • Authentication method: No authentication, Static token, or Client credentials.
   • For a static token: Access token.
   • For client credentials: Authorization server URL, Client ID, and Client secret. For a platform Iceberg REST Catalog, set Client ID and Client secret to clientId and clientSecret of the RestCatalogPrincipal user, respectively. In the Additional submenu, you can specify Scope, Token update, and Token exchange.

   Data storage:

   • Storage type: s3 or stackland-storage. stackland-storage is only available for clusters with enabled Object Storage.
   • For s3: Endpoint, Region, Access key ID, Secret access key, and Path-style access.
   • For stackland-storage: Bucket: Selecting a bucket from the list of Bucket resources in the current namespace.

   Additional settings (optional)

   This section contains custom connector settings in key-value format. You can add each key only once.

7. Click Create.

The new catalog is ready and shown in the Catalogs list. After the operator applies the new configuration and the cluster switches to Running, the catalog will be available in SQL queries.