Kyuubi Gateway通过Kerberos实现安全的身份验证和访问控制，确保分布式计算环境中的数据安全性。 - 开源大数据平台E-MapReduce

在Serverless Spark的Kyuubi Gateway中，通过Kerberos您可以实现安全的身份验证和访问控制。完成配置后，向该工作空间的Kyuubi Gateway提交任务时，客户端需进行Kerberos认证，从而增强任务执行的安全性。

使用限制

kdc和Serverless Spark工作空间在同一个地域。

前提条件

已创建开启Kerberos身份认证的EMR on ECS集群，详情请参见创建集群。
已创建开启Kerberos身份认证的Serverless Spark工作空间，详情请参见开启Kerberos身份认证。
已在Serverless Spark工作空间中创建Kyuubi Gateway（无需启动，仅创建即可）。

打通网络

Kyuubi Gateway使用Kerberos，需要配置私网连接（PrivateLink），打通Serverless Spark和Kerberos集群之间的网络。该网络配置目前不支持用户自行设置，您需提供相关信息并提交工单，并获取终端节点服务ID，如：epsrv-bp10******2j5ms。

说明

请将以下信息提交至工单系统，获取终端节点服务ID。

Serverless Spark工作空间ID，如w-f8cfXXXXXX。
Kyuubi Gateway ID，如kb-564e********266f。
至少提供用于访问Kyuubi服务的2个可用区，如cn-hangzhou-j,cn-hangzhou-k。地域支持的可用区范围，请咨询工单中的客服获取。

创建终端节点

终端节点（Endpoint）由服务使用方创建和维护，可以与终端节点服务相关联，从而建立通过PrivateLink私网访问外部服务的网络连接。详情请参见终端节点概述。

登录终端节点控制台。

在创建终端节点页面，根据以下信息配置终端节点，然后单击确定创建。

配置	说明
所属地域	选择终端节点所属地域。确保与Kerberos集群、Serverless Spark工作空间所在地域保持一致。
节点名称	输入自定义终端节点的名称。
终端节点类型	选择接口终端节点。
终端节点服务	单击选择可用服务，然后选择或输入目标终端节点服务ID，即上文获取的`epsrv-bp10******2j5ms`。
专有网络	选择访问Kyuubi Gateway节点所在VPC。
可用区与交换机	选择前述可用区及其对应的交换机，建议至少选择两个。
安全组	选择要与终端节点网卡关联的安全组，建议选择访问Kyuubi Gateway所在节点的集群安全组，避免连接请求被安全组拦截。
IP版本	支持的网络类型，默认IPv4。
资源组	可选配置终端节点所属的资源组。
标签	可选配置标签键与标签值。

在终端节点基本信息页面，状态为可用时，即表明创建成功，终端节点服务域名为ep-xxxxxxxxxxx.epsrv-xxxxxxxxxxx.cn-hangzhou.privatelink.aliyuncs.com。

登录Kerberos集群，测试网络连接。

在 Kerberos 集群节点上通过 ping 命令验证终端节点的私网连通性，确认响应正常，表明网络已经打通：

[root@master-1-1(xxx) ~]# ping ep-bp1ixxx.cn-hangzhou.privatelink.aliyuncs.com
PING ep-bp1xxx              xxx.cn-hangzhou.privatelink.aliyuncs.com (xxx) 56(84) bytes of data.
64 bytes from xxx (xxx): icmp_seq=1 ttl=102 time=0.989 ms

配置域名解析（可选）

默认终端节点服务域名比较长，为方便使用，您可以配置自定义内网权威域名。详情请参见内网权域名。

登录。在 内网权威 的用户域名页签下，点击添加域名（Zone） 。
输入内网权威域名，选择域名生效范围VPC，然后点击确定。本文示例是kyuubi-kerberos.abc。
说明
如果有域名类型选项，请选择内网权威加速区。如果没有域名类型选项，则无需选择，默认创建的是内网权威加速区域名。
在用户域名页签，点击目标域名操作列的解析设置按钮，点击添加记录，对话框内选择表单填写模式。
记录类型选择CNAME，主机记录按照选择填写（本文示例是test），记录值填写终端节点服务域名ep-xxxxxxxxxxx.epsrv-xxxxxxxxxxx.cn-hangzhou.privatelink.aliyuncs.com。单机确定后，即将终端节点服务域名映射到test.kyuubi-kerberos.abc。
登录Kerberos集群，测试网络连接。
```
ping test.kyuubi-kerberos.abc
```

创建keytab

创建kyuubi.keytab，该keytab仅用于Serverless Spark的Kyuubi Gateway认证服务。

