Kubernetes集群Jenkins Agent报HOME is not set错误咨询

两个报错是连锁反应，核心根因和HOME环境变量无关，是添加TLS配置后路由规则和Kubernetes插件配置不匹配，导致JNLP Agent根本没有连上正确的Jenkins Controller端点，连带触发后续所有异常。

核心问题修复：解决tcpSlaveListener 404 #

• 先明确流量逻辑：Jenkins UI走8080端口的HTTP/HTTPS七层流量，可以挂Ingress配置Let's Encrypt证书；但JNLP Agent和Controller的通信走50000端口的原生TCP流量，不能走七层Ingress的HTTPS终止，你现在日志里出现访问8080端口下的tcpSlaveAgentListener返回404，就是重配插件时漏了JNLP专用连接地址配置，Agent默认去8080端口找TCP监听端点，被Ingress的HTTP规则拦截返回404。
• 按以下顺序修正配置：
  • 检查现有Service配置，确认8080、50000两个端口都正常映射到Jenkins Controller Pod的对应端口，Service selector标签和Controller Pod标签完全匹配，不要修改50000端口的暴露方式
  • 打开Jenkins系统配置页找到Kubernetes插件配置项：
    • Jenkins URL字段填写你配置了TLS之后的HTTPS协议UI访问地址（就是浏览器正常打开Jenkins的地址）
    • Jenkins tunnel字段单独填写集群内部直连地址：<jenkins-service-name>.<jenkins-namespace>.svc.cluster.local:50000，这个地址走集群内部DNS，不经过Ingress，不会被TLS规则拦截
  • 如果你确实需要JNLP流量走Ingress，需要在Nginx Ingress控制器中单独配置TCP层转发规则，把50000端口的TCP流量直接透传给Jenkins Service的50000端口，不能用HTTP/HTTPS的七层路由规则转发，否则握手必失败。
• 配置校验：在集群内启动一个临时调试Pod，执行curl -I http://<jenkins-svc-ip>:8080/tcpSlaveAgentListener/，正常返回的响应头里会包含Jenkins-Agent-Protocols: JNLP4-connect字段；如果直接返回404，先排查Service和Controller Pod的连通性，不要往下调Agent配置。

连带问题修复：HOME未设置、echo命令执行失败 #

• 这个报错是Agent连接失败的次生问题：当Agent连错端点时，jnlp容器拿不到Controller下发的启动上下文，容器初始化脚本根本没执行到加载环境变量的步骤，Gradle注入插件检测不到HOME变量就会抛出对应错误，甚至连基础的echo测试命令都无法执行，本质是Pod还没完成正常初始化就被存活探针拉起重启，和你手动配置的HOME环境变量没有关系。
• 只要把前面的路由配置修正，Agent能正常通过50000端口和Controller完成JNLP握手，这个报错会自动消失，不需要额外在jnlp容器中注入HOME变量。如果修正路由后仍然报HOME相关错误，再检查jnlp容器的安全上下文配置：确认runAsUser配置的UID和镜像内jenkins用户UID一致（默认官方镜像UID为1000），工作目录没有被修改为jenkins用户无读写权限的路径即可。

验证流程 #

• 保存Kubernetes插件配置后，手动触发一个测试构建，查看新启动的Agent Pod日志，出现INFO: Connected to Jenkins controller字样即代表连接正常
• 连接正常后再测试简单echo命令、Gradle构建任务，确认功能恢复
• 后续调整Ingress证书配置时，注意不要给50000端口的TCP流量配置HTTPS终止，避免TLS握手拦截JNLP连接。

内容的提问来源于stack exchange，提问作者user3334871