KnowForge/Apache Kyuubi 1.9.1 简体中文
管理指南

配置

qianmoQqianmoQ· 更新于 2026-09-29· 阅读 127 分钟· 0 次阅读
登录后可跨设备保存划线和私人笔记登录

配置

配置

Kyuubi 提供了多种方式来配置系统及其相应的引擎。

环境变量

你可以在 $KYUUBI_HOME/conf/kyuubi-env.sh 中配置环境变量，例如 JAVA_HOME，此时该 Java 运行时将同时用于 Kyuubi 服务实例以及它所启动的应用程序。你也可以修改子进程的环境配置文件，例如 $SPARK_HOME/conf/spark-env.sh，以便为 SQL 引擎应用程序使用更具体的环境变量。示例可参见 $KYUUBI_HOME/conf/kyuubi-env.sh.template。对于只需要传递到引擎侧的环境变量，你可以使用格式为 kyuubi.engineEnv.VAR_NAME 的 Kyuubi 配置项进行设置。例如，设置 kyuubi.engineEnv.SPARK_DRIVER_MEMORY=4g 后，值为 4g 的环境变量 SPARK_DRIVER_MEMORY 将被传递到引擎侧；设置 kyuubi.engineEnv.SPARK_CONF_DIR=/apache/confs/spark/conf 后，引擎侧的 SPARK_CONF_DIR 的值将被设置为 /apache/confs/spark/conf。

Kyuubi 配置

你可以在 $KYUUBI_HOME/conf/kyuubi-defaults.conf 中配置 Kyuubi 属性，示例可参见 $KYUUBI_HOME/conf/kyuubi-defaults.conf.template。

认证

Key Default Meaning Type Since

kyuubi.authentication NONE 以逗号分隔的客户端认证类型列表。

  • NOSASL：原始传输。
  • NONE：不进行认证检查。
  • KERBEROS：Kerberos/GSSAPI 认证。
  • CUSTOM：用户自定义认证。
  • JDBC：JDBC 查询认证。
  • LDAP：轻量级目录访问协议（LDAP）认证。

以下树形结构描述了各个选项的分类。

  • NOSASL

  • SASL

    • SASL/PLAIN

      • NONE
      • LDAP
      • JDBC
      • CUSTOM

    • SASL/GSSAPI

      • KERBEROS

注意：对于 SASL 认证，KERBEROS 和 PLAIN 认证类型可以同时启用，且只有第一个指定的 PLAIN 认证类型有效。seq 1.0.0

kyuubi.authentication.custom.class <undefined> 用户自定义的 org.apache.kyuubi.service.authentication.PasswdAuthenticationProvider 认证实现 string 1.3.0

kyuubi.authentication.jdbc.driver.class <undefined> JDBC 认证提供者的驱动类名 string 1.6.0

kyuubi.authentication.jdbc.password <undefined> JDBC 认证提供者使用的数据库密码 string 1.6.0

kyuubi.authentication.jdbc.query <undefined> 供 JDBC 认证提供者执行的带占位符的查询 SQL 模板。若结果集非空，则认证通过。SQL 语句必须以 SELECT 子句开头。可用的占位符为 ${user} 和 ${password}。 string 1.6.0

kyuubi.authentication.jdbc.url <undefined> JDBC 认证提供者使用的 JDBC URL string 1.6.0

kyuubi.authentication.jdbc.user <undefined> JDBC 认证提供者使用的数据库用户 string 1.6.0

kyuubi.authentication.ldap.baseDN <undefined> LDAP 基础 DN string 1.7.0

kyuubi.authentication.ldap.binddn <undefined> 用于绑定到 LDAP 服务器并搜索被认证用户完整域名的用户。该值应为用户的完整域名，并且需要在 LDAP 树中对所有用户具有搜索权限。如果未指定，则使用被认证的用户作为绑定用户。例如：CN=bindUser,CN=Users,DC=subdomain,DC=domain,DC=com string 1.7.0

kyuubi.authentication.ldap.bindpw <undefined> 绑定用户的密码，用于搜索被认证用户的完整名称。如果指定了用户名，则也必须指定此参数。string 1.7.0

kyuubi.authentication.ldap.customLDAPQuery <undefined> LDAP 认证提供者用于对 LDAP 服务器执行的完整 LDAP 查询语句。如果该查询返回空结果集，则 LDAP 提供者认证请求失败；如果用户属于该结果集，则认证成功。例如：(&(objectClass=group)(objectClass=top)(instanceType=4)(cn=Domain*))、(&(objectClass=person)(|(sAMAccountName=admin)(|(memberOf=CN=Domain Admins,CN=Users,DC=domain,DC=com)(memberOf=CN=Administrators,CN=Builtin,DC=domain,DC=com)))) string 1.7.0

kyuubi.authentication.ldap.domain <undefined> LDAP 域。string 1.0.0

kyuubi.authentication.ldap.groupClassKey groupOfNames 在 LDAP 组搜索中用于组条目的 LDAP 属性名称。例如：group、groupOfNames 或 groupOfUniqueNames。string 1.7.0

kyuubi.authentication.ldap.groupDNPattern <undefined> 以冒号分隔的模式列表，用于在该目录中查找组实体的 DN。使用 %s 作为实际组名的占位符。例如：CN=%s,CN=Groups,DC=subdomain,DC=domain,DC=com。string 1.7.0

kyuubi.authentication.ldap.groupFilter 以逗号分隔的 LDAP 组名列表（仅为短名称，而非完整 DN）。例如：HiveAdmins,HadoopAdmins,Administrators set 1.7.0

kyuubi.authentication.ldap.groupMembershipKey member 组对象上的 LDAP 属性名称，其中包含作为该组成员的用户、组和联系人对象的可分辨名称列表。例如：member、uniqueMember 或 memberUid string 1.7.0

kyuubi.authentication.ldap.guidKey uid 在该 LDAP 服务器上取值唯一的 LDAP 属性名称。例如：uid 或 CN。string 1.2.0

kyuubi.authentication.ldap.url <undefined> 以空格分隔的 LDAP 连接 URL。string 1.0.0

kyuubi.authentication.ldap.userDNPattern <undefined> 以冒号分隔的模式列表，用于在该目录中查找用户的 DN。使用 %s 作为实际组名的占位符。例如：CN=%s,CN=Users,DC=subdomain,DC=domain,DC=com。string 1.7.0

kyuubi.authentication.ldap.userFilter 以逗号分隔的 LDAP 用户名列表（仅为短名称，而非完整 DN）。例如：hiveuser,impalauser,hiveadmin,hadoopadmin set 1.7.0

kyuubi.authentication.ldap.userMembershipKey <undefined> 用户对象上包含该用户为直接成员（primaryGroupId 所代表的主组除外）的各个组的 LDAP 属性名。例如：memberOf string 1.7.0

kyuubi.authentication.sasl.qop auth Sasl QOP，为 Kyuubi 与客户端之间的通信提供更高级别的保护。

  • auth - 仅认证（默认）
  • auth-int - 认证加上完整性保护
  • auth-conf - 认证加上完整性和机密性保护。仅当 Kyuubi 配置为使用 Kerberos 认证时适用。

string 1.0.0

后端

Key Default Meaning Type Since

kyuubi.backend.engine.exec.pool.keepalive.time PT1M 在 SQL 引擎应用中，操作执行线程池的空闲异步线程在终止前等待新任务到达的时间（毫秒） duration 1.0.0

kyuubi.backend.engine.exec.pool.shutdown.timeout PT10S 在 SQL 引擎应用中，操作执行线程池终止的超时时间（毫秒） duration 1.0.0

kyuubi.backend.engine.exec.pool.size 100 SQL 引擎应用中操作执行线程池的线程数 int 1.0.0

kyuubi.backend.engine.exec.pool.wait.queue.size 100 SQL 引擎应用中操作执行线程池的等待队列大小 int 1.0.0

kyuubi.backend.server.event.json.log.path file:///tmp/kyuubi/events 内置 JSON 记录器输出服务端事件的位置 string 1.4.0

kyuubi.backend.server.event.kafka.close.timeout PT5S 等待服务端事件处理器的 Kafka 生产者关闭的时长。 duration 1.8.0

kyuubi.backend.server.event.kafka.topic <undefined> 内置 Kafka 记录器输出服务端事件的主题 string 1.8.0

kyuubi.backend.server.event.loggers 以逗号分隔的服务端历史记录器列表，会话、操作等事件将写入其中。

  • JSON：事件将写入 kyuubi.backend.server.event.json.log.path 指定的位置
  • KAFKA：事件将以 JSON 格式序列化并发送到 kyuubi.backend.server.event.kafka.topic 指定的主题。注意：Kafka 生产者的配置需要加上前缀：kyuubi.backend.server.event.kafka.。例如 kyuubi.backend.server.event.kafka.bootstrap.servers=127.0.0.1:9092
  • JDBC：待实现
  • CUSTOM：用户自定义的事件处理器。

注意：Kyuubi 支持通过 Java SPI 实现自定义事件处理器。要注册自定义事件处理器，用户需要实现一个 org.apache.kyuubi.events.handler.CustomEventHandlerProvider 的子类，并且该类具有一个无参构造函数。 seq 1.4.0

kyuubi.backend.server.exec.pool.keepalive.time PT1M 在 Kyuubi 服务端中，操作执行线程池的空闲异步线程在终止前等待新任务到达的时间（毫秒） duration 1.0.0

kyuubi.backend.server.exec.pool.shutdown.timeout PT10S 在 Kyuubi 服务端中，操作执行线程池终止的超时时间（毫秒） duration 1.0.0

kyuubi.backend.server.exec.pool.size 100 Kyuubi 服务器操作执行线程池中的线程数量 int 1.0.0

kyuubi.backend.server.exec.pool.wait.queue.size 100 Kyuubi 服务器操作执行线程池的等待队列大小 int 1.0.0

批处理

KeyDefaultMeaningTypeSince
kyuubi.batch.application.check.intervalPT5S检查批处理作业应用信息的时间间隔。duration1.6.0
kyuubi.batch.application.starvation.timeoutPT3M超过该阈值时，将警告批处理应用可能处于饥饿状态。duration1.7.0
kyuubi.batch.conf.ignore.list以逗号分隔的批处理配置忽略键列表。如果批处理配置中包含其中任何一个键，则在提交批处理作业时，该键及其对应的值将被静默移除。请注意，此规则是通过管理员定义的服务端保护机制，用于防止某些关键配置被篡改。您还可以通过前缀 kyuubi.batchConf.[batchType] 为批处理作业提交预定义一些配置。例如，可以使用键 kyuubi.batchConf.spark.spark.master 为 Spark 批处理作业预定义 spark.master。set1.6.0
kyuubi.batch.session.idle.timeoutPT6H批处理会话空闲超时时间，若在此时长内未被访问，会话将被关闭duration1.6.2

