Kyuubi engine profiles

Lisa Vaysman

Overview

Kyuubi acts as a unified multi-engine SQL gateway: users connect to a single Kyuubi endpoint, while administrators can route sessions to different underlying engines (e.g. Spark3, Spark4, Flink, Trino, or JDBC) by using engine profiles.

Engine profile overview

An engine profile is an administrator-declared configuration bundle that groups an engine type, engine environment variables, Kyuubi session variables, and engine-native properties under a single profile name.

Profiles let administrators define engine-specific setups once in ADCM, instead of requiring users to pass parameters such as Spark versions, SPARK_HOME paths, or database connection settings in every connection string. Users only select a profile by name, and Kyuubi converts the resolved profile parameters into runtime settings for a specific engine.

Engine profiles are backward compatible with existing Kyuubi deployments in ADH clusters. If no profiles are declared or applied, Kyuubi sessions behave exactly as they did before, with no changes to engine launch or discovery mechanisms.

NOTE

Applied profiles affect engine discovery and isolation because the profile name is included in the engine subdomain name. For details, see Engine isolation and subdomains.

The example below declares a profile named spark4-prod. It instructs the Kyuubi service to:

  • allocate a Spark SQL engine;

  • use specific environment variables for Spark;

  • apply a session-level configuration;

  • pass native configurations to the Spark engine.

kyuubi.engine.profile.spark4-prod.type=SPARK_SQL
kyuubi.engine.profile.spark4-prod.env.SPARK_HOME=/usr/lib/spark4
kyuubi.engine.profile.spark4-prod.env.SPARK_CONF_DIR=/etc/spark4/conf
kyuubi.engine.profile.spark4-prod.session.engine.share.level=USER
kyuubi.engine.profile.spark4-prod.conf.spark.executor.memory=4g
kyuubi.engine.profile.spark4-prod.conf.spark.executor.cores=2

The example below shows the user request to allocate an engine with the spark4-prod profile:

jdbc:hive2://kyuubi:10009/default?kyuubi.engine.profile=spark4-prod

Profile blacklists overview

Administrators can restrict access to specific profiles for individual users or user groups. If a profile is blacklisted for a user or one of the user’s groups, Kyuubi prevents that user from running sessions with this profile.

For details, see Restrict profile usage.

Configure profile-related properties in ADCM

To add or edit profile-related properties in ADCM, perform the following steps:

  1. Open the Kyuubi service configuration as described in Configure services.

  2. Go to the Components tab and click the Kyuubi Server component.

  3. In the Configuration tab that opens, select the Engine profiles configuration section.

  4. Add profile-related properties using the Add property field.

  5. Save the configuration.

  6. Restart Kyuubi or Kyuubi Server using the Restart action.

You can configure the following profile-related properties in the Engine profiles configuration section:

NOTE

When the Spark3, Spark4, Flink, or Trino services are added to an ADH cluster, ADCM automatically creates the corresponding local engine profiles for Kyuubi. See details in Kyuubi UI overview. Kubernetes engine profiles are not created automatically and must be configured manually in ADCM.

Declare engine profiles

This section explains the structure of profile properties that you add in ADCM in the Engine profiles configuration section.

Profile properties are <key>:<value> pairs. All profile configuration keys begin with a common prefix:

kyuubi.engine.profile.<name>.<bucket>

where:

  • <name> is the profile identifier. It must not conflict with the bucket names listed in the table below;

  • <bucket> is a keyword that determines how Kyuubi interprets, routes, and applies the setting. Supported buckets are: type, env, session, and conf. The full key format depends on the selected bucket and is described in the table below.

Bucket Syntax Description and example

type

kyuubi.engine.profile.<name>.type

Engine type. For a profile named <name> (e.g. spark4-prod), specifies the engine type to allocate. At startup, Kyuubi validates this value. Example:

kyuubi.engine.profile.spark4-prod.type=SPARK_SQL

env

kyuubi.engine.profile.<name>.env.<VAR>

Engine environment variable. For a profile named <name>, exports the <VAR> environment variable directly to the engine process. Example:

kyuubi.engine.profile.spark4-prod.env.SPARK_HOME=/usr/lib/spark4

session

kyuubi.engine.profile.<name>.session.<rest>

Kyuubi session setting. For a profile named <name>, sets the <rest> Kyuubi session-level variable to a particular value. Example:

kyuubi.engine.profile.spark4-prod.session.engine.share.level=USER

conf

kyuubi.engine.profile.<name>.conf.<rest>

Native engine setting. For a profile named <name>, passes the <rest> engine-native configuration property directly to the engine. Example:

kyuubi.engine.profile.spark4-prod.conf.spark.executor.memory=4g

Keys in the kyuubi.engine.profile.<name>.* format describe a profile only on the Kyuubi Server side. Therefore, these keys themselves are not passed to engine subprocesses. Instead, Kyuubi parses the profile declaration, extracts values from the env, session, and conf buckets, and then converts them into runtime settings that are applied when the engine starts.

For example, a JDBC profile can contain connection settings, including a password:

kyuubi.engine.profile.pg.type=JDBC
kyuubi.engine.profile.pg.conf.kyuubi.engine.jdbc.type=postgresql
kyuubi.engine.profile.pg.conf.kyuubi.engine.jdbc.driver.class=org.postgresql.Driver
kyuubi.engine.profile.pg.conf.kyuubi.engine.jdbc.connection.url=jdbc:postgresql://postgres.example.com:5432/analytics
kyuubi.engine.profile.pg.conf.kyuubi.engine.jdbc.connection.user=analytics_reader
kyuubi.engine.profile.pg.conf.kyuubi.engine.jdbc.connection.password=<password>

In this example, kyuubi.engine.profile.pg.conf.kyuubi.engine.jdbc.connection.password becomes kyuubi.engine.jdbc.connection.password for the engine. The engine still receives the password, but it does not receive the full server-side profile declaration as raw kyuubi.engine.profile.pg.* properties.

The following examples demonstrate how to declare various engine profiles in ADCM:

Spark profiles

A sample profile for a local Spark3 installation that sets the default value for Spark executor memory:

kyuubi.engine.profile.spark3.type=SPARK_SQL
kyuubi.engine.profile.spark3.env.SPARK_HOME=/usr/lib/spark3
kyuubi.engine.profile.spark3.env.SPARK_CONF_DIR=/etc/spark3/conf
kyuubi.engine.profile.spark3.conf.spark.executor.memory=2g

A sample profile for a local Spark4 installation that sets the default value for Spark executor memory:

kyuubi.engine.profile.spark4.type=SPARK_SQL
kyuubi.engine.profile.spark4.env.SPARK_HOME=/usr/lib/spark4
kyuubi.engine.profile.spark4.env.SPARK_CONF_DIR=/etc/spark4/conf
kyuubi.engine.profile.spark4.conf.spark.executor.memory=2g

The following example configures a profile for running Spark4 engines on Kubernetes:

kyuubi.engine.profile.spark4-k8s.type=SPARK_SQL
kyuubi.engine.profile.spark4-k8s.conf.spark.master=k8s://https://<k8s-apiserver-host>:<k8s-apiserver-port>
kyuubi.engine.profile.spark4-k8s.conf.spark.kubernetes.container.image=<spark4-image>
kyuubi.engine.profile.spark4-k8s.conf.spark.kubernetes.namespace=<namespace>
kyuubi.engine.profile.spark4-k8s.conf.spark.executor.instances=2
kyuubi.engine.profile.spark4-k8s.conf.spark.executor.memory=1g

Clients can request this profile explicitly in the connection string:

jdbc:hive2://kyuubi:10009/default?kyuubi.engine.profile=spark4-k8s

Trino profile

A sample profile for routing queries to a specific Trino cluster:

kyuubi.engine.profile.trino-prod.type=TRINO
kyuubi.engine.profile.trino-prod.conf.kyuubi.engine.trino.connection.url=http://trino-coordinator.example.com:8080
kyuubi.engine.profile.trino-prod.conf.kyuubi.engine.trino.connection.catalog=system
kyuubi.engine.profile.trino-prod.conf.kyuubi.engine.trino.connection.user=analytics_reader
kyuubi.engine.profile.trino-prod.conf.kyuubi.engine.trino.connection.password=<password>

A sample profile for connecting to a Trino coordinator deployed in Kubernetes and exposed through an external IP address:

kyuubi.engine.profile.trino-k8s.type=TRINO
kyuubi.engine.profile.trino-k8s.conf.kyuubi.engine.trino.connection.url=jdbc:trino://<external-ip>:8080
kyuubi.engine.profile.trino-k8s.conf.kyuubi.engine.trino.connection.catalog=adh-iceberg

A sample profile configured to run Flink engine applications:

kyuubi.engine.profile.flink-test.type=FLINK_SQL
kyuubi.engine.profile.flink-test.conf.flink.execution.target=remote
kyuubi.engine.profile.flink-test.conf.flink.app.name=test_app
kyuubi.engine.profile.flink-test.conf.kyuubi.engine.flink.doAs.enabled=false

Assign default profiles

You can assign default profiles in ADCM:

  • to specific users or groups;

  • globally per engine type.

User and group default profiles

You can set default profiles for individual users or user groups. Kyuubi uses these default profiles when the session does not specify a profile explicitly.

___<user_name>___.kyuubi.engine.profile=<profile_name>
___<group_name>___.kyuubi.engine.profile=<profile_name>

Example:

___alice___.kyuubi.engine.profile=trino-prod
___analysts___.kyuubi.engine.profile=spark4-prod

Engine-type default profiles

You can set a default profile for an engine type. Kyuubi uses it when the session does not specify a profile and no user or group default profile matches:

kyuubi.engine.<TYPE>.profile.default=<profile_name>

where <TYPE> is a valid engine type, such as SPARK_SQL, TRINO, FLINK_SQL, or JDBC.

Example:

kyuubi.engine.SPARK_SQL.profile.default=spark3-prod

Restrict profile usage