登录Kerberos集群Kadmin节点，例如EMR on ECS的master-1-1节点。
执行以下命令，进入Kerberos的admin.local工具。
```
kadmin.local
```
查看已存在的principal：
```
listprincs
```
创建principal，principal的格式为kyuubi/<fqdn>@<REALM>，principal的fqdn部分建议使用终端节点域名ep-xxxxxxxxxxx.epsrv-xxxxxxxxxxx.cn-hangzhou.privatelink.aliyuncs.com，若配置了CNAME解析自定义域名，则使用自定义域名test.kyuubi-kerberos.abc，principal的<REALM>需要和集群当前配置保持一致，可参考其他已有principal。
```
addprinc -randkey kyuubi/ep-xxxxxxxxxxx.epsrv-xxxxxxxxxxx.cn-hangzhou.privatelink.aliyuncs.com@EMR.C-DFD4*****C204.COM
```

导出keytab文件，导出成功后退出Kerberos的admin.local工具。

xst -kt /root/kyuubi.keytab kyuubi/ep-xxxxxxxxxxx.epsrv-xxxxxxxxxxx.cn-hangzhou.privatelink.aliyuncs.com@EMR.C-DFD4*****C204.COM

quit

将生成的keytab文件上传到OSS Bucket中。

hadoop fs -put /root/kyuubi.keytab oss://<bucket_name>.oss-<region-id>-internal.aliyuncs.com/<path>/

配置Kyuubi Gateway

Kyuubi Gateway在使用Kerberos时，需要选择能访问KDC集群的网络连接，还需进行以下Kyuubi 配置。

kyuubi.authentication              KERBEROS
kyuubi.kinit.principal             kyuubi/ep-xxxxxxxxxxx.epsrv-xxxxxxxxxxx.cn-hangzhou.privatelink.aliyuncs.com@EMR.C-DFD43******7C204.COM
kyuubi.files                       oss://<bucket_name>/<path>/kyuubi.keytab
kyuubi.kinit.keytab                /opt/kyuubi/work-dir/kyuubi.keytab

配置项	说明
kyuubi.authentication	指定Kyuubi Gateway使用的认证方式。设置为 `KERBEROS` 。
kyuubi.kinit.principal	指定Kyuubi Gateway用于Kerberos认证的Principal主体，格式为 `<user>/<host>@<realm>`。
kyuubi.files	该配置会下载指定文件至`/opt/kyuubi/work-dir/`目录。可填上方步骤中上传keytab的OSS路径，无需带`oss-<region-id>-internal.aliyuncs.com`域名。
kyuubi.kinit.keytab	指定Kyuubi Gateway使用keytab文件。注：路径固定为`/opt/kyuubi/work-dir/`目录，按需修改文件名。

如需要连接开启Kerberos的HMS，且工作空间数据目录已经配置该HMS数据目录，Spark 配置如下。

spark.hive.metastore.kerberos.principal             hive/_HOST@EMR.C-DFD4*****C204.COM
spark.hive.metastore.sasl.enabled                   true

配置项	说明
spark.hive.metastore.kerberos.principal	Kerberos环境下HMS对应的认证主体（principal），需填上方步骤listprincs命令获取的hive principal，其中`<fqdn>`可简化为`_HOST`，即hive/_HOST@<REALM>。
spark.hive.metastore.sasl.enabled	是否开启Kerberos认证，填true。

（选填），如需要连接开启Kerberos的HMS，且工作空间数据目录没有配置该HMS数据目录，还需额外添加Spark 配置如下。

spark.hadoop.hive.metastore.uris                    thrift://master-1-1.c-1d36*****e840c.cn-hangzhou.emr.aliyuncs.com:9083
spark.hadoop.hive.imetastoreclient.factory.class    org.apache.hadoop.hive.ql.metadata.SessionHiveMetaStoreClientFactory

配置项	说明
spark.hadoop.hive.metastore.uris	Hive Metastore（HMS）地址。
spark.hadoop.hive.imetastoreclient.factory.class	固定值。

说明

在HA集群环境中，metastore.uris可以配置多个thrift地址，地址之间用逗号分隔，且必须使用hostname，不能使用IP地址。
若metastore.uris仅填写一个thrift地址，可以使用IP地址，但metastore.kerberos.principal必须采用hive/<hostname of HMS>@<REALM>的格式。
仅当metastore.uris使用主机名时，metastore.kerberos.principal才能简化为hive/_HOST@<REALM>的格式。

保存以上配置后即可启动Kyuubi Gateway。

提交作业

验证Kerberos集群连接Kyuubi Gateway启动执行Spark作业是否成功。