凭证

KeyDefaultMeaningTypeSince
kyuubi.credentials.check.intervalPT5M检查已缓存凭证对过期状态的时间间隔。duration1.6.0
kyuubi.credentials.hadoopfs.enabledtrue是否续期 Hadoop 文件系统委托令牌boolean1.4.0
kyuubi.credentials.hadoopfs.uris需要申请委托令牌的额外 Hadoop 文件系统 URI。承载 fs.defaultFS 的文件系统无需在此列出。seq1.4.0
kyuubi.credentials.hive.enabledtrue是否续期 Hive metastore 委托令牌boolean1.4.0
kyuubi.credentials.idle.timeoutPT6H不活跃用户的凭证将在配置的超时时间后过期duration1.6.0
kyuubi.credentials.renewal.intervalPT1HKyuubi 续期单个用户委托令牌的频率duration1.4.0
kyuubi.credentials.renewal.retry.waitPT1M获取新凭证失败后，重试前需要等待的时间。duration1.4.0
kyuubi.credentials.update.wait.timeoutPT1M等待凭证就绪的时间。duration1.5.0

Ctl

KeyDefault含义类型起始版本
kyuubi.ctl.batch.log.on.failure.timeoutPT10S批处理失败时，获取剩余批处理日志的超时时间。duration1.6.1
kyuubi.ctl.batch.log.query.intervalPT3S获取批处理日志的时间间隔。duration1.6.0
kyuubi.ctl.rest.auth.schemabasic认证方案。可选值有：basic、spnego。string1.6.0
kyuubi.ctl.rest.base.url<undefined>REST API 基础 URL，包含协议（http:// 或 https://）、主机名、端口号string1.6.0
kyuubi.ctl.rest.connect.timeoutPT30S与 kyuubi server 建立连接的超时时间[ms]。超时值为 0 表示无限等待。duration1.6.0
kyuubi.ctl.rest.request.attempt.waitPT3Sctl rest 请求两次尝试之间的等待时长。duration1.6.0
kyuubi.ctl.rest.request.max.attempts3ctl rest 请求的最大尝试次数。int1.6.0
kyuubi.ctl.rest.socket.timeoutPT2M连接建立后等待数据包的超时时间[ms]。超时值为 0 表示无限等待。duration1.6.0
kyuubi.ctl.rest.spnego.host<undefined>当认证方案为 spnego 时，需要配置 spnego host。string1.6.0

委托

键默认值说明类型引入版本
kyuubi.delegation.key.update.intervalPT24H尚未使用duration1.0.0
kyuubi.delegation.token.gc.intervalPT1H尚未使用duration1.0.0
kyuubi.delegation.token.max.lifetimePT168H尚未使用duration1.0.0
kyuubi.delegation.token.renew.intervalPT168H尚未使用duration1.0.0

Engine

键 默认值 说明 类型 引入版本

kyuubi.engine.chat.ernie.http.connect.timeout PT2M 与文心一言服务器建立连接的超时时间[毫秒]。超时值为 0 表示无限超时。duration 1.9.0

kyuubi.engine.chat.ernie.http.proxy <undefined> 文心一言引擎调用 API 时使用的 HTTP 代理地址，例如 http://127.0.0.1:1088 string 1.9.0

kyuubi.engine.chat.ernie.http.socket.timeout PT2M 与文心一言服务器建立连接后，等待数据包的超时时间[毫秒]。超时值为 0 表示无限超时。duration 1.9.0

kyuubi.engine.chat.ernie.model completions 文心一言所使用的模型 ID。可用模型包括 completions_pro、ernie_bot_8k、completions 和 eb-instant，详见模型概览。string 1.9.0

kyuubi.engine.chat.ernie.token <undefined> 访问文心一言开放 API 的令牌，可在 https://cloud.baidu.com/doc/WENXINWORKSHOP/s/Ilkkrb0i5 获取 string 1.9.0

kyuubi.engine.chat.extra.classpath <undefined> Chat 引擎的额外 classpath，用于配置 SDK 等的位置 string 1.8.0

kyuubi.engine.chat.gpt.apiKey <undefined> 访问 OpenAI 开放 API 的密钥，可在 https://platform.openai.com/account/api-keys 获取 string 1.8.0

kyuubi.engine.chat.gpt.http.connect.timeout PT2M 与 Chat GPT 服务器建立连接的超时时间[毫秒]。超时值为 0 表示无限超时。duration 1.8.0

kyuubi.engine.chat.gpt.http.proxy <undefined> Chat GPT 引擎调用 API 时使用的 HTTP 代理地址，例如 http://127.0.0.1:1087 string 1.8.0

kyuubi.engine.chat.gpt.http.socket.timeout PT2M 与 Chat GPT 服务器建立连接后，等待数据包的超时时间[毫秒]。超时值为 0 表示无限超时。duration 1.8.0

kyuubi.engine.chat.gpt.model gpt-3.5-turbo ChatGPT 所使用的模型 ID。可用模型参见 OpenAI 的模型概览。string 1.8.0

kyuubi.engine.chat.java.options <undefined> Chat 引擎的额外 Java 选项 string 1.8.0

kyuubi.engine.chat.memory 1g Chat 引擎的堆内存 string 1.8.0

kyuubi.engine.chat.provider ECHO Chat 引擎的提供者。可选值：

  • ECHO：仅返回一条欢迎消息。
  • GPT：即 ChatGPT，由 OpenAI 提供支持。
  • ERNIE：即文心一言，由百度提供支持。

string 1.8.0

kyuubi.engine.connection.url.use.hostname true（已弃用）为 true 时，引擎使用主机名向 ZooKeeper 注册。当 Spark 以集群模式运行在 K8s 上时，将其设为 false，以确保服务器能够连接到引擎 boolean 1.3.0

kyuubi.engine.deregister.exception.classes 以逗号分隔的异常类列表。如果抛出的任何异常的类与指定的类相匹配，引擎将自行注销。set 1.2.0

kyuubi.engine.deregister.exception.messages 以逗号分隔的异常消息列表。如果抛出的任何异常的消息或堆栈跟踪与指定的消息列表相匹配，引擎将自行注销。set 1.2.0

kyuubi.engine.deregister.exception.ttl PT30M 用于注销引擎的、在 kyuubi.engine.deregister.exception.classes 和 kyuubi.engine.deregister.exception.messages 中指定的异常模式的生存时间（TTL）。一旦在 TTL 内错误总数达到 kyuubi.engine.deregister.job.max.failures，引擎将自行注销并等待自我终止；否则，我们认为引擎已经从临时故障中恢复。duration 1.2.0

kyuubi.engine.deregister.job.max.failures 4 在注销引擎之前允许的作业失败次数。int 1.2.0

kyuubi.engine.doAs.enabled true 是否在启动引擎时启用用户模拟。启用后，对于支持用户模拟的引擎（例如 SPARK），会根据 kyuubi.engine.share.level 的设置使用不同的用户来启动引擎；否则将始终使用 Kyuubi Server 的用户来启动引擎。boolean 1.9.0

kyuubi.engine.event.json.log.path file:///tmp/kyuubi/events 内置 JSON 记录器输出所有引擎事件的位置。

  • 本地路径：以 'file://' 开头
  • HDFS 路径：以 'hdfs://' 开头

string 1.3.0

kyuubi.engine.event.loggers SPARK 以逗号分隔的引擎历史记录日志器列表，引擎/会话/操作等事件将写入其中。

  • SPARK：事件将被写入 Spark 监听器总线。
  • JSON：事件将被写入 kyuubi.engine.event.json.log.path 所指定的位置
  • JDBC：待实现
  • CUSTOM：用户自定义的事件处理器。

注意：Kyuubi 通过 Java SPI 支持自定义事件处理器。要注册自定义事件处理器，用户需要实现 org.apache.kyuubi.events.handler.CustomEventHandlerProvider 的一个具有无参构造函数的子类。seq 1.3.0

kyuubi.engine.flink.application.jars <undefined> 以逗号分隔的本地 jar 列表，这些 jar 将随作业一起分发到集群。例如 SQL UDF 的 jar。仅在 yarn application 模式下生效。string 1.8.0

kyuubi.engine.flink.extra.classpath <undefined> Flink SQL 引擎的额外 classpath，用于配置 Hadoop 客户端 jar 等的位置。仅在 yarn session 模式下生效。string 1.6.0

kyuubi.engine.flink.initialize.sql SHOW DATABASES Flink 引擎的初始化 SQL。若未配置则回退到 kyuubi.engine.initialize.sql。seq 1.8.1

kyuubi.engine.flink.java.options <undefined> Flink SQL 引擎的额外 Java 选项，仅在 yarn session 模式下生效。string 1.6.0

kyuubi.engine.flink.memory 1g Flink SQL 引擎的堆内存，仅在 yarn session 模式下生效。string 1.6.0

kyuubi.engine.hive.deploy.mode LOCAL 配置 hive 引擎的部署模式，取值可以是 'local'、'yarn'。在 local 模式下，引擎与 KyuubiServer 运行在相同节点上；在 YARN 模式下，引擎运行在 YARN 的 Application Master (AM) 容器中。string 1.9.0

kyuubi.engine.hive.event.loggers JSON 以逗号分隔的引擎历史日志记录器列表，用于接收引擎、会话、操作等事件。

  • JSON：事件将写入 kyuubi.engine.event.json.log.path 指定的位置
  • JDBC：待实现
  • CUSTOM：待实现。

seq 1.7.0

kyuubi.engine.hive.extra.classpath <undefined> Hive 查询引擎的额外 classpath，用于配置 hadoop 客户端 jar 包等的位置。string 1.6.0

kyuubi.engine.hive.java.options <undefined> Hive 查询引擎的额外 Java 选项。string 1.6.0

kyuubi.engine.hive.memory 1g Hive 查询引擎的堆内存。string 1.6.0

kyuubi.engine.initialize.sql SHOW DATABASES 以分号分隔的 SQL 语句列表，在新创建的引擎接收查询之前执行初始化。例如：使用 SHOW DATABASES 可以提前激活 HiveClient。由于 Beeline/JDBC 驱动的限制，该配置无法在 JDBC url 中使用。seq 1.2.0

kyuubi.engine.jdbc.connection.password <undefined> 用于连接服务器的密码。string 1.6.0

kyuubi.engine.jdbc.connection.propagateCredential false 是否使用会话的用户和密码连接数据库。boolean 1.8.0

kyuubi.engine.jdbc.connection.properties 用于连接服务器的额外属性。seq 1.6.0

kyuubi.engine.jdbc.connection.provider <undefined> Kyuubi Server 用于建立 JDBC URL 连接的 JDBC 连接提供者插件。配置值应为 org.apache.kyuubi.engine.jdbc.connection.JdbcConnectionProvider 的子类。Kyuubi 提供以下内置实现：

