Kyuubi Gateway uses Kerberos for secure authentication and access control to ensure data security in distributed computing environments. - E-MapReduce: Central de Documentação do Alibaba Cloud

Limitações

O KDC e o workspace do Serverless Spark devem estar na mesma região.

Pré-requisitos

Crie um cluster EMR on ECS com autenticação Kerberos ativada. Para mais informações, consulte Crie um cluster.
Crie um workspace do Serverless Spark com autenticação Kerberos ativada. Para mais informações, consulte Ative a autenticação Kerberos.
Crie um Kyuubi Gateway no workspace do Serverless Spark. O gateway não precisa estar em execução.

Estabeleça a conectividade de rede

Para usar o Kerberos com o Kyuubi Gateway, configure o PrivateLink para estabelecer a conectividade de rede entre o Serverless Spark e o cluster Kerberos. Essa configuração não está disponível em modo de autoatendimento. Para concluir a configuração, envie um ticket com as informações necessárias para obter o ID do endpoint service, como epsrv-bp10******2j5ms.

Nota

Envie as seguintes informações no sistema de tickets para obter o ID do endpoint service.

O ID do workspace do Serverless Spark, como w-f8cfXXXXXX.
O ID do Kyuubi Gateway, como kb-564e********266f.
Pelo menos duas zonas disponíveis para acessar o service do Kyuubi, como cn-hangzhou-j,cn-hangzhou-k. Para obter mais informações sobre as zonas compatíveis com cada região, entre em contato com o suporte ao cliente através do ticket.

Crie um endpoint

O consumidor do service cria e mantém o endpoint. É possível associá-lo a um endpoint service para estabelecer uma conexão de rede privada e acessar services externos por meio do PrivateLink. Para mais informações, consulte Endpoints.

Faça login no console do Endpoint.

Na página Create Endpoint, configure o endpoint com os seguintes parâmetros e clique em Create.

Parameter	Description
Region	Selecione a região do endpoint. A região deve ser a mesma do cluster Kerberos e do workspace do Serverless Spark.
Endpoint Name	Insira um nome personalizado para o endpoint.
Endpoint Type	Selecione Interface Endpoint.
Endpoint Service	Clique em Select Service e selecione ou insira o ID do endpoint service de destino (o valor `epsrv-bp10******2j5ms` obtido na etapa anterior).
VPC	Selecione a VPC do nó que acessa o Kyuubi Gateway.
Zone and vSwitch	Selecione as zonas e os vSwitches especificados anteriormente. Recomendamos selecionar pelo menos duas zonas.
Security Group	Selecione o grupo de segurança para associar à interface de rede do endpoint. Recomendamos o grupo de segurança do cluster do nó que acessa o Kyuubi Gateway, a fim de evitar o bloqueio de solicitações de conexão.
IP Version	O tipo de rede compatível. O IPv4 é usado por padrão.
Resource Group	Opcional. Selecione o grupo de recursos ao qual o endpoint pertence.
Tags	Opcional. Configure uma Tag Key e uma Tag Value.

Na página Basic Information do endpoint, se o Status for Available, a criação do endpoint foi concluída. O nome de domínio do endpoint service é ep-xxxxxxxxxxx.epsrv-xxxxxxxxxxx.cn-hangzhou.privatelink.aliyuncs.com.

Faça login no cluster Kerberos e teste a conexão de rede.

Verifique a conectividade de rede privada do endpoint a partir de um nó do cluster Kerberos com o comando ping. Uma resposta normal indica que a rede está conectada:

