Install and configure control plane#

Install and configure the Starburst control plane using one of the following methods:

  • tar.gz archive

  • Helm

Choose the mode#

Control plane runs in one of two modes. The properties that you set in the control plane’s config.properties file decide the mode.

Mode

What you set

Standalone mode

gateway.enabled=true. Each cluster keeps its own catalogs and access control. Not recommended for new deployments.

Managed mode

gateway.enabled=true, control-plane.enabled=true, and cluster authentication. Control plane holds the catalogs and Starburst access control for all clusters.

Control plane does not start with an invalid combination. In managed mode, it routes only to clusters that run in managed mode. Cluster authentication requires auto tag-based routing (gateway.routing.type=AUTO_TAGS), which is the default, so managed mode needs it too.

Install with tar.gz archive#

Use the following steps to install control plane with the tar.gz archive.

Download the archive#

Download the tar.gz archive for your platform from Starburst software downloads:

  • Use starburst-portal-<version>-x86_64.tar.gz for x86_64 systems

  • Use starburst-portal-<version>-aarch64.tar.gz for ARM64 systems

Extract and install the archive#

Extract the archive:

tar -xzf starburst-portal-<version>-<arch>.tar.gz

Move the extracted directory to the installation directory:

sudo mv starburst-portal-<version>-<arch> /usr/lib/starburst-portal

If it does not already exist, create a configuration directory named starburst under the system /etc directory:

sudo mkdir -p /etc/starburst

Directories#

The archive contains the following directories:

starburst-portal/
|-- bin/                    # Launcher executable
|-- jvm/                    # Bundled JDK
|-- lib/                    # Application JAR files
+-- secrets-plugin/         # Secrets provider plugin

Create configuration files#

Create the main control plane configuration file as /etc/starburst/config.properties.

For the minimum set of properties that starts control plane, see Minimal configuration.

For example, in managed mode, use the following config.properties file. In a Helm installation, put the properties under etcFiles.config.

# Control plane config.properties (Helm: etcFiles.config)
node.environment=production

# Backend database
persistence.jdbc.url=jdbc:postgresql://db.example.com:5432/starburst_portal
persistence.jdbc.user=starburst_portal
persistence.jdbc.password=${ENV:DB_PASSWORD}

# Gateway
gateway.enabled=true
gateway.clusters.encryption.secret=${ENV:CLUSTERS_ENCRYPTION_SECRET}

# Trust tokens for managed clusters
gateway.clusters.authentication.enabled=true
gateway.clusters.authentication.issuer=https://control-plane.example.com
# The issuer is required. It must match
# http-server.authentication.managed.issuer on the clusters, or their
# discovery.uri when that is not set.
gateway.clusters.authentication.secret=${ENV:CLUSTERS_AUTH_SECRET}
# Set the secret or the private key file, and not both.
gateway.clusters.authentication.token.ttl=6h
gateway.clusters.authentication.statement.ttl=30s

# Starburst access control and catalogs on control plane (managed mode)
control-plane.enabled=true

# User sign-in - LDAP, OAuth 2.0, or Okta only (OAuth 2.0 example)
http-server.authentication.type=oauth2
web-ui.authentication.type=oauth2
http-server.authentication.oauth2.issuer=https://idp.example.com/
http-server.authentication.oauth2.client-id=${ENV:OAUTH2_CLIENT_ID}
http-server.authentication.oauth2.client-secret=${ENV:OAUTH2_CLIENT_SECRET}

# Administrators
starburst.access-control.authorized-groups=portal-admins

# Optional features. Set only the properties of the features that you use.

# --- Provision users and groups from LDAP or SCIM ---
ldap-user-provisioning[.<server>].group-membership-attribute=<group-membership-attribute>
# LDAP attribute for group membership (for example, member or uniqueMember)
ldap-user-provisioning[.<server>].group-name-attribute=<group-name-attribute>
# LDAP attribute for group name (for example, cn)
ldap-user-provisioning[.<server>].group-search-base=<group-search-base-dn>
# Search base DN for group searches
ldap-user-provisioning[.<server>].group-search-filter=<group-search-filter>
# LDAP filter for group searches
ldap-user-provisioning[.<server>].ldap.bind-password=${ENV:LDAP_USER_PROVISIONING_SERVER_LDAP_BIND_PASSWORD}
# Password for the bind user
ldap-user-provisioning[.<server>].ldap.bind-user=<bind-user-dn>
# Distinguished name (DN) of the service account to bind as
ldap-user-provisioning[.<server>].user-name-attribute=<user-name-attribute>
# LDAP attribute for username (for example, sAMAccountName)
ldap-user-provisioning[.<server>].user-search-base=<user-search-base-dn>
# Search base DN for user searches
ldap-user-provisioning[.<server>].user-search-filter=<user-search-filter>
# LDAP filter for user searches
starburst.users.provisioning.scim.secret-token=${ENV:STARBURST_USERS_PROVISIONING_SCIM_SECRET_TOKEN}
# Secret used by SCIM client to authenticate