doris：用于建立 Doris 连接。

mysql：用于建立 MySQL 连接。

phoenix：用于建立 Phoenix 连接。

postgresql：用于建立 PostgreSQL 连接。

starrocks：用于建立 StarRocks 连接。

impala：用于建立 Impala 连接。

string 1.6.0

kyuubi.engine.jdbc.connection.url <undefined> 引擎将要连接的服务器 url。string 1.6.0

kyuubi.engine.jdbc.connection.user <undefined> 用于连接服务器的用户。string 1.6.0

kyuubi.engine.jdbc.driver.class <undefined> JDBC 引擎连接所使用的驱动类。string 1.6.0

kyuubi.engine.jdbc.extra.classpath <undefined> JDBC 查询引擎的额外 classpath，用于配置 JDBC 驱动等的位置。string 1.6.0

kyuubi.engine.jdbc.fetch.size 1000 JDBC 引擎的抓取大小 int 1.9.0

kyuubi.engine.jdbc.initialize.sql SELECT 1 在新建引擎中、执行查询之前用于初始化的以分号分隔的 SQL 语句列表。例如使用 SELECT 1 来提前激活 JDBCClient。seq 1.8.0

kyuubi.engine.jdbc.java.options <undefined> JDBC 查询引擎的额外 Java 选项 string 1.6.0

kyuubi.engine.jdbc.memory 1g JDBC 查询引擎的堆内存 string 1.6.0

kyuubi.engine.jdbc.session.initialize.sql 在新建引擎会话中、执行查询之前用于初始化的以分号分隔的 SQL 语句列表。seq 1.8.0

kyuubi.engine.jdbc.type <undefined> JDBC 类型的简称 string 1.6.0

kyuubi.engine.kubernetes.submit.timeout PT30S Kubernetes 应用的引擎提交超时时间 duration 1.7.2

kyuubi.engine.operation.convert.catalog.database.enabled true 设置为 true 时，引擎会将 Catalog 和 Schema 的 set/get 这些 JDBC 方法转换为不同引擎的实现 boolean 1.6.0

kyuubi.engine.operation.log.dir.root engine_operation_logs 引擎端查询操作日志的根目录。string 1.4.0

kyuubi.engine.pool.name engine-pool 引擎池的名称。string 1.5.0

kyuubi.engine.pool.selectPolicy RANDOM 从相应的引擎池中为会话选择引擎的策略。

  • RANDOM - 随机使用池中的引擎
  • POLLING - 轮询使用池中的引擎

string 1.7.0

kyuubi.engine.pool.size -1 引擎池的大小。注意：如果该值小于 1，则引擎池不会启用；否则，引擎池的实际大小为 min(this, kyuubi.engine.pool.size.threshold)。int 1.4.0

kyuubi.engine.pool.size.threshold 9 该参数作为服务端参数引入，用于控制引擎池的上限。int 1.4.0

kyuubi.engine.session.initialize.sql 在新建引擎会话中、执行查询之前用于初始化的以分号分隔的 SQL 语句列表。由于 Beeline/JDBC 驱动的限制，该配置无法在 JDBC url 中使用。seq 1.3.0

kyuubi.engine.share.level USER 引擎将按不同的级别进行共享，可配置的值有：

  • CONNECTION：引擎不会被共享，仅供当前客户端连接使用，且引擎由会话用户启动。
  • USER：引擎将由同一唯一用户名创建的所有会话共享，且引擎由会话用户启动。
  • GROUP：引擎将由属于同一主组名的所有用户创建的所有会话共享。引擎将以主组名作为有效用户名启动，因此这里的组名相当于一个特殊用户，该用户能够访问团队的计算资源/数据。它遵循 Hadoop GroupsMapping 将用户映射到主组。如果未找到主组，则回退到 USER 级别。
  • SERVER：引擎将由 Kyuubi 服务器共享，且引擎以服务器的用户身份启动。

另请参阅 kyuubi.engine.share.level.subdomain 和 kyuubi.engine.doAs.enabled。string 1.2.0

kyuubi.engine.share.level.sub.domain <undefined> （已废弃）- 请改用 kyuubi.engine.share.level.subdomain。string 1.2.0

kyuubi.engine.share.level.subdomain <undefined> 允许最终用户为引擎的共享级别创建一个子域。子域是不区分大小写的字符串值，必须是合法的 ZooKeeper 子路径。例如，对于 USER 共享级别，最终用户可以在某个子域内共享特定引擎，而不是与其所有客户端共享。最终用户可以自由地在 USER 共享级别下创建多个引擎。当禁用引擎池时，若未配置则使用 'default'。string 1.4.0

kyuubi.engine.single.spark.session false 设置为 true 时，该引擎以单会话模式运行。所有 JDBC/ODBC 连接共享临时视图、函数注册、SQL 配置和当前数据库。boolean 1.3.0

kyuubi.engine.spark.event.loggers SPARK 以逗号分隔的引擎日志记录器列表，用于输出引擎/会话/操作等事件。

  • SPARK：事件将写入 Spark 监听器总线。
  • JSON：事件将写入 kyuubi.engine.event.json.log.path 指定的位置
  • JDBC：待实现
  • CUSTOM：待实现。

seq 1.7.0

kyuubi.engine.spark.initialize.sql SHOW DATABASES Spark 引擎的初始化 SQL。会回退到 kyuubi.engine.initialize.sql。seq 1.8.1

kyuubi.engine.spark.output.mode AUTO Spark 引擎的输出模式：

  • AUTO：对于 PySpark，从 python 响应中提取的 text/plain 作为输出。
  • NOTEBOOK：对于 PySpark，python 的原始响应作为输出。

string 1.9.0

kyuubi.engine.spark.python.env.archive <undefined> 用于 Spark 引擎 Python 语言模式的可移植 Python 环境归档包。string 1.7.0

kyuubi.engine.spark.python.env.archive.exec.path bin/python Python 环境归档包中的 Python 可执行文件路径。string 1.7.0

kyuubi.engine.spark.python.home.archive <undefined> 包含 $SPARK_HOME/python 目录的 Spark 归档包，用于在 Python 语言模式下初始化会话 Python worker。string 1.7.0

| kyuubi.engine.submit.timeout | PT30S | 提交后容忍 Driver Pod 短暂不可见的时间周期。在某些资源管理器（例如 K8s）中，spark-submit 返回后 Driver Pod 并不会立即可见。 | duration | 1.7.1 |
| kyuubi.engine.trino.connection.keystore.password | <undefined> | 用于连接 Trino 集群的密钥库密码 | string | 1.8.0 |
| kyuubi.engine.trino.connection.keystore.path | <undefined> | 用于连接 Trino 集群的密钥库路径 | string | 1.8.0 |
| kyuubi.engine.trino.connection.keystore.type | <undefined> | 用于连接 Trino 集群的密钥库类型 | string | 1.8.0 |
| kyuubi.engine.trino.connection.password | <undefined> | 用于连接 Trino 集群的密码 | string | 1.8.0 |
| kyuubi.engine.trino.connection.truststore.password | <undefined> | 用于连接 Trino 集群的信任库密码 | string | 1.8.0 |
| kyuubi.engine.trino.connection.truststore.path | <undefined> | 用于连接 Trino 集群的信任库路径 | string | 1.8.0 |
| kyuubi.engine.trino.connection.truststore.type | <undefined> | 用于连接 Trino 集群的信任库类型 | string | 1.8.0 |
| kyuubi.engine.trino.connection.user | <undefined> | 用于连接 Trino 集群的用户 | string | 1.9.0 |
| kyuubi.engine.trino.event.loggers | JSON | 由逗号分隔的引擎历史日志记录器列表，引擎、会话、操作等事件将发送到这些记录器。- JSON：事件将被写入 kyuubi.engine.event.json.log.path 所指定的位置- JDBC：待实现- CUSTOM：待实现。 | seq | 1.7.0 |
| kyuubi.engine.trino.extra.classpath | <undefined> | Trino 查询引擎的额外类路径，用于配置 Trino 引擎可能需要的其他依赖库 | string | 1.6.0 |
| kyuubi.engine.trino.java.options | <undefined> | Trino 查询引擎的额外 Java 选项 | string | 1.6.0 |
| kyuubi.engine.trino.memory | 1g | Trino 查询引擎的堆内存 | string | 1.6.0 |
| kyuubi.engine.type | SPARK_SQL | 指定 Kyuubi 支持的具体引擎。该配置与 SESSION 作用域绑定。此配置为实验性配置。目前可用的配置有：- SPARK_SQL：指定此引擎类型将启动 Spark 引擎，它可以提供 Apache Spark 的全部能力。注意，这是默认的引擎类型。- FLINK_SQL：指定此引擎类型将启动 Flink 引擎，它可以提供 Apache Flink 的全部能力。- TRINO：指定此引擎类型将启动 Trino 引擎，它可以提供 Trino 的全部能力。- HIVE_SQL：指定此引擎类型将启动 Hive 引擎，它可以提供 Hive Server2 的全部能力。- JDBC：指定此引擎类型将启动 JDBC 引擎，它可以通过特定的 JDBC 驱动将查询转发到数据库系统，目前支持 Doris、MySQL、Phoenix、PostgreSQL、StarRocks 和 Impala。- CHAT：指定此引擎类型将启动 Chat 引擎。 | string | 1.4.0 |

kyuubi.engine.ui.retainedSessions 200 Kyuubi 查询引擎 Web UI 中保留的 SQL 客户端会话数量。 int 1.4.0

kyuubi.engine.ui.retainedStatements 200 Kyuubi 查询引擎 Web UI 中保留的语句数量。 int 1.4.0

kyuubi.engine.ui.stop.enabled true 设置为 true 时，允许从 Spark Web UI 中终止 Kyuubi 引擎。 boolean 1.3.0

kyuubi.engine.user.isolated.spark.session true 设置为 false 时，如果引擎运行在 group 或 server 共享级别，则所有 JDBC/ODBC 连接都会按用户进行隔离，包括临时视图、函数注册、SQL 配置以及当前数据库。注意，当共享级别为 connection 或 user 时，该设置不会产生影响。 boolean 1.6.0

kyuubi.engine.user.isolated.spark.session.idle.interval PT1M 检查用户隔离的 Spark 会话是否超时的时间间隔。 duration 1.6.0

kyuubi.engine.user.isolated.spark.session.idle.timeout PT6H 当 kyuubi.engine.user.isolated.spark.session 为 false 时，如果对应的用户在此配置的超时时间后处于非活动状态，我们将释放该 Spark 会话。 duration 1.6.0

kyuubi.engine.yarn.app.name <undefined> 引擎部署模式为 YARN 时的 YARN 应用名称。 string 1.9.0

