Manage clusters#
Use the Clusters pane to associate SEP clusters with Starburst control plane and to put them in cluster groups. This topic covers the tasks for individual clusters. For the tasks for cluster groups, see Manage cluster groups.
Before you add a cluster, make sure that it meets the requirements in Cluster requirements.
Add a cluster#
You add a cluster on the Clusters tab in both modes. In standalone mode, you enter the URL of the cluster. In managed mode, control plane requires discovery, so you turn on Use discovery and enter no URL. To prepare a managed cluster, see Connect a cluster to control plane.
On the Clusters tab, click Add cluster.
In the dialog, enter the name of the cluster. The name must match the
node.environmentproperty of the cluster coordinator. In standalone mode, also enter the URL of the cluster. In managed mode, turn on Use discovery instead.In the Cluster group field, select a cluster group. If you do not select one, control plane uses the default cluster group. The field lists the groups that you can assign. Adding a cluster needs the
CREATE_CLUSTERprivilege, which lets you select any group. See Cluster requirements.In the Shared secret field, enter the value of the
internal-communication.shared-secretproperty of the cluster. The values must match, or control plane marks the cluster asUNHEALTHY. For more information, see Shared secrets and Secure internal communication.To let control plane monitor the status of the cluster, turn on the Active toggle. For the status values, see Monitor cluster status.
Click Add cluster.
When control plane detects that the cluster is active and healthy, it includes the cluster in its routing decisions. This is how you add capacity to a cluster group.
Discovery in managed mode#
When control plane runs in managed mode, every cluster needs discovery. Control
plane uses the node addresses that the coordinator announces, and not a URL that
you enter, so control plane must be able to reach those addresses. The dialog
does not let you save a cluster without discovery. The public API rejects
useDiscovery=false with the error Control Plane requires discovery. Set useDiscovery to true and omit backendUrl and externalUrl. A cluster that you
registered with a URL has the status UNSUPPORTED with the reason
DISCOVERY_REQUIRED. To fix it, edit the cluster, turn on Use discovery,
and save. Leave the Shared secret field empty to keep the existing secret.
Changing deployment.mode on the cluster does not change its registration in
control plane. After you set deployment.mode=MANAGED on a cluster, edit the
registration, and turn on discovery.
Edit a cluster#
You can change the details of a cluster that you added. These include the cluster group and the Active toggle.
Cluster group. If you hold the
MANAGE_SECURITY,CREATE_CLUSTER, orMANAGE_QUERY_ROUTING_RULESprivilege, you can move a cluster to any other cluster group. If you hold none of them, you can still edit a cluster that you own, but it stays in its group, and you cannot move it to another group. If you save the cluster with its current group, or with no group, it stays in the group.Shared secret. If you leave the Shared secret field empty, control plane keeps the existing secret. To remove the secret, see Delete a shared secret.
Discovery. In standalone mode, you can turn off discovery for a cluster. Coordinator high availability then stops for the cluster, because it runs only for clusters that use discovery.
Control who can see and change a cluster#
When control-plane.enabled is true, Starburst Access Control decides what you
can do with a cluster. The role that creates a cluster owns it. You can also
grant a role the privileges USE_CLUSTER, ENABLE_DISABLE_CLUSTER,
MONITOR_CLUSTER, and TROUBLESHOOT_QUERY on a single cluster, in the
privileges UI.
Task |
Requirement |
|---|---|
Create a cluster |
The |
View a cluster, its status, and its metrics |
You own the cluster, or you have |
Turn a cluster on or off |
You own the cluster, or you have |
Update or delete a cluster |
You own the cluster |
Trigger a hard failover |
You own the cluster |
Set query limits#
The query limit of a cluster is the maximum number of queries that can run on it at the same time. A cluster without a limit of its own uses the limit of its cluster group. New groups start with a limit of 100.
To set the limit of a cluster:
In the Clusters pane, open the more_vert options menu of the cluster, and select Set query limits.
Enter a limit from 1 to 10,000, or clear the limit to use the limit of the group. Control plane rejects any other value.
Click Save.
Control plane counts a query against a cluster from the moment that it picks the cluster. Clusters report their running queries every 5 seconds. The count therefore includes queries that did not come through control plane, such as the refresh of a materialized view and table maintenance.
The clusters table shows the limit of each cluster. When a cluster is at its limit, control plane does not send it new queries. The limits have an effect only when the smart load balancing statement queue is on. The queue is on by default with auto tag-based routing, and it must be off in standalone mode, so the limits have no effect there. See Smart load balancing.
Trigger a hard failover#
If a cluster has coordinator high availability, you can start a failover
yourself. The cluster must use discovery. For a cluster without discovery, the
API rejects the request with the code DiscoveryDisabled. A hard failover
starts immediately. The standby coordinator takes over from the active
coordinator. Only the owner of the cluster can trigger a hard failover. If the
action is unavailable, a tooltip says why.
Check the state of the cluster. Make sure that a standby coordinator is ready, and note the queries that are running.
In the Clusters pane, open the more_vert options menu of the cluster, and select Hard failover.
The alternative is to stop the active coordinator. See Trigger a failover by stopping the active coordinator.
Delete a cluster#
To remove capacity, delete a cluster from its cluster group, or set its status to inactive.
To delete a cluster, open its more_vert options menu, and select Delete.
To set a cluster to inactive, edit the cluster, and turn off the Active toggle. Control plane stops monitoring the cluster.