Routing logic

Overview

Starburst Gateway routes requests differently depending on whether they are related to previous requests:

• If a request is related to a previous request, the Gateway routes it to the same backend that handled the previous request.

• If a request is unrelated to a previous request, the Gateway uses routing rules to select a routing group, then chooses a backend from that group.

Sticky routing

Requests that are part of ongoing processes or depend on backend-managed state must be routed to the same backend cluster that initiated or maintains that state.

Starburst Gateway uses two methods to identify and route related requests.

Query identifier routing

The default query routing mechanism is query identifier routing.

With this method, when you submit a query, the Gateway extracts the query ID from your backend’s response. The Gateway then routes all subsequent requests that reference this query ID to the same backend.

For example, when retrieving query results, the client polls URIs like v1/statement/executing/queryid/nonce/counter to check if results are available. Starburst Gateway extracts the query ID from these URIs and routes the requests accordingly.

Cookie-based routing

OAuth2 authentication requires the same backend for each step of the authentication process. Enable cookie-based routing to ensure consistent backend selection during OAuth2 flows.

Basic configuration

Enable cookie-based routing by setting the gatewayCookieConfiguration.enabled property to true and providing a signing secret:

gatewayCookieConfiguration:
    enabled: true
    cookieSigningSecret: "your-high-entropy-secret-string"

When you enable this property, Starburst Gateway adds a signed cookie to requests sent to URLs that start with /oauth2 (unless a cookie is already present). This cookie routes subsequent /oauth2/* requests to the correct backend.

Note

If you load balance requests across multiple Starburst Gateway instances, use the same cookieSigningSecret value on all instances.

Advanced configuration

For SEP distributions that modify OAuth2 paths, configure additional routing behavior. Use the following configuration properties:

• routingPaths: The request URIs that trigger cookie-based routing

  • If a cookie exists, the Gateway routes to the backend that the cookie specifies

  • If no cookie exists, the Gateway adds a routing cookie

• deletePaths: The request URIs that return a response instructing the client to delete the cookie

• lifetime: The duration for which the cookies are valid

  • Defaults to 10m

  • Ensure this exceeds the time needed to complete OAuth2 handshakes

See the following example configuration:

oauth2GatewayCookieConfiguration:
  routingPaths:
    - "/oauth2"
    - "/custom/oauth2/callback"
    - "/alternative/oauth2/initiate"
  deletePaths:
    - "/custom/logout"
  lifetime: "5m"

Note

Starburst Gateway handles standard OAuth2 handshakes without additional configuration. Only customize these settings if you are using modified OAuth2 paths.