kyuubi.engine.yarn.cores 1 引擎部署模式为 YARN 时，Kyuubi 引擎容器的核数。 int 1.9.0

kyuubi.engine.yarn.java.options <undefined> 引擎部署模式为 YARN 时，AM（ApplicationMaster）的额外 Java 选项。 string 1.9.0

kyuubi.engine.yarn.memory 1024 引擎部署模式为 YARN 时，Kyuubi 引擎容器的内存，单位为 MB。 int 1.9.0

kyuubi.engine.yarn.priority <undefined> 引擎部署模式为 YARN 时，Kyuubi 引擎在 YARN 中的优先级。 int 1.9.0

kyuubi.engine.yarn.queue default 引擎部署模式为 YARN 时，Kyuubi 引擎在 YARN 中使用的队列。 string 1.9.0

kyuubi.engine.yarn.stagingDir <undefined> 提交 Kyuubi 引擎到 YARN 时使用的暂存目录，应为 HDFS 上的绝对路径。 string 1.9.0

kyuubi.engine.yarn.submit.timeout PT30S YARN 应用的引擎提交超时时间。 duration 1.7.2

kyuubi.engine.yarn.tags <undefined> 引擎部署模式为 YARN 时，Kyuubi 引擎在 YARN 中的标签。 seq 1.9.0

事件

键默认值含义类型起始版本
kyuubi.event.async.pool.keepalive.timePT1M异步事件处理器线程池中空闲异步线程在终止前等待新任务到达的时间（毫秒）duration1.7.0
kyuubi.event.async.pool.size8异步事件处理器线程池的线程数量int1.7.0
kyuubi.event.async.pool.wait.queue.size100异步事件处理器线程池的等待队列大小int1.7.0

前端服务

键 默认值 含义 类型 起始版本

kyuubi.frontend.advertised.host <undefined> 要向外部系统（例如服务发现集群和元数据存储）发布的 Kyuubi 服务器前端服务的主机名或 IP。当你希望公布与绑定主机不同的主机名或 IP 时使用该项。string 1.8.0

kyuubi.frontend.bind.host <undefined> 运行前端服务的机器的主机名或 IP。string 1.0.0

kyuubi.frontend.bind.port 10009 (deprecated) 运行通过二进制协议提供 thrift 前端服务的机器的端口。int 1.0.0

kyuubi.frontend.connection.url.use.hostname true 为 true 时，前端服务优先使用主机名，否则使用 IP 地址。注意，当引擎运行在 Kubernetes 上时，默认值会被设置为 false，以避免潜在的网络问题。boolean 1.5.0

kyuubi.frontend.max.message.size 104857600 (deprecated) Kyuubi 服务器将接受的最大消息大小（字节）。int 1.0.0

kyuubi.frontend.max.worker.threads 999 (deprecated) thrift 前端服务的前端工作线程池的最大线程数 int 1.0.0

kyuubi.frontend.min.worker.threads 9 (deprecated) thrift 前端服务的前端工作线程池的最小线程数 int 1.0.0

kyuubi.frontend.mysql.bind.host <undefined> 运行 MySQL 前端服务的机器的主机名或 IP。string 1.4.0

kyuubi.frontend.mysql.bind.port 3309 运行 MySQL 前端服务的机器的端口。int 1.4.0

kyuubi.frontend.mysql.max.worker.threads 999 MySQL 前端服务的命令执行线程池的最大线程数 int 1.4.0

kyuubi.frontend.mysql.min.worker.threads 9 MySQL 前端服务的命令执行线程池的最小线程数 int 1.4.0

kyuubi.frontend.mysql.netty.worker.threads <undefined> MySQL 前端服务 netty worker 事件循环中的线程数量。默认使用 min(cpu_cores, 8)。int 1.4.0

kyuubi.frontend.mysql.worker.keepalive.time PT1M 在 MySQL 前端服务中，命令执行线程池里的空闲异步线程在终止前等待新任务到达的时间（毫秒）。duration 1.4.0

kyuubi.frontend.protocols THRIFT_BINARY,REST 以逗号分隔的所有前端协议列表

  • THRIFT_BINARY - 与 HiveServer2 兼容的 thrift 二进制协议。
  • THRIFT_HTTP - 与 HiveServer2 兼容的 thrift http 协议。
  • REST - Kyuubi 定义的 REST API（实验性）。
  • MYSQL - 与 MySQL 兼容的文本协议（实验性）。
  • TRINO - 与 Trino 兼容的 http 协议（实验性）。

seq 1.4.0

kyuubi.frontend.proxy.http.client.ip.header X-Real-IP 用于记录真实客户端 IP 地址的 HTTP 头。如果你的服务器位于负载均衡器或其他代理之后，服务器会将该负载均衡器或代理的 IP 地址视为客户端 IP 地址。为了解决这一常见问题，大多数负载均衡器或代理都支持将真实的远程 IP 地址记录在 HTTP 头中，该头会随请求一同发送，供其他设备使用。注意，由于该头的值可以被指定为任意 IP 地址，因此不会将其用于身份认证。string 1.6.0

kyuubi.frontend.rest.bind.host <undefined> 运行 REST 前端服务的机器的主机名或 IP 地址。string 1.4.0

kyuubi.frontend.rest.bind.port 10099 运行 REST 前端服务的机器的端口号。int 1.4.0

kyuubi.frontend.rest.jetty.stopTimeout PT5S RESTful 前端服务所使用的 Jetty 服务器的停止超时时间。duration 1.8.1

kyuubi.frontend.rest.max.worker.threads 999 rest 前端服务的前端工作线程池中的最大线程数 int 1.6.2

kyuubi.frontend.ssl.keystore.algorithm <undefined> SSL 证书密钥库算法。string 1.7.0

kyuubi.frontend.ssl.keystore.password <undefined> SSL 证书密钥库密码。string 1.7.0

kyuubi.frontend.ssl.keystore.path <undefined> SSL 证书密钥库位置。string 1.7.0

kyuubi.frontend.ssl.keystore.type <undefined> SSL 证书密钥库类型。string 1.7.0

kyuubi.frontend.thrift.binary.bind.host <undefined> 运行通过二进制协议提供 thrift 前端服务的机器的主机名或 IP 地址。string 1.4.0

kyuubi.frontend.thrift.binary.bind.port 10009 运行通过二进制协议提供 thrift 前端服务的机器的端口号。int 1.4.0

kyuubi.frontend.thrift.binary.ssl.disallowed.protocols SSLv2,SSLv3 Kyuubi thrift 二进制前端禁止使用的 SSL 版本。set 1.7.0

kyuubi.frontend.thrift.binary.ssl.enabled false 将其设置为 true 可在 thrift 二进制前端服务器中使用 SSL 加密。boolean 1.7.0

kyuubi.frontend.thrift.binary.ssl.include.ciphersuites 以逗号分隔的 SSL 密码套件名称列表，用于 thrift 二进制前端。 seq 1.7.0

kyuubi.frontend.thrift.http.bind.host <undefined> 运行通过 HTTP 协议提供服务的 thrift 前端服务所在机器的主机名或 IP 地址。 string 1.6.0

kyuubi.frontend.thrift.http.bind.port 10010 运行通过 HTTP 协议提供服务的 thrift 前端服务所在机器的端口号。 int 1.6.0

kyuubi.frontend.thrift.http.compression.enabled true 通过 Jetty 的压缩支持启用 thrift HTTP 压缩。 boolean 1.6.0

kyuubi.frontend.thrift.http.cookie.auth.enabled true 设置为 true 时，Kyuubi 在 HTTP 传输模式下将使用基于 cookie 的认证机制。 boolean 1.6.0

kyuubi.frontend.thrift.http.cookie.domain <undefined> Kyuubi 生成的 cookie 所属的域名。 string 1.6.0

kyuubi.frontend.thrift.http.cookie.is.httponly true Kyuubi 生成的 cookie 的 HttpOnly 属性。 boolean 1.6.0

kyuubi.frontend.thrift.http.cookie.max.age 86400 Kyuubi 在 HTTP 模式下使用的服务器端 cookie 的最大生存时间（秒）。 int 1.6.0

kyuubi.frontend.thrift.http.cookie.path <undefined> Kyuubi 生成的 cookie 的路径。 string 1.6.0

kyuubi.frontend.thrift.http.max.idle.time PT30M HTTP 模式下服务器端连接的最大空闲时间。 duration 1.6.0

kyuubi.frontend.thrift.http.path cliservice HTTP 模式下 URL 端点的路径部分。 string 1.6.0

kyuubi.frontend.thrift.http.request.header.size 6144 使用 HTTP 传输模式时，请求头的大小（字节），使用 Jetty 默认值。 int 1.6.0

kyuubi.frontend.thrift.http.response.header.size 6144 使用 HTTP 传输模式时，响应头的大小（字节），使用 Jetty 默认值。 int 1.6.0

kyuubi.frontend.thrift.http.ssl.exclude.ciphersuites 以逗号分隔的 SSL 密码套件名称排除列表，用于 thrift HTTP 前端。 seq 1.7.0

kyuubi.frontend.thrift.http.ssl.keystore.password <undefined> SSL 证书密钥库密码。 string 1.6.0

kyuubi.frontend.thrift.http.ssl.keystore.path <undefined> SSL 证书密钥库位置。 string 1.6.0

kyuubi.frontend.thrift.http.ssl.protocol.blacklist SSLv2,SSLv3 使用 HTTP 传输模式时需要禁用的 SSL 版本。 seq 1.6.0

kyuubi.frontend.thrift.http.use.SSL false 将其设置为 true 可在 HTTP 模式下使用 SSL 加密。 boolean 1.6.0

kyuubi.frontend.thrift.http.xsrf.filter.enabled false 启用后，如果请求中不存在 X-XSRF-HEADER 请求头，Kyuubi 将阻止所有通过 HTTP 发送给它的请求。 boolean 1.6.0

kyuubi.frontend.thrift.max.message.size 104857600 Kyuubi 服务器可接受的最大消息大小（字节）。 int 1.4.0

kyuubi.frontend.thrift.max.worker.threads 999 thrift 前端服务的前端工作线程池中的最大线程数。 int 1.4.0

kyuubi.frontend.thrift.min.worker.threads 9 thrift 前端服务的前端工作线程池中的最小线程数。 int 1.4.0

kyuubi.frontend.thrift.worker.keepalive.time PT1M 空闲工作线程的保活时间（以毫秒为单位） duration 1.4.0

kyuubi.frontend.trino.bind.host <undefined> 运行 TRINO 前端服务的机器的主机名或 IP。string 1.7.0

kyuubi.frontend.trino.bind.port 10999 运行 TRINO 前端服务的机器的端口。int 1.7.0

kyuubi.frontend.trino.jetty.stopTimeout PT5S Trino 前端服务所使用的 Jetty 服务器的停止超时。duration 1.8.1

