SQL Server PolyBase HDFS Kerberos 连接故障排查：hdfs-kerberos-tester 工具完全指南

示例工程数据库教程后端【免费下载链接】sql-server-samplesAzure Data SQL Samples - Official Microsoft GitHub Repository containing code samples for SQL Server, Azure SQL, Azure Synapse, and Azure SQL Edge项目地址https://gitcode.com/gh_mirrors/sq/sql-server-samples点击查看免费下载导读在 SQL Server 中通过 PolyBase 对 Kerberos 加固KDC 安全的 Hadoop 集群Cloudera 或 Hortonworks创建外部表时HDFS Kerberos 连接失败是常见且难定位的问题——它可能源自用户名/密码配置错误也可能源自集群 Kerberos 配置本身的问题。samples/manage/hdfs-kerberos-tester目录下的 HDFS Kerberos Tester 是一款完全独立于 SQL Server 的探针工具可先于 PolyBase 本身验证 HDFS Kerberos 链路的每一环帮助你把问题收敛到“到底是 SQL Server 侧还是 Hadoop/Kerberos 侧”。读完本文你将掌握该工具的工作原理、在 Azure Data Studio 中逐 Cell 运行的完整步骤、全部输入项的含义与取值建议以及如何解读 CHECKPOINT 与各类报错信息并学会用 PolyBase 配置进一步验证。1. 工具定位为什么需要一个独立于 SQL Server 的 Kerberos 测试器1.1 使用场景当你在 Kerberos 加固的 HDFS 集群上通过 PolyBase 创建外部表遇到 HDFS Kerberos 失败时故障链路可能很长KDC 可达性、Realm 名称、KDC 主机名、服务主体principal、密码、HDFS NameNode 端口与路径……任何一环出错都会表现为“连接失败”而 SQL Server 侧报错往往无法直接告诉你根因。HDFS Kerberos Tester 正是用来排除非 SQL Server 问题的它在完全不依赖 PolyBase 特性、不依赖任何 SQL Server 组件的前提下用与 PolyBase 相同的 Kerberos 认证流程去访问 HDFS从而快速识别两类典型问题用户名/密码配置错误Username/password misconfigurations集群 Kerberos 设置配置错误Cluster Kerberos setup misconfigurations1.2 前置条件项目要求说明Hadoop 集群使用 Kerberos 加固Active Directory 或 MIT KDC的 Cloudera / Hortonworks 集群工具不关心发行版只关心标准 Kerberos HDFS 协议JavaJava 7 或更高版本工具本体是 Java 程序需要java可执行文件且在 classpath 中可被调用Azure Data Studio安装最新版本用于打开并运行.ipynbNotebook磁盘空间约 40 MBNotebook 及随附 JAR 包的体积注意本工具不要求安装 PolyBase 特性也不依赖 SQL Server 的任何组件它纯粹从客户端发起 Kerberos 认证并访问 HDFS因此可用于在 SQL Server 部署之前先行验证环境。1.3 目录内容[samples/manage/hdfs-kerberos-tester](https://link.gitcode.com/i/db8e1ba5d2d70c40cc2c7399cf8b9de6)目录下共 5 个文件必须全部下载到同一文件夹并保持共处co-located文件作用hdfs-kerberos-tester.ipynbAzure Data Studio 可直接打开运行的 Notebook包含全部交互与诊断逻辑hdfs-kerberos-tester-0.0.1-jar-with-dependencies.jar带全部依赖的 Fat JAR内含com.microsoft.kerberos.client.HdfsBridge主类及 Hadoop/Kerberos 客户端库hdfs-kerberos-tester-0.0.1.jar精简版 JAR不含依赖用于结合 PolyBase 安装目录中的 Hadoop 依赖运行jaas.confJAAS 登录配置定义Client使用com.sun.security.auth.module.Krb5LoginModule且useTicketCachefalsemyKerbPass.txt密码占位文件默认内容是{change the password}使用前必须替换为真实密码jaas.conf内容如下Client { com.sun.security.auth.module.Krb5LoginModule required useTicketCachefalse; };关键点useTicketCachefalse表示不使用本地票据缓存而是直接用提供的用户名 密码文件向 KDC 发起 AS 请求换取票据——这正是它能独立复现 PolyBase 认证流程的原因也意味着你提供的密码文件内容必须准确。2. 快速开始在 Azure Data Studio 中运行 Notebook2.1 启动步骤将[hdfs-kerberos-tester](https://link.gitcode.com/i/db8e1ba5d2d70c40cc2c7399cf8b9de6)目录下所有文件下载到本地同一个文件夹。打开 Azure Data Studio。点击顶部菜单File → Open File导航到保存hdfs-kerberos-tester.ipynb的文件夹选择该文件并打开。Notebook 加载后在内核选择器中选择Python3Notebook 元数据中kernelspec声明的正是python3语言版本记录为 Python 3.6.6。点击Run Cells按钮依次运行全部 Cell并遵循 Notebook 内的交互提示输入参数。2.2 运行前需要准备的输入项Notebook 会逐个提示输入以下信息对应源码中PromptForInfo的交互逻辑输入项Notebook 提示取值说明HDFS 集群节点名Please provide your cluster hdfs node IP address or host nameHDFS NameNode 主机名或 IP 地址HDFS 端口Please provide your Cluster hdfs listening port number通常为8020HDFS 默认 RPC 端口Kerberos RealmPlease provide your Kerberos realm(UPPER CASE)必须大写例如EXAMPLE.COMKDC 主机名/IPPlease provide your Kerberos KDC host name or IP可从 Ambari 或 Hortonworks 管理界面查到Kerberos 用户名Please provide your Kerberos Username for login:例如pdw_user不带 Realm 后缀密码文件路径Kerberos Password file name:直接输入myKerbPass.txt默认同目录或输入存有密码的文本文件的完整路径其中密码文件需要你提前编辑将[myKerbPass.txt](https://link.gitcode.com/i/3695680b8166feb1d94679ebbd21ad8b)中的占位文本{change the password}替换为真实 Kerberos 密码。PromptForInfo的源码逻辑Notebook 第 1 个代码 Cell保证任何输入为空都会立即终止def PromptForInfo(promptMsg, errorMsg): promptResponse input(promptMsg) if promptResponse : raise SystemExit(errorMsg \n) return promptResponse2.3 Notebook 的执行流程Notebook 按以下顺序执行每个 Cell 都有明确的 markdown 标题检查 Java 是否安装运行java -version成功标志为输出中包含java version或build。若输出不含这些关键字executeCommand会抛出“Java was not installed. Please check pre requisits and rerun this cell.”判定关键字为not recongnized。逐个输入六个参数主机、端口、Realm、KDC、用户名、密码文件。运行测试拼接 Java 命令并调用HdfsBridge主类等待CHECKPOINT 2 COMPLETED成功标志。3. 核心原理HdfsBridge 的两个检查点CHECKPOINT机制Notebook 最终执行的核心命令为java -classpath hdfs-kerberos-tester-0.0.1-jar-with-dependencies.jar \ com.microsoft.kerberos.client.HdfsBridge \ hdfs_node_name port_number kerberos_realm kerberos_kdc \ kerberos_username kerberos_password_file命令参数顺序与HdfsBridge主类的 Usage 提示完全一致Usage (Kerberos): HdfsBridge [HDFS Namenode IP] [HDFS Namenode Port] [kerberos realm] [KDC host name] [Kerberos Username(no realm suffix)] [Kerberos Password File] ([ HDFS Filepath ])从 JAR 内嵌的类字节码com/microsoft/kerberos/client/HdfsBridge.class可以看到完整的检查点设计CHECKPOINT 1 —— KDC 认证输出CHECKPOINT 1 STARTING: Authentication against KDC server成功后输出Successfully authenticated against KDC server.与CHECKPOINT 1 COMPLETED: Authenticated against KDC server。此阶段失败意味着用户名、密码、Realm、KDC 主机名四者中至少一个有问题。CHECKPOINT 2 —— HDFS 访问输出CHECKPOINT 2 STARTING: Attempting to access external filesystem at URI: ...成功访问后输出CHECKPOINT 2 COMPLETED: Successfully accessed the external file system. Kerberos test has been passed.。Notebook 正是以字符串CHECKPOINT 2 COMPLETED作为整条命令的成功判定标志。此阶段失败说明 KDC 认证已通过但 HDFS 访问失败端口、NameNode 或路径问题。工具默认测试路径为根目录/也可在命令末尾追加第七个参数指定具体 HDFS 文件路径Notebook 中以注释形式给出了带路径的用法示例。从com.microsoft.kerberos.client包内的类结构看认证流程的调用链为HdfsBridge.main→HdfsBridge.connect→kerberosLoginHelper→KerberosSecureLogin.secureLogin内部通过javax.security.auth.login.LoginContext结合 JAAS 配置完成Krb5LoginModule登录登录失败时抛出HdfsBridgeException并区分“Kerberos login failed”与后续“Exception at connect”两个层级。4. 错误诊断Notebook 内置的错误分类与含义Notebook 的executeCommand函数是诊断能力的核心命令输出中若包含成功标志即打印Kerberos Success否则依次匹配典型错误特征串并给出针对性的修复建议全部匹配失败才抛出通用失败信息def executeCommand(cmd, successMsgs, printMsg): print(printMsg) cmdOutput !{cmd} cmdOutput \n.join(cmdOutput) if any(msg in cmdOutput for msg in successMsgs): print(f\nKerberos Success ) else: if any(msg in cmdOutput for msg in [java.net.SocketTimeoutException: Receive timed out]): raise SystemExit(f\nFailed due to wrong kdc hostname: Please check the kdc name and rerun the notebook after changing kdc hostname.\n cmd \n output:\n cmdOutput) if any(msg in cmdOutput for msg in [Client not found in Kerberos database (6) - CLIENT_NOT_FOUND]): raise SystemExit(f\nThe admin Service Principal supplied does not exist in the realm. Please check if user exist in kerberos realm.\n cmd \n output:\n cmdOutput) if any(msg in cmdOutput for msg in [Checksum failed]): raise SystemExit(f\n Bad password. Please check the password and re run the test with right password.\n cmd \n output:\n cmdOutput) if any(msg in cmdOutput for msg in [java.io.FileNotFoundException File does not exist]): raise SystemExit(f\n specified file location does not exist on hdfs. change the location.\n cmd \n output:\n cmdOutput) if any(msg in cmdOutput for msg in [not recongnized]): raise SystemExit(f\n Java was not installed. Please check pre requisits and rerun this cell.\n cmd \n output:\n cmdOutput) if any(msg in cmdOutput for msg in [java.net.ConnectException: Connection refused]): raise SystemExit(f\n Port number is not correct. Please check hdfs connection port number is active.\n cmd \n output:\n cmdOutput) raise SystemExit(f\nFailed during:\n\n\t{cmd}\n\nreturned: \n .join(cmdOutput) .\n)错误特征串与诊断结论对照如下输出特征串诊断结论修复方向java.net.SocketTimeoutException: Receive timed outKDC 主机名错误检查 KDC 名称修正后重跑 NotebookClient not found in Kerberos database (6) - CLIENT_NOT_FOUND提供的服务主体在 Realm 中不存在确认该用户是否存在于 Kerberos Realm 中Checksum failed密码错误检查密码并重新运行测试java.io.FileNotFoundException File does not exist指定的 HDFS 路径不存在修改测试路径not recongnizedJava 未安装检查前置条件Java 7后重跑java.net.ConnectException: Connection refused端口错误检查 HDFS 监听端口是否有效Notebook 自带一个真实失败样例execution_count 22使用pdw_user1APSHDPMS.COM向 KDC10.193.27.236认证时KDC 返回error code is 6, error Message is Client not found in Kerberos database随后Krb5LoginModule抛出LoginException最终HdfsBridge输出KDC authentication has failed. Unable to connect to KDC server with provided information. Please contact hadoop admin to resolve this issue.。该样例演示了完整链路日志中的 KrbKdcReq send: kdc10.193.27.236 UDP:88, timeout30000, number of retries 3表明认证走 UDP 88 端口、超时 30 秒、最多重试 3 次可以据此判断 KDC 网络链路是否通畅。补充判定参考成功输出会包含Successfully authenticated against KDC serverCHECKPOINT 1 完成与Connected to external storage.而Unable to contact HDFS name node with provided information. KDC connection succeeded but HDFS connection failed.则表示 KDC 认证已通过、但 HDFS NameNode 连接失败。5. 结合 PolyBase 配置验证用安装目录的 Hadoop 配置重跑如果目标机器上已安装 PolyBase 特性工具还提供第二种运行模式直接使用 PolyBase 安装目录下的 Hadoop 配置与依赖重跑测试验证 PolyBase 的配置本身是否正确。操作步骤将 PolyBase 安装目录中的Hadoop文件夹复制到 Notebook 的当前工作目录。运行 Notebook 中最后一个默认被注释掉的Celljava -classpath hdfs-kerberos-tester-0.0.1.jar;.\Hadoop\HDP2_2\*;.\Hadoop\*;.\Hadoop\conf \ com.microsoft.kerberos.client.HdfsBridge \ hdfs_node_name port_number kerberos_realm kerberos_kdc \ kerberos_username kerberos_password_file这条命令与主模式的关键差异使用不含依赖的hdfs-kerberos-tester-0.0.1.jar依赖改为从 PolyBase 的Hadoop目录按HDP2_2\*、Hadoop\*、Hadoop\conf顺序加载类路径中的.\Hadoop\conf会把 PolyBase 实际使用的 Hadoop 配置文件如core-site.xml、hdfs-site.xml纳入从而复现 PolyBase 真实运行时的配置组合。从 JAR 中com/microsoft/kerberos/common/HadoopConfigurationProperties.class的枚举常量可确认工具识别到 PolyBase 侧的两个核心 Kerberos 配置项polybase.kerberos.realmKerberos Realmpolybase.kerberos.kdchostKDC 主机这意味着如果这条命令成功完成CHECKPOINT 2而 SQL Server 中创建外部表仍失败问题就基本收敛到 SQL Server / PolyBase 服务侧如服务主体映射、CREATE DATABASE SCOPED CREDENTIAL中的身份与密码配置如果这条命令失败则说明问题出在 PolyBase 使用的 Hadoop/Kerberos 配置上应回到集群侧排查。6. 常见问题与注意事项Q1密码文件应该怎么准备直接用仓库自带的[myKerbPass.txt](https://link.gitcode.com/i/3695680b8166feb1d94679ebbd21ad8b)位于工具目录与 Notebook 共处把第一行{change the password}替换为真实密码也可以自建任意文本文件并输入其完整路径。注意密码文件内容是明文运行完毕后应及时清理。Q2Realm 大小写敏感吗敏感。Notebook 提示明确要求UPPER CASE例如EXAMPLE.COM错误的大小写会导致 KDC 认证失败典型表现为Client not found in Kerberos database或 Realm 不匹配类错误。Q3为什么我的环境总在 CHECKPOINT 1 失败CHECKPOINT 1 只涉及 KDC 认证请按顺序核对KDC 主机名/IP可从 Ambari 或 Hortonworks 界面查询、Realm 大小写、用户名是否真实存在于 Realm不含REALM后缀、密码文件内容。Notebook 报错文案会针对性地指出是哪一类问题。Q4CHECKPOINT 1 成功但 CHECKPOINT 2 失败说明 KDC 认证链路正常问题在 HDFS 侧核对 NameNode 主机名/IP、端口默认 8020需确认监听端口有效、以及默认测试路径/或自定义路径的权限与存在性。日志中若出现Connection refused即为端口问题。Q5能否在 Linux 上使用工具本身是跨平台的 Java Python Notebook 方案jaas.conf、密码文件与 JAR 不依赖 Windows。Notebook 内嵌示例日志显示的是 Windows 路径f:\azure-data-studio\notebooks-python但命令结构java -classpath ...与路径语法在不同平台按各自习惯调整即可类路径分隔符在 Linux/macOS 上需从;改为:。Q6工具的独立性有什么好处Notebook 内明确说明“This tool does not require Polybase feature and it does not depend on any SQL server components.”。这使你可以在任何一台能访问集群的机器上先行验证 Kerberos HDFS 链路把环境问题与 SQL Server 问题彻底隔离避免在 SQL Server 实例上反复尝试创建外部表来试错。7. 关联资源工具本体与说明文档samples/manage/hdfs-kerberos-tester/readme.md、hdfs-kerberos-tester.ipynbPolyBase 外部表统计信息维护示例samples/manage/polybase/external-table/README.md涉及 PolyBase 外部表维护的配套知识仓库中 PolyBase 相关脚本sp-drop-create-stats-external-table.sql8. 小结HDFS Kerberos Tester 的价值在于“先隔离、再定位”它独立于 SQL Server 复现 PolyBase 的 Kerberos HDFS 访问链路通过两个 CHECKPOINT 将问题精确划分为 KDC 认证问题与 HDFS 访问问题再借助内置的错误特征匹配把SocketTimeoutException、CLIENT_NOT_FOUND、Checksum failed、Connection refused等常见故障自动映射到对应的修复动作。配合“复制 PolyBase Hadoop 配置重跑”的第二模式你可以在几分钟内判断故障到底在 SQL Server 侧还是 Hadoop/Kerberos 集群侧从而把精力集中在真正需要修复的环节上。使用前请确认Java 7 已安装、全部 5 个文件共处同一文件夹、密码文件已更新、KDC 与 Realm 信息准确。赞分享示例工程数据库教程后端【免费下载链接】sql-server-samplesAzure Data SQL Samples - Official Microsoft GitHub Repository containing code samples for SQL Server, Azure SQL, Azure Synapse, and Azure SQL Edge项目地址https://gitcode.com/gh_mirrors/sq/sql-server-samples点击查看免费下载相关推荐Apache Airflow HDFS ProviderWebHDFS 连接配置全解字段、Extra 参数与 Kerberos 实现细节Apache Airflow HDFS ProviderWebHDFS 连接配置全解字段、Extra 参数与 Kerberos 实现细节 本文基于 Apa后端任务调度工作流自动化数据编排批处理数据工程流程编排Argo Workflows HDFS 制品HDFSArtifact完整配置指南字段、Kerberos 认证与源码解析Argo Workflows HDFS 制品HDFSArtifact完整配置指南字段、Kerberos 认证与源码解析 HDFSArtifact 是 Ar云原生容器编排工作流自动化任务调度后端Presto Coordinator Kerberos 认证配置完整指南从环境准备到 HTTPS 与故障排查Presto Coordinator Kerberos 认证配置完整指南从环境准备到 HTTPS 与故障排查 导读 本文基于 Presto 官方文档 serv大数据数据库后端上一篇5分钟完成Adobe软件永久激活Adobe-GenP破解工具终极指南下一篇CUTLASS 功能矩阵Device 级 GEMM、隐式 GEMM 卷积与 Warp 级 Tensor Core 计算能力全解析创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考