# --- Smart load balancing queue ---
statement-queue.enabled=true
# default true

# --- Catalog management & metastore ---
metastore.enabled=true
# default true
metastore.materialization.enabled=true
# default true

# --- LakeOps ---
icehouse-tasks.enabled=true
# Enables control plane Icehouse tasks
icehouse.server.name=<icehouse-server-name>
icehouse.server.shared-secret=${ENV:ICEHOUSE_SERVER_SHARED_SECRET}
# control-plane.enabled=true also required

# --- Notifications & email ---
email.mailgun.api-key=${ENV:EMAIL_MAILGUN_API_KEY}
# The mailgun-provided API key
email.mailgun.send-domain=<mailgun-send-domain>
# The mailgun-registered domain to send emails from
email.smtp.host=<smtp-host>
email.smtp.password=${ENV:EMAIL_SMTP_PASSWORD}
email.smtp.port=<smtp-port>
email.smtp.tls=<smtp-tls-setting>
email.smtp.username=<smtp-username>

# --- Usage metrics, telemetry & event bus ---
telemetry.enabled=true
# default true

The optional features section lists properties by feature. If you use a feature, you must set its properties that show a value in angle brackets, which is a placeholder for a value that you provide. Properties that show a default value are optional.

The ${ENV:...} references read environment variables. Replace them with literal values only if you cannot use environment variables, and then restrict access to the file. See Restrict access to configuration files. Set gateway.clusters.authentication.secret or gateway.clusters.authentication.private-key-file, and not both.

To configure control plane in standalone mode, use the following config.properties file. In a Helm installation, put the properties under etcFiles.config.

# Node configuration
node.environment=production

# HTTP server (plain HTTP, for evaluation only. See the note after the example.)
http-server.http.enabled=true
http-server.http.port=8080

# Database persistence
persistence.jdbc.url=jdbc:postgresql://your-database-url:5432/starburst_portal
persistence.jdbc.user=starburst_portal
persistence.jdbc.password=${ENV:DB_PASSWORD}

# Gateway configuration
gateway.enabled=true
gateway.clusters.encryption.secret=${ENV:CLUSTERS_ENCRYPTION_SECRET}

# Standalone mode: the statement queue must be off
statement-queue.enabled=false

# Catalog
metastore.enabled=true
credentials-provider.type=file
credentials-provider.credentials-file-path=/etc/starburst/catalog-credentials.json

# Notifications & email
email.mailgun.api-key=${ENV:EMAIL_MAILGUN_API_KEY}
# The mailgun-provided API key
email.mailgun.send-domain=<mailgun-send-domain>
# The mailgun-registered domain to send emails from
email.smtp.host=<smtp-host>
email.smtp.password=${ENV:EMAIL_SMTP_PASSWORD}
email.smtp.port=<smtp-port>
email.smtp.tls=<smtp-tls-setting>
email.smtp.username=<smtp-username>

# Define control plane administrators:
starburst.access-control.authorized-users=alice,bob
starburst.access-control.authorized-groups=portal-admins

The ${ENV:...} references read environment variables. Replace them with literal values only if you cannot use environment variables, and then restrict access to the file. See Restrict access to configuration files.

The example uses plain HTTP to keep the configuration short. In production, enable HTTPS so that credentials and queries are not sent in clear text. See Configure TLS.

Create the catalog credentials file at /etc/starburst/catalog-credentials.json:

[
  {
    "emulated": {
      "accessKey": "your-emulated-access-key",
      "secretKey": "your-emulated-secret-key"
    }
  }
]

Create the JVM configuration at /etc/starburst/jvm.config:

-server
-XX:InitialRAMPercentage=80
-XX:MaxRAMPercentage=80
-XX:+ExplicitGCInvokesConcurrent
-XX:+HeapDumpOnOutOfMemoryError
-XX:+ExitOnOutOfMemoryError
-Djdk.attach.allowAttachSelf=true
-Dfile.encoding=UTF-8

Create the logging configuration at /etc/starburst/log.properties:

io.starburst=INFO
io.trino=INFO

Configuration files#

Use the following files to configure control plane for tar.gz installations:

File

Purpose

/etc/starburst/config.properties

Main configuration file for control plane. Contains database connection, gateway configuration, authentication, and HTTP server settings.

/etc/starburst/catalog-credentials.json

JSON file that contains credentials for AWS authentication when accessing the Glue API for catalog operations.

/etc/starburst/jvm.config

JVM startup options including memory settings, garbage collection, and system properties. Specify one option per line.