kyuubi.frontend.trino.max.worker.threads 999 Trino 前端服务的前端工作线程池的最大线程数 int 1.7.0

kyuubi.frontend.worker.keepalive.time PT1M (已弃用) 空闲工作线程的保活时间（以毫秒为单位） duration 1.0.0

Ha

Key Default Meaning Type Since

kyuubi.ha.addresses 用于服务发现的 ensemble 连接字符串 string 1.6.0

kyuubi.ha.client.class org.apache.kyuubi.ha.client.zookeeper.ZookeeperDiscoveryClient 服务发现客户端的类名。

  • Zookeeper：org.apache.kyuubi.ha.client.zookeeper.ZookeeperDiscoveryClient
  • Etcd：org.apache.kyuubi.ha.client.etcd.EtcdDiscoveryClient

string 1.6.0

kyuubi.ha.etcd.lease.timeout PT10S etcd 保活租约的超时时间。最长经过该秒数后，Kyuubi 服务器将得知引擎的意外丢失。duration 1.6.0

kyuubi.ha.etcd.ssl.ca.path <undefined> etcd CA 证书文件的存放位置。string 1.6.0

kyuubi.ha.etcd.ssl.client.certificate.path <undefined> etcd SSL 证书文件的存放位置。string 1.6.0

kyuubi.ha.etcd.ssl.client.key.path <undefined> etcd SSL 密钥文件的存放位置。string 1.6.0

kyuubi.ha.etcd.ssl.enabled false 设置为 true 时，将构建一个受 SSL 保护的 etcd 客户端。boolean 1.6.0

kyuubi.ha.namespace kyuubi 服务用于部署其实例 URI 的根目录 string 1.6.0

kyuubi.ha.zookeeper.acl.enabled false (已弃用) 如果 ZooKeeper 集群启用了 Kerberos，则设置为 true boolean 1.0.0

kyuubi.ha.zookeeper.auth.digest <undefined> 用于 ZooKeeper 认证的 digest 认证字符串，例如：username:password。string 1.3.2

kyuubi.ha.zookeeper.auth.keytab <undefined> 用于 ZooKeeper 认证的 Kyuubi 服务器 keytab 文件位置。string 1.3.2

kyuubi.ha.zookeeper.auth.principal <undefined> 用于 ZooKeeper 认证的 Kerberos 主体名称。string 1.3.2

kyuubi.ha.zookeeper.auth.serverPrincipal <undefined> ZooKeeper 服务器的 Kerberos 主体名称。仅当 Zookeeper 客户端版本不低于 3.5.7 或 3.6.0，或已应用 ZOOKEEPER-1467 时才生效。要使用 Zookeeper 3.6 客户端，请使用 -Pzookeeper-3.6 编译 Kyuubi。string 1.8.0

kyuubi.ha.zookeeper.auth.type NONE ZooKeeper 认证的类型，所有可选值为

  • NONE
  • KERBEROS
  • DIGEST

string 1.3.2

kyuubi.ha.zookeeper.connection.base.retry.wait 1000 重试连接 ZooKeeper 集群时两次尝试之间的初始等待时间 int 1.0.0

kyuubi.ha.zookeeper.connection.max.retries 3 连接 ZooKeeper 集群的最大重试次数 int 1.0.0

kyuubi.ha.zookeeper.connection.max.retry.wait 30000 使用 BOUNDED_EXPONENTIAL_BACKOFF 策略时，两次重试之间允许等待的最大时间；使用 UNTIL_ELAPSED 策略时，连接 ZooKeeper 集群之前允许经过的最大时间 int 1.0.0

kyuubi.ha.zookeeper.connection.retry.policy EXPONENTIAL_BACKOFF 连接 ZooKeeper 集群所使用的重试策略，所有可选值为：

  • ONE_TIME
  • N_TIME
  • EXPONENTIAL_BACKOFF
  • BOUNDED_EXPONENTIAL_BACKOFF
  • UNTIL_ELAPSED

string 1.0.0

kyuubi.ha.zookeeper.connection.timeout 15000 创建到 ZooKeeper 集群连接的超时时间（毫秒） int 1.0.0

kyuubi.ha.zookeeper.engine.auth.type NONE 引擎所使用的 ZooKeeper 认证类型，所有可选值为

  • NONE
  • KERBEROS
  • DIGEST

string 1.3.2

kyuubi.ha.zookeeper.namespace kyuubi （已废弃）服务发布其实例 URI 的根目录 string 1.0.0

kyuubi.ha.zookeeper.node.creation.timeout PT2M 创建 ZooKeeper 节点的超时时间 duration 1.2.0

kyuubi.ha.zookeeper.publish.configs false 设置为 true 时，将 Kerberos 配置发布到 ZooKeeper。注意：Hive 驱动需要高于 1.3 或 2.0，或者应用 HIVE-11581 补丁。boolean 1.4.0

kyuubi.ha.zookeeper.quorum （已废弃）ZooKeeper 集群的连接字符串 string 1.0.0

kyuubi.ha.zookeeper.session.timeout 60000 已连接会话进入空闲状态的超时时间（毫秒） int 1.0.0

Kinit

键默认值含义类型引入版本
kyuubi.kinit.intervalPT1HKyuubi 服务器执行 kinit -kt [keytab] [principal] 以刷新本地 Kerberos 凭据缓存的频率duration1.0.0
kyuubi.kinit.keytab<undefined>Kyuubi 服务器 keytab 的存放位置。string1.0.0
kyuubi.kinit.max.attempts10kinit 进程的重试次数int1.0.0
kyuubi.kinit.principal<undefined>Kerberos principal 的名称。string1.0.0

Kubernetes

配置项默认值含义类型引入版本
kyuubi.kubernetes.application.state.containerspark-kubernetes-driver用于获取应用程序状态的容器名称。string1.8.1
kyuubi.kubernetes.application.state.sourcePOD用于获取应用程序状态的来源。可选值为 pod 和 container。如果来源为 container，且 Pod 中存在名称与 kyuubi.kubernetes.application.state.container 相同的容器，则应用程序状态将取自该匹配容器的状态；否则，应用程序状态将取自 Pod 的状态。string1.8.1
kyuubi.kubernetes.authenticate.caCertFile<undefined>Kyuubi 通过 TLS 连接 Kubernetes API Server 时所使用的 CA 证书文件路径。请指定为文件路径而非 URI（即不要提供 scheme）string1.7.0
kyuubi.kubernetes.authenticate.clientCertFile<undefined>Kyuubi 通过 TLS 连接 Kubernetes API Server 时所使用的客户端证书文件路径。请指定为文件路径而非 URI（即不要提供 scheme）string1.7.0
kyuubi.kubernetes.authenticate.clientKeyFile<undefined>Kyuubi 通过 TLS 连接 Kubernetes API Server 时所使用的客户端密钥文件路径。请指定为文件路径而非 URI（即不要提供 scheme）string1.7.0
kyuubi.kubernetes.authenticate.oauthToken<undefined>向 Kubernetes API Server 进行身份验证时使用的 OAuth 令牌。请注意，与其他认证选项不同，此处必须填写用于认证的令牌的确切字符串值。string1.7.0
kyuubi.kubernetes.authenticate.oauthTokenFile<undefined>包含向 Kubernetes API Server 进行身份验证时所用 OAuth 令牌的文件路径。请指定为文件路径而非 URI（即不要提供 scheme）string1.7.0
kyuubi.kubernetes.context<undefined>从 Kubernetes 配置文件中选取的所需上下文，用于配置与集群交互的 K8s 客户端。string1.6.0
kyuubi.kubernetes.context.allow.list允许使用的 Kubernetes 上下文列表，如果为空，则不限制 Kubernetes 上下文。set1.8.0
kyuubi.kubernetes.master.address<undefined>Kyuubi 所使用的 Kubernetes 内部 Master（API Server）地址。string1.7.0
kyuubi.kubernetes.namespacedefault用于运行 Kyuubi Pod 和查找引擎的命名空间。string1.7.0
kyuubi.kubernetes.namespace.allow.list允许使用的 Kubernetes 命名空间列表，如果为空，则不限制 Kubernetes 命名空间。set1.8.0
kyuubi.kubernetes.spark.cleanupTerminatedDriverPod.checkIntervalPT1MKyuubi 服务端使用基于时间淘汰的 Guava 缓存作为清理触发器，但在发生任何 get/put 操作之前不会执行淘汰。该配置项会调度一个守护线程定期执行缓存淘汰。duration1.8.1
kyuubi.kubernetes.spark.cleanupTerminatedDriverPod.kindNONEKyuubi 服务端会在应用程序终止并经过 kyuubi.kubernetes.terminatedApplicationRetainPeriod 后删除 Spark Driver Pod。可选值为 NONE、ALL、COMPLETED，默认值为 NONE，表示不会删除任何 Pod。string1.8.1
kyuubi.kubernetes.spark.forciblyRewriteDriverPodName.enabledfalse是否强制将 Spark Driver Pod 名称重写为 'kyuubi--driver'。如果禁用，Kyuubi 会在满足 K8s Pod 命名策略的同时尽量保留应用程序名称，但部分厂商可能有更严格的 Pod 命名策略，从而导致生成的名称不合法。boolean1.8.1
kyuubi.kubernetes.spark.forciblyRewriteExecutorPodNamePrefix.enabledfalse是否强制将 Spark Executor Pod 名称前缀重写为 'kyuubi-'。如果禁用，Kyuubi 会在满足 K8s Pod 命名策略的同时尽量保留应用程序名称，但部分厂商可能有更严格的 Pod 命名策略，从而导致生成的名称不合法。boolean1.8.1
kyuubi.kubernetes.terminatedApplicationRetainPeriodPT5M应用程序终止后，Kyuubi 服务端保留其应用程序信息的时长。duration1.7.1
kyuubi.kubernetes.trust.certificatesfalse如果设置为 true，则客户端只能通过令牌向 Kubernetes 集群提交作业boolean1.7.0

血缘

键默认值含义类型引入版本
kyuubi.lineage.parser.plugin.providerorg.apache.kyuubi.plugin.lineage.LineageParserProviderSpark 血缘解析插件的提供者。string1.8.0

元数据

键 默认值 含义 类型 引入版本

kyuubi.metadata.cleaner.enabled true 是否定期清理元数据。若启用，Kyuubi 将清理处于终止状态且超过最大存续时限的元数据。boolean 1.6.0

kyuubi.metadata.cleaner.interval PT30M 检查并清理过期元数据的时间间隔。duration 1.6.0

kyuubi.metadata.max.age PT72H 元数据的最大存续时限，超过该时限的元数据将被清理。duration 1.6.0

kyuubi.metadata.recovery.threads 10 Kyuubi 服务器重启时，从元数据存储恢复数据所使用的线程数。int 1.6.0

