Control Plane administration#

Note

The previous name of the Starburst Control Plane was Starburst Portal.

The Starburst Control Plane UI helps you coordinate tasks across multiple SEP clusters.

For tasks that involve only one cluster, use the SEP web ui.

The Starburst Control Plane UI contains the following panes.

Query editor#

Use the Query editor pane to run SQL queries directly in Starburst Control Plane.

When either client tag-based or auto tag-based routing is enabled, the query editor includes a Client tags field. Tags you enter here are sent as the X-Trino-Client-Tags header with each query, and the normal routing pipeline applies. This lets you test routing behavior directly from the UI without a separate client application.

See Workload isolation for more information.

Note

If no adhoc clusters are defined, the query editor displays an error.

Clusters#

Use the Clusters pane to associate SEP clusters with the Starburst Control Plane and to assign clusters to routing groups. A routing group is a set of clusters that Starburst Control Plane treats as interchangeable.

Important

  • Make sure all clusters across all routing groups have the same catalog, access control, and authentication configurations.

  • Make sure all clusters within a routing group have the same physical properties (size and worker node count), execution modes (such as FTE or Warp Speed), and database objects (tables, materialized views, data products). These properties can vary across routing groups.

To associate a cluster with Starburst Control Plane and assign it to a routing group, click Create cluster.

Note

The cluster’s coordinator environment name must match the cluster name you specify. Otherwise, Starburst Control Plane marks the cluster as unhealthy.

In the Create cluster dialog, enter the cluster details. In the Routing group field, enter the name of an existing routing group to add the cluster to that group, or enter a new name to create a new routing group. In the Shared secret field, enter the shared secret that your cluster uses for internal communication. For more information, see Secure internal communication.

To remove a shared secret from an existing cluster, select Delete shared secret from the cluster’s menu. Leaving the Shared secret field empty when editing a cluster does not remove the existing secret.

To remove a shared secret from an existing cluster, use the action menu on the cluster row. Leaving the Shared secret field empty when editing a cluster does not remove the existing secret.

Click the Active toggle to enable Starburst Control Plane monitoring of the cluster status. Starburst Control Plane checks the status every few seconds and reports one of the following:

  • PENDING: The cluster is starting up.

  • HEALTHY: The cluster is ready and available.

  • UNHEALTHY: The cluster failed health checks, or the shared secret does not match the cluster’s internal communication secret.

  • UNKNOWN: Starburst Control Plane cannot communicate with the cluster. Possible reasons include the cluster going offline or a typo in the cluster URL.

  • UNSUPPORTED: The cluster is not a supported SEP cluster.

Limitations#

  • Health status monitoring is not available by default when using legacy Trino Gateway-compatible configuration. Contact Starburst Support for further information.

  • Otherwise, health status monitoring works automatically.

Query insights#

Use the Query insights pane to view all queries processed by Starburst Control Plane, including failed queries. For each query, the pane shows:

  • The routing group the query was sent to.

  • The cluster within that routing group that processed the query.

  • The routing rule that matched the query (when auto tag-based routing is enabled and a rule was matched).

Use this information to test and verify routing rules. When a query is routed by a specific routing rule, the rule name appears in the query detail view, making it easy to confirm that the intended rule was applied.

Queries that you run directly against an individual SEP cluster from the Clusters pane, without routing enabled, are also visible in the Query insights pane.

Limitations#

  • Starburst Control Plane automatically deletes query history older than 60 days. This does not affect query history on individual SEP clusters. To change the retention time, configure the persistence.retention.max-age property.

Routing rules#

Use the Routing rules pane to create, view, and update the rules that Starburst Control Plane uses to route queries to routing groups.

To create a routing rule, click Create routing rule.

  1. In the Create routing rule dialog, enter the following information:

For client tag-based routing:

  • Name: a unique label for the rule.

  • Priority: controls evaluation order. Lower priority numbers are evaluated first.

  • Description: optional text description.

  • Tag names: Values from the X-Trino-Client-Tags HTTP header. When the specified tags are present, the routing rule applies.

  • Action: the routing group to receive the query when the condition matches.

For auto tag-based routing:

  • Name: a unique label for the rule.

  • Description: optional text description.

  • Condition: when the rule applies. The condition can match against any of the available tags for the query: all system tags (source, clientTag, user, group, role) plus any custom tags produced by tagging rules.

  • Action: the routing group to receive the query when the condition matches.

  1. Click Save.

The Control Plane evaluates routing rules in priority order. For more information, see routing rule matching.

Note

To use routing rules from legacy Trino Gateway-compatible files, contact Starburst Support. Otherwise, Starburst Control Plane ignores these files and uses only routing rules you create through the Routing rules UI.

Tagging rules#

Use the Tagging rules tab to create and manage the rules that generate custom tags for each query. Tagging rules are only active when gateway.routing.type=AUTO_TAGS is set. See workload isolation and cluster configuration for more information.

Each tagging rule has the following properties:

  • Name: a unique label for the rule.

  • Description: optional text description.

  • Tag key: the key of the tag this rule produces.

  • Condition: when the rule applies. Conditions can check any system tag or any custom tag produced by a higher-priority tagging rule.

  • Action: how the tag value is produced. Use one of the following:

    • Fixed value: the tag value is a literal string you specify.

    • Regular expression extraction: the tag value is extracted from an existing tag using a regex with one capturing group. The captured group becomes the tag value.

You can reorder tagging rules in the Tagging rules tab. Click Routing rules > Tagging rules, then more_vert options > Re-order rules. Drag and drop the rules in the grid. You can not manually set a priority number for a rule.

Condition syntax#

A condition is a list of groups. A query matches if it satisfies any group (logical OR). Within a group, all expressions must match (logical AND).

Each expression compares a tag against a value using either an exact string match or a regular expression match.

Creating a tagging rule#

In the Tagging rules pane, click Create tagging rule.

  1. Enter a name and optional description.

  2. Enter a priority number. Rules with a lower number are evaluated first.

  3. Enter the Tag key — the name of the tag this rule produces.

  4. Build the condition. Click Add condition group to add an OR branch. Within each group, click Add condition to add AND clauses. Select the tag key to compare, the operator, and the value.

  5. Select the action:

  • Choose Fixed value and enter the tag value.

  • Choose Regular expression extraction, select the source tag, and enter a regular expression with exactly one capturing group.

  1. Click Save.

Examples#

Route queries by user group using a fixed value#

Create a tagging rule that sets the tier tag to premium when the user belongs to the premium_users group:

Field

Value

Tag key

tier

Condition

group equals premium_users

Action

Fixed value: premium

Then, create a routing rule that routes queries where tier EQUALS premium to the premium-cluster routing group.

Extract environment from application source tag#

Create a tagging rule that extracts the environment from an application-set source tag, such as prod-reporting or staging-etl:

Field

Value

Tag key

env

Condition

source matches regular expression ^(prod|staging)-.*

Action

Regular expression extraction from source with expression ^(prod|staging)-.*

The captured group (prod or staging) becomes the value of the env tag, which routing rules can then match against.