[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

Configure a resolução de DNS (Opcional)

O nome de domínio padrão do endpoint service é longo. Para simplificar o uso, configure um nome de domínio autoritativo interno personalizado. Para mais informações, consulte Internal authoritative domain names.

Faça login no . Na página Authoritative Zone, clique na aba User-defined Zones e, em seguida, em Add Zone.
Insira um nome de domínio Authoritative Zone, selecione a VPC de aplicação do nome de domínio e clique em OK. Neste exemplo, é usado kyuubi-kerberos.abc.

Nota
Se a opção Domain Type estiver disponível, selecione Acceleration Zone. Se a opção Domain Type não estiver disponível, não é necessária nenhuma seleção, pois um nome de domínio Acceleration Zone é criado por padrão.
Na aba User-defined Zones, localize o nome de domínio de destino e clique em Settings na coluna Actions. Em seguida, clique em Add Record e selecione Form Editor Mode na caixa de diálogo.
Defina o Record Type como CNAME. Em Hostname, insira um valor conforme os requisitos do seu negócio (neste exemplo, test). Em Record Value, insira o nome de domínio do endpoint service ep-xxxxxxxxxxx.epsrv-xxxxxxxxxxx.cn-hangzhou.privatelink.aliyuncs.com. Após clicar em OK, o nome de domínio do endpoint service será mapeado para test.kyuubi-kerberos.abc.
Log on to the Kerberos cluster e teste a conexão de rede.
```
ping test.kyuubi-kerberos.abc
```

Crie um arquivo keytab

Crie um arquivo kyuubi.keytab. Esse arquivo keytab é usado apenas pelo service de autenticação do Kyuubi Gateway do Serverless Spark.

Log on to the Kerberos cluster e acesse o nó Kadmin, como o nó master-1-1 de um cluster EMR on ECS.
Execute o comando a seguir para iniciar a ferramenta kadmin.local do Kerberos.
```
kadmin.local
```
Execute o comando a seguir para visualizar os principals existentes:
```
listprincs
```
Crie um principal no formato kyuubi/<fqdn>@<REALM>. Recomendamos usar o nome de domínio do endpoint ep-xxxxxxxxxxx.epsrv-xxxxxxxxxxx.cn-hangzhou.privatelink.aliyuncs.com na parte fqdn. Caso tenha configurado um registro CNAME para resolver um nome de domínio personalizado, use o nome de domínio personalizado test.kyuubi-kerberos.abc. A parte <REALM> deve ser consistente com a configuração atual do cluster. Consulte outros principals existentes como referência.
```
addprinc -randkey kyuubi/ep-xxxxxxxxxxx.epsrv-xxxxxxxxxxx.cn-hangzhou.privatelink.aliyuncs.com@EMR.C-DFD4*****C204.COM
```

Exporte o arquivo keytab e saia da ferramenta kadmin.local após concluir a exportação.

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

quit

Faça o upload do arquivo keytab gerado para um bucket do Object Storage Service (OSS).

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

Configure o Kyuubi Gateway

Para usar o Kerberos com o Kyuubi Gateway, selecione uma network connection que possa acessar o cluster KDC e adicione a seguinte Kyuubi Configuration.

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

Parameter	Description
kyuubi.authentication	Especifique o modo de autenticação usado pelo Kyuubi Gateway. Defina este parâmetro como `KERBEROS`.
kyuubi.kinit.principal	Especifique o principal usado pelo Kyuubi Gateway para autenticação Kerberos. O formato é `<user>/<host>@<realm>`.
kyuubi.files	Este parâmetro faz com que o sistema baixe o arquivo especificado para o diretório `/opt/kyuubi/work-dir/`. Insira o caminho do OSS do arquivo keytab enviado nas etapas anteriores. O caminho não precisa incluir o domínio `oss-<region-id>-internal.aliyuncs.com`.
kyuubi.kinit.keytab	Especifique o arquivo keytab usado pelo Kyuubi Gateway. Nota: o caminho é fixo no diretório `/opt/kyuubi/work-dir/`. Altere o nome do arquivo conforme a sua necessidade.

Caso precise se conectar a um Hive Metastore (HMS) com Kerberos ativado e o catálogo de dados do workspace já esteja configurado com o catálogo de dados do HMS, adicione a seguinte Spark Configuration.

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

Parameter	Description
spark.hive.metastore.kerberos.principal	O principal do HMS em um ambiente Kerberos. Insira o principal do hive obtido ao executar o comando `listprincs` nas etapas anteriores. A parte `<fqdn>` pode ser simplificada para `_HOST` (ou seja, hive/_HOST@<REALM>).
spark.hive.metastore.sasl.enabled	Especifique se a autenticação Kerberos deve ser ativada. Defina este parâmetro como true.

Opcional. Caso precise se conectar a um HMS com Kerberos ativado e o catálogo de dados do workspace not esteja configurado com o catálogo de dados do HMS, você também precisa add as seguintes configurações do 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

Parameter	Description
spark.hadoop.hive.metastore.uris	O endereço do Hive Metastore (HMS).
spark.hadoop.hive.imetastoreclient.factory.class	Um valor fixo.

Nota

Em um cluster de alta disponibilidade (HA), é possível configurar vários endereços Thrift para metastore.uris. Os endereços devem ser separados por vírgulas e é obrigatório usar hostnames, não endereços IP.
Se for especificado apenas um endereço Thrift para metastore.uris, será possível usar um endereço IP. No entanto, metastore.kerberos.principal deve estar no formato hive/<hostname of HMS>@<REALM>.
A simplificação de metastore.kerberos.principal para o formato hive/_HOST@<REALM> só é possível quando metastore.uris usa um hostname.

Salve as configurações e inicie o Kyuubi Gateway.

Envie um job

Verifique se o cluster Kerberos consegue se conectar ao Kyuubi Gateway e inicie um job Spark.

(Opcional) Prepare um usuário Kerberos com as permissões necessárias e exporte o respectivo arquivo keytab.
1. Log on to the Kerberos cluster.
2. Execute os comandos a seguir para exportar o arquivo 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
```
Autentique-se com o Kerberos usando o arquivo keytab.
```
kinit -kt /root/emr-user.keytab emr-user
```
Se nenhum arquivo keytab tiver sido criado na etapa anterior, também será possível usar um arquivo keytab de service existente, como o arquivo hive.keytab disponível por padrão no EMR on ECS.

Nota
Para fins de teste, use diretamente um arquivo keytab existente no cluster. No entanto, não modifique nem reexporte arquivos keytab de service existentes, pois os services originais podem ficar indisponíveis.
```
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
```
Visualize os tickets Kerberos atuais.
```
klist
```
Use o kyuubi-beeline ou o spark-beeline para se conectar ao Kyuubi Gateway e iniciar um job Spark.
```
kyuubi-beeline -u 'jdbc:hive2://ep-xxxxxxxxxxx.epsrv-xxxxxxxxxxx.cn-hangzhou.privatelink.aliyuncs.com:10009/;principal=kyuubi/_HOST@EMR.C-DFD43*****7C204.COM'
```
Nota
- ep-xxxxxxxxxxx.epsrv-xxxxxxxxxxx.cn-hangzhou.privatelink.aliyuncs.com é o nome de domínio do service obtido na seção "Crie um endpoint".
- O número da porta padrão é 10009.
- O principal é o principal do service Kyuubi. A parte <fqdn> pode ser simplificada para _HOST (ou seja, kyuubi/_HOST@EMR.C-DFD43*****7C204.COM).

Após estabelecer a conexão, execute 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)

FAQ

Como me conectar a um service HDFS com Kerberos ativado?

Modifique o arquivo de configuração core-site.xml do componente HADOOP-COMMON ou HDFS no cluster onde o service HDFS reside. Adicione as seguintes propriedades ao arquivo para permitir que o usuário kyuubi represente outros usuários ao acessar os services HDFS/HMS. Caso contrário, a conexão pode falhar. Após adicionar as propriedades, reinicie o service HDFS/HMS. Versões mais recentes dos clusters EMR DataLake já incluem essas propriedades por padrão.

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

Também é necessário adicionar as seguintes Spark configurations.

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

Como envio jobs para o Kyuubi sem autenticação Kerberos e realizo a autenticação Kerberos apenas quando os jobs Spark acessam o HMS?

Modifique as configurações do Kyuubi da seguinte forma. Nesse caso, não é necessário especificar um principal ao se conectar ao Kyuubi.

kyuubi.authentication              KERBEROS,NONE

Como me conectar ao service Ranger após a ativação do Kerberos?

Adicione as seguintes configurações do 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

Parameter	Description
spark.files	Este parâmetro faz com que o sistema baixe o arquivo especificado para o diretório `/opt/spark/work-dir/`. Insira o caminho do OSS do arquivo keytab enviado nas etapas anteriores. O caminho não precisa incluir o domínio `oss-<region-id>-internal.aliyuncs.com`.
ranger.plugin.spark.policy.download.loginKeytab	Um valor fixo.
ranger.plugin.spark.policy.download.keytab	Qualquer arquivo keytab válido.
ranger.plugin.spark.policy.download.principal	O principal armazenado no arquivo keytab. Esse principal é usado para baixar as políticas do Ranger e evitar falhas de autenticação.