kyuubi.metadata.request.async.retry.enabled true 元数据请求失败时是否进行异步重试。设置为 true 时，即使元数据请求失败也会立即返回成功响应，并在后台持续调度重试直至成功，从而在不阻塞提交请求的情况下容忍元数据存储的长时间故障。boolean 1.7.0

kyuubi.metadata.request.async.retry.queue.size 65536 当外部元数据存储不可用时，用于在内存中缓冲元数据请求的最大队列长度。队列超出后请求将被丢弃。仅当 kyuubi.metadata.request.async.retry.enabled 为 true 时生效。int 1.6.0

kyuubi.metadata.request.async.retry.threads 10 元数据请求异步重试管理器线程池中的线程数。仅当 kyuubi.metadata.request.async.retry.enabled 为 true 时生效。int 1.6.0

kyuubi.metadata.request.retry.interval PT5S 检查并触发元数据请求重试任务的时间间隔。duration 1.6.0

kyuubi.metadata.store.class org.apache.kyuubi.server.metadata.jdbc.JDBCMetadataStore 服务器元数据存储的全限定类名。string 1.6.0

kyuubi.metadata.store.jdbc.database.schema.init true 是否初始化 JDBC 元数据存储的数据库模式。boolean 1.6.0

kyuubi.metadata.store.jdbc.database.type SQLITE 服务器 JDBC 元数据存储所使用的数据库类型。

  • SQLITE：SQLite3，JDBC 驱动 org.sqlite.JDBC。
  • MYSQL：MySQL，JDBC 驱动 com.mysql.cj.jdbc.Driver（回退至 com.mysql.jdbc.Driver）。
  • POSTGRESQL：PostgreSQL，JDBC 驱动 org.postgresql.Driver。
  • CUSTOM：用户自定义的数据库类型，需要指定相应的 JDBC 驱动。注意：JDBC 数据源由 HiKariCP 提供支持，数据源属性请以 kyuubi.metadata.store.jdbc.datasource. 为前缀指定。例如：kyuubi.metadata.store.jdbc.datasource.connectionTimeout=10000。

string 1.6.0

kyuubi.metadata.store.jdbc.driver <undefined> 用于服务器 JDBC 元数据存储的 JDBC 驱动类名。string 1.6.0

kyuubi.metadata.store.jdbc.password 服务器 JDBC 元数据存储的密码。string 1.6.0

kyuubi.metadata.store.jdbc.priority.enabled false 是否为 batch impl v2 启用优先级调度。设为 false 时，忽略 kyuubi.batch.priority，并使用 FIFO 排序策略进行批处理作业调度。注意：由于 MySQL 5.7 不支持混合顺序索引，使用该功能作为元数据存储后端时可能会导致严重的性能问题。更多详情参见 KYUUBI devlive-community/knowforge#5329。boolean 1.8.0

kyuubi.metadata.store.jdbc.url jdbc<KYUUBI_HOME>/kyuubi_state_store.db 服务器 JDBC 元数据存储的 JDBC URL。默认情况下，它是一个 SQLite 数据库 URL，状态信息不会在多个 Kyuubi 实例之间共享。要为多个 Kyuubi 实例实现高可用，请指定一个生产环境的 JDBC URL。注意：该值支持变量替换：<KYUUBI_HOME>。string 1.6.0

kyuubi.metadata.store.jdbc.user 服务器 JDBC 元数据存储的用户名。string 1.6.0

指标

键 默认值 含义 类型 引入版本

kyuubi.metrics.console.interval PT5S 向控制台报告指标的频率 duration 1.2.0

kyuubi.metrics.enabled true 设为 true 以启用 Kyuubi 指标系统 boolean 1.2.0

kyuubi.metrics.json.interval PT5S 向 JSON 文件报告指标的频率 duration 1.2.0

kyuubi.metrics.json.location metrics JSON 指标文件的存放位置 string 1.2.0

kyuubi.metrics.prometheus.path /metrics Prometheus 指标 HTTP 服务器的 URI 上下文路径 string 1.2.0

kyuubi.metrics.prometheus.port 10019 Prometheus 指标 HTTP 服务器端口 int 1.2.0

kyuubi.metrics.reporters PROMETHEUS 以逗号分隔的所有指标报告器列表

  • CONSOLE - ConsoleReporter，定期将测量结果输出到控制台。
  • JMX - JmxReporter，监听新的指标并将其暴露为 MBean。
  • JSON - JsonReporter，定期将测量结果输出到 json 文件。
  • PROMETHEUS - PrometheusReporter，以 Prometheus 格式暴露指标。
  • SLF4J - Slf4jReporter，定期将测量结果输出到系统日志。

set 1.2.0

kyuubi.metrics.slf4j.interval PT5S 向 SLF4J 日志记录器报告指标的频率 duration 1.2.0

操作

键 默认值 含义 类型 引入版本

kyuubi.operation.getTables.ignoreTableProperties false 通过忽略 tableTypes 查询条件、仅返回表标识来加速 GetTables 操作。boolean 1.8.0

kyuubi.operation.idle.timeout PT3H 操作在该时间段内未被访问时将被关闭 duration 1.0.0

kyuubi.operation.interrupt.on.cancel true 设为 true 时，如果用户取消查询，所有正在运行的任务都会被中断；设为 false 时，所有正在运行的任务将继续运行直到完成。boolean 1.2.0

kyuubi.operation.language SQL 为后续输入选择编程语言

  • SQL：（默认）将后续所有语句作为 SQL 查询执行。
  • SCALA：将后续所有输入作为 Scala 代码执行。
  • PYTHON：（实验性）将后续所有输入作为 Python 代码，使用 Spark 引擎执行。

string 1.5.0

kyuubi.operation.log.dir.root server_operation_logs 服务端查询操作日志的根目录。string 1.4.0

kyuubi.operation.plan.only.excludes SetCatalogAndNamespace,UseStatement,SetNamespaceCommand,SetCommand,ResetCommand 以简单类名形式给出的、以逗号分隔的查询计划名称列表，例如对于 SET abc=xyz，其值为 SetCommand。对于那些用于搭建环境以分析实际查询的辅助计划，例如 switch databases、set properties 或 create temporary view 等，我们可以使用此配置将其排除，使其正常生效。另请参阅 kyuubi.operation.plan.only.mode。set 1.5.0

kyuubi.operation.plan.only.mode none 配置语句的执行模式，取值可以为 'parse'、'analyze'、'optimize'、'optimize_with_stats'、'physical'、'execution'、'lineage' 或 'none'。当取值为 'none' 时，表示语句将被完整执行；否则只获取执行路径而不真正执行查询。不同引擎目前支持的模式不同：Spark 引擎支持全部模式，Flink 引擎支持 'parse'、'physical' 和 'execution'，其他引擎目前尚不支持 planOnly。string 1.4.0

kyuubi.operation.plan.only.output.style plain 配置 planOnly 的输出样式，取值可以为 'plain' 或 'json'，默认值为 'plain'。该配置仅支持 Spark 引擎的输出样式。string 1.7.0

kyuubi.operation.progress.enabled false 是否启用操作进度。设置为 true 时，操作进度会在 GetOperationStatus 中返回。boolean 1.6.0

kyuubi.operation.query.timeout <undefined> 服务端查询执行的超时时间，与客户端超时（java.sql.Statement.setQueryTimeout）共同生效，超时后正在运行的查询会被自动取消。默认关闭，即完全由客户端决定查询是否超时。若设置该值，客户端超时时长的上限即为该值。若希望立即取消查询而不等待任务结束，可同时启用 kyuubi.operation.interrupt.on.cancel。duration 1.2.0

kyuubi.operation.result.arrow.timestampAsString false 设置为 true 时，基于 Arrow 的行集在传输前会将 timestamp 类型的列转换为字符串。boolean 1.7.0

kyuubi.operation.result.format thrift 指定结果格式，可选配置有：

  • THRIFT：结果在引擎 driver 侧转换为 TRow。
  • ARROW：结果在 executor 侧被编码为 Arrow 格式，由 driver 收集后在客户端反序列化。注意，目前仅对 kyuubi-hive-jdbc 客户端生效。

string 1.7.0

kyuubi.operation.result.max.rows 0 Spark 查询结果的最大返回行数。超过该限制的行将被忽略。将此值设置为 0 可禁用最大行数限制。int 1.6.0

kyuubi.operation.result.saveToFile.dir /tmp/kyuubi/tmp_kyuubi_result Spark 查询结果的保存目录，该目录应当是所有引擎都可公共访问的。结果以 ORC 格式保存，目录结构为 /OPERATION_RESULT_SAVE_TO_FILE_DIR/engineId/sessionId/statementId。每个查询的结果会在查询结束后被删除。string 1.9.0

kyuubi.operation.result.saveToFile.enabled false 是否将 Spark 查询结果保存到文件的开关。boolean 1.9.0

kyuubi.operation.result.saveToFile.minRows 10000 Spark 结果保存到文件的最小行数，默认值为 10000。long 1.9.1

kyuubi.operation.result.saveToFile.minSize 209715200 Spark 结果保存到文件的最小大小，默认值为 200 MB。我们使用 Spark 的 EstimationUtils#getSizePerRowestimate 来估算执行计划的输出大小。long 1.9.0

kyuubi.operation.scheduler.pool <undefined> 作业的调度器池。请注意，该配置应在将 Spark 配置 spark.scheduler.mode 设为 FAIR 之后使用。string 1.1.1

kyuubi.operation.spark.listener.enabled true 设置为 true 时，Spark 引擎会在执行语句前注册一个 SQLOperationListener，在每个 stage 完成时记录一些汇总统计信息。boolean 1.6.0

kyuubi.operation.status.polling.timeout PT5S 长轮询异步运行的 SQL 查询状态持续时间的超时时间（毫秒） 1.0.0

Server

Key Default Meaning Type Since

kyuubi.server.administrators 以逗号分隔的 Kyuubi 服务管理员列表。当启用安全机制时，我们使用该配置为任意服务账号授予管理员权限。请注意，当 kyuubi.authentication 被配置为 NOSASL 或 NONE 时，所有人都会被视为管理员。set 1.8.0

kyuubi.server.info.provider ENGINE 服务器信息提供者的名称，部分客户端可能会依赖该信息来检查服务器的兼容性与功能。

SERVER：返回 Kyuubi 服务端信息。

ENGINE：返回 Kyuubi 引擎信息。

string 1.6.1

kyuubi.server.limit.batch.connections.per.ipaddress <undefined> Kyuubi 服务端每个 IP 地址的最大批量连接数。任何超过该限制的用户将不被允许连接。int 1.7.0

kyuubi.server.limit.batch.connections.per.user <undefined> Kyuubi 服务端每个用户的最大批量连接数。任何超过该限制的用户将不被允许连接。int 1.7.0

