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. Starburst Control Plane routes all queries from the query editor to the default adhoc routing group.

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. The pane shows each query’s routing group and the cluster that processed the query. Use this information to test and verify routing rules.

To run SQL queries directly against an individual SEP cluster, select the cluster from the Clusters pane, then navigate to the query editor. Queries you run this way appear on 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.

In the Create routing rule dialog, specify a condition and an action for the routing rule:

  • The condition consists of one or more Trino client tags that the query’s HTTP request header must include, such as application name or user ID. To set Trino client tags, use the Trino CLI.

  • The action specifies which routing group receives the query when the condition matches.

Click Save.

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.