（可选）准备一个有权限的Kerberos用户，并导出keytab文件。
1. 登录Kerberos集群。
2. 执行以下命令导出keytab文件。
```
kadmin.local
addprinc -randkey emr-user@EMR.C-DFD4*****C204.COM
xst -kt /root/emr-user.keytab emr-user@EMR.C-DFD4*****C204.COM
quit
```
使用该keytab文件进行Kerberos认证。
```
kinit -kt /root/emr-user.keytab emr-user
```
如步骤1未创建，也可使用已存在的服务keytab，例如EMR on ECS默认存在的hive.keytab。
说明
测试场景可直接使用集群上已存在的keytab，但禁止修改、重新导出已经存在的服务keytab，否则会导致原有服务不可用。
```
klist -kt /etc/taihao-apps/hive-conf/keytab/hive.keytab
kinit -kt /etc/taihao-apps/hive-conf/keytab/hive.keytab hive/master-1-1.c-596f1842f3ed8ad0.cn-hangzhou.emr.aliyuncs.com@EMR.C-596F1842F3ED8AD0.COM
```
查看当前Kerberos 票据。
```
klist
```
使用kyuubi-beeline或spark-beeline连接Kyuubi Gateway启动执行Spark作业。
```
kyuubi-beeline -u 'jdbc:hive2://ep-xxxxxxxxxxx.epsrv-xxxxxxxxxxx.cn-hangzhou.privatelink.aliyuncs.com:10009/;principal=kyuubi/_HOST@EMR.C-DFD43*****7C204.COM'
```
说明
- ep-xxxxxxxxxxx.epsrv-xxxxxxxxxxx.cn-hangzhou.privatelink.aliyuncs.com为创建终端节点章节获取的服务域名。
- 端口号默认为10009。
- principal为kyuubi服务principal，<fqdn>可简化为_HOST，即kyuubi/_HOST@EMR.C-DFD43*****7C204.COM。

连接后执行show databases。

2025-08-21 14:55:18.392 INFO KyuubiSessionManager-exec-pool: Thread-83 org.apache.kyuubi.operation.ExecuteState STATE -> FINISHED_STATE, time taken: 0.301 seconds
2025-08-21 14:55:18.393 INFO nioEventLoopGroup-3-1 org.apache.kyuubi.websocket.MessageSender: [KyuubiSqlStateme success!
2025-08-21 14:55:18.418 INFO nioEventLoopGroup-3-1 org.apache.kyuubi.websocket.MessageSender: channel listener
2025-08-21 14:55:18.420 INFO nioEventLoopGroup-3-1 org.apache.kyuubi.websocket.WebSocketClientHandler: channel: !
+------------+
| namespace  |
+------------+
| default    |
+------------+
1 row selected (0.539 seconds)

常见问题

如何连接开启Kerberos认证的HDFS服务？

需要在HDFS所在集群中修改HADOOP-COMMON或HDFS组件的core-site.xml配置文件。在该文件中添加以下两个配置，以允许kyuubi用户模拟其他用户访问HDFS/HMS服务，否则可能会导致连接失败，参数添加后需重启HDFS/HMS服务。新版本的EMR Datalake集群已经默认增加了该参数。

hadoop.proxyuser.kyuubi.hosts = *
hadoop.proxyuser.kyuubi.groups = *

还需额外添加Spark 配置如下。

spark.kerberos.access.hadoopFileSystems hdfs://hdfs-cluster

如何提交作业至Kyuubi时无需Kerberos认证，仅在Spark作业访问HMS时进行Kerberos认证？

修改Kyuubi配置如下。连接时无需指定principal。

kyuubi.authentication              KERBEROS,NONE

开启Kerberos后如何连接Ranger服务？

新增Spark配置如下。

spark.ranger.plugin.enabled                      true
spark.emr.serverless.user.defined.jars           /opt/ranger/ranger-spark.jar
ranger.plugin.spark.policy.rest.url              http://master-1-1.c-xxxx.cn-hangzhou.emr.aliyuncs.com:6080
spark.files                                      oss://<bucket_name>/<path>/kyuubi.keytab
ranger.plugin.spark.policy.download.loginKeytab  true
ranger.plugin.spark.policy.download.keytab       /opt/spark/work-dir/kyuubi.keytab
ranger.plugin.spark.policy.download.principal    kyuubi/ep-xxxxxxxxxxx.epsrv-xxxxxxxxxxx.cn-hangzhou.privatelink.aliyuncs.com@EMR.C-DFD43******7C204.COM

配置项	说明
spark.files	该配置会下载指定文件至`/opt/spark/work-dir/`目录。可填上方步骤中上传keytab的OSS路径，无需带`oss-<region-id>-internal.aliyuncs.com`域名。
ranger.plugin.spark.policy.download.loginKeytab	固定值。
ranger.plugin.spark.policy.download.keytab	任意生效的keytab文件。
ranger.plugin.spark.policy.download.principal	keytab中保存的principal，使用该principal下载Ranger policy，避免请求认证失败。