kyuubi.server.limit.batch.connections.per.user.ipaddress <undefined> Kyuubi 服务端每个 用户:IP地址 组合的最大批量连接数。任何超过该限制的用户-IP地址将不被允许连接。int 1.7.0

kyuubi.server.limit.client.fetch.max.rows <undefined> 获取结果行集操作的最大行数限制。如果客户端指定的最大行数大于该限制，请求将直接失败。int 1.8.0

kyuubi.server.limit.connections.ip.deny.list 拒绝列表中的客户端 IP 将被禁止连接 Kyuubi 服务器。 set 1.9.1

kyuubi.server.limit.connections.per.ipaddress <undefined> Kyuubi 服务器单个 IP 地址的最大连接数。任何超过该限制的用户将不被允许连接。int 1.6.0

kyuubi.server.limit.connections.per.user <undefined> Kyuubi 服务器单个用户的最大连接数。任何超过该限制的用户将不被允许连接。int 1.6.0

kyuubi.server.limit.connections.per.user.ipaddress <undefined> Kyuubi 服务器单个“用户:IP 地址”组合的最大连接数。任何超过该限制的用户-IP 组合将不被允许连接。int 1.6.0

kyuubi.server.limit.connections.user.deny.list 拒绝列表中的用户将被禁止连接 Kyuubi 服务器；如果用户同时配置了 user.unlimited.list 和 user.deny.list，则以后者（user.deny.list）优先。set 1.8.0

kyuubi.server.limit.connections.user.unlimited.list 白名单中的用户的最大连接数不受限制。set 1.7.0

kyuubi.server.name <undefined> Kyuubi 服务器的名称。string 1.5.0

kyuubi.server.periodicGC.interval PT30M 触发垃圾回收的频率。duration 1.7.0

kyuubi.server.redaction.regex <undefined> 用于判定哪些 Kyuubi 配置包含敏感信息的正则表达式。当该正则表达式匹配到属性键或属性值时，该值将从各类日志中被脱敏处理。1.6.0

kyuubi.server.thrift.resultset.default.fetch.size 1000 当客户端未指定时，服务器在一次 Fetch RPC 调用中发送给客户端的行数。遵循 hive.server2.thrift.resultset.default.fetch.size Hive 配置。int 1.9.1

会话

Key Default Meaning Type Since

kyuubi.session.check.interval PT5M 会话超时的检查间隔。duration 1.0.0

kyuubi.session.close.on.disconnect true 当客户端与 Kyuubi 网关断开连接时关闭会话。将其设置为 false 可使会话在其父连接结束后继续存在。boolean 1.8.0

kyuubi.session.conf.advisor <undefined> Kyuubi 服务器的配置顾问插件。该插件可以针对不同用户或会话配置提供一组自定义配置，并在开启新会话之前覆盖会话配置。该配置值应为 org.apache.kyuubi.plugin.SessionConfAdvisor 的子类，并具有一个无参构造函数。seq 1.5.0

kyuubi.session.conf.file.reload.interval PT10M 当使用 FileSessionConfAdvisor 时，该配置定义了 $KYUUBI_CONF_DIR/kyuubi-session-<profile>.conf 在缓存中的过期时间。超过该时间后，文件将被重新加载。duration 1.7.0

kyuubi.session.conf.ignore.list 以逗号分隔的忽略键列表。如果客户端连接中包含其中任何一个键，该键及其对应的值将在引擎引导和连接建立期间被静默移除。请注意，该规则是管理员定义的服务端保护机制，用于防止某些关键配置被篡改，但不会禁止用户通过 SET 语法设置动态配置。set 1.2.0

kyuubi.session.conf.profile <undefined> 指定一个 profile，用于从 $KYUUBI_CONF_DIR/kyuubi-session-<profile>.conf 加载会话级配置。如果该文件不存在，此配置将被忽略。此配置仅在 kyuubi.session.conf.advisor 设置为 org.apache.kyuubi.session.FileSessionConfAdvisor 时生效。string 1.7.0

kyuubi.session.conf.restrict.list 以逗号分隔的受限键列表。如果客户端连接中包含其中任何一个键，该连接将在引擎引导和连接建立期间被明确拒绝。请注意，该规则是管理员定义的服务端保护机制，用于防止某些关键配置被篡改，但不会禁止用户通过 SET 语法设置动态配置。set 1.2.0

kyuubi.session.engine.alive.max.failures 3 允许引擎失败的最大次数。int 1.8.1

kyuubi.session.engine.alive.probe.enabled false 是否启用引擎存活探测。如果为 true，我们将创建一个伴随的 thrift 客户端，持续发送简单请求以检查引擎是否存活。boolean 1.6.0

kyuubi.session.engine.alive.probe.interval PT10S 引擎存活探测的间隔时间。duration 1.6.0

kyuubi.session.engine.alive.timeout PT2M 引擎存活的超时时间。如果在最近的超时窗口内没有一次存活探测成功，该引擎将被标记为不存活。duration 1.6.0

kyuubi.session.engine.check.interval PT1M 引擎超时检查的间隔时间 duration 1.0.0

kyuubi.session.engine.flink.fetch.timeout <undefined> Flink 引擎的结果获取超时时间。如果达到超时，结果获取将被停止，并返回当前已获取的数据。如果没有获取到任何数据，将抛出 TimeoutException。duration 1.8.0

kyuubi.session.engine.flink.initialize.sql Flink 会话的初始化 SQL。它会回退到 kyuubi.engine.session.initialize.sql seq 1.8.1

kyuubi.session.engine.flink.main.resource <undefined> 用于创建 Flink SQL 引擎远程作业的程序包。如果未定义，Kyuubi 将使用默认的 string 1.4.0

kyuubi.session.engine.flink.max.rows 1000000 Flink 查询结果的最大行数。对于批处理查询，超过该限制的行将被忽略；对于流式查询，达到该限制时查询将被取消。int 1.5.0

kyuubi.session.engine.hive.main.resource <undefined> 用于创建 Hive 引擎远程作业的程序包。如果未定义，Kyuubi 将使用默认的 string 1.6.0

kyuubi.session.engine.idle.timeout PT30M 引擎超时时间，引擎在该时长内未被访问时将自行终止。0 或负值表示不自行终止。duration 1.0.0

kyuubi.session.engine.initialize.timeout PT3M 后台引擎（例如 SparkSQLEngine）的启动超时时间。duration 1.0.0

kyuubi.session.engine.launch.async true 打开 kyuubi 会话时，是否异步启动后端引擎。为 true 时，后端引擎将被异步创建，Kyuubi 服务器会立即与客户端建立连接而不会产生延迟。boolean 1.4.0

kyuubi.session.engine.log.timeout PT24H 如果我们使用 Spark 作为引擎，则会话提交日志即为 spark-submit 的控制台输出。我们会保留该会话提交日志，直到超过该配置值。duration 1.1.0

kyuubi.session.engine.login.timeout PT15S 创建到远程 SQL 查询引擎的连接的超时时间。duration 1.0.0

kyuubi.session.engine.open.max.attempts 9 打开引擎时遇到特定错误后的重试次数。int 1.7.0

kyuubi.session.engine.open.onFailure RETRY 打开引擎失败时的行为：

  • RETRY：重试打开引擎，最多重试 kyuubi.session.engine.open.max.attempts 次。
  • DEREGISTER_IMMEDIATELY：立即注销引擎。
  • DEREGISTER_AFTER_RETRY：重试打开引擎 kyuubi.session.engine.open.max.attempts 次之后注销引擎。

string 1.8.1

kyuubi.session.engine.open.retry.wait PT10S 打开引擎失败后，再次重试之前需要等待的时长。duration 1.7.0

kyuubi.session.engine.share.level USER （已废弃）- 请改用 kyuubi.engine.share.level string 1.0.0

kyuubi.session.engine.spark.initialize.sql Spark 会话的初始化 SQL。若未配置，则回退使用 kyuubi.engine.session.initialize.sql。seq 1.8.1

kyuubi.session.engine.spark.main.resource <undefined> 用于创建 Spark SQL 引擎远程应用的包。若未定义，Kyuubi 将使用默认值。string 1.0.0

kyuubi.session.engine.spark.max.initial.wait PT1M 初始连接到 Spark 引擎的最大等待时间。如果在此时间内没有建立新的传入连接，引擎将自行终止。该设置仅在 CONNECTION 共享级别下生效。0 或负值表示不自行终止。duration 1.8.0

kyuubi.session.engine.spark.max.lifetime PT0S Spark 引擎的最大生命周期，达到生命周期终点时引擎将自行终止。0 或负值表示不自行终止。duration 1.6.0

kyuubi.session.engine.spark.max.lifetime.gracefulPeriod PT0S Spark 引擎在达到生命周期终点后，等待连接断开的宽限期。宽限期结束后，所有没有正在运行操作的连接将被强制断开。0 或负值表示始终等待连接自行断开。duration 1.8.1

kyuubi.session.engine.spark.progress.timeFormat yyyy-MM-dd HHss.SSS 进度条的时间格式。string 1.6.0

kyuubi.session.engine.spark.progress.update.interval PT1S 进度条的更新周期。duration 1.6.0

kyuubi.session.engine.spark.showProgress false 为 true 时，在 Spark 引擎日志中显示进度条。boolean 1.6.0

kyuubi.session.engine.startup.destroy.timeout PT5S 引擎启动过程的销毁等待时间，若进程在此时间后仍未停止，则强制销毁。该配置仅在 kyuubi.session.engine.startup.waitCompletion=false 时生效。duration 1.8.0

kyuubi.session.engine.startup.error.max.size 8192 在引擎启动过程中，若发生错误，使用此配置限制错误信息的长度（字符数）。int 1.1.0

kyuubi.session.engine.startup.maxLogLines 10 引擎启动阶段发生错误时，引擎日志的最大行数。注意，此配置作用于客户端侧，用于帮助排查引擎启动问题。int 1.4.0

kyuubi.session.engine.startup.waitCompletion true 引擎启动后是否等待其完成。若为 false，引擎启动后将销毁启动进程。注意，仅在 driver 非本地运行时使用，例如 yarn-cluster 模式；否则，引擎将被杀死。boolean 1.5.0

kyuubi.session.engine.trino.connection.catalog <undefined> Trino 引擎将连接的默认 catalog string 1.5.0

kyuubi.session.engine.trino.connection.url <undefined> Trino 引擎将连接的服务器 URL string 1.5.0

kyuubi.session.engine.trino.main.resource <undefined> 用于创建 Trino 引擎远程作业的包。若未定义，Kyuubi 将使用默认值 string 1.5.0

kyuubi.session.engine.trino.showProgress true 为 true 时，在 Trino 引擎日志中显示进度条和最终信息。boolean 1.6.0

