使用自定义Docker镜像的Jenkins Agent无法连接Minikube中的Controller

我之前也碰到过类似的情况，既然默认JNLP镜像能正常工作，说明Kubernetes和Jenkins Controller的基础配置没问题，问题大概率出在自定义镜像或者它的启动配置上，咱们一步步排查：

1. 检查自定义镜像的核心依赖 #

默认的jenkins/jnlp-slave已经打包了所有必要组件，自定义镜像很容易漏掉关键项：

• 必须包含Java运行时：JNLP Agent是Java程序，没有Java根本跑不起来。如果用Alpine基础镜像，Dockerfile里要加上安装步骤：

  FROM alpine:3.18
  RUN apk add --no-cache openjdk11-jre-headless
  

• 确保包含jenkins-agent.jar：这个Jar是Agent连接Controller的核心，你可以从Jenkins Controller的http://<jenkins-url>/jnlpJars/jenkins-agent.jar下载，然后复制到镜像里：

  COPY jenkins-agent.jar /usr/share/jenkins/
  

  注意Jar包版本要和Jenkins Controller版本匹配，不然可能出现兼容性问题。

2. 确认Agent启动命令参数正确 #

自定义镜像的启动命令必须带全JNLP连接参数，默认逻辑是这样的：

java -jar /usr/share/jenkins/jenkins-agent.jar \
  -jnlpUrl http://<jenkins-service-name>:8080/computer/${computer.name}/slave-agent.jnlp \
  -secret ${computer.jnlpmac} \
  -workDir "/home/jenkins/agent"

在Jenkins的Kubernetes Pod模板里要注意：

• 检查“Command to run”或“Arguments”配置，有没有正确引用Jenkins提供的${computer.jnlpmac}和${computer.name}变量
• 确认-jnlpUrl里的服务地址正确，Minikube里同namespace下直接用Controller的Service名称（比如jenkins:8080）即可访问

3. 排查网络连通性 #

Agent Pod必须能访问到Jenkins Controller的JNLP端口：

• 先确认Controller开启了JNLP端口：进入Manage Jenkins -> Configure Global Security，找到“TCP port for JNLP agents”，要么设为固定端口（比如50000），要么勾选“Random”
• 检查Controller的Service配置，有没有暴露JNLP端口：

  ports:
    - name: http
      port: 8080
      targetPort: 8080
    - name: jnlp
      port: 50000
      targetPort: 50000
  

• 测试Agent Pod能不能ping通Jenkins Service：

  kubectl exec -it <agent-pod-name> -- ping jenkins
  

  如果ping不通，检查namespace是否一致，或者有没有网络策略限制了访问。

4. 检查认证与权限配置 #

• 确保Jenkins生成的secret令牌正确传递：Pod模板里的-secret参数必须是${computer.jnlpmac}，这个是Jenkins动态生成的，不能硬编码
• 检查Agent运行权限：自定义镜像里的工作目录（比如/home/jenkins/agent）要给Jenkins用户读写权限，Dockerfile里可以加：

  RUN adduser -D jenkins && mkdir -p /home/jenkins/agent && chown -R jenkins:jenkins /home/jenkins/agent
  USER jenkins
  WORKDIR /home/jenkins/agent
  

5. 查看Agent Pod日志定位具体错误 #

这是最直接的排查方式，看日志就能知道哪里出问题：

kubectl logs <agent-pod-name> -n <jenkins-namespace>

常见错误包括：

• java.io.FileNotFoundException: jenkins-agent.jar：Jar包路径错误，检查镜像里的文件位置
• Connection refused：网络不通，检查Controller端口和Service配置
• Invalid secret：令牌传递错误，核对Pod模板参数

6. 本地镜像测试 #

可以先在Minikube里手动运行自定义镜像，传入参数测试连接：

kubectl run test-agent --rm -it --image=<your-custom-image> -- \
  java -jar /usr/share/jenkins/jenkins-agent.jar \
  -jnlpUrl http://<jenkins-ip>:8080/computer/test-agent/slave-agent.jnlp \
  -secret <your-secret-token>

这里的secret-token可以从Jenkins新建永久节点的JNLP连接信息里获取，如果手动运行能成功连接，说明镜像本身没问题，问题出在Jenkins的Pod模板配置上。

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