You can configure blacklists in ADCM to deny selected profiles for individual users or user groups.

___<user_name>___.kyuubi.engine.profiles.blacklist=<profile1>,<profile2>
___<group_name>___.kyuubi.engine.profiles.blacklist=<profile1>,<profile2>

Blacklists follow these rules:

  • Restrictions for the session user and all the user’s groups are combined. A profile is denied if it appears in any matching blacklist.

  • If a user explicitly requests a blacklisted profile in a connection string using kyuubi.engine.profile=<profile_name>, Kyuubi rejects the session.

  • If a blacklisted profile is resolved implicitly (for example, through a user, group, or engine-type default profile), Kyuubi skips this profile and continues with the next lower-priority source. For details, see Profile resolution order.

Example:

___analysts___.kyuubi.engine.profiles.blacklist=spark4-prod,trino-k8s
___bob___.kyuubi.engine.profiles.blacklist=flink-test

How profiles are selected

Profile resolution order

When a new Kyuubi session opens, Kyuubi Server resolves at most one profile for it. Kyuubi evaluates the following sources in strict priority order and stops at the first source that returns a profile name:

  1. Explicit session parameter
    The client explicitly requests a profile by its name (for example, via kyuubi.engine.profile=<name> inside the JDBC connection string). If the requested profile is blacklisted for the user, the session fails immediately.

  2. User/group default profile
    If no explicit profile is requested, Kyuubi checks for a default profile suitable for the user or their group using the <principal>.kyuubi.engine.profile property. It evaluates the session user first, and then the user’s groups. If a resolved default profile is blacklisted for that user, Kyuubi skips it and moves to the next default profile with a lower priority.

  3. Engine-type default profile
    If no applicable user or group default profiles are found, Kyuubi looks for an engine-type default profile using the kyuubi.engine.<TYPE>.profile.default property, where <TYPE> is the resolved engine type for the session. If this profile is blacklisted for the current user, it is ignored and no profile is applied.

  4. No profile
    If none of the above sources provide a profile name, no profile is applied. The session behaves as it would in a Kyuubi deployment without engine profiles.

If the profile resolution algorithm returns a profile name that has not been declared, Kyuubi handles this case as described in the Unknown profile strategy section.

Effective session configuration

Any configuration parameter explicitly provided by the client in the connection string overrides the corresponding value defined inside the engine profile.

When Kyuubi compiles the final session configuration, it applies properties from lowest to highest priority:

  1. Base session configuration (Kyuubi Server default values and user/group default configuration values).

  2. Parameters defined by a resolved profile.

  3. Parameters explicitly requested by the client.

Engine isolation and subdomains

Engines launched under different profiles are isolated from each other: they never share the same engine instance or reuse runtime resources created for another profile. This rule applies even when sessions use the same share level of the engine, such as USER, GROUP, or SERVER.

For example, two sessions opened by the same user with different profiles start separate engine processes.

Without profiles, a subdomain is usually based only on the share level identifier, such as a username or a group name. With profiles enabled, Kyuubi builds the subdomain by joining the profile name and the original subdomain with an underscore: <profile>_<subdomain>. The following table shows an example.

Share level Subdomain without profile Subdomain with spark4 profile

USER

alice

spark4_alice

GROUP

analytics

spark4_analytics

If no profile is applied, the subdomain remains unchanged.

IMPORTANT

If a profile is applied, then client applications, CLI commands, and REST API requests that use an engine subdomain must use the <profile>_<subdomain> format.

For example, for engines started with the spark4 profile, an administrative operation that previously targeted the alice subdomain must target spark4_alice.

Validation and error handling

Fail-fast startup validation

Engine profiles are static configurations that Kyuubi Server reads only once during startup. Kyuubi validates them fail-fast: if any profile is malformed, the Kyuubi Server stops immediately at startup.

A profile declaration is rejected at startup in the following cases:

  • The value assigned to the type bucket is not a recognized Kyuubi engine type. Recognized types:

    • SPARK_SQL

    • FLINK_SQL

    • TRINO

    • JDBC

  • Profile declaration includes an unknown bucket type (anything other than type, env, session, or conf).

  • A bucket is declared in the wrong format (e.g. the type bucket has a subkey, or the env bucket is not followed by the variable name).

Unknown profile strategy

If profile resolution returns an undeclared profile name, Kyuubi handles it according to the kyuubi.engine.profiles.unknown.strategy property:

  • FAIL (default value) — aborts the connection attempt immediately and returns an error message listing all available profile names to the client.

  • LOG — logs a warning on the Kyuubi Server side and continues the session initialization without applying any profile.

View engine profiles

The Kyuubi web interface provides an engine profile view where you can:

  • view engines grouped by engine profile;

  • see idle profiles that have no running engine instances;

  • refresh the profile list;

  • kill running engines associated with a profile.

See details in Kyuubi UI overview.

The same profile information is available through the REST API endpoint:

$ curl -X GET http://<kyuubi_host>:<kyuubi_port>/api/v1/admin/engine/profile
Found a mistake? Seleсt text and press Ctrl+Enter to report it