kyuubi.session.engine.trino.showProgress.debug false 为 true 时，在 Trino 引擎日志中显示进度调试信息。boolean 1.6.0

kyuubi.session.group.provider hadoop Kyuubi Server 的组提供者插件。该插件可以为不同的用户或会话配置提供主组和组信息。此配置值应为 org.apache.kyuubi.plugin.GroupProvider 的子类，且具有无参构造函数。Kyuubi 提供了以下内置实现：

hadoop：将用户组映射委托给 hadoop 的 UserGroupInformation。

string 1.7.0

kyuubi.session.idle.timeout PT6H 会话空闲超时时间，在此时间段内未被访问则会被关闭 duration 1.2.0

kyuubi.session.local.dir.allow.list Kyuubi 会话应用允许访问的本地目录列表。终端用户可能会设置诸如 spark.files 之类的参数，在启动 Kyuubi 引擎时会上传一些本地文件。如果定义了本地目录允许列表，Kyuubi 将检查待上传的路径是否在允许列表中。注意，若列表为空，则不做任何限制。请使用绝对路径。set 1.6.0

kyuubi.session.name <undefined> 会话的可读名称，默认使用空字符串。该名称将记录在事件中。请注意，此配置值仅从会话配置中生效。string 1.4.0

kyuubi.session.proxy.user <undefined> hive.server2.proxy.user 的替代配置。当前行为与 hive.server2.proxy.user 一致，并且目前仅在 RESTful API 中生效。当两个参数同时设置时，kyuubi.session.proxy.user 优先。string 1.9.0

kyuubi.session.timeout PT6H （已废弃）会话超时时间，超过该时长未被访问时会话将被关闭 duration 1.0.0

kyuubi.session.user.sign.enabled false 是否在引擎端校验会话用户名的完整性，例如 Spark 中的 Authz 插件。boolean 1.7.0

Spnego

KeyDefaultMeaningTypeSince
kyuubi.spnego.keytab<undefined>SPNego 主体的 keytab 文件string1.6.0
kyuubi.spnego.principal<undefined>SPNego 服务主体，典型取值形如 HTTP/_HOST@EXAMPLE.COM。当启用 RESTful Kerberos 安全时会使用 SPNego 服务主体。仅当需要在认证中使用 SPNEGO 时才需设置此项。string1.6.0

Yarn

Key Default Meaning Type Since

kyuubi.yarn.user.admin yarn 当 kyuubi.yarn.user.strategy 设置为 ADMIN 时，使用该管理员用户来构建用于应用管理（例如 kill 应用）的 YARN 客户端。string 1.8.0

kyuubi.yarn.user.strategy NONE 确定使用哪个用户来构建用于应用管理（例如 kill 应用）的 YARN 客户端。可选值：

  • NONE：使用 Kyuubi 服务端用户。
  • ADMIN：使用 kyuubi.yarn.user.admin 中配置的管理员用户。
  • OWNER：使用会话用户，通常即应用的属主。

string 1.8.0

Zookeeper

Key默认值含义类型起始版本
kyuubi.zookeeper.embedded.client.port2181内嵌 ZooKeeper 服务器监听客户端连接的 clientPort，这里的客户端可以是 Kyuubi 服务器、引擎和 JDBC 客户端int1.2.0
kyuubi.zookeeper.embedded.client.port.address<未定义>内嵌 ZooKeeper 服务器的 clientPortAddressstring1.2.0
kyuubi.zookeeper.embedded.client.use.hostnamefalse为 true 时，内嵌 ZooKeeper 优先绑定主机名，否则绑定 IP 地址boolean1.7.2
kyuubi.zookeeper.embedded.data.dirembedded_zookeeper内嵌 ZooKeeper 服务器的 dataDir，用于存储内存数据库快照，以及（除非另有指定）数据库更新的事务日志。如果为相对路径，则相对于 KYUUBI_HOME 解析。string1.2.0
kyuubi.zookeeper.embedded.data.log.dirembedded_zookeeper内嵌 ZooKeeper 服务器的 dataLogDir，用于写入事务日志。如果为相对路径，则相对于 KYUUBI_HOME 解析。string1.2.0
kyuubi.zookeeper.embedded.directoryembedded_zookeeper（已废弃）内嵌 ZooKeeper 服务器的临时目录。如果为相对路径，则相对于 KYUUBI_HOME 解析。string1.0.0
kyuubi.zookeeper.embedded.max.client.connections120内嵌 ZooKeeper 服务器的 maxClientCnxns，用于限制由 IP 地址标识的单个客户端的并发连接数int1.2.0
kyuubi.zookeeper.embedded.max.session.timeout60000内嵌 ZooKeeper 服务器允许客户端协商的 maxSessionTimeout，单位为毫秒。默认为 tickTime 的 20 倍int1.2.0
kyuubi.zookeeper.embedded.min.session.timeout6000内嵌 ZooKeeper 服务器允许客户端协商的 minSessionTimeout，单位为毫秒。默认为 tickTime 的 2 倍int1.2.0
kyuubi.zookeeper.embedded.port2181（已废弃）内嵌 ZooKeeper 服务器的端口int1.0.0
kyuubi.zookeeper.embedded.tick.time3000内嵌 ZooKeeper 服务器的 tickTime，单位为毫秒int1.2.0

Spark 配置

通过 spark-defaults.conf

在 $SPARK_HOME/conf/spark-defaults.conf 中进行设置，将为 SQL 引擎应用提供默认值。可用属性可以在 Spark 官方在线文档 Spark Configurations 中找到。

通过 kyuubi-defaults.conf

在 $KYUUBI_HOME/conf/kyuubi-defaults.conf 中进行设置，同样会为 SQL 引擎应用提供默认值。这些属性将覆盖 $SPARK_HOME/conf/spark-defaults.conf 中的所有设置。

通过 JDBC 连接 URL

在 JDBC 连接 URL 中进行设置，将为每个 SQL 引擎提供会话级别的配置。例如：

jdbc:hive2://localhost:10009/default;#spark.sql.shuffle.partitions=2;spark.executor.memory=5g

  • 运行时 SQL 配置

  • 静态 SQL 与 Spark Core 配置

    • 对于静态 SQL 配置以及其他 Spark core 配置（例如 spark.executor.memory），如果当前不存在正在运行的 SQL 引擎应用，它们就会生效；否则将被忽略

通过 SET 语法

请参阅 Spark 官方在线文档中的 SET 命令

Flink 配置

通过 flink-conf.yaml

在 $FLINK_HOME/conf/flink-conf.yaml 中进行设置，可为 SQL 引擎应用提供默认值。可用的属性可以在 Flink 官方在线文档的 Flink 配置 中找到。

通过 kyuubi-defaults.conf

在 $KYUUBI_HOME/conf/kyuubi-defaults.conf 中进行设置，同样可以为 SQL 引擎应用提供默认值。你可以使用带有额外前缀 flink. 的属性来覆盖 $FLINK_HOME/conf/flink-conf.yaml 中的设置。

例如：

flink.parallelism.default 2
flink.taskmanager.memory.process.size 5g

kyuubi-defaults.conf 中的以下选项会将 parallelism.default: 2 和 taskmanager.memory.process.size: 5g 设置到 Flink 配置中。

通过 JDBC 连接 URL

在 JDBC 连接 URL 中设置这些选项，可为每个 SQL 引擎提供会话级别的配置。例如：

jdbc:hive2://localhost:10009/default;#flink.parallelism.default=2;flink.taskmanager.memory.process.size=5g

通过 SET 语句

请参阅 Flink 官方在线文档中的 SET 语句

Trino 配置

通过 config.properties

在 $TRINO_HOME/etc/config.properties 中进行设置，可为 SQL 引擎应用提供默认值。可用属性请参阅 Trino 官方在线文档中的 Trino 配置

通过 kyuubi-defaults.conf

在 $KYUUBI_HOME/conf/kyuubi-defaults.conf 中进行设置，同样可为 SQL 引擎应用提供默认值。您可以使用带有额外前缀 trino. 的属性，以覆盖 $TRINO_HOME/etc/config.properties 中的设置。

例如：

trino.query_max_stage_count 500
trino.parse_decimal_literals_as_double true

kyuubi-defaults.conf 中的以下选项会将 query_max_stage_count: 500 和 parse_decimal_literals_as_double: true 设置到 Trino 会话属性中。

通过 JDBC 连接 URL

在 JDBC 连接 URL 中进行设置，可为每个 SQL 引擎提供会话级别的配置。例如：

jdbc:hive2://localhost:10009/default;#trino.query_max_stage_count=500;trino.parse_decimal_literals_as_double=true

通过 SET 语句

请参考 Trino 官方在线文档中的 SET 语句

日志

Kyuubi 使用 log4j 进行日志记录。你可以通过 $KYUUBI_HOME/conf/log4j2.xml 对其进行配置，可参考示例文件 $KYUUBI_HOME/conf/log4j2.xml.template。

其他配置

Hadoop 配置

可以将 HADOOP_CONF_DIR 指定为包含 Hadoop 配置文件的目录，也可以将这些配置以 spark.hadoop. 前缀的形式作为 Spark 属性进行配置。请参考 Spark 官方在线文档中的 继承 Hadoop 集群配置。另外，请参考 Apache Hadoop 的在线文档，了解如何配置 Hadoop 的概览。

Hive 配置

这些配置用于 SQL 引擎应用与 Hive MetaStore 进行通信，可以在 hive-site.xml 中进行配置。将该文件放置在 $SPARK_HOME/conf 目录下，或者以 spark.hadoop. 前缀的形式将其作为 Spark 属性进行配置。

用户默认配置

在 Kyuubi 中，我们可以配置用户默认设置，以满足不同的需求。这些用户默认配置会覆盖系统默认配置，但如果可以的话，它们会被来自 JDBC 连接 URL 或 Set 命令 的配置所覆盖。它们仅在创建 SQL 引擎应用时生效。用户默认设置的格式为 ___{username}___.{config key}，username 的左右两侧各有三个连续的下划线（_），并且配置键与该前缀之间用一个点号（.）分隔。例如：

# For system defaults
spark.master=local
spark.sql.adaptive.enabled=true
# For a user named kent
___kent___.spark.master=yarn
___kent___.spark.sql.adaptive.enabled=false
# For a user named bob
___bob___.spark.master=spark://master:7077
___bob___.spark.executor.memory=8g

在上述情况下，如果存在来自 JDBC 连接 URL 的相关配置，kent 将在 YARN 上运行其 SQL 引擎应用，并优先关闭 Spark AQE；而 bob 将在 Spark 独立集群上启动其 SQL 引擎应用，每个执行器的堆内存为 8g，并遵循 Kyuubi 系统默认的 Spark AQE 行为。另一方面，对于没有自定义配置的用户，将使用系统默认值。

评论

登录后参与评论

正在加载评论…