Workload isolation#

Note

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

Overview#

Starburst Control Plane routes queries to specific routing groups to prevent competing workloads from interfering with each other, and to enable workload-optimized clusters for specific use cases.

When a query arrives, the Control Plane evaluates routing rules against different tags to determine the appropriate routing group. You can configure one of two different routing methods:

  • Client tag-based routing (default method). Routing rules match against values from the HTTP header supplied by the client application.

  • Auto tag-based routing. Routing rules match against a richer set of tags derived from HTTP request headers and the authenticated user’s portal identity. Tagging rules can further derive custom tags from these inputs.

After the Control Plane selects a routing group, load balancing determines which cluster within that group handles the query. For more information, see Load balancing.

Client tag-based routing#

Client tag-based routing is based on Trino client tags. When you send a query to Starburst Control Plane, the Control Plane checks the values from the X-Trino-Client-Tags HTTP request header. If the header contains tags that match a routing rule, the Control Plane routes the query to the routing group specified by that rule. Otherwise, the Control Plane routes the query to the default adhoc routing group.

Important

You must set Trino client tags using your client application. This might require client-side changes. For example, in the Trino CLI, include the --client-tags flag in your SQL statements. If an application cannot set client tags, Starburst Control Plane routes all queries from that application to the default adhoc routing group.

Auto tag-based routing#

Auto tag-based routing derives higher-level routing tags using pattern matching, and lets you route based on user identity without requiring clients to set any headers.

When you enable auto tag-based routing, Starburst Control Plane routes each query through a two-stage process. First, the Control Plane builds a set of tags for the query by combining system tags and custom tags.

  • System tags are extracted automatically from two sources:

    • The HTTP request: source (from X-Trino-Source) and clientTag (from X-Trino-Client-Tags).

    • The authenticated user’s portal identity: username (user), group memberships (group), and roles (role).

  • Custom tags are generated by evaluating tagging rules against the system tags.

After the Control Plane computes all the tags, it evaluates routing rules in priority order against the full set of tags. The first matching routing rule determines the routing group. If no rule matches, the query goes to the default adhoc routing group.

Routing rule matching#

Starburst Control Plane evaluates routing rules in priority order.

  • In client tag-based mode, the last matching rule wins. To control the order, you can assign priority numbers in the Create routing rule or Edit routing rule panes.

  • In auto tag-based mode, the first matching rule wins. You can reorder rules in the Routing rules pane. Click more_vert options > Re-order rules, then drag and drop the rules in the grid. You can not manually set a priority number for a rule.

Workload-optimized clusters#

After you isolate workloads to specific routing groups, size and configure the clusters within each group to meet the requirements of the workload. For example, for a customer-facing application that requires low latency, enable Warp Speed on the clusters in that routing group.

Verify routing#

To verify routing behavior, check the Starburst Control Plane Query insights pane. 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 was routed by a specific routing rule, the rule name appears in the query detail view, making it easy to confirm that the intended rule applied.

Troubleshooting#

If your queries do not route as expected, check the following common issues.

Queries route to the wrong routing group#

If queries route to different routing groups than you expect:

  • Confirm you defined your routing rules correctly.

  • Verify your client application sets Trino client tags with every query.

Inconsistent query performance within routing group#

If some queries in a routing group perform worse than you expect:

  • Check the query history on each cluster in the routing group to confirm no workloads bypass Starburst Control Plane and send queries directly to the cluster.

  • Confirm queries in the routing group are compatible and unlikely to interfere with each other. Consider moving incompatible queries to a different routing group.