Install and configure control plane#
Install and configure the Starburst control plane using one of the following methods:
tar.gzarchiveHelm
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 |
|
Managed mode |
|
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.gzfor x86_64 systemsUse
starburst-portal-<version>-aarch64.tar.gzfor 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 |
|---|---|
|
Main configuration file for control plane. Contains database connection, gateway configuration, authentication, and HTTP server settings. |
|
JSON file that contains credentials for AWS authentication when accessing the Glue API for catalog operations. |
|
JVM startup options including memory settings, garbage collection, and system properties. Specify one option per line. |
|
Logging level configuration for different packages. Controls verbosity of logs for troubleshooting and monitoring. |
|
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 |
|---|---|---|
|
Enables the gateway functionality and allows control plane to route queries to backend clusters. This property is required for cluster management features. |
|
|
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 |
|---|---|---|
|
Turns on Starburst access control and catalogs on control plane. It requires
|
|
|
Authenticates the requests that control plane sends to clusters with
tokens that control plane signs. It is required when
|
|
|
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
|
None (required) |
|
The secret that control plane uses to derive the signing key of its tokens. |
None |
|
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 |
|
How long a token is valid. |
|
|
How long a statement submission token is valid. It must not be longer
than |
|
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 accepticeberg.catalog.type=glue_v2. Change it toglue:iceberg.catalog.type=glue
Catalogs that use an S3 IAM role. In 2026.6.0,
s3.iam-rolerequiress3.auth-type=IAM_ROLE. Without it, the catalog fails with the errors3.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.