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.

Settings that every instance shares#

Every instance must use the same value for each of the following:

  • The backend database. All instances connect to the same database. See Configure the backend database.

  • gateway.clusters.encryption.secret. The control plane encrypts the credentials of clusters, the catalog files, and the queued statements with a key that it derives from this secret.

  • The secret that signs the web UI session. Without it, each instance creates its own random key at startup, and it cannot validate the sessions that another instance created. See Shared secrets.

  • In standalone mode, the OAuth2 keys. If http-server.authentication.oauth2.refresh-tokens is true, set http-server.authentication.oauth2.refresh-tokens.secret-key and http-server.authentication.oauth2.state-key to the same value on every instance. Otherwise, each instance generates its own random key, and the other instances reject the tokens that it issues.

  • In managed mode, the cluster authentication settings. Use the same issuer, and the same secret or private key file, on every instance. See Configure cluster authentication. Set the issuer to the address of the load balancer, which is also the address that the clusters use in deployment.manager.uri.

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