Managed Service for Trino

Managed Service for ClickHouse® is a managed service for working with Trino, a distributed SQL engine. The service streamlines deployment and updates of Trino clusters and provides declarative management of data source catalogs along with Identity and Access Management integration.

With Managed Service for Trino, you can:

• Create clusters using the TrinoCluster custom resource.
• Connect data sources to the cluster using the TrinoCatalog custom resource.
• Set up access rules for catalogs, schemas, tables, functions, procedures, and queries.
• Manage Trino image versions using the TrinoImageCatalog custom resource.

Cluster architectureCluster architecture

A Trino cluster consists of two node types:

• Coordinator: The only node that accepts and schedules SQL queries and distributes jobs between workers. The coordinator also provisions the Trino UI and API.
• Workers: Nodes that run parts of SQL queries and return results to the coordinator. You can modify the number of workers manually using the spec.worker.replicas property.

Editing certain properties triggers cluster recreation and terminates active queries. For more information, see Updating a cluster.

Creating a clusterCreating a cluster

Here is an example of a minimal cluster configuration:

apiVersion: trino.stackland.yandex.cloud/v1alpha1
kind: TrinoCluster
metadata:
  name: trino-min
spec:
  version: "483"
  coordinator:
    resources:
      requests:
        cpu: 500m
        memory: 1Gi
      limits:
        cpu: "1"
        memory: 2Gi
  worker:
    replicas: 1
    resources:
      requests:
        cpu: 500m
        memory: 1Gi
      limits:
        cpu: "1"
        memory: 2Gi

Where:

• version: Trino version. The valid values are retrieved from the TrinoImageCatalog resource set by the operator.
• coordinator.resources: Queries and CPU / RAM limits for the coordinator pod.
• worker.replicas: Number of workers per cluster. The minimum value is 1.
• worker.resources: Queries and CPU / RAM limits for each worker pod.

You can also set the following under spec:

• config: Additional Trino settings in key–value format. The available keys and values are defined in the validation schema for the relevant Trino cluster version. The operator publishes schemas in ConfigMap trino-omdb-operator-<version> within its namespace, where you can view the current list. For example, the io.trino key specifies a logging level (the possible values are DEBUG, INFO, WARN, and ERROR). Any keys or values that do not match the validation schema will be rejected during cluster creation or update.
• accessControl: Trino resource access rules. See Access management.
• deletionProtection: Protection against accidental cluster deletion. See Deletion protection.

Updating a clusterUpdating a cluster

When you update certain properties, Managed Service for Trino recreates the cluster. While the new configuration is being applied, the cluster switches to Updating and active queries get interrupted.

The system will recreate a cluster if any of the following TrinoCluster resource properties are updated:

• spec.version
• spec.coordinator.resources
• spec.worker.resources
• spec.config
• Any properties of the associated TrinoCatalog resources.

Updates to the following properties are applied without recreating the cluster:

• spec.worker.replicas
• spec.accessControl

CatalogsCatalogs

A catalog in Trino configures a connection to a data source. Managed Service for Trino manages catalogs using the TrinoCatalog custom resource. Each resource describes a single catalog and is associated with a specific cluster via the spec.cluster field.

Supported connector types:

• PostgreSQL: Connection properties are specified in spec.postgres.
• ClickHouse®: Connection properties are specified in spec.clickhouse.
• Apache Iceberg™: Connection to Iceberg REST Catalog in Stackland is set in spec.stacklandRestCatalog.

In the manifest, specify a single section with connector settings. spec.type is not used.

For PostgreSQL and ClickHouse®, credentials and certificates are stored in Kubernetes secrets referenced in the credentialsSecretRef and certificateSecretRef fields.

For Apache Iceberg™, specify the name of an existing StacklandRestCatalog resource in spec.stacklandRestCatalog.catalogRef. The catalog must reside in the same namespace as TrinoCatalog and the Trino cluster. The connection and storage access settings are configured automatically. See the example in the Creating a Managed Service for Trino catalog guide.

When you update a catalog, Managed Service for Trino recreates the cluster. While the new configuration is being applied, the cluster switches to Updating and active queries are interrupted. For more information, see Updating a cluster.

Data storage for IcebergData storage for Iceberg

Apache Iceberg™ data files are stored in Object Storage. A bucket is created automatically together with the Iceberg REST Catalog catalog. When connecting a catalog to Trino, there is no need to specify a bucket, storage address, or access keys.

REST catalog authenticationREST catalog authentication

When working with a catalog, the permissions of the user or service account used for Trino queries are used. Assign it a role for the folder or required catalog resources. Also, the relevant operations must be permitted in the Trino access rules.

The IAM token is provided to Trino via auth-proxy in the additional iam-token parameter and is used when accessing the REST catalog. There is no need to create a separate catalog user and specify OAuth2 credentials in TrinoCatalog.

For a service account, specify the ServiceAccount resource name in spec.accessControl in Kubernetes, not the IAM subject ID.

Additional Iceberg settingsAdditional Iceberg settings

Under spec.stacklandRestCatalog.additionalProperties in the TrinoCatalog resource, you can configure data storage and queries to run for the Apache Iceberg™ catalog. All properties in this section are optional.

Iceberg viewsIceberg views

For creating and reading Iceberg views via Iceberg REST Catalog, meet these two conditions:

1. Under spec.stacklandRestCatalog.additionalProperties, specify the iceberg.rest-catalog.view-endpoints-enabled: true value.
2. In the CREATE VIEW command, add SECURITY INVOKER.

When working with Iceberg REST Catalog, permissions are checked for the user or service account used for the query. With SECURITY INVOKER, when reading a view, Trino accesses base tables with the IAM token of the user running the query. If SECURITY INVOKER is not specified, SECURITY DEFINER mode is used: permissions are checked on behalf of the view owner, which is incompatible with the Iceberg REST Catalog access model.

Here is an example:

CREATE VIEW analytics.events_summary
SECURITY INVOKER
AS
SELECT id, name FROM analytics.events;

To learn how these properties behave, see the Trino documentation: Iceberg settings and working with S3.

Specify property names in full, including dots. Write Boolean values (true and false) and digits without quotation marks. Specify sizes and time intervals as strings with a measurement unit, e.g., "512MB", "30s", or "7d".

Property names and possible values are checked for the selected Trino version. If the property is not supported or the value is of the wrong type, the attempt to create or update a catalog will fail.

See an example of a manifest with additional settings in the Creating a Managed Service for Trino catalog guide.

Access managementAccess management

The spec.accessControl property of the TrinoCluster resource sets access rules for Trino resources. Rules are categorized by resource type:

• catalogs: Access to catalogs. Privileges: all, read-only, and none.
• schemas: Access to schemas. The owner field defines whether or not the user is the schema owner.
• tables: Access to tables and specific columns. Privileges: SELECT, INSERT, DELETE, UPDATE, OWNERSHIP, and GRANT_SELECT. You can set a filter by rows and masks for columns.
• functions: Access to functions. Privileges: EXECUTE, GRANT_EXECUTE, and OWNERSHIP.
• procedures: Access to procedures. Privileges: EXECUTE and GRANT_EXECUTE.
• queries: Managing queries. Privileges: execute, view, and kill. If the queryOwner field is specified, the execute privilege is not available.

The matching fields (user, catalog, schema, table, function, procedure, and queryOwner) are set as regular expressions. If a field is not set, Trino inserts .* so the rule applies to all values.

For queries on behalf of a service account, specify the ServiceAccount resource name in the user field in Kubernetes, not the IAM subject ID.

Cluster network accessCluster network access

After the cluster is created, you can find connection addresses in the status.fqdn field of the TrinoCluster resource:

kubectl get trinocluster <cluster_name> -n <namespace> -o jsonpath='{.status.fqdn}'

Response structure:

• external: Coordinator FQDN for connecting via Trino clients (CLI, JDBC).
• webUI: FQDN for access to Trino UI.

Image versionsImage versions

The TrinoImageCatalog resource defines the list of available Trino versions. The operator creates it automatically during the component installation. The version set in spec.version of the TrinoCluster resource must also be specified in TrinoImageCatalog. Otherwise, the system will reject any attempt to create or update a cluster.

Deletion protectionDeletion protection

The spec.deletionProtection property in the TrinoCluster resource prevents accidental deletion of the cluster via the Kubernetes API. With protection enabled (spec.deletionProtection: true), the operator rejects any attempt to delete the resource; the kubectl delete command and deletion through the management console do not work until protection is disabled.

• The default value is false, meaning that protection is disabled.
• To enable or disable deletion protection, set the relevant spec.deletionProtection value when creating or updating your cluster.
• Protection is limited to the TrinoCluster resource. It does not apply to operator-created resources, such as Pod, Service, ConfigMap, and Secret.

Cluster health statesCluster health states

You can check the cluster’s current state in the status.phase field of the TrinoCluster resource. Valid values:

• Running: Cluster is running, and all nodes are ready.
• Updating: Operator is applying a new configuration (workers, coordinator, or catalogs are being updated).
• Warning: Cluster is running with minor errors. For details, refer to status.conditions.
• Failed: Cluster failed to start or is not operational. For info on the root cause, refer to status.conditions with reason: NodesFailed.
• Deleting: Cluster is being deleted.

For a complete list of reconciliation conditions, see status.conditions.