Control Plane installation#

Note

The previous name of the Starburst Control Plane was Starburst Portal. At this writing, the Control Plane is delivered with the name portal in many locations, including the names of the tar.gz archives and in the Helm installation scripts. These are the correct names to use for the current SEP release.

The SEP LTS release due at the end of May, 2026 is expected to replace portal with control-plane in all artifacts.

Install and configure the Starburst Control Plane using one of the following methods:

Requirements#

Before you install Starburst Control Plane, make sure you have the following:

  • A valid SEP license

  • A supported backend database

  • For tar.gz installation: a Linux server with x86_64 or AArch64 architecture

  • For Helm installation: a Kubernetes cluster with kubectl and Helm

Backend database#

Starburst Control Plane requires a backend database for persistence. You must provision and configure the database before you start Starburst Control Plane. Use one of the following databases:

  • MySQL

  • PostgreSQL

  • Oracle

Create a dedicated database and user for Starburst Control Plane.

On startup, Starburst Control Plane automatically initializes your database and runs any required schema migrations.

For a list of available database configuration properties, see Backend database configuration.

Install with tar.gz archive#

Use the following steps to install Starburst Control Plane using 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 archive to the installation directory:

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

If it does not already exist, create a configuration directory name 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 Starburst Control Plane configuration file as /etc/starburst/config.properties. For example:

# Node configuration
node.environment=production

# HTTP server
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=your-secure-password

# Gateway configuration
gateway.enabled=true
gateway.clusters.enabled=true
gateway.clusters.encryption.secret=your-encryption-secret

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

# Define admin users with at least one of:
starburst.access-control.authorized-users=alice,bob
starburst.access-control.authorized-groups=portal-admins

# Define a shared secret for internal communication within Control Plane
internal-communication.shared-secret=<portal-secret>

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

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

Create 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 logging configuration at /etc/starburst/log.properties:

io.starburst=INFO
io.trino=INFO

For more information about each configuration file, see Configuration files.

Copy license file#

Copy your Starburst license file to the configuration directory:

sudo cp starburstdata.license /etc/starburst/

Start Starburst Control Plane#

To start Starburst Control Plane, use the following command:

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

To run Starburst 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 Starburst Control Plane on Kubernetes with Helm.

Configure Harbor registry access#

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

helm registry login "harbor.starburstdata.net" \
  --username "<your-registry-username>" \
  --password "<your-registry-password>"

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:

kubectl create secret docker-registry regcred \
  --docker-server="https://harbor.starburstdata.net" \
  --docker-username="<your-registry-username>" \
  --docker-password="<your-registry-password>"

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:

kubectl create secret generic portal-secret \
  --from-literal=DB_PASSWORD='your-secure-password' \
  --from-literal=CLUSTERS_ENCRYPTION_SECRET='your-encryption-secret'

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}

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

envFrom:
  - secretRef:
      name: portal-secret

Configure secrets providers#

Starburst Control Plane supports secrets providers that allow sensitive values to be resolved at runtime rather than stored as plain text in Helm values.

To activate a secrets provider, place a secrets.toml file in the /etc/starburst/ directory using the etcFiles.other map.

Once a secrets provider is configured, you can reference secrets in any Starburst Control Plane configuration property using the provider-specific syntax.

The following example reads secrets from environment variables:

etcFiles:
  other:
    secrets.toml: |
      [env]
      secrets-provider.name="env"
  config: |
    persistence.jdbc.password=${ENV:DB_PASSWORD}
    gateway.clusters.encryption.secret=${ENV:PORTAL_ENCRYPTION_SECRET}

The following example reads secrets from AWS Secrets Manager:

etcFiles:
  other:
    secrets.toml: |
      [asm]
      secrets-provider.name="asm"
      region="us-east-2"
  config: |
    persistence.jdbc.url=${ASM:myapp/db:url}
    persistence.jdbc.user=${ASM:myapp/db:username}
    persistence.jdbc.password=${ASM:myapp/db:password}

The following example reads secrets from multiple providers simultaneously:

etcFiles:
  other:
    secrets.toml: |
      [asm]
      secrets-provider.name="asm"
      region="us-east-2"
      [env]
      secrets-provider.name="env"

