Configure control plane high availability#
To run several Starburst control plane instances, point all of them at one backend database, give them the same secrets, and put a load balancer or a reverse proxy in front of them.
Helm configuration#
To deploy the control plane with multiple replicas, set replicaCount to two
or more.
The default strategy is Recreate, which terminates all existing pods before
starting new ones. This is appropriate for a single-replica deployment but
causes downtime during any rollout when running multiple replicas.
RollingUpdate is not safe for version upgrades that include a database schema
migration. The control plane runs migrations on startup, and it does not
maintain backward compatibility across schema versions. A rolling upgrade
therefore leaves older pods running against a database that a newer pod has
already migrated, which causes errors. Upgrade the image version as a
coordinated operation that replaces all pods together. For example, temporarily
scale down to zero replicas, or use the Recreate strategy for the upgrade.
Accept that a version upgrade incurs downtime. Use RollingUpdate for
restarts and configuration changes that do not change the image version.
The chart sets terminationGracePeriodSeconds to 30, matching Kubernetes’
own default. This must stay above http-server.stop-timeout (20s by
default), or Kubernetes kills the pod before it finishes draining in-flight
requests. The defaults already leave a safe margin. Raise
terminationGracePeriodSeconds if you increase http-server.stop-timeout, for
example to accommodate a slower backend.
In practice, set these parameters as follows:
Longest expected time for polling nextUri < http-server.stop-timeout <
terminationGracePeriodSeconds
Helm chart minimal values.yaml example#
The following example runs two replicas in standalone mode:
replicaCount: 2
etcFiles:
config: |
node.environment=env
# Database. All replicas must connect to the same database.
persistence.jdbc.url=jdbc:postgresql://your-database-host:5432/starburst-control-plane
persistence.jdbc.user=starburst-control-plane
persistence.jdbc.password=${ENV:DB_PASSWORD}
# Shared secret for consistent web UI session validation across replicas.
# Without it, each replica generates its own random key at startup and
# cannot validate sessions created by a different replica.
internal-communication.shared-secret=${ENV:INTERNAL_COMM_SHARED_SECRET}
gateway.enabled=true
gateway.clusters.encryption.secret=${ENV:CLUSTERS_ENCRYPTION_SECRET}
# Standalone mode: the statement queue must be off.
statement-queue.enabled=false
# At least one administrator is required.
starburst.access-control.authorized-users=alice
Spread replicas across nodes#
If your Starburst Enterprise platform (SEP) installation runs on multiple K8S nodes, add a pod anti-affinity rule to ensure replicas are scheduled on separate nodes. This prevents a single node failure from taking down all instances at once:
affinity:
podAntiAffinity:
requiredDuringSchedulingIgnoredDuringExecution:
- labelSelector:
matchLabels:
role: starburst-control-plane
topologyKey: kubernetes.io/hostname