/etc/starburst/log.properties

Logging level configuration for different packages. Controls verbosity of logs for troubleshooting and monitoring.

/etc/starburst/starburstdata.license

Starburst license file. Obtain from your Starburst representative or the software downloads portal.

Copy license file#

Copy your Starburst license file to the configuration directory:

sudo cp starburstdata.license /etc/starburst/

Restrict access to configuration files#

The configuration directory can contain database passwords, encryption secrets, catalog credentials, and your license. Make it readable only by the account that runs control plane:

sudo chown -R <service-user>: /etc/starburst
sudo chmod 700 /etc/starburst
sudo chmod 600 /etc/starburst/*

Start control plane#

To start control plane, use the following command:

/usr/lib/starburst-portal/bin/launcher run --etc-dir /etc/starburst

To run control plane as a background service, use the following command:

/usr/lib/starburst-portal/bin/launcher start --etc-dir /etc/starburst

Install with Helm#

Use the following steps to deploy control plane on Kubernetes with Helm.

Configure Harbor registry access#

To log in to the Starburst Harbor registry, use the following command:

printf '%s' "$REGISTRY_PASSWORD" | helm registry login "harbor.starburstdata.net" \
  --username "<your-registry-username>" \
  --password-stdin

Set the REGISTRY_PASSWORD environment variable to your registry password before you run the command. Reading the password from standard input keeps it out of the process list and your shell history, unlike the --password option.

To verify your registry access, use the following command:

helm pull oci://harbor.starburstdata.net/starburstdata/charts/starburst-portal --version <version>

Create image pull secret#

Create a Docker registry secret for the private registry from a Docker configuration file that contains your registry credentials, so that the password is not on the command line:

kubectl create secret generic regcred \
  --type=kubernetes.io/dockerconfigjson \
  --from-file=.dockerconfigjson=<path-to-docker-config.json>

Create configuration secrets#

Create a Kubernetes secret for the license:

kubectl create secret generic starburst \
  --from-file=starburstdata.license=./starburstdata.license

Create a secret for sensitive configuration values. First, create a file named portal-secret.env that is readable only by you, with one value per line:

DB_PASSWORD=<your-database-password>
CLUSTERS_ENCRYPTION_SECRET=<your-encryption-secret>

Then create the secret from the file, and delete the file:

kubectl create secret generic portal-secret \
  --from-env-file=portal-secret.env
rm portal-secret.env

Do not pass these values with --from-literal. They would appear in your shell history and in the process list.

Create configuration file#

Create a portal-values.yaml file with your configuration:

imagePullSecrets:
  - name: regcred

etcFiles:
  config: |
    # Node identification
    node.environment=production

    # Database (required)
    persistence.jdbc.url=jdbc:postgresql://starburst-persistence-postgresql:5432/starburst_portal
    persistence.jdbc.user=starburst_portal
    persistence.jdbc.password=${ENV:DB_PASSWORD}

    # Gateway configuration
    gateway.enabled=true
    gateway.clusters.encryption.secret=${ENV:CLUSTERS_ENCRYPTION_SECRET}

    # Standalone mode: the statement queue must be off
    statement-queue.enabled=false

  catalogCredentials: |
    [
      {
        "emulated": {
          "accessKey": "your-emulated-access-key",
          "secretKey": "your-emulated-secret-key"
        }
      }
    ]

envFrom:
  - secretRef:
      name: portal-secret

See also

To resolve secrets at runtime instead of storing them in Helm values, see Configure a secrets provider.

Deploy control plane#

To deploy control plane, use the following command:

helm install starburst-portal \
  oci://harbor.starburstdata.net/starburstdata/charts/starburst-portal \
  -f portal-values.yaml

Verify deployment#

To verify your deployment, use the following commands:

kubectl get pods -l app=starburst-portal
kubectl logs -l app=starburst-portal

Minimal configuration#

The following properties are required for a minimal working configuration:

# Node identification
node.environment=production

# Database (required)
persistence.jdbc.url=jdbc:postgresql://hostname:5432/database
persistence.jdbc.user=username
persistence.jdbc.password=${ENV:DB_PASSWORD}

# Gateway with cluster management
gateway.enabled=true
gateway.clusters.encryption.secret=${ENV:CLUSTERS_ENCRYPTION_SECRET}

# Administrators
starburst.access-control.authorized-users=admin

In standalone mode, also set the following properties:

# Standalone mode
control-plane.enabled=false
statement-queue.enabled=false

In managed mode, instead add the following properties to those above:

# Managed mode
control-plane.enabled=true
gateway.clusters.authentication.enabled=true
gateway.clusters.authentication.issuer=https://control-plane.example.com
gateway.clusters.authentication.secret=${ENV:CLUSTERS_AUTH_SECRET}

Set gateway.clusters.authentication.secret or gateway.clusters.authentication.private-key-file, and not both.

Gateway properties#

Property

Description

Default

gateway.enabled

Enables the gateway functionality and allows control plane to route queries to backend clusters. This property is required for cluster management features.

false

gateway.clusters.encryption.secret

Secret key that encrypts cluster credentials stored in the database. Keep this value secure and consistent across restarts.

None (required)

Managed mode properties#

Property

Description

Default

control-plane.enabled

Turns on Starburst access control and catalogs on control plane. It requires gateway.enabled and gateway.clusters.authentication.enabled.

false

gateway.clusters.authentication.enabled

Authenticates the requests that control plane sends to clusters with tokens that control plane signs. It is required when control-plane.enabled is true.

false

gateway.clusters.authentication.issuer

The issuer of the tokens that control plane creates. It must be an HTTP or HTTPS URL without a query or a fragment. It must match http-server.authentication.managed.issuer on the clusters, or their discovery.uri when that is not set.

None (required)

gateway.clusters.authentication.secret

The secret that control plane uses to derive the signing key of its tokens.

None

gateway.clusters.authentication.private-key-file

The path to a PEM-encoded RSA private key that signs the tokens. Use it where you cannot derive the key from a secret.

None

gateway.clusters.authentication.token.ttl

How long a token is valid.

6h

gateway.clusters.authentication.statement.ttl

How long a statement submission token is valid. It must not be longer than gateway.clusters.authentication.token.ttl.

30s

If a property is missing, control plane does not start, and the error names the property. For example, the error control-plane.enabled requires gateway.enabled and gateway.clusters.authentication.enabled means that one of the two is not set.

Next steps#

After control plane is running, add your SEP clusters from the Clusters pane. See Clusters and cluster groups.

In managed mode, connect your clusters by setting two properties in their configuration. See Connect a cluster to control plane.

Before you upgrade a standalone deployment#

You can upgrade an existing (480-e through 483-e) control plane in standalone mode. If you want to use the control plane in managed mode, Starburst recommends starting with a net new deployment.

These steps apply when gateway.enabled is true on control plane, control-plane.enabled is not set or is false, and each SEP cluster runs in standalone mode, which is the default.

Statement queue. In 2026.6.0 and later, the statement queue is on by default. Smart load balancing uses the queue, and it is available only in managed mode. Control plane does not start if the queue is on and gateway.clusters.authentication.enabled is not true, so in standalone mode you must turn the queue off. When you upgrade, set statement-queue.enabled to false in the config.properties file of control plane. Control plane then sends statements straight to the clusters. Do not set gateway.clusters.authentication.enabled to true to keep the queue on. That setting makes control plane sign the requests that it sends to clusters with tokens, and the clusters must then trust those tokens, which moves the deployment toward managed mode.

Cluster deployment mode. You do not need to change the deployment mode of your SEP clusters. The default deployment mode is standalone, which is correct for a standalone control plane. Do not set deployment.mode=MANAGED on these clusters.

Catalog configuration. Make the following changes in the catalogs of your SEP clusters before you upgrade the clusters to 2026.6.0. Otherwise, the affected catalogs fail to load.

  • Iceberg catalogs that use glue_v2. SEP 2026.6.0 does not accept iceberg.catalog.type=glue_v2. Change it to glue:

    iceberg.catalog.type=glue
    
  • Catalogs that use an S3 IAM role. In 2026.6.0, s3.iam-role requires s3.auth-type=IAM_ROLE. Without it, the catalog fails with the error s3.iam-role must be set when, and only when, s3.auth-type=IAM_ROLE. Add the authentication type:

    s3.auth-type=IAM_ROLE
    s3.iam-role=<role-arn>
    

System tag names. The upgrade renames the system tags source, clientTag, user, group, and role to system.request.source, system.request.clientTag, system.identity.user, system.identity.group, and system.identity.role. The upgrade also rewrites your routing rules and tagging rules. If a tagging rule produces a tag key that starts with system., the upgrade stops with an error that lists the rules by ID and name. Change those rules, and run the upgrade again. Also update the scripts that create rules through the API.

Scheduled materialized view refreshes. Control plane routes the scheduled refresh of a materialized view with your routing rules. A rule can match the source scheduled-mv-refresh. A refresh that no rule matches goes to the default cluster group, which can differ from the group adhoc that it used before. To send the refreshes to one cluster group, add a routing rule on system.request.source, or set background-work.materialized-view-refresh.routing-group.explicit-override. The property was named background-work.materialized-view-refresh.routing-group before.

Cluster groups. The upgrade creates a cluster group for each routing group that a cluster or a routing rule named, and the group adhoc.

A cluster that you save through the public API without a group no longer moves to adhoc. An update keeps the group, and a create uses the default cluster group.