Deploy Starburst Control Plane#

To deploy Starburst 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 command:

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

Configuration#

Use the following sections to configure Starburst Control Plane.

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=password

# Gateway with cluster management
gateway.enabled=true
gateway.clusters.encryption.secret=secret-key

Backend database configuration#

Use the following properties to configure the backend database:

Backend database configuration properties#

Property

Description

Default

persistence.jdbc.url

JDBC connection URL for the Starburst Control Plane backend database. The URL must include the protocol, hostname, port, and database name. The supported formats are:

  • PostgreSQL: jdbc:postgresql://hostname:5432/database_name

  • MySQL: jdbc:mysql://hostname:3306/database_name

  • Oracle: jdbc:oracle:thin:@hostname:1521:database_name

None (required)

persistence.jdbc.user

Username for authenticating to the database. This user must have permissions to create and modify tables for schema migrations.

None (required)

persistence.jdbc.password

Password for the database user. For production deployments, use secrets substitution such as ${ENV:VAR_NAME}.

None (required)

persistence.retention.max-age

Duration to retain query history records. Starburst Control Plane automatically deletes older records. Use h for hours or d for days.

60d

persistence.jdbc.connection-pool.max-size

Maximum number of database connections in the connection pool. Increase this value based on your workload and database capacity.

10

Starburst Control Plane also supports Kerberos and AWS IAM authentication for the backend database.

Kerberos authentication#

To use Kerberos authentication with an Oracle database, set the following properties in your config.properties file:

persistence.jdbc.url=jdbc:oracle:thin:@oracle.example.com:1521/starburstenterprise
persistence.jdbc.authentication-type=KERBEROS
persistence.jdbc.kerberos.client.principal=example@STARBURSTDATA.COM
persistence.jdbc.kerberos.client.keytab=
persistence.jdbc.kerberos.config=/etc/kerberos/krb5.conf

AWS IAM authentication#

To use AWS IAM token-based authentication with a MySQL database, set the following properties in your config.properties file:

persistence.jdbc.url=jdbc:mysql://mysql.example.com:3306/starburstenterprise?sessionVariables=sql_mode=ANSI
persistence.jdbc.authentication-type=AWS_IAM
persistence.jdbc.connection-user=db_user
persistence.jdbc.aws.region-name=us-east-2
persistence.jdbc.aws.iam-role=${ENV:RDS_ROLE_ARN}
persistence.jdbc.aws.external-id=for_product_test
persistence.jdbc.aws.token-expiration-timeout=1s

Cluster configuration#

Use the following properties to configure how Starburst Control Plane manages and routes queries to clusters. Manage individual cluster configurations through the Starburst Control Plane UI.

Property

Description

Default

gateway.enabled

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

false

gateway.clusters.enabled

Enables UI-based cluster management. When you enable this property, Starburst Control Plane stores cluster configurations in the database.

true

gateway.clusters.encryption.secret

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

None (required)

gateway.clusters.monitoring.refresh-interval

Interval between health check requests to registered clusters. Lower values provide faster detection of cluster failures but increase network traffic.

30s

gateway.load-balancing.strategy

Algorithm that distributes queries across healthy clusters in a routing group. Choose between the following strategies:

  • RANDOM: Distribute queries randomly across healthy clusters

  • QUERY_COUNT_BASED: Route based on active query count

RANDOM

HTTPS configuration#

To enable HTTPS, add the following properties to your configuration file:

http-server.http.enabled=false
http-server.https.enabled=true
http-server.https.port=8443
http-server.https.keystore.path=/etc/starburst/keystore.jks
http-server.https.keystore.key=keystore-password

Health checks#

Use the following endpoints to monitor the health of your Starburst Control Plane instance:

  • Liveness: GET /status/livez

    • Returns 200 when the process is running

  • Readiness: GET /status/readyz

    • Returns 200 when Starburst Control Plane is ready to serve requests

Configuration files#

Use the following files to configure Starburst Control Plane for tar.gz installations:

File

Purpose

/etc/starburst/config.properties

Main configuration file for Starburst 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.