Catalogs

Catalogs are separated from runtimes so teams can reuse data-source definitions without duplicating Trino configuration in every XTrinode resource.

Resource Model

XTrinodeCatalog declares catalog configuration. XTrinode runtimes select catalogs and the operator mounts the rendered configuration into coordinator and worker pods.

XTrinodeCatalog
  -> catalog ConfigMap and secret references
  -> selected by XTrinode runtime
  -> mounted into Trino coordinator and workers

Secret-Backed Values

Secret-backed values stay in Kubernetes secrets. Catalog resources reference those secrets instead of embedding credentials directly.

Keep the following out of public reports and documentation:

• object storage credentials;
• metastore passwords;
• OAuth tokens;
• raw authorization headers;
• private catalog connection strings.

Example Catalog

apiVersion: v1
kind: Secret
metadata:
  name: postgres-credentials
  namespace: team-a
type: Opaque
stringData:
  password: change-me
---
apiVersion: analytics.xtrinode.io/v1
kind: XTrinodeCatalog
metadata:
  name: postgres-analytics
  namespace: team-a
spec:
  labels:
    team: analytics
  connector:
    postgres:
      connectionURL: jdbc:postgresql://postgres.example.com:5432/analytics
      connectionUser: trino
      connectionPasswordSecret:
        name: postgres-credentials
        key: password

Select Catalogs From A Runtime

apiVersion: analytics.xtrinode.io/v1
kind: XTrinode
metadata:
  name: analytics
  namespace: team-a
spec:
  catalogSelector:
    matchLabels:
      team: analytics

Validation

XTrinodeCatalog.spec.connector is a union: set exactly one connector field. The API exposes typed fields for common Trino connectors plus custom for exact property-level control.

Connector validation is intentionally layered:

Connector area	Status
PostgreSQL, MySQL, Kafka	Stronger typed validation
Hive, Iceberg	Partial typed validation
Other connectors	Prefer custom when you need exact upstream Trino properties

The API contains many connector shapes, but that should not be read as equal runtime maturity for every connector. Treat PostgreSQL as the current live runtime proof point, use the stronger typed paths where they are validated, and use custom for exact upstream Trino properties when a typed connector is still partial.

Connector Coverage

The CRD has shapes for the official Trino connector set, including:

Pattern	Connectors
JDBC databases	PostgreSQL, MySQL, Oracle, SQL Server, ClickHouse, MariaDB, Redshift, Snowflake, Vertica
Lake and metastore	Hive, Iceberg, Delta Lake, Hudi, Lakehouse
Search, streaming, and services	Elasticsearch, OpenSearch, Kafka, Pinot, Cassandra, MongoDB, Redis, Prometheus, Loki
Utility and test	System, JMX, Memory, TPC-H, TPC-DS, Faker, Black Hole
Other typed connectors	BigQuery, Google Sheets, Druid, DuckDB, Exasol, Ignite, Thrift, SingleStore
Escape hatch	custom with explicit connector name and properties

Use properties for non-sensitive Trino properties and propertySecretRefs for arbitrary Secret-backed properties. Catalog property names should be validated against the pinned Trino runtime before production rollout.

Secret Injection

Secret-backed catalog fields are rendered as environment placeholders in the generated catalog ConfigMap. The actual secret values stay in Kubernetes Secret objects and are injected into coordinator and worker pods.

Example generated property:

connection-password=${ENV:CATALOG_POSTGRES_ANALYTICS_CONNECTION_PASSWORD}

Example pod environment:

env:
  - name: CATALOG_POSTGRES_ANALYTICS_CONNECTION_PASSWORD
    valueFrom:
      secretKeyRef:
        name: postgres-credentials
        key: password

Generic propertySecretRefs can be used for connector properties that are not modeled as a dedicated typed secret field.

Environment variable names follow the generated CATALOG_<CATALOG_NAME>_<PROPERTY_NAME> pattern after names are uppercased and non-alphanumeric characters are replaced with underscores. Referenced Secrets must live in the same namespace as the XTrinodeCatalog.

When admission webhooks are enabled, catalog create and update requests that reference Secrets are authorized with a Kubernetes Secret get check for the requesting user. Plaintext sensitive properties are rejected in favor of typed Secret fields or propertySecretRefs.

Operational Notes

• Keep catalog definitions reusable and small.
• Keep credentials in namespace-local Kubernetes secrets.
• Use labels when several runtimes should consume the same approved catalog set.
• Watch runtime rollout status after changing catalog configuration.
• Treat connector property drift as a compatibility decision when changing the pinned Trino runtime image.
• Keep tenant-facing catalog APIs narrow. Use typed connector fields where they exist and reserve raw custom